Firebird Docwriting Guide Paul Vinkenoog, Mark Rotteveel Version 2.2, 23 May 2020 Table of Contents Table of Contents General . 4 1. Introduction . 5 1.1. Purpose of this guide . 5 1.2. Assumed knowledge . 5 1.3. Topics discussed in this guide . 5 2. Where the docmakers meet. 7 2.1. The subproject homepage . 7 2.2. The firebird-docs list . 7 3. Picking a subject. 8 4. Preparing to write: make an outline! . 9 5. Language and style . 10 5.1. Language . 10 5.2. Style . 10 5.2.1. Docwriter’s block . 11 6. Copyright issues . 12 6.1. Your copyright and the PDL. 12 6.1.1. How to apply the PDL to your work. 12 6.1.2. Including a Document History . 13 6.1.3. A copyright notice at the start . 14 6.1.4. Attaching the entire Public Documentation License . 14 6.1.5. Translator’s notices . 15 6.1.6. Translating the PDL . 15 6.2. Using material written by others . 15 6.2.1. Borland InterBase manuals . 16 6.2.2. PostgreSQL docs . 16 7. Adding your document to the firebird-documentation repository . 17 7.1. Asking for commit rights . 17 7.2. Dos and don’ts if you have received commit rights. 17 7.3. Committing your work . 18 8. Publishing your document on the Firebird website . 20 8.1. Naming the PDF file. 20 8.1.1. Naming DocBook generated PDF files . 20 8.2. Uploading the documentation . 21 8.3. Updating the Firebird Documentation Index . 22 AsciiDoc and Asciidoctor . 23 9. AsciiDoc and Asciidoctor — an introduction. 24 9.1. What is AsciiDoc. 24 9.2. What is Asciidoctor . 24 1 Table of Contents 9.3. Where to get more information? . 24 9.4. Firebird documentation AsciiDoc code style. 25 9.4.1. Linebreaks . 25 9.4.2. Section IDs . 25 9.4.3. Float vs discrete headings . 26 9.4.4. Custom roles . 26 9.4.5. Links . 27 10. AsciiDoc authoring tools . 28 11. Setting up your AsciiDoc doc . 29 11.1. Project layout . 29 11.1.1. Images. 31 11.2. Start of a document . 32 11.2.1. Document header. 32 11.2.2. Document preamble . 33 11.2.3. Document parts and sections . 34 12. Frequently used AsciiDoc . 35 12.1. Your copyright and the PDL in AsciiDoc. 35 12.1.1. Including a Document History in AsciiDoc . 35 12.1.2. A copyright notice at the start in AsciiDoc . ..