Sometimes you know what you want to write, and you have all the words ready, but you can’t get the sentence started – you just don’t get it to flow. This is very frustrating and it can sometimes block the advance of your text for many minutes. And it’s all the more frustrating because you do know what you want to tell your readers, but you don’t seem to be able to produce a decent sentence. After many painful experiences of this kind, I’ve developed the following strategy (not that I think I’m the first):

This approach works well for me. So if you’re stuck in this way, try it out; hopefully it will help you too.

In order to release your work under the PDL, add an appendix titled License Notice, with this text:

Everything that looks LIKE THIS must of course be replaced. If you are not the original author, you should leave his or her notice intact and append the following:

There may be several Contributor’s sections in the License Notice.

If your contribution consists of more than a simple change or addition in one spot, also include an appendix called Document History before or after the License Notice. If such an appendix already exists, always enter a description of your modification(s) in it. Please note that even if there’s a Document History, you must still add a contributor’s section to the License Notice – but then you can fill in “see Document History” in place of the short description.

If you’re the original author, it’s also perfectly OK to include a Document History in the first version of a document, to serve as a starting point for future revisions. See the first revision element in the example below.

For AsciiDoc, see Including a Document History in AsciiDoc. For DocBook, see Including a Document History in DocBook.

Below is a Document History example (output view, not source!). Notice the referral to GitHub: we are legally obliged to identify and date all changes. But since git already does that, we can simply alert the user to it and give a less extensive but nicer-to-read history in the document itself.

License Notice and Document History both appear at the end of the document. If you want to make your copyright obvious right from the start, you may also include a short copyright notice in the document’s preamble.

For AsciiDoc, see A copyright notice at the start in AsciiDoc. For DocBOok, see A copyright notice at the start in DocBook.

Such a notice does not replace the License Notice and/or Document History – it’s an extra.

Instead of providing the URL, you can also attach the entire PDL to your document. This may especially be useful if your work is a book or long article and you expect (or hope) that people will print it and distribute hardcopies. On a short document the PDL may be a little heavy, but it’s your call.

You can get the PDL’s DocBook source from src/docs/firebirddocs/licenses.xml. Please note that only the section with the license text itself (including the generic license notice ) belongs to the PDL proper. The Introduction is not part of the license.

If you include the PDL in your document, you can fill in the blanks in section 5.2 of the license. But you may also leave them as they are (provided your name is in the License Notice) or just fill in “the Initial Writer” or “the Copyright holder”.

Translating a document is a form of modification. So, as a translator, you should:

For AsciiDoc, see Translator’s notices in AsciiDoc. For DocBook, see Translator’s notices in DocBook.

You don’t have to translate the PDL itself. But if you do:

You can optionally also attach the translated PDL to the document itself, if you don’t mind the extra load and bloat.

The Borland InterBase 6 beta docs – although free – are not part of the InterBase package that was open-sourced in July 2000. We have asked Borland several times if we could use these docs “as if they fell under the InterBase Public License”, but they didn’t even bother to answer. So feel free to use this documentation set as a source of information, but don’t copy text from it.

PostgreSQL is another major open source database, with (not surprisingly) many similarities to Firebird, but also many differences. Depending on the kind of documentation you are going to write, it may be beneficial to base it on existing PostgreSQL docs. Be aware though that if you use PostgreSQL material, you MUST include their copyright notice in your document!

The PostgreSQL documentation homepage is here:

https://www.postgresql.org/docs/

The most recent PostgreSQL license is currently at:

https://www.postgresql.org/about/licence

One nice thing about the PostgreSQL docs is that they are authored in DocBook, just like ours. However, they use DocBook SGML instead of XML, so some tweaking may be necessary. The DocBook SGML sources can be found here:

https://git.postgresql.org/gitweb/?p=postgresql.git;a=tree;f=doc/src;hb=HEAD

Or clone the entire Git tree, docs and all. For instructions, go to:

