Chapter 1: Introduction

This is not a guide to be published – it's not even supposed to be built into PDF or HTML – but a collection of templates or skeletons that may come in handy when you're writing, translating or extending one of the Firebird Language Reference documents.

Each of the following chapters contains the section template that makes the most sense for the material covered in the chapter. The templates are not cast in concrete; feel free to drop, add or change elements if this improves the document. For instance, "Added in" makes no sense for items that were already present in InterBase. "Changed in" is nonsensical if the statement or feature has never been changed. But please remain consistent — within your document, but also, as much as possible, across our language reference documents.

Some guidelines for the language reference docs:

Always use formalpara elements if you alter the informational headers, or add new ones, at the top of the sections.
Wrap capitalized database terms in "database" elements throughout the text, except in programlisting blocks (Syntax, Example and Declaration).
If you give more than one example, put each one in its own programlisting within the same blockquote. You can insert para elements with explanatory text between the programlistings.
Once you're past the short headers (the last one is usually Description, except with external functions where it's Syntax), you can add free-text paras between and/or after the rest of the elements.
In the Syntax blocks, wrap placeholders in "replaceable" elements. For function arguments you may also use "parameter" elements. Either way they'll appear as italics in the output.
In the Syntax and Declaration blocks, use all-caps for SQL terms, and lower or mixed case for placeholders and comments.
In the Examples, use lower and mixed case.
The markup and capitalization of internal and external functions is PURPOSELY different. Internal functions are marked up in much the same way as database statements, underlining the fact that they are an integral part of the language. External functions (UDFs) have a more "programming language"-like appearance.
Quite often, a section dealing with a statement has a number of subsections, each one covering one aspect or subclause of that statement. In that case, you keep the headers that apply to the statement as a whole in the top section and move the others to the child sections. Some headers (especially Description, but Syntax is also a candidate) may occur in both the top section and the subsection(s).
If a feature is deprecated in or before the most recent version covered by the guide, create a "Deprecated since" header (remember to use a formalpara) and place it after "Added in" or "Changed in" (whichever is present and comes last).
If you've created a section from a template and you're left with some empty para elements when you're done, remove them. If they're part of a formalpara, remove the entire formalpara (including the title) after making sure you really don't need it.
Don't forget to give each chapter, section and table an id attribute.

In the chapters below, each template is given twice: once with some bogus data to show how it's supposed to be filled, and once completely empty for easy copying and pasting.

The templates are subject to change: they're currently based on the Firebird 1.5 Language Reference Update, but as we continue our work we may find that e.g. the full references need a different set of headers.