| <?xml version="1.0" encoding="utf-8"?> |
| <!-- |
| Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> |
| |
| Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file LICENSE_1_0.txt or copy at |
| http://www.boost.org/LICENSE_1_0.txt) |
| --> |
| <!DOCTYPE part PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
| "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
| <part xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook" |
| last-revision="$Date: 2010-07-19 19:29:09 -0400 (Mon, 19 Jul 2010) $"> |
| <partinfo> |
| <author> |
| <firstname>Douglas</firstname> |
| <surname>Gregor</surname> |
| </author> |
| |
| <copyright> |
| <year>2003</year> |
| <year>2004</year> |
| <year>2005</year> |
| <holder>Douglas Gregor</holder> |
| </copyright> |
| |
| <legalnotice> |
| <para>Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file LICENSE_1_0.txt or copy at |
| <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>). |
| </para> |
| </legalnotice> |
| </partinfo> |
| |
| <title>The BoostBook Documentation Format</title> |
| |
| <chapter id="boostbook.introduction"> |
| <title>Introduction</title> |
| |
| <para>The BoostBook documentation format is an extension of <ulink |
| url="http://www.docbook.org">DocBook</ulink>, an SGML- or |
| XML-based format for describing documentation. BoostBook augments |
| DocBook with semantic markup that aids in the documentation of C++ |
| libraries, specifically the <ulink |
| url="http://www.boost.org">Boost C++ libraries</ulink>, by |
| providing the ability to express and refer to C++ constructs such |
| as namespaces, classes, overloaded functions, templates, and |
| specializations.</para> |
| |
| <para> |
| BoostBook offers additional features more specific to its use for |
| documenting the <ulink url="http://www.boost.org">Boost C++ |
| libraries</ulink>. These features are intended to eliminate or |
| reduce the need for duplication of information and to aid in |
| documenting portions of Boost that might otherwise not be |
| documented. Examples of Boost-centric features include: |
| <itemizedlist> |
| <listitem> |
| <para><emphasis role="bold">Testsuites</emphasis>: |
| Testsuites in Boost are created by writing an appropriate |
| Jamfile and including that Jamfile in |
| <filename>status/Jamfile</filename>. If the testsuites are |
| documented (<ulink |
| url="http://www.boost.org/libs/multi_array/doc/test_cases.html">as |
| in the MultiArray library</ulink>), the documentation is |
| maintained separately from the testcase Jamfile, leading to |
| duplication of information and the possibility of having the |
| documentation out of sync with the Jamfile. BoostBook |
| contains elements that describe a testsuite for both |
| purposes: the BoostBook stylesheets can generate |
| documentation for the testcases and also generate an |
| appropriate Jamfile to integrate the testcases with the |
| regression testing system.</para> |
| </listitem> |
| <listitem> |
| <para><emphasis role="bold">Example programs</emphasis>: |
| Example programs in documentation need to be duplicated in |
| testcases to ensure that the examples compile and execute |
| correctly. Keeping the two copies in sync is a tedious and |
| error-prone task. For instance, the following code snippet |
| persisted for six months:</para> |
| <programlisting> |
| std::cout << f(5, 3) >> std::endl; |
| </programlisting> |
| <para>The BoostBook format allows testcases to be generated |
| by weaving together program fragments from example programs |
| in the documentation. This capability is integrated with |
| testsuite generation so that example programs are normal |
| tests in BoostBook.</para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </chapter> |
| |
| <chapter id="boostbook.getting.started"> |
| <title>Getting Started</title> |
| |
| <para>To use the Boost documentation tools, you will need several tools:</para> |
| <itemizedlist> |
| <listitem><simpara><command>xsltproc</command>:</simpara> |
| <itemizedlist> |
| <listitem>Windows with <ulink |
| url="http://www.cygwin.com/">Cygwin</ulink>: select the libxml2 and libxslt packages.</listitem> |
| <listitem>Windows without Cygwin: Download the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary packages</ulink> |
| from Igor Zlatkovic. At the very least, you'll need iconv, zlib, libxml2 and libxslt.</listitem> |
| <listitem>Mac OS X with Fink: Get the <code>libxslt</code> package.</listitem> |
| <listitem>Mac OS X without Fink: <ulink url="http://www.zveno.com/open_source/libxml2xslt.html">Download the libxslt binaries</ulink></listitem> |
| <listitem>Any platform: <ulink |
| url="http://xmlsoft.org/XSLT/">libxslt source</ulink>.</listitem> |
| </itemizedlist> |
| </listitem> |
| <listitem><simpara><command>doxygen</command>:</simpara> Available from <ulink url="http://www.doxygen.org">http://www.doxygen.org</ulink></listitem> |
| </itemizedlist> |
| |
| <section id="boostbook.setup.autounix"> |
| <title>Automatic setup for Unix-like systems</title> |
| |
| <para>BoostBook provides a nearly-automatic setup script. Once |
| you have downloaded and |
| installed <command>xsltproc</command>, <command>doxygen</command>, |
| and (optionally) <command>java</command>, 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.</para> |
| |
| <para>The script requires: <command>sh</command>, |
| <command>curl</command> and <command>gunzip</command>. |
| To perform the installation, execute the |
| script <command>tools/boostbook/setup_boostbook.sh</command> |
| from a directory where you would like the resulting XSL, DTD, |
| and Apache FOP installations to occur. </para> |
| </section> |
| |
| <section id="boostbook.setup.manual"> |
| <title>Manual setup for all systems</title> |
| |
| <para>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, |
| <filename>user-config.jam</filename>. If you do not have a copy |
| of this file in your home directory, you should copy the one |
| that resides in <code>tools/build/v2</code> to your home |
| directory. Alternatively, you can edit |
| <filename>tools/build/v2/user-config.jam</filename> directly or |
| a site-wide <filename>site-config.jam</filename> file.</para> |
| |
| <section id="boostbook.setup.xsltproc"> |
| <title>Configuring <command>xsltproc</command></title> |
| |
| <para>To configure <command>xsltproc</command> manually, you |
| will need to add a directive to |
| <filename>user-config.jam</filename> telling it where to find |
| <command>xsltproc</command>. If the program is in your path, |
| just add the following line to |
| <filename>user-config.jam</filename>:</para> |
| |
| <programlisting>using xsltproc ;</programlisting> |
| |
| <para>If <command>xsltproc</command> is somewhere else, use |
| this directive, where <code>XSLTPROC</code> is the full |
| pathname to <command>xsltproc</command> (including |
| <command>xsltproc</command>):</para> |
| |
| <programlisting>using xsltproc : XSLTPROC ;</programlisting> |
| </section> |
| |
| <section id="boostbook.setup.docbook"> |
| <title>Configuring local DocBook XSL and DTD distributions</title> |
| |
| <para>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: |
| |
| <itemizedlist> |
| <listitem><para>Norman Walsh's DocBook XSL stylesheets, |
| available at the <ulink |
| url="http://docbook.sourceforge.net">DocBook sourceforge |
| site</ulink>. Extract the DocBook XSL stylesheets to a |
| directory on your hard disk (which we'll refer to as the |
| <code>DOCBOOK_XSL_DIR</code>).</para> |
| </listitem> |
| |
| <listitem><para>The DocBook DTD, available as a ZIP archive |
| at the <ulink |
| url="http://www.oasis-open.org/docbook/xml/4.2/">OASIS |
| DocBook site</ulink>. 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 |
| <code>DOCBOOK_DTD_DIR</code>). You will want to extract this |
| archive in a subdirectory!</para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para>Add the following directive telling BBv2 where to find |
| the DocBook DTD and XSL stylesheets:</para> |
| |
| <programlisting># BoostBook configuration |
| using boostbook |
| : DOCBOOK_XSL_DIR |
| : DOCBOOK_DTD_DIR |
| ;</programlisting> |
| |
| <para>Whenever you change this directive, you will need to |
| remove the <code>bin.v2</code> directory that BBv2 generates. |
| This is due to longstanding bug we are trying to fix.</para> |
| |
| <para>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 <filename |
| class="directory">$BOOST_ROOT/libs/function/doc</filename> and |
| run the command <code>bjam</code>: it should produce HTML |
| documentation for the Boost.Function library in the |
| <code>html</code> subdirectory.</para> |
| </section> |
| |
| <section id="boostbook.setup.doxygen"> |
| <title>Configuring Doxygen for Documentation Extraction</title> |
| |
| <para>Doxygen is required to build the documentation for |
| several Boost libraries. You will need a recent version of |
| <ulink url="http://www.doxygen.org">Doxygen</ulink> (most of |
| the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the |
| following directive to |
| <filename>user-config.jam</filename>:</para> |
| |
| <programlisting>using doxygen : DOXYGEN ;</programlisting> |
| |
| <para><filename>DOXYGEN</filename> should be replaced with the |
| name of the <command>doxygen</command> executable (with full |
| path name). If the right <command>doxygen</command> executable |
| can be found via the path, this parameter can be |
| omitted, e.g.</para> |
| |
| <programlisting>using doxygen ;</programlisting> |
| |
| <important> |
| <para>The relative order of declarations in |
| <filename>user-config.jam</filename> / |
| <filename>site-config.jam</filename> files is |
| significant. In particular, the <literal>using |
| doxygen</literal> line should come |
| <emphasis>after</emphasis> the <literal>using |
| boostbook</literal> declaration. |
| </para> |
| </important> |
| </section> |
| |
| <section id="boostbook.setup.fop"> |
| <title>Configuring Apache FOP</title> |
| |
| <para>In order to generate PDF and PostScript output using |
| Apache FOP, you will need a <ulink |
| url="http://java.sun.com">Java interpreter</ulink> and <ulink |
| url="http://xml.apache.org/fop/download.html">Apache FOP</ulink> |
| (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 <filename>fop.sh</filename> on Unix |
| and <filename>fop.bat</filename> on Windows. You need to specify |
| the location of that script and Java location to |
| Boost.Build. Add the following to your |
| <filename>user-config.jam</filename> or |
| <filename>site-config.jam</filename>: |
| <programlisting> |
| using fop : FOP_COMMAND |
| : JAVA_HOME |
| ; |
| </programlisting> replacing |
| <code>FOP_COMMAND</code> with the full path to the FOP main script, and |
| replacing <code>JAVA_HOME</code> with the directory where Java is |
| installed. If the <envar>JAVA_HOME</envar> environment variable is |
| already set, you don't need to specify it above. |
| </para> |
| |
| <para> |
| Proper generation of images in PDFs depends on the <ulink |
| url="http://java.sun.com/products/jimi/#">Jimi Image |
| Library</ulink>. To get FOP to use Jimi, extract the |
| <filename>JimiProClasses.zip</filename> file from the Jimi SDK |
| and rename it—if on Windows, to |
| <filename>jimi-1.0.jar</filename>, or if on *nix, to |
| <filename>JimiProClasses.jar</filename>—and place it in the |
| <filename>lib/</filename> subdirectory of your FOP |
| installation. |
| </para> |
| |
| <para>To test PDF generation, switch to the directory <filename |
| class="directory">$BOOST_ROOT/libs/function/doc</filename> and |
| execute the command <command>bjam pdf</command>. In the |
| absence of any errors, Apache FOP will be executed to transform |
| the XSL:FO output of DocBook into a PDF file.</para> |
| </section> |
| </section> |
| |
| <section id="boostbook.setup.running"> |
| <title>Running BoostBook</title> |
| |
| <para>Once BoostBook has been configured, we can build some |
| documentation. First, change to the directory |
| <code>$BOOST_ROOT/doc</code> and remove (or make writable) the |
| <code>.html</code> files in |
| <code>$BOOST_ROOT/doc/html</code>. Then, run <code>bjam</code> |
| to build HTML documentation. You should see several |
| warnings like these while DocBook documentation is being built |
| from BoostBook documentation:</para> |
| |
| <programlisting>Cannot find function named 'checked_delete' |
| Cannot find function named 'checked_array_delete' |
| Cannot find function named 'next'</programlisting> |
| |
| <para>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 |
| <code>$BOOST_ROOT/doc/html</code>. You can also create HTML |
| documentation in a single (large!) HTML file with the command line |
| <code>bjam onehtml</code>, or Unix man pages with the command |
| line <code>bjam man</code>. The complete list of output |
| formats is listed in <xref |
| linkend="boostbook.output.formats"/>. Several output formats can |
| be passed to a single invocation of <code>bjam</code>, e.g., |
| <code>bjam html man docbook</code> would generate HTML |
| (multiple files), man pages, and DocBook documentation.</para> |
| |
| <table id="boostbook.output.formats"> |
| <title>BoostBook Output Formats</title> |
| <tgroup cols="2"> |
| <thead> |
| <row><entry>Format</entry><entry>Description</entry></row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>html</entry> |
| <entry><simpara>HTML output (multiple files). This is the default</simpara></entry> |
| </row> |
| <row> |
| <entry>onehtml</entry> |
| <entry><simpara>HTML output in a single HTML file.</simpara></entry> |
| </row> |
| <row> |
| <entry>man</entry> |
| <entry><simpara>Unix man pages.</simpara></entry> |
| </row> |
| <row> |
| <entry>pdf</entry> |
| <entry><simpara>PDF. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry> |
| </row> |
| <row> |
| <entry>ps</entry> |
| <entry><simpara>Postscript. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry> |
| </row> |
| <row> |
| <entry>docbook</entry> |
| <entry><ulink url="http://www.docbook.org/">DocBook</ulink>.</entry> |
| </row> |
| <row> |
| <entry>fo</entry> |
| <entry><ulink url="http://www.w3.org/TR/xsl/">XSL Formatting Objects</ulink></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </section> |
| |
| <section id="boostbook.setup.troubleshooting"> |
| <title>Troubleshooting</title> |
| |
| <para>The Boost documentation tools are still in their early phase of |
| development, and some things don't work as seamlessly as we would like |
| them to, yet. In particular, error messages can be somewhat |
| uninformative at times. If you find yourself in the situation when |
| you have double checked everything, and yet things still don't work as |
| expected, consider helping the tools by deleting |
| <literal>bin.v2</literal> build directory. |
| </para> |
| |
| </section> |
| </chapter> |
| |
| <xi:include href="documenting.xml"/> |
| <xi:include href="together.xml"/> |
| <xi:include href="reference.xml"/> |
| </part> |