https://www.postgresql.org/docs/devel/static/sourcerepo.html

The DocBook build tools automatically name each file after the ID of the topmost DocBook element it contains. We don’t change the names of the multi-page HTML output – these pages are primarily intended for online browsing, and changing even a single file name would immediately break a number of links contained in the other pages. But PDFs are often downloaded by the reader, and having files called qsg2.pdf or ubusetup.pdf in a download directory or on one’s desktop doesn’t really help to identify them as Firebird manuals. So here are some guidelines for the file names:

To illustrate these guidelines, some of our existing file names are listed below:

We specifically want to highlight the line breaking convention: a single sentence per line, no line breaks within a sentence. If a line becomes too long, take that as a hint to rewrite (if possible).

Converted documentation may not always adhere to this style due to limitations of the converter. These style inconsistencies should only be addressed when touching a paragraph for other reasons.

Although Asciidoctor generates section IDs from a section title, we recommend specifying a custom ID for each section.

An ID should start with the docId of the document. We recommend making the id a summary abbreviation of the section title. To avoid ambiguity, it is advisable to also include information on the parent section when this makes sense.

An ID does not need to be language-specific, that is it does not need to include the language-code. For historic reasons, existing documents in languages other than English may include the language-code in their IDs. These IDs should not be changed to preserve backwards compatibility (for example with links).

You can define a custom ID using:

or

The second syntax offers more flexibility when you need to provide more options and attributes than just the ID.

AsciiDoctor allows you to define headings that are not part of the document outline (e.g. the TOC). See also Discrete Headings (aka Floating Titles). AsciiDoctor offers two roles to do this: float and discrete:

In the HTML output we generate the TOC dynamically using tocbot. Unfortunately, tocbot allows us to only exclude a single class from the selection of headings. To avoid the introduction of a separate custom role, we chose float as the role to use for these types of elements. Do not use the discrete role to prevent it from showing up in the HTML TOC generated by tocbot.

During conversion from DocBook to AsciiDoc, the conversion tool has applied semantic roles to styled inline elements, for example:

This applies emphasis on the text “processing instructions”, where the emphasis has the role “term”. Semantic roles can be used to apply custom styles (for inline elements in HTML and PDF, and for block elements only in HTML).

We currently do not use custom styling on custom roles, so in general, we recommend not to apply custom roles unless you have a clear need for additional styling. The additional mental overhead of deciding which roles to apply, or what they mean, is not worth the additional effort. However, leave existing roles in place unless you rewrite a specific paragraph and are sure the custom role is really unused.

For links to external sites (especially those outside of the firebirdsql.org domain), make sure the link opens to a new page in the HTML rendering.

This can be achieved by adding ^ at the end of the link title:

For more information see URLs in the Asciidoctor User Manual.

Store images per language in src/asciidoc/<language>/images. Put images shared by multiple documents in the root of this directory, images shared only in a specific base in src/asciidoc/<language>/images/<baseName>, and images for a specific document in src/asciidoc/<language>/images/<baseName>/<documentId>. In other words, the structure inside the images folder follows the structure inside the <language> folder for the documentation sources.

A document has to explicitly define the imagesdir location. Given the documentation structure, its value should normally be ../../images (so :imagesdir: ../../images). For deeper nested directory structures Explicitly defining this in each document allows for deviation from the defined structure if necessary.

Images linked from documents are — by default — relative to this directory.

The header of a (root) document has a document title, optional subtitle, optionally followed by additional metadata like authors, document revision and release date.

For an in-depth look at the document header, see Header in the Asciidoctor User Manual.

The document title can have an ID, just like normal sections. If the file is a root document, the ID should be equal to the docId (as identified by the parent directory name). Although not strictly necessary, adding this ID is helpful when a document might be included in another, aggregate, document.

This title information is followed by a list of attributes:

The header of a (root) document should normally include the following attributes:

For easy copying without the callouts:

