<?xml version="1.0" encoding="utf-8"?>
<!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: 2004/11/02 06:31:59 $">
  <partinfo>
    <author>
      <firstname>Douglas</firstname>
      <surname>Gregor</surname>
    </author>
    
    <copyright>
      <year>2003</year>
      <holder>Douglas Gregor</holder>
    </copyright>

    <legalnotice>
      <para>Permission to copy, use, sell and distribute this software
      is granted provided this copyright notice appears in all copies.
      Permission to modify the code and to distribute modified code is
      granted provided this copyright notice appears in all copies,
      and a notice that the code was modified is included with the
      copyright notice. </para>

      <para> This software is provided "as is" without express or
      implied warranty, and with no claim as to its suitability for
      any purpose. </para> 
    </legalnotice>
  </partinfo>

  <title>The BoostBook Documentation Format</title>

  <chapter>
    <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 &lt;&lt; f(5, 3) &gt;&gt; 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>
        <listitem>
          <para><emphasis role="bold">Library
          categorization</emphasis>: BoostBook contains primitives for
          placing libraries into categories and generating categorized
          and alphabetized lists of libraries.</para>
        </listitem>
      </itemizedlist>
    </para>
  </chapter>

  <chapter id="boostbook.getting.started">
    <title>Getting Started</title>

    <para>To use the Boost documentation tools, you will need an
    <ulink url="http://www.w3c.org/Style/XSL/">XSLT</ulink>
    processor. There are many XSLT processors available, but for now
    we suggest that you use <code>xsltproc</code>, part of <ulink
    url="http://xmlsoft.org/XSLT/">libxslt</ulink>. There are several
    ways to get libxslt, depending on your platform:</para>

    <itemizedlist>
      <listitem>
        <para>On Unix: Build and install <ulink
        url="http://xmlsoft.org/">libxml2</ulink> and then <ulink
        url="http://xmlsoft.org/XSLT/">libxslt</ulink>. Both
        libraries are part of the <ulink
        url="http://www.gnome.org">GNOME</ulink> project.</para>
      </listitem>
      <listitem>
        <para>On Windows:</para>

        <itemizedlist>
          <listitem>
            <para>With <ulink
            url="http://www.cygwin.com/">Cygwin</ulink>, select the
            libxml2 and libxslt packages</para>
          </listitem>
          <listitem>
            <para>Without Cygwin, you need a patched version of the tools available from 
            <ulink url="http://www.meta-comm.com/engineering/boost/xsltproc-win32.zip">
            here</ulink>.</para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>On MacOS X:</para> 

        <itemizedlist>
          <listitem>
            <para>If you have Fink, just get the <code>libxslt</code> and <code>doxygen</code> packages.</para>
            <para>Without Fink, you can <ulink url="http://www.zveno.com/open_source/libxml2xslt.html">download the libxslt binaries</ulink>.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>

    <para>You will also need a recent checkout of Boost from <ulink
    url="http://www.boost.org/more/download.html#CVS">CVS</ulink>. 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 <xref
    linkend="boostbook.docbook.config"/>. You should delete or make
    writable the <code>.html</code> files in
    <code>$BOOST_ROOT/doc/html</code> before continuing.</para>

    <para>Now we can build some documentation. Change to the directory
    <code>$BOOST_ROOT/doc</code> and run <code>bjam --v2</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 --v2 onehtml</code>, or Unix man pages with the command
    line <code>bjam --v2 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 --v2 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 id="boostbook.docbook.config">
      <title>Configuring local DocBook XSL and DTD distributions</title>
 
      <para>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:

      <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/index.shtml">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>).</para></listitem>
      </itemizedlist>
      </para>

      <para>In the directory <code>tools/build/v2</code> is a file
      named <filename>user-config.jam</filename>. 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 <code>DOCBOOK_XSL_DIR</code> and
      <code>DOCBOOK_DTD_DIR</code> with the paths of the DocBook XSL
      stylsheets and DTD, respectively:

<programlisting>#  BoostBook configuration
using boostbook : DOCBOOK_XSL_DIR
                : DOCBOOK_DTD_DIR
                ;</programlisting></para>   
      
      <para>Future invocations of <command>bjam</command> will use the
      specified local copies of the DTD and XSL stylesheets in lieu of
      downloading the same sources over the network.</para>
    </section>

    <section id="boostbook.fop">
      <title>Configuring Apache FOP for PostScript/PDF Output</title>

      <para>This section describes the steps required to configure
      <ulink url="http://xml.apache.org/fop/index.html">Apache
      FOP</ulink> to generate PostScript and PDF output for BoostBook
      documents. To begin, you will need two pieces of software:
        <itemizedlist> 
          <listitem><simpara>A Java interpreter, available at <ulink url="http://java.sun.com"/>.</simpara></listitem>
          <listitem><simpara>Apache FOP, available at <ulink url="http://xml.apache.org/fop/download.html"/>. Version 0.20.4 seems to be most stable.</simpara></listitem>
        </itemizedlist> 
      </para>
 
      <para>Once Java is installed (we'll call Java's directory
      <code>JAVA_HOME</code>) and Apache FOP has been extracted into a
      directory (we'll call FOP's directory <code>FOP_DIR</code>), we
      need to configure Boost.Build to use FOP. Edit your
      <filename>user-config.jam</filename> or
      <filename>site-config.jam</filename> and add the following,
      replacing <code>FOP_DIR</code> with the directory where Apache
      FOP is installed, and replace <code>JAVA_HOME</code> with the
      directory where Java is installed:

<programlisting>using fop : FOP_DIR
          : JAVA_HOME
          ;</programlisting>

      In some cases, <code>JAVA_HOME</code> is optional, but it often
      helps to specify it.</para>
    
      <para>To test PDF generation, switch to the directory <filename
      class="directory">$BOOST_ROOT/doc</filename> and execute the
      command <command>bjam --v2 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 id="boostbook.doxygen">
      <title>Configuring Doxygen for Documentation Extraction</title>
 
      <para>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 <ulink url="http://www.doxygen.org">Doxygen</ulink>; 1.2.18 or newer should suffice.</para>

      <para>Boost.Build can be configured for Doxygen support by editing
      <filename>user-config.jam</filename> or
      <filename>site-config.jam</filename> to add:

        <programlisting>using doxygen : DOXYGEN ;</programlisting>

      <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.</para>
      
      <important>
        <para>The relative order of declarations in 
        <filename>user-config.jam</filename> / <filename>site-config.jam</filename>
        files is significant. In particular, <literal>using doxygen</literal> 
        line should come <emphasis>after</emphasis> the
        <literal>using boostbook</literal> declaration.
        </para>
      </important>
      

      <para>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 <filename>Jamfile.v2</filename> illustrates a simple
      case of generating reference documentation for the
      <libraryname>Any</libraryname> library: </para>

      <programlisting>project boost/any/doc ;
import boostbook : boostbook ; 
import doxygen : doxygen ;

doxygen any.doxygen : ../../../boost/any.hpp ;
boostbook any : any.doxygen ;</programlisting>

      <para>In this example, we generate the Doxygen XML
      representation in the file <filename>any.doxygen</filename> from
      the source file <filename>../../../boost/any.hpp</filename> by
      invocing Doxygen. We then use <filename>any.doxygen</filename>
      as a source for the BoostBook target <code>any</code>, which
      will generate documentation in any format the user requests. The
      actual sequence of events in this transformation is:</para>
 
      <orderedlist>
        <listitem><simpara>Doxygen parses the header file <filename>../../../boost/any.hpp</filename> and outputs a single XML file <filename>any.doxygen</filename>.</simpara></listitem>
        <listitem><simpara>The XSLT processor applies the stylesheet <filename>doxygen2boostbook.xsl</filename> to transform <filename>any.doxygen</filename> into the BoostBook file <filename>any.xml</filename>.</simpara></listitem>
        <listitem><simpara>The XSLT processor applies the stylesheet <filename>docbook.xsl</filename> to transform <filename>any.xml</filename> into the DocBook XML document <filename>any.docbook</filename>.</simpara></listitem>
        <listitem><simpara>Further transformations may generate HTML, FO, PDF, etc. from <filename>any.docbook</filename>.</simpara></listitem>
      </orderedlist>
    </section>

    <section id="boostbook.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>
