From 086c2585ff7a293148902023d0979c6d4630c9ea Mon Sep 17 00:00:00 2001 From: Douglas Gregor Date: Sun, 23 Jan 2005 16:25:15 +0000 Subject: [PATCH] Working on BoostBook docs... [SVN r26822] --- doc/boostbook.xml | 213 +++++++++++++++++++++++----------------------- 1 file changed, 105 insertions(+), 108 deletions(-) diff --git a/doc/boostbook.xml b/doc/boostbook.xml index 7e20269..4905e6e 100644 --- a/doc/boostbook.xml +++ b/doc/boostbook.xml @@ -11,6 +11,8 @@ 2003 + 2004 + 2005 Douglas Gregor @@ -97,121 +99,43 @@ std::cout << f(5, 3) >> std::endl; Getting Started - To use the Boost documentation tools, you will need an - XSLT - processor. There are many XSLT processors available, but for now - we suggest that you use xsltproc, part of libxslt. There are several - ways to get libxslt, depending on your platform: - + To use the Boost documentation tools, you will need several tools: - - On Unix: Build and install libxml2 and then libxslt. Both - libraries are part of the GNOME project. - - - On Windows: - + xsltproc: - - With Cygwin, select the - libxml2 and libxslt packages - - - Without Cygwin, you need a patched version of the tools available from - - here. - - - - - On MacOS X: - - - - If you have Fink, just get the libxslt and doxygen packages. - Without Fink, you can download the libxslt binaries. - + Windows with Cygwin: select the libxml2 and libxslt packages. + Windows without Cygwin: Download packages + here. + Mac OS X with Fink: Get the libxslt package. + Mac OS X without Fink: Download the libxslt binaries + Any platform: libxslt source. + doxygen: Available from http://www.doxygen.org - You will also need a recent checkout of Boost from CVS. If - you would like to limit your network bandwidth or limit delays in - building documentation, now might be a good time to download the - DocBook DTD and XSL stylesheets as described in . You should delete or make - writable the .html files in - $BOOST_ROOT/doc/html before continuing. +
+ Automatic setup for Unix-like systems + + BoostBook provides a nearly-automatic setup script. Once + you have downloaded and + installed xsltproc, doxygen, + and (optionally) java, the setup script can + download the required DocBook stylesheets, DocBook DTD, and + (when Java is enabled) Apache FOP for PDF output. It will then + configure Boost.Build version 2 to build BoostBook + documentation. To perform the installation, execute the + script tools/boostbook/setup_boostbook.sh + from a directory where you would like the resulting XSL, DTD, + and Apache FOP installations to occur. +
- Now we can build some documentation. Change to the directory - $BOOST_ROOT/doc and 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' -Cannot find function named 'next' - - These warnings are emitted when the Boost documentation - tools cannot find documentation for functions, methods, or classes - that are referenced in the source, and are not harmful in any - way. Once Boost.Jam has completed its execution, HTML - documentation for Boost will be available in - $BOOST_ROOT/doc/html. You can also create HTML - documentation in a single (large!) HTML file with the command line - bjam --v2 onehtml, or Unix man pages with the command - line bjam --v2 man. The complete list of output - formats is listed in . Several output formats can - be passed to a single invocation of bjam, e.g., - bjam --v2 html man docbook would generate HTML - (multiple files), man pages, and DocBook documentation. - - - BoostBook Output Formats - - - FormatDescription - - - - html - HTML output (multiple files). This is the default - - - onehtml - HTML output in a single HTML file. - - - man - Unix man pages. - - - pdf - PDF. Requires Apache FOP. - - - ps - Postscript. Requires Apache FOP. - - - docbook - DocBook. - - - fo - XSL Formatting Objects - - - -
+
+ Manual setup for all systems + + Manual setup for TBD
Configuring local DocBook XSL and DTD distributions @@ -357,6 +281,79 @@ boostbook any : any.doxygen ; 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: + + Cannot find function named 'checked_delete' +Cannot find function named 'checked_array_delete' +Cannot find function named 'next' + + These warnings are emitted when the Boost documentation + tools cannot find documentation for functions, methods, or classes + that are referenced in the source, and are not harmful in any + way. Once Boost.Jam has completed its execution, HTML + documentation for Boost will be available in + $BOOST_ROOT/doc/html. You can also create HTML + documentation in a single (large!) HTML file with the command line + bjam --v2 onehtml, or Unix man pages with the command + line bjam --v2 man. The complete list of output + formats is listed in . Several output formats can + be passed to a single invocation of bjam, e.g., + bjam --v2 html man docbook would generate HTML + (multiple files), man pages, and DocBook documentation. + + + BoostBook Output Formats + + + FormatDescription + + + + html + HTML output (multiple files). This is the default + + + onehtml + HTML output in a single HTML file. + + + man + Unix man pages. + + + pdf + PDF. Requires Apache FOP. + + + ps + Postscript. Requires Apache FOP. + + + docbook + DocBook. + + + fo + XSL Formatting Objects + + + +
+
Troubleshooting