apache > db
Apache DB Project
Font size:      

Apache Derby: Writing guidelines

The Derby documentation is sourced in DITA. The tagging used with DITA is similar to HTML tagging. This page contains guidelines for working with DITA topics and tagging.

New topics: Choosing the correct topic type

There are three types of topics used in the Derby documentation: concepts, reference, and tasks.

Concept topics are overview information that answer the question "What is...?". They explain "why" something is important or behaves the way it does. Concepts provide the background information users must understand before they can complete the tasks successfully.

Reference topics provide detailed information about product capabilities for quick reference and for completeness. Reference information provides quick access to facts, but no explanation of concepts or procedures. Examples of reference topics are the syntax for commands, and SQL statements, class descriptions, detailed examples, and troubleshooting information.

Task topics answer the question "How do I?". Tasks typically include step-by-step instructions. Task topics often list (or link to) prerequisites that need to be completed before the user can perform the task. Tasks also list (or link to) any restrictions on performing the task.

New topics: Using a template to create a new topic

When you need to create a new topic, use one of the templates that are included with the Derby source files. The templates are located in the \trunk\templates directory.

New topics: Selecting the best filename

When you create a new topic, use a filename that is easy to understand. Filenames should consist of four parts:

  1. 1 letter that indicates the type of topic: r=reference, c=concept, t=task
  2. Several letters that designate the abbreviation for the manual that the topic is in.
    Abbreviation Derby Manual
    admin Derby Server and Administration Guide
    dev Derby Developer's Guide
    gs Getting Started with Derby
    ref Derby Reference Manual
    tools Derby Tools and Utilities Guide
    tuning Tuning Derby
    wwd Working with Derby
  3. Several letters that indicate a category of information
  4. Several letters that specify the exact information in the file

The following table shows some examples of good filenames.

Information in the topic Sample filename Comments
A new function, ROUND, is being documented in the Reference Manual rreffuncround If all functions start with rreffunc, then they will be grouped together alphabetically which makes the files that discuss functions easier to find when the files need to be updated.

The exclusive lock, is being documented in the Developers Guide cdevlocksshared Because this is a concept topic in the developers guide about locks, the beginning of the topic filename is cdevlocks. The end of the filename shared indicates the specific type of locks that the topic describes.

The description of the support Derby has for shared locks should be documented in a concept topic. How users set the locks should be documented in a task topic. Information, such a table listing compatibility between the types of locks, should be documented in a reference topic.

A new utility, abc, is being documented in the Tools and Utilities Guide ttoolsabcstarting This topic is a task that describes how to start the abc utility.

Understanding DITA tags

The tags that are used in DITA topics are similar to HTML and XML tags.

  • Structural tags: paragraphs, lists, tables, syntax diagrams, index entries
  • Textual tags: external links, inline examples, notes

The next 2 sections describe these tags and provides tagging examples.

If you have questions about DITA tagging, ask on the derby-dev mail list.

Tagging examples - structural tags

The following table lists the proper structural tags to use for the most common features within the Derby topics.

Feature Tag to use Comments
Paragraphs <p> A paragraph tag is used for a block of text that contains a single main idea.

Bulleted lists (also known as unordered lists) <ul> and <li> The list starts with the <ul> tag. For each bullet that you want in the list, use a <li> tag. In an unordered list, the order of the list items is not significant. The output displays a "bullet" character at the beginning of each item.

For example:

<li>This is an item in an unordered list.</li>
<li>To separate it from other items in the list, the formatter puts a bullet beside it.</li>
<li>This is the last list item in our unordered list.</li>

Tables <table> There are several tags that you need to use to create a table. The simpliest type of table uses the following tagging. For more advanced tagging see the section below on "Customizing tables in the Derby documentation".

<tgroup cols="3" colsep="1" rowsep="1">
<colspec colname="1">
<colspec colname="2">
<colspec colname="3">
<entry colname="1">Column Name</entry>
<entry colname="2">Type</entry>
<entry colname="3">Description</entry>
<entry colname="1">CONSTRAINTID</entry>
<entry colname="2">CHAR</entry>
<entry colname="3">Unique identifier for the constraint</entry>
<entry colname="1">CHECKDEFINITION</entry>
<entry colname="2">LONG VARCHAR</entry>
<entry colname="3">Text of check constraint definition</entry>

Index entries <indexterm> Indexing tags are used to index important terms. Index entries are displayed at the end of the PDF output for each Derby manual. When there is an Information Center, the index terms are added as metadata to help in searching for content in the Information Center.

Syntax diagrams <codeblock> Use the <codeblock> tag when you need to specify the syntax for commands and SQL statements. The content of this tag preserves line endings and the output is in a monospaced font. See the topic SQL Syntax for the correct symbols to use in Derby syntax diagrams.

Definition lists <dl>
A definition list is a list of terms and their corresponding definitions. The term appears flush left, followed by the description or definition that is indented starting on the next line. Definition list require a series of tags.