The text immediately following the header, but before the first section is the preamble. The preamble can be used for additional copyright information, etc.

We recommend putting the toc::[] macro at the end of the preamble, so the preamble is rendered before the TOC in PDF documents.

For an in-depth look at the preamble, see Preamble in the Asciidoctor User Manual.

Following the preamble, you define the various parts (only available in doctype book) and sections.

For an in-depth look at sections, see Sections in the Asciidoctor User Manual.

See also Including a Document History

AsciiDoc itself doesn’t have special features for a document history. We use a simple table for this purpose:

The use of a| allows the full use of AsciiDoc syntax within the table cell. Apply this for all description cells, even if they are single line, to avoid rendering differences between rows.

Please abbreviate the month name in the date element, as the date column in the PDF output is rather narrow.

If you open the AsciiDoc source of an existing DocBook document (one of the .adoc files in src/docs/asciidoc) in your favourite editor, you can easily copy-and-paste the Document History and License Notice into your own document. Don’t copy the examples given above; copy the real appendices at the end of the document, and edit them to fit your work.

See also A copyright notice at the start

License Notice and Document History both appear at the end of the document. If you want to make your copyright obvious right from the start, you may also include a short copyright notice in the document’s preamble, like this:

Such a notice does not replace the License Notice and/or Document History – it’s an extra.

See also Translator’s notices,

Translating a document is a form of modification. So, as a translator, you should:

In the example given above, the words and phrases enclosed in angle brackets are the markup tags. <italics> is a start tag, </italics> is an end tag, and <picture file="bloody_hand.png" is a standalone tag, officially termed empty-element tag. XML tags are always formatted like this:

Still referring to our example, the words paragraph, loud, scary, italics and picture are tag names. In the <picture…​/> tag, file="bloody_hand.png" is called an attribute, with file the attribute name and bloody_hand.png the attribute value. Attribute values must always be quoted; both single and double quotes are allowed.

XML allows you to define any tags you like, as long as you build them correctly. So <thistag>, <thattag>, and <this_is_not_a_tag/> are all well-formed XML tags. (XML that follows the standard is called well-formed; the term valid is only used for specifically defined implementations – DocBook XML, for instance.)

Clearly the tags themselves are not meant to appear in the final document (that is, the document as it is presented to the readers). Rather, they contain instructions that affect its appearance. XML, when used for writing documentation, is a typical source format, intended to be processed by software to produce nicely formatted output documents. This processing is usually called rendering.

Some tags are unmistakably makeup instructions:

means of course that the words kept on creeping must be displayed or printed in italics. However,

is a little less obvious. Should the word No! appear in boldface? Or underlined? Or again in italics? Or maybe this text is going to be read out aloud by a speech synthesizer, and the <loud> tag instructs it to raise its voice? All these things are possible, and what’s more: often a single XML source document is converted into several different output formats – say, a PDF document, an HTML web page, and a sound file. This is called multichannel publishing. With multichannel publishing, <loud> may be translated to boldface for the PDF document; to a bold, red-colored font for the web page; and to a 50% volume increase for the synthesizer.

Looking at the other tags, <picture…​/> is obviously an instruction to insert the image bloody_hand.png into the document, and <scary>, well…​ this is even less clear then <loud>. Maybe the phrase between the <scary> tags has to drip with blood. Maybe frightening music must be played here. It all depends on the people who defined the tags, and the software they use to do the rendering.

The <paragraph> tag, finally, is a structural tag. It tells us something about the place that the lines have within the document’s internal hierarchy. In the final document, paragraphs may or may not be separated by empty lines. Again, that depends on the rendering software and possibly also on user-configurable options. Other structural tags one might think of are e.g. <chapter>, <section>, and <subdocument>.

Because the character “<” has a special meaning as the start of a tag, you can’t include it directly as a literal value. Instead, if you want your readers to see an opening angle bracket, you type this:

<

