diff --git a/doc/boostbook.xml b/doc/boostbook.xml
index 4905e6e..9bc95fe 100644
--- a/doc/boostbook.xml
+++ b/doc/boostbook.xml
@@ -32,7 +32,7 @@
The BoostBook Documentation Format
-
+
Introduction
The BoostBook documentation format is an extension of
-
- Library
- categorization: BoostBook contains primitives for
- placing libraries into categories and generating categorized
- and alphabetized lists of libraries.
-
@@ -135,74 +129,134 @@ std::cout << f(5, 3) >> std::endl;
Manual setup for all systems
- Manual setup for TBD
+ This section describes how to manually configure Boost
+ Boost version 2 (BBv@) for BoostBook. If you can use the
+ automatic setup script, you should. All configuration will
+ happen in the BBv2 user configuration file,
+ user-config.jam. If you do not have a copy
+ of this file in your home directory, you should copy the one
+ that resides in tools/build/v2 to your home
+ directory. Alternatively, you can edit
+ tools/build/v2/user-config.jam directly or
+ a site-wide site-config.jam file.
-
- Configuring local DocBook XSL and DTD distributions
+
+ Configuring <command>xsltproc</command>
+
+ To configure xsltproc manually, you
+ will need to add a directive to
+ user-config.jam telling it where to find
+ xsltproc. If the program is in your path,
+ just add the following line to
+ user-config.jam:
+
+using xsltproc ;
+
+ If xsltproc is somewhere else, use
+ this directive, where XSLTPROC is the full
+ pathname to xsltproc (including
+ xsltproc):
+
+using xsltproc : XSLTPROC ;
+
+
+
+ Configuring local DocBook XSL and DTD distributions
- By default, the DocBook DTD and XSL stylesheets are
- accessed over a network automatically by the XSLT
- processor. However, these documents tend to be large and
- introduce a noticeable delay in the XSLT transformation
- step. This section describes how to configure Boost.Build to use
- local copies of the DocBook DTD and XSL stylesheets to improve
- processing time. There are a few requirements:
+ This section describes how to configure Boost.Build to
+ use local copies of the DocBook DTD and XSL stylesheets to
+ improve processing time. You will first need to download two
+ packages:
-
- Norman Walsh's DocBook XSL stylesheets,
- available at the DocBook sourceforge
- site. Extract the DocBook XSL stylesheets to a
- directory on your hard disk (which we'll refer to as the
- DOCBOOK_XSL_DIR).
-
+
+ Norman Walsh's DocBook XSL stylesheets,
+ available at the DocBook sourceforge
+ site. Extract the DocBook XSL stylesheets to a
+ directory on your hard disk (which we'll refer to as the
+ DOCBOOK_XSL_DIR).
+
- The DocBook DTD, available as a ZIP archive at
- the OASIS
- DocBook site. The package is called "DocBook XML
- 4.2". Extract the DocBook DTD to a directory on your hard disk
- (which we'll refer to as the
- DOCBOOK_DTD_DIR).
-
-
+ The DocBook DTD, available as a ZIP archive
+ at the OASIS
+ DocBook site. The package is called "DocBook XML
+ 4.2". Extract the DocBook DTD to a directory on your hard
+ disk (which we'll refer to as the
+ DOCBOOK_DTD_DIR). You will want to extract this
+ archive in a subdirectory!
+
+
- In the directory tools/build/v2 is a file
- named user-config.jam. Copy it to your home
- directory (or edit it in-place), and add a directive telling
- Boost.Build where to find the DocBook DTD and XSL stylesheets,
- replacing DOCBOOK_XSL_DIR and
- DOCBOOK_DTD_DIR with the paths of the DocBook XSL
- stylsheets and DTD, respectively:
+ Add the following directive telling BBv2 where to find
+ the DocBook DTD and XSL stylesheets:
-# BoostBook configuration
-using boostbook : DOCBOOK_XSL_DIR
- : DOCBOOK_DTD_DIR
- ;
+ # BoostBook configuration
+using boostbook
+ : DOCBOOK_XSL_DIR
+ : DOCBOOK_DTD_DIR
+ ;
+
+ Whenever you change this directive, you will need to
+ remove the bin.v2 directory that BBv2 generates.
+ This is due to longstanding bug we are trying to fix.
+
+ At this point, you should be able to build HTML
+ documentation for libraries that do not require Doxygen. To
+ test this, change into the directory $BOOST_ROOT/libs/function/doc and
+ run the command bjam --v2: it should produce HTML
+ documentation for the Boost.Function library in the
+ html subdirectory.
+
+
+
+ Configuring Doxygen for Documentation Extraction
+
+ Doxygen is required to build the documentation for
+ several Boost libraries. You will need a recent version of
+ Doxygen (most of
+ the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the
+ following directive to
+ user-config.jam:
+
+ using doxygen : DOXYGEN ;
+
+ DOXYGEN should be replaced with the
+ name of the doxygen executable (with full
+ path name). If the right doxygen executable
+ can be found via the path, this parameter can be
+ omitted, e.g.
+
+ using doxygen ;
- Future invocations of bjam will use the
- specified local copies of the DTD and XSL stylesheets in lieu of
- downloading the same sources over the network.
-
+
+ The relative order of declarations in
+ user-config.jam /
+ site-config.jam files is
+ significant. In particular, the using
+ doxygen line should come
+ after the using
+ boostbook declaration.
+
+
+
-
- Configuring PDF and PostScript Output
+
+ Configuring Apache FOP
- In order to generate PDF and PostScript output, you have to
- install two tools:
-
- A Java interpreter, available at .
- Apache FOP, available at . Version 0.20.4 seems to be most stable.
-
-
-
- Install the Java interpreter and then unpack Apache FOP to some
- directory. The top level directory of the FOP tool should contain a main
- script called fop.sh on Unix and
- fop.bat on Windows. You need to specify the
- location of that script and Java location to Boost.Build. Add the
- following to your user-config.jam or
- site-config.jam:
+ In order to generate PDF and PostScript output using
+ Apache FOP, you will need a Java interpreter and Apache FOP
+ (version 0.20.5 is best). Unpack Apache FOP to some
+ directory. The top level directory of the FOP tool should
+ contain a main script called fop.sh on Unix
+ and fop.bat on Windows. You need to specify
+ the location of that script and Java location to
+ Boost.Build. Add the following to your
+ user-config.jam or
+ site-config.jam:
using fop : FOP_COMMAND
: JAVA_HOME
@@ -215,86 +269,24 @@ using fop : FOP_COMMAND
To test PDF generation, switch to the directory $BOOST_ROOT/doc and execute the
- command bjam --v2 pdf. In the absence of any
- errors, Apache FOP will be executed to transform the XSL:FO
- output of DocBook into a PDF file.
+ class="directory">$BOOST_ROOT/libs/function/doc and
+ execute the command bjam --v2 pdf. In the
+ absence of any errors, Apache FOP will be executed to transform
+ the XSL:FO output of DocBook into a PDF file.
+
-
- Configuring Doxygen for Documentation Extraction
-
- This section details the steps necessary to use Doxygen to
- extract documentation and comments from source code to build a
- BoostBook document (and transform it into end-user
- documentation). You will need a somewhat recent version of Doxygen; 1.2.18 or newer should suffice.
+
+ Running BoostBook
- Boost.Build can be configured for Doxygen support by editing
- user-config.jam or
- site-config.jam to add:
-
- using doxygen : DOXYGEN ;
-
- DOXYGEN should be replaced with the name of
- the doxygen executable (with full path
- name). If the right doxygen executable can be
- found via the path, this parameter can be omitted.
-
-
- The relative order of declarations in
- user-config.jam / site-config.jam
- files is significant. In particular, using doxygen
- line should come after the
- using boostbook declaration.
-
-
-
-
- Generating of documentation from source files using
- Doxygen requires two steps. The first step involves identifying
- the source files so that Doxygen can process them. The second
- step is to specify that the output of this process, a file in
- the Doxygen XML format, is input for a BoostBook document. The
- following Jamfile.v2 illustrates a simple
- case of generating reference documentation for the
- Any library:
-
- project boost/any/doc ;
-import boostbook : boostbook ;
-import doxygen : doxygen ;
-
-doxygen any.doxygen : ../../../boost/any.hpp ;
-boostbook any : any.doxygen ;
-
- In this example, we generate the Doxygen XML
- representation in the file any.doxygen from
- the source file ../../../boost/any.hpp by
- invocing Doxygen. We then use any.doxygen
- as a source for the BoostBook target any, which
- will generate documentation in any format the user requests. The
- actual sequence of events in this transformation is:
-
-
- Doxygen parses the header file ../../../boost/any.hpp and outputs a single XML file any.doxygen.
- The XSLT processor applies the stylesheet doxygen2boostbook.xsl to transform any.doxygen into the BoostBook file any.xml.
- The XSLT processor applies the stylesheet docbook.xsl to transform any.xml into the DocBook XML document any.docbook.
- Further transformations may generate HTML, FO, PDF, etc. from any.docbook.
-
-
-
-
-
- Running BoostBook
-
- Once BoostBook has been configured, we can build some
- documentation. First, change to the
- directory $BOOST_ROOT/doc and remove (or make
- writable) the .html files
- in $BOOST_ROOT/doc/html. Then,
- run bjam --v2 to build HTML documentation. You
- should see several warnings like these while DocBook
- documentation is being built from BoostBook
- documentation:
+ Once BoostBook has been configured, we can build some
+ documentation. First, change to the directory
+ $BOOST_ROOT/doc and remove (or make writable) the
+ .html files in
+ $BOOST_ROOT/doc/html. Then, run bjam
+ --v2 to build HTML documentation. You should see several
+ warnings like these while DocBook documentation is being built
+ from BoostBook documentation:
Cannot find function named 'checked_delete'
Cannot find function named 'checked_array_delete'
@@ -355,7 +347,7 @@ Cannot find function named 'next'
-
+
Troubleshooting
The Boost documentation tools are still in their early phase of
@@ -368,7 +360,6 @@ Cannot find function named 'next'
-