4.2 Document-Writing Conventions

Most of our documents are written using DocBook, a dialect of XML. We use the following conventions:

  • Our DocBook source files use UTF-8 encoding, so they begin with an XML prolog that looks like this:

    <?xml version="1.0" encoding="utf-8"?>
  • We validate documents against the DocBook DTD. At the time of writing this (2012), we use version 4.5 of the DTD.

  • We process documents into various output formats such as HTML and PDF using the DocBook XSL stylesheets. At the time of writing this (2012), we use version 1.77.0 of the stylesheets. For some output formats not supported by the DocBook stylesheets, we have implemented the necessary transforms by writing our own stylesheets. The DocBook-to-Texinfo transform is one of these.

  • Generally, we set up each document in its own directory. The content for a short document usually is written in a single DocBook file. For larger documents, we use XInclude so that we can modularize content using multiple XML files. The usual modularization unit is the chapter, so the document consists of a main document file that refers to other parts of the document using XInclude directives.

    Sometimes the files for a document are located in multiple directories. This occurs when two or more documents need to share files. In that case, we put the shared files in their own directory. Examples:

    • There are several versions of the Reference Manual, all of which use files from the refman-common directory.

  • Each document has an info section that includes certain standard elements: Markup that causes the current date and revision number to be inserted into formatted output, a legal notice, copyright information, and (for translated documents) a disclaimer that points out that the translation might not be as up to date as the English version.

  • If a document uses images, they'll usually be located in an images directory under the document directory. If multiple documents share images, they'll be located in the images directory under the directory that holds shared files.

  • Each document directory contains a Makefile that provides the make target rules for document-processing operations such as validating the document or producing formatted output from it.