diff --git a/doc/boostbook.xml b/doc/boostbook.xml index 818e009..99d6a12 100644 --- a/doc/boostbook.xml +++ b/doc/boostbook.xml @@ -230,6 +230,102 @@ Cannot find function named 'next' + +
+ Configuring Apache FOP for PostScript/PDF Output + + This section describes the steps required to configure + Apache + FOP to generate PostScript and PDF output for BoostBook + documents. To begin, you will need two pieces of software: + + A Java interpreter, available at . + Apache FOP, available at . + + + + Once Java is installed (we'll call Java's directory + JAVA_HOME) and Apache FOP has been extracted into a + directory (we'll call FOP's directory FOP_DIR), we + need to configure Boost.Build to use FOP. Edit your + user-config.jam or + site-config.jam and add the following, + replacing FOP_DIR with the directory where Apache + FOP is installed, and replace JAVA_HOME with the + directory where Java is installed: + +using fop : FOP_DIR + : JAVA_HOME + ; + + In some cases, JAVA_HOME is optional, but it often + helps to specify it. + + 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. +
+ +
+ 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). This capability is under heavy development + (you've been warned). Requirements are: + + Doxygen from CVS, described at + My monolithic XML file patch to Doxygen CVS, available at + + + + Once you have a checkout of Doxygen from CVS, apple the + monolithic XML file patch and rebuild Doxygen. Next, we + configure Boost.Build 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. + + 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. + +