That’s an ampersand, followed by the letters l and t (for less than), followed by a semicolon. You can also use > (greater than) for the closing angle bracket “>”, but you don’t have to.

XML has lots of codes like this; they are called entities. Some represent characters, like < and ä (lower a with umlaut) and some serve totally different purposes. But they all start with an ampersand and end with a semicolon.

But wait a minute…​ if an ampersand marks the start of an entity, how do you include a literal ampersand in your text? Well, there’s an entity for that too:

&

So this line of XML:

will wind up in the final documents as:

Kernigan & Ritchie chose '<' as the less-than operator for C.

And here’s some good news: if you use a dedicated XML editor to author your document, you can probably just type “<” and “&” anywhere you want to use them as literals. The editor will make sure that they end up as < and & in the XML as it is saved to disk. You’ll find pointers to some XML/DocBook editors later in this guide.

There’s one more important XML concept you need to know about: the element. An element is the combination of a start tag, a matching end tag, and everything in between. This “everything in between” is called the element’s content, and it may include other elements. Elements are named after their tags, so we can talk about paragraph elements, italics elements etc.

This is an element:

This is also an element:

Empty-element tags constitute an element all by themselves. These elements can have no content of course, because they don’t have a pair of tags:

I’m stressing the element concept here because most documentation tends to speak of “chapter elements”, “title elements” etc. rather than “chapter tags” and “title tags”. The terms are often used interchangeably, but there are cases where it’s important to know the difference.

Good – that’s about all you need to know about XML. By now you should have a general idea of what an XML text looks like, what tags and elements are, and what they are for. As said earlier, the picture is oversimplified, but it’s good enough for our purposes.

It should also be understood that just writing away in plain, self-invented XML is pretty pointless unless you have processing software that understands your tags. How else are you going to turn your XML source into a nicely formatted, presentable document?

Fortunately, we don’t have to worry about developing our own element definitions and conversion software. There are a number of formalized XML types available, each defining a set of tags and, equally important, a set of rules on how to use them. DocBook XML is one of those types.

Important characteristics of DocBook – as opposed to “general” XML – are:

DocBook has a lot of advantages for anybody writing technical documentation. These are the most important ones for us:

Admittedly, none of these benefits is unique to DocBook. But DocBook has them all, and it’s widely supported. That makes it the perfect choice for our Firebird documentation.

Here are some links in case you want to find out more about DocBook:

If you know of some other great online resource, please let use know by posting a message to the firebird-devel list.

Files for the English user documentation set must be placed in the manual/src/docs/firebirddocs directory tree. Non-English docs go in trees like manual/src/docs/firebirddocs-fr, manual/src/docs/firebirddocs-es, etc.

Since January 2006 we have the possibility of creating additional base sets, the first one added being rlsnotes, the Release Notes set. The same logic applies here: English Release Notes stuff goes into manual/src/docs/rlsnotes, French into manual/src/docs/rlsnotes-fr, and so on.

Each of these directory trees – firebirddocs, firebirddocs-es, firebirddocs-nl, rlsnotes, rlsnotes-fr, etc. – houses a separate <set>, with one master document and any number of include files.

Sets, books, chapters, articles and top-level sections should always have an id attribute. Other elements may also have one. The id allows an element to be referenced from another part of the document, and even from another document in the set. Ids are not visible in the rendered docs (except in the HTML source text), but they are used to form the HTML file names.

All id attributes must be unique within the entire bookset. Note that the different language versions each live in their own set, so it’s OK to keep the original ids in a translation.

Within a book or article, all ids should start with the same lowercase word, e.g. usersguide, followed by a dash, followed by one or more other lowercase words. Examples are usersguide-intro and usersguide-download-install. This is not a DocBook requirement, but our own convention.

If you create a new set, or translate one, you must set the lang attribute on the root element:

This will ensure that the right captions are generated for notes, warnings etc., and that localized quotation marks are used. It’s also good practice to use this attribute on the individual docs, just in case they’re ever build out of the context of your set.

