I'm going to try to write a better getting started guide for the boost documentation tools, outside of the individual tools' documentation. Just a very rough outline to start with. This will be of only limited scope - full documentation will be in the tools' documentation.

How to build boost documentation

Required packages (see below for platform specific instructions).

• bjam
• xsltproc
• ​Norman Walsh's DocBook XSL stylesheets
• ​The DocBook DTD
• doxygen (optional for writing your own, but required for several libraries' documentation).
• latex (optional for writing your own, but required for Boost.Accumulators' formulae)

TODO

Windows

It might be easier to use Cygwin (see below).

Build bjam and add to path

Unpack under a single directory, such as C:/Users/example/Documents/boost/ (maybe bjam could be included in the same directory structure....):

• xml tools from ​Igor Zlatkovic. Require: iconv, zlib, libxml2 and libxslt.
• ​Norman Walsh's DocBook XSL stylesheets
• ​The DocBook DTD

Also install:

• Doxygen.
• ​ProTeXt?, ghostscript?

user-config.jam:

using xsltproc
    : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
    ;

using boostbook
    : "C:/Users/example/Documents/boost/xml/docbook-xsl"
    : "C:/Users/example/Documents/boost/xml/docbook-xml"
    ;

Cygwin

Cygwin packages:

• Libs/libxml2
• Libs/libxslt
• Devel/doxygen
• Text/docbook-xml42
• Text/docbook-xsl
• Text/tetex-extra (for accumulators, I'm not sure if this is the right one?)
• Graphics/ghostscript

Build bjam

user-config.jam:

using xsltproc ;

using boostbook
    : /usr/share/docbook-xsl
    : /usr/share/xml/docbook/4.2
    ;

using doxygen ;
using quickbook ;

Unix with automatic script

TODO

OS X

• Doxygen has an OS X download.
• xsltproc is included with OS X, but might be a little old, ​binaries are available.
• Need to install docbook manually.
• ​MacTex

(Alternatively use macports or fink?)

Debian/ubuntu

# TODO: What's the correct latex package?
sudo apt-get install xsltproc docbook-xsl docbook-xml doxygen texlive-full

Add to user-config.jam:

using xsltproc ;

using boostbook
    : /usr/share/xml/docbook/stylesheet/nwalsh
    : /usr/share/xml/docbook/schema/dtd/4.2
    ;

# Remove this line if you're not using doxygen
using doxygen ;
using quickbook ;

Pre-build quickbook

TODO

How to build pdfs

TODO

DocUtils

Some of the documentation uses python docutils, but I don't think it should be included with the main getting started documentation, as that is complicated enough. And unfortunately the docutils toolset doesn't support the debian package layout, so it would ruin the almost automatic installation & maintenance. Hopefully cygwin will fare better.