From cd42b0c19c773fde6e856d260c4184df8da1871d Mon Sep 17 00:00:00 2001 From: Douglas Gregor Date: Mon, 24 Jan 2005 02:13:05 +0000 Subject: [PATCH] Updated documentation [SVN r26827] --- doc/boostbook.xml | 281 ++++++++++++++++++++++------------------------ 1 file changed, 136 insertions(+), 145 deletions(-) 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'
-