For example:

<dd>The name of the machine where the server is running.</dd>
<dd>The port that the server is listening to.</dd>
<dd>The name of the database that you are connecting to. </dd>

Tagging examples - textual tags

The following table lists the proper textual tags to use for the most common features within the Derby topics.

Feature Tag to use Comments
Links to external sites <xref> Use the cross-reference <xref> tag to specify a link to an external Web page. You should specify the scope attribute to "external" when you create the cross-reference.

For example:
<xref href=http://db.apache.org/derby/manuals/index.html scope="external">Derby Documentation</xref>

To create links to other topics in the Derby documentation, edit the ditamap for the source manual to specify a related link to another Derby topic.

Code or examples in paragraphs <codeph> The code phrase tag represents a snippet of code within the main flow of text. The code phrase is displayed in a monospaced font for emphasis.

For example:
A runtime rollback is a system-generated rollback of a statement or transaction by Derby, as opposed to an explicit <codeph>rollback</codeph> call from your application.

Notes <note> A note tag contains information, differentiated from the main text, that expands on or calls attention to a particular point. Notes are displayed in their own paragraph and do not need to be inside of a paragraph <p> tag. You can specify a type of note, which displays as the lable for the note text in the output. If you do not specify the type of note, the label is "Note:". Commonly used types are: Attention, Fastpath, Important, Remember, Restriction, and Tip.

For example, this tagging <note="tip"> You can override the default locale for ij with a property on the JVM.</note>

produces this result:

Tip: You can override the default locale for ij with a property on the JVM.

Indexing guidelines

What to index? You should index general and specific terms. You should look at the index entries in other topics to see what valid entries look like. Nesting index terms can be very useful.

What tags do I use to index terms? In Derby, the index entries are inserted inside the <prolog> tag. The <prolog> tag is immediately after the <title> and <shortdesc> tags. Index entries use the <indexterm> tag, but that tag must be nested inside serveral other tags. For example, if the index term is CREATE TABLE and the topic currently does not have any index entries, the tags that you would need are:

<indexterm>CREATE TABLE</indexterm>

If the topic already has at least one index term, then you only need to add the new term inside the keywords tag.

For example:

<indexterm>CREATE TABLE</indexterm>

How do I add an index term? Add the <indexterm> tag and enter the term that you want to use. Typically you specify a general category of information followed by a specify term. For example, if you have added a new parameter called "abc", you would use "parameters" as the general catagory and "abc" as the specific term. The tagging for this entry is:


The output appears like this:


The specific term "abc" is nested under the general term "properties". Nesting index terms can be very useful, when done properly. You should never nest terms more than 3 levels.

The following examples show how to index properly.

Bad Indexing Good Indexing Explanation
tables, constraints 16
tables, locking 18
tables, altering 17
tables, temporary 16
  constraints 16
  locking 18
  altering 17
  temporary 16
The primary entry is repeated unnecessarily. Combine all of the secondary entries under one primary entry.
XML operators 21, 22, 24, 30, 32, 33   
XML operators
  XMLEXISTS 21, 30   
  XMLPARSE 22, 32   
  XMLQUERY 24, 33   
  XMLSERIALIZE 24, 33   
An entry should have no more than two page references. Split the entry into logical secondary entries.
  ACOS 70
  ASIN 70
  ATAN 71
  FLOOR 82
  CEIL 75
  LOG 86
  ACOS 70
  ASIN 70
  ATAN 71
  CEIL 75
  FLOOR 82
  LOG 86
Entries that are capitalized and worded inconsistently appear as separate entries, even though they are related. Make the primary entries consistent (in this case, plural, non-capitalized) so that all of the secondary entries appear under one primary entry.

Customizing tables in the Derby documentation

How do I specify the widths of each column in the table? You can specify the column widths by using the colwidth attribute in the <colspec> tag. The <colspec> tag appears just after the <tgroup> tag. When you use the colwidth attribute, You specify the percent that the column width should be of the total width of the table. If you want the column to be 25% of the total width of the table,you specify 25* in the colwidth attribute for that column.

For example:

<tgroup cols="3" colsep="1" rowsep="1">
<colspec colname="1" colwidth=25*">
<colspec colname="2" colwidth=25*>
<colspec colname="3" colwidth=50*>

How do I specify the alignment of the text in the header row? You can specify the heading aligment by using the align and valign attributes in the <entry> tag. Use the align attribute to specify horizontal alignment. Use the valign attribute to specify vertical alignment.

For example:

<entry align="left" colname="1" valign="bottom">Column Name</entry>
<entry align="left" colname="2" valign="bottom">Type</entry>
<entry align="left" colname="3" valign="bottom">Description</entry>

Valid settings for the align attribute are: left, right, center, justify.
Valid settings for the valign attribute are: top, middle, bottom.

Please post feedback to the derby-dev mail list.

Last Updated: March 19, 2007