Apache Derby: Documenting messages

-The Derby documentation is sourced in DITA. The tagging used with DITA is -similar to HTML tagging. This page contains 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

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 @@ -161,15 +169,33 @@

Tagging guidelines

Understanding DITA tags

The following table lists the proper tags to use for the most common -features within the Derby topics. If you are not certain which tags to use, +

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 section describes these tags and provides tagging examples. +

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

- + + + +

Tagging examples

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

@@ -179,21 +205,230 @@ + + + + + + + + + + + + + + + + + + - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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: + + + <ul> + <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> + </ul> + + +
Index entries	<indexterm>	See the section below for Indexing guidelines.	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> +<tgroup cols="3" colsep="1" rowsep="1"> +<colspec colname="1"> +<colspec colname="2"> +<colspec colname="3"> +<thead> +<row> +<entry colname="1">Column Name</entry> +<entry colname="2">Type</entry> +<entry colname="3">Description</entry> +</row> +</thead> +<tbody> +<row> +<entry colname="1">CONSTRAINTID</entry> +<entry colname="2">CHAR</entry> +<entry colname="3">Unique identifier for the constraint</entry> +</row> +<row> +<entry colname="1">CHECKDEFINITION</entry> +<entry colname="2">LONG VARCHAR</entry> +<entry colname="3">Text of check constraint definition</entry> +</row> +</tbody> +</tgroup> +</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. + + + + +
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. + + +
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: + + +<dl> +<dlentry> +<dt>server</dt> +<dd>The name of the machine where the server is running.</dd> +</dlentry> +<dlentry> +<dt>port</dt> +<dd>The port that the server is listening to.</dd> +</dlentry> +<dlentry> +<dt>databaseName</dt> +<dd>The name of the database that you are connecting to. </dd> +</dlentry> +</dl> + + + +
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

@@ -203,39 +438,42 @@

What tags do I use to index terms? In Derby, the index -entries are inserted -inside the <prolog> tag. The <prolog> tag is +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> +

+<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: +the new term inside the keywords tag. +

+For example:
+
<indexterm>CREATE TABLE</indexterm> -

-How do I add an index term? Add the <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>>
+<indexterm>parameters<indexterm>abc</indexterm></indexterm>

The output appears like this:

@@ -352,21 +590,70 @@ 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. +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. +

Apache Derby: Documenting messages

+Error and warning messages are documented in the Derby Reference Manual. +When you add internationalized messages to the Derby engine, add the messages to +the xml descriptors file that is located in ..java/engine/org/apache/derby/loc/messages.xml. +Specify friendly names for the message arguments. The friendly names appear in the SQLState tables in +the Derby Reference Manual. Valid friendly names are: +

+ +

authorizationID

+ +

columnName

+ +

constraintName

+ +

databaseName

+ +

indexName

+ +

objectName

+ +

tableName

+ +

triggerName

+ +

valueName

+ +

viewName

+ +

+Do not edit the java/engine/apache/derby/loc/messages.xml file. This file +has been removed from code management and is now generated from +messages.xml during the Derby build.

A utility takes the content of the ..java/engine/org/apache/derby/loc/messages.xml +file, and updates the topic in the Derby Reference Manual that lists all of the +messages. That topic is rrefexcept71493.dita. +

+Please post feedback to the +derby-dev mail list. +

+Last Updated: November 2, 2006 +

Feature	Tag to use	Comments
Paragraphs +	]]>	A paragraph tag is used for a block of text that contains a single main idea. + + +
Index entries	]]>	See the section below for Indexing guidelines.
Bulleted lists (also known as unordered lists)	]]> and ]]>	The list starts with the ]]> tag. For each bullet that you want in the list, use a ]]> 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: + + ]]> + ]]>This is an item in an unordered list.]]> + ]]>To separate it from other items in the list, the formatter puts a bullet beside it.]]> + ]]>This is the last list item in our unordered list.]]> + ]]> + +
Tables	]]>	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". + +]]> +]]> +]]> +]]> +]]> +]]> +]]> +]]>Column Name]]> +]]>Type]]> +]]>Description]]> +]]> +]]> +]]> +]]> +]]>CONSTRAINTID]]> +]]>CHAR]]> +]]>Unique identifier for the constraint]]> +]]> +]]> +]]>CHECKDEFINITION]]> +]]>LONG VARCHAR]]> +]]>Text of check constraint definition]]> +]]> +]]> +]]> +]]> + +
Index entries	]]>	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	]]>	Use the ]]> 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. + + +
Links to external sites	]]>	Use the cross-reference ]]> 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: + ]]>Derby Documentation]]> + + + 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	]]>	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 ]]>rollback]]> + call from your application. + +
Definition lists	]]> + ]]> + ]]> + ]]>	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: + +]]> +]]> +]]>server]]> +]]>The name of the machine where the server is running.]]> +]]> +]]> +]]>port]]> +]]>The port that the server is listening to.]]> +]]> +]]> +]]>databaseName]]> +]]>The name of the database that you are connecting to. ]]> +]]> +]]> + +
Notes	]]>	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 ]]> 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 + ]]> You can override the default locale for ij with a + property on the JVM.]]> + + + produces this result: + + + Tip: You can override the default locale for ij with a property on the JVM. + +