Documentation sources for Docbook are maintained in doc/*/*.xml files. For the ones that require preprocessing to insert examples, the primary source files are doc/*/*.in. We have our own preprocessing stage to update and insert examples into XML sources before they are processed.

List of tools you'll need to build documentation

These package names can be passed directly to 'apt-get install' for Ubuntu or Debian.

• python-epydoc
• jade
• openjade
• tetex-bin
• tetex-latex
• texlive-latex-extra
• jadetex ?
• docbook
• docbook-doc
• docbook-dsssl
• docbook-to-man
• docbook-utils
• docbook-xml
• docbook-xsl
• docbook2x
• man2html

[GaryOberbrunner 15-Jul-12] As of Ubuntu 10.04, some of the above pkgs don't exist. These do:

• apt-get install python-epydoc jade openjade texinfo texlive-latex-extra jadetex docbook docbook-dsssl docbook-to-man docbook-utils docbook-xml docbook-xsl docbook2x man2html

and the doc seems to build OK with those packages (and their dependencies).

Not strictly doc-related, but if you're doing release builds, you also need rpm if you're on a non-RedHat/CentOS machine:

• apt-get install rpm

Steps to update or add content to the User Guide

1. Edit the doc/user/file.in
2. python bin/scons-doc.py --diff file
3. Review the diffs introduced by your changes, and proceed if they look correct
4. python bin/scons-doc.py --update file
5. python bootstrap.py doc
6. Review the generated documents in build/doc/html/scons-user.html (and .ps and .pdf)
7. Submit patch for review

Future work

1. Make documentation building process cross-platform
2. Cut the amount of tools and dependencies (preferably to Python modules)

Behind the curtain

The following image depicts the single steps of a full build for the documentation. The first (and zeroth) column shows the required tools (= dependencies) for each section (= second column).