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 letter that indicates the type of topic: r=reference, c=concept, t=task
- 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 - Several letters that indicate a category of information
- 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: |
| 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".
<table> |
| 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> <dlentry> <dt> <dd> |
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: |
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: 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: |
| 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:
<prolog>
<metadata>
<keywords>
<indexterm>CREATE TABLE</indexterm>
</keywords>
</metadata>
</prolog>
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:
<indexterm>parameters<indexterm>abc</indexterm></indexterm>
The output appears like this:
parameters abc
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 |
tables 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. |
functions ACOS 70 ASIN 70 ATAN 71 DEGREES 81 FLOOR 82 Function CEIL 75 CEILING 75 LOG 86 |
functions ACOS 70 ASIN 70 ATAN 71 CEIL 75 CEILING 75 DEGREES 81 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:
<thead>
<row>
<thead>
<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>
</row>
</thead>
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