Apache Derby: Writing FAQs

To create a cross reference to another DITA topic in the same Derby manual, use the xref tag. You must specify the filename for the DITA topic, followed by the pound symbol and the ID specified inside the topic.

For example:

<xref href="rrefjdbc32052.dita#rrefjdbc32052"></xref>

Currently, you cannot create a cross reference to a DITA topic in a different Derby manual. However, you can create a citation to the other manual.

You specify the manual by using the cite and conref tags. If you mention the name of the topic, use quotations around the name of the topic. Here is an example:

For information about Derby properties, see the "derby.stream.error.logSeverityLevel property" topic 
in the <cite> <ph conref="refconrefs.dita#pub/cittuning"></ph> guide</cite> 
for instructions on how to print more information to Derby log files.

To create a cross reference to a Web site, use the xref tag. You must specify the type, href, and scope attributes.

For example:

<xref format="html" href="http://www.w3.org/TR/xpath" scope="external">http://www.w3.org/TR/xpath</xref>

When you have a long code example, it is a good idea to display the code over several lines. There are several reasons for this:

1. The example is easier to read if it is broken up into logical sections
2. In PDF output, a long code example might extend beyond the page borders and get truncated.

You should always use 4 spaces to indent the lines that are below the first line in the code example. Do not use tabs to indent. Tabs produce inconsistent output.

Here an example of a simple SQL statement:

SELECT * FROM flights 
    WHERE HOUR(departure_time) = 6 and MINUTE(departure_time) < 31  

Here an example of a more complex SQL statement:

CREATE TABLE x_table 
    ( id INT, 
    xcol XML CHECK (XMLEXISTS ('//student[@age < 25]' PASSING BY REF xcol))
    ) 

The semi-colon should be included only when you want to document an example statement that will be issued in ij. For example:

   ij> connect 'mydb'; 
   ij> select * from t1; 

If the example is just an example of how to use the syntax for a Derby SQL statement, the semi-colon should not be used. For example:

   select * from t1 

This issue was discussed on derby-dev in August 2006:
Documentation Style Issue - semi-colon at the end of SQL statement examples.

Statement should be used only for actual SQL statements, such as these statements:

   ALTER
   CREATE
   DELETE
   GRANT
   INSERT
   SELECT
   UPDATE

Clause should be used for parts of SQL statements, such as these clauses:

   FROM
   GROUP BY
   HAVING
   ORDER BY
   WHERE

Parameter should be used to describe SQL values that are being passed into and out of procedures.

Expression should be used for parts of SQL statements that return a value. For more information, see "SQL expressions" in the Derby Reference Manual