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
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.