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. Currently, we use version 4.3 of the DTD.

We process documents into various output formats such as HTML and PDF using the DocBook XSL stylesheets. Currently, we use version 1.69.1 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:

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.