For English sets, the lang attribute is optional.

Sets, books, chapters, articles and sections must always have a title – either as a direct child, or within an xxxinfo element (see below). It is even legal to include it in both, but in that case the two titles must be the same. Unlike id, which is an attribute, title is an element. And unlike the id, the title will appear in the output docs.

If the title is long, you should add a titleabbrev element immediately after it, containing a shortened form of the title. The main reason for this is that each generated HTML page contains a so-called hierarchy bar or “you-are-here line” at the top and bottom. This bar shows all the steps from the topmost element (the set) down to the page you are on. The items are clickable so the bar doesn’t only give you an insight in where you are in the hierarchy, but it also lets you navigate up to the higher-level elements easily. It looks best if all the items fit on one line, so for each item the titleabbrev is shown if the element in question has one; if not, the title is used. The same strategy is followed for the outline in the PDF documents (that’s the navigation frame on the left).

If you write a book or an article, you must include a bookinfo or articleinfo element at the start. Inside it, you can put author information and more. Other xxxinfo elements exist, but you will rarely need them.

If the author is a company or other organisation, or a group you want to refer to as a collective, use corpauthor instead of author:

If there are several authors and you want to name them separately, create an author (or corpauthor) element for each of them and wrap them together in an authorgroup element – all within the xxxinfo element.

Section elements are a bit different from the rest in that there are two flavors of them:

You can add one or more appendix elements after the last chapter in a book, or after the last section in an article. Appendices can contain just about everything that a section can contain, including other sections.

The following example gives you an idea of how to structure your document:

Skip the rest of the elements subsections if you already know everything about DocBook elements.

DocBook versions 4.3 and up also allow you to fill a table the HTML way, with trs instead of rows, and td/th instead of entry elements. Why would you want to do that? There are two situations where it may be advantageous to use an HTML table:

An HTML table can’t have tgroups; you put the trs either directly in the table or in thead / tfoot / tbody elements which are direct children of the table. Also, it has a caption instead of a title. (An informaltable has neither caption nor title.)

Here is the source of an HTML table:

And here’s the result:

Not all HTML table elements and attributes are supported by our stylesheets. For instance, properties specified in col and colgroup elements won’t be picked up. Specify them in the td/th elements instead – or extend the stylesheets!

DocBook tables belong to a group called formal elements. Formal elements are included in automatically generated indices (list of tables, list of figures etc.); if a formal element doesn’t have an id attribute, the stylesheets assign one. The templates that generate the XSL-FO output (this is the intermediate stage for the PDF) also give each formal object the attribute keep-together.within-page="always" to prevent page breaks to occur within the object. This is usually fine, but what if the object doesn’t fit on one page? Until recently, we used Apache FOP 0.20.5 to render the XSL-FO output to PDF. This processor simply ignored the keep-together attribute if the object was too large. But the current version (0.93 or higher) always enforces it. The result is that if the object is too large, it is truncated (or wrecked in some other way) to make it fit on the page. This is a feature, not a bug, so there’s no use complaining about it.

There are two ways to work around this problem if a table grows too large to fit on a single page:

See also Including a Document History

Centerpiece of the Document History is the revhistory element with its children:

Please abbreviate the month name in the date element, as the date column in the PDF output is rather narrow.

If you open the DocBook source of an existing DocBook document (one of the .xml files in src/docs) in your favourite XML editor, you can easily copy-and-paste the Document History and License Notice into your own document. Don’t copy the examples given above; copy the real appendices at the end of the document, and edit them to fit your work.

See also A copyright notice at the start

License Notice and Document History both appear at the end of the document. If you want to make your copyright obvious right from the start, you may also include a short copyright notice in the document’s xxxinfo, like this:

Such a notice does not replace the License Notice and/or Document History – it’s an extra.

See also Translator’s notices,

Translating a document is a form of modification. So, as a translator, you should: