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' formulas).
• An FO processor, either Apache FOP from ​http://xmlgraphics.apache.org/fop/ or XEP Personal edition from ​http://www.renderx.com/download/personal.html (Optional, required only for building PDF's).
• A Java runtime (Optional, required for the FO procesors).

The overall toolchain setup looks like this:

Windows

First, you need to get the boost build tools set up, see the getting started guide for an introduction.

• Create directory for boost tools, say c:\boost-tools.
• Create directory for binaries, say c:\boost-tools\bin.
• Add to path.
• xml tools from ​Igor Zlatkovic. Require: iconv, libxml2 and libxslt, zlib.

Make directory for xml files, say c:\boost-tools\xml.

• ​Norman Walsh's DocBook XSL stylesheets from their ​Sourceforge download page to c:\boost-tools\xml\docbook-xsl.
• ​The DocBook DTD to c:\boost-tools\xml\docbook-xml.

user-config.jam in the boost build search path, for most people this will be C:\Documents and Settings\username.

using xsltproc
    : "C:/boost-tools/bin/xsltproc.exe"
    ;

using boostbook
    : "C:/boost-tools/xml/docbook-xsl"
    : "C:/boost-tools/xml/docbook-xml"
    ;

If you want to build the complete documentation, you'll also need to install:

• ​Doxygen
• ​MikTeX - select the version under 'Download' in the left column, the basic installer should be fine.
• ​Ghostscript - click on the latest version of 'GPL Ghostscript', there should be a link for the latest self extracting download near the bottom.

The bin directories of these tools needs to be added to the path. I think Doxygen and MikTex's installers do this for you, but ghostscript's doesn't.

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"
    ;

using doxygen ;
using quickbook ;

Cygwin

First, you need to get the boost build tools set up. bjam will need to be built using cygwin, so don't use the prebuilt windows binary.

Cygwin packages:

• Libs/libxml2
• Libs/libxslt
• Text/docbook-xml42
• Text/docbook-xsl
• Devel/gcc4-g++
• Devel/doxygen (optional, used for several libraries)
• Text/tetex-extra (optional, used for the accumulators library documentation)
• Graphics/ghostscript (optional, also used for the accumulators library documentation)

Build bjam:

1. cd tools/src
2. ./build.sh
3. copy file (bin.cygwinx86/bjam.exe) to path

user-config.jam:

using gcc : 4 : /usr/bin/g++-4 ;

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

I'm not sure about any of this...

• Doxygen has an OS X download.
• xsltproc is included with OS X, but is too old, ​binaries are available. I haven't tried them yet.
• Need to install docbook manually.
• ​MacTex

(Alternatively use macports or fink?)

Macports

(I'm working on this, so just assorted notes for now).

Doxygen doesn't compile on tiger at the moment: ​http://trac.macports.org/ticket/18258 Texlive_base doesn't seem to compile with x11: ​http://trac.macports.org/ticket/18326

Which doesn't look very good. I think macports might be useful for gcc, xsl and docbook. For doxygen and latex, I think it might be best to use prebuilt packages from elsewhere.

To avoid installing x11:

sudo port install graphviz +no_x11
sudo port install texlive_base +no_x11

(or maybe just add +no_x11 to the command line). Formulas won't be anti-aliased - not suitable for production build.

sudo port install docbook-xml-4.2 docbook-xsl libxslt doxygen texlive

This takes a long time - in particular, texlive is a large download.

Macports has packages for boost-build and boost-jam but I think it might be best to manually install them, so that you're up to date.

On Tiger, you need to be using xsltproc from macport's libxslt as the one included in OS X is very old but it might not be needed on Leopard.

Leopard's version:

$ /usr/bin/xsltproc --version
Using libxml 20616, libxslt 10112 and libexslt 810
xsltproc was compiled against libxml 20616, libxslt 10112 and libexslt 810
libxslt 10112 was compiled against libxml 20616
libexslt 810 was compiled against libxml 20616

Macport's version:

$ /opt/local/bin/xsltproc --version
Using libxml 20703, libxslt 10124 and libexslt 813
xsltproc was compiled against libxml 20703, libxslt 10124 and libexslt 813
libxslt 10124 was compiled against libxml 20703
libexslt 813 was compiled against libxml 20703

I think we should recommend getting an up to date version.

user-config.jam:

using darwin ;
using doxygen ;
using boostbook
    : /opt/local/share/xsl/docbook-xsl/
    : /opt/local/share/xml/docbook/4.2
    ;

Debian/ubuntu

First, you need to get the boost build tools set up, see the getting started guide for an introduction. You can probably use the bjam package from your distribution.

sudo apt-get install xsltproc docbook-xsl docbook-xml

# Optional extras:
# TODO: What's the correct latex package?
sudo apt-get install 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
    ;

using quickbook ;

# Remove this line if you haven't installed doxygen
using doxygen ;

Pre-build quickbook

Quickbook is built automatically during the build process, but as it takes a little while to build you might prefer to build it in advance. To do this, in the command line type (replacing $BOOST_ROOT with the root directory of boost):

cd $BOOST_ROOT/tools/quickbook
bjam dist-bin

Or for windows:

cd $BOOST_ROOT\tools\quickbook
bjam dist-bin

Change using quickbook in user-config.jam to (replacing $BOOST_ROOT with the root directory of boost, as before):

using quickbook : $BOOST_ROOT/dist/bin/quickbook

Windows:

using quickbook : $BOOST_ROOT\\dist\\bin\\quickbook

How to build pdfs

First of all you will need an FO processor, there are basically only two free two choices here:

• Apache FOP from ​http://xmlgraphics.apache.org/fop/
• XEP Personal edition from ​http://www.renderx.com/download/personal.html

The XEP processor generally produces much better results, but inserts a small "built with XEP" advert in the footer of each page. You will also need a Java virtual machine to run the FO processor on.

You will then need to edit your user-config.jam file to point to the location of the FO processor, for example:

using fop :  
   # path to invocation batch file:
   C:/Progra~1/RenderX/xep/xep.bat
   :
   # path to Java installation, this is ignored if you're using XEP:
   C:/PROGRA~1/Java/j2re1.4.2_12 
   ;

You should now be able to build pdf docs via:

bjam pdf

Note: you may actually experience errors at this point if Java runs out of memory, whether or not this occurs depends on the complexity of the documentation being built and how you Java runtime is configured. One way to fix this error is to add the -Xmx option to the Java invocation command in the batch file that invokes the FO processor, for example -Xmx500m if you want to allow the FO processor to use 500MBytes of memory.

How to test your build setup

There is a set of test documentation that covers all the tools that can be used in the boost-root/doc/test directory.

Building this requires quickbook, doxygen, latex, dvips and ps as well as the basic Boostbook setup.

Useful Links

• ​DocBook XSL: The Complete Guide
• ​Docbook XSL Stylesheet Reference.
• ​Docbook, the Definitive Guide.