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.

See also Including a Document History in AsciiDoc.

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.

See also A copyright notice at the start in AsciiDoc.

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 AsciiDoc source from src/docs/asciidoc/licenses/pdl/public-documentation-license.adoc.

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:

See also Translator’s notices in AsciiDoc.

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

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.

For the Firebird Language Reference — starting with version 6.0 — an alternative convention is used for IDs, instead of the docId, it uses the “family-id” langref as the prefix of ids, except for the top-level id, which will be the docId (e.g. `fblangref60). See also 2025-01: Naming Convention Changes for Language Reference.

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:

This syntax offers more flexibility when you need to provide more options and attributes than just the ID compared to the alternative syntax:

We recommend using the first syntax, but initially we (and our converter) used this second syntax.

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>/<docId>. 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: