Apache Derby: Writing FAQs
- Cross references: To another DITA topic in the same Derby manual
- Cross references: To a DITA topic in a different Derby manual
- Cross references: To a Web site
- Code Examples
- Semi-colon use at the end of statements and commands
- SQL terminology: When do I use the terms statement, clause, parameter, or expression?
Cross references: To another DITA topic in the same Derby manual
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.
Cross references: To a DITA topic in a different Derby manual
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.
Cross references: To a Web site
To create a cross reference to a Web site, use the xref tag. You must specify the type, href, and scope attributes.
<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:
- The example is easier to read if it is broken up into logical sections
- 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)) )
Semi-colon use at the end of statements and commands
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.
SQL terminology: When do I use the terms statement, clause, parameter, or expression?
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
Please post feedback to the derby-dev mail list.
Last Updated: March 19, 2007