1<?xml version="1.0" encoding="utf-8"?>
2<!--
3   Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
4
5   Distributed under the Boost Software License, Version 1.0.
6   (See accompanying file LICENSE_1_0.txt or copy at
7   http://www.boost.org/LICENSE_1_0.txt)
8  -->
9<!DOCTYPE part PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
10  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
11<part xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook"
12     last-revision="$Date$">
13  <partinfo>
14    <author>
15      <firstname>Douglas</firstname>
16      <surname>Gregor</surname>
17    </author>
18
19    <copyright>
20      <year>2003</year>
21      <year>2004</year>
22      <year>2005</year>
23      <holder>Douglas Gregor</holder>
24    </copyright>
25
26    <legalnotice>
27      <para>Distributed under the Boost Software License, Version 1.0.
28      (See accompanying file LICENSE_1_0.txt or copy at
29      <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>).
30      </para>
31    </legalnotice>
32  </partinfo>
33
34  <title>The BoostBook Documentation Format</title>
35
36  <chapter id="boostbook.introduction">
37    <title>Introduction</title>
38
39    <para>The BoostBook documentation format is an extension of <ulink
40    url="http://www.docbook.org">DocBook</ulink>, an SGML- or
41    XML-based format for describing documentation. BoostBook augments
42    DocBook with semantic markup that aids in the documentation of C++
43    libraries, specifically the <ulink
44    url="http://www.boost.org">Boost C++ libraries</ulink>, by
45    providing the ability to express and refer to C++ constructs such
46    as namespaces, classes, overloaded functions, templates, and
47    specializations.</para>
48
49    <para>
50    BoostBook offers additional features more specific to its use for
51    documenting the <ulink url="http://www.boost.org">Boost C++
52    libraries</ulink>. These features are intended to eliminate or
53    reduce the need for duplication of information and to aid in
54    documenting portions of Boost that might otherwise not be
55    documented. Examples of Boost-centric features include:
56      <itemizedlist>
57        <listitem>
58          <para><emphasis role="bold">Testsuites</emphasis>:
59          Testsuites in Boost are created by writing an appropriate
60          Jamfile and including that Jamfile in
61          <filename>status/Jamfile</filename>. If the testsuites are
62          documented (<ulink
63          url="http://www.boost.org/libs/multi_array/doc/test_cases.html">as
64          in the MultiArray library</ulink>), the documentation is
65          maintained separately from the testcase Jamfile, leading to
66          duplication of information and the possibility of having the
67          documentation out of sync with the Jamfile. BoostBook
68          contains elements that describe a testsuite for both
69          purposes: the BoostBook stylesheets can generate
70          documentation for the testcases and also generate an
71          appropriate Jamfile to integrate the testcases with the
72          regression testing system.</para>
73        </listitem>
74        <listitem>
75          <para><emphasis role="bold">Example programs</emphasis>:
76          Example programs in documentation need to be duplicated in
77          testcases to ensure that the examples compile and execute
78          correctly. Keeping the two copies in sync is a tedious and
79          error-prone task. For instance, the following code snippet
80          persisted for six months:</para>
81<programlisting>
82std::cout &lt;&lt; f(5, 3) &gt;&gt; std::endl;
83</programlisting>
84          <para>The BoostBook format allows testcases to be generated
85          by weaving together program fragments from example programs
86          in the documentation. This capability is integrated with
87          testsuite generation so that example programs are normal
88          tests in BoostBook.</para>
89        </listitem>
90      </itemizedlist>
91    </para>
92  </chapter>
93
94  <chapter id="boostbook.getting.started">
95    <title>Getting Started</title>
96
97    <para>To use the Boost documentation tools, you will need several tools:</para>
98    <itemizedlist>
99      <listitem><simpara><command>xsltproc</command>:</simpara>
100        <itemizedlist>
101          <listitem>Windows with <ulink
102                       url="http://www.cygwin.com/">Cygwin</ulink>: select the libxml2 and libxslt packages.</listitem>
103          <listitem>Windows without Cygwin: Download the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary packages</ulink>
104            from Igor Zlatkovic. At the very least, you'll need iconv, zlib, libxml2 and libxslt.</listitem>
105          <listitem>Mac OS X with Fink: Get the <code>libxslt</code> package.</listitem>
106          <listitem>Mac OS X without Fink: <ulink url="http://www.zveno.com/open_source/libxml2xslt.html">Download the libxslt binaries</ulink></listitem>
107          <listitem>Any platform: <ulink
108                                     url="http://xmlsoft.org/XSLT/">libxslt source</ulink>.</listitem>
109        </itemizedlist>
110      </listitem>
111        <listitem><simpara><command>doxygen</command>:</simpara> Available from <ulink url="http://www.doxygen.org">http://www.doxygen.org</ulink></listitem>
112    </itemizedlist>
113
114    <section id="boostbook.setup.autounix">
115      <title>Automatic setup for Unix-like systems</title>
116
117      <para>BoostBook provides a nearly-automatic setup script. Once
118      you have downloaded and
119      installed <command>xsltproc</command>, <command>doxygen</command>,
120      and (optionally) <command>java</command>, the setup script can
121      download the required DocBook stylesheets, DocBook DTD, and
122      (when Java is enabled) Apache FOP for PDF output. It will then
123      configure Boost.Build version 2 to build BoostBook
124      documentation.</para>
125
126      <para>The script requires: <command>sh</command>,
127      <command>curl</command> and <command>gunzip</command>.
128      To perform the installation, execute the
129      script <command>tools/boostbook/setup_boostbook.sh</command>
130      from a directory where you would like the resulting XSL, DTD,
131      and Apache FOP installations to occur. </para>
132    </section>
133
134    <section id="boostbook.setup.manual">
135      <title>Manual setup for all systems</title>
136
137      <para>This section describes how to manually configure Boost
138      Boost version 2 (BBv@) for BoostBook. If you can use the
139      automatic setup script, you should. All configuration will
140      happen in the BBv2 user configuration file,
141      <filename>user-config.jam</filename>. If you do not have a copy
142      of this file in your home directory, you should copy the one
143      that resides in <code>tools/build/</code> to your home
144      directory. Alternatively, you can edit
145      <filename>tools/build/user-config.jam</filename> directly or
146      a site-wide <filename>site-config.jam</filename> file.</para>
147
148      <section id="boostbook.setup.xsltproc">
149        <title>Configuring <command>xsltproc</command></title>
150
151        <para>To configure <command>xsltproc</command> manually, you
152        will need to add a directive to
153        <filename>user-config.jam</filename> telling it where to find
154        <command>xsltproc</command>. If the program is in your path,
155        just add the following line to
156        <filename>user-config.jam</filename>:</para>
157
158<programlisting>using xsltproc ;</programlisting>
159
160        <para>If <command>xsltproc</command> is somewhere else, use
161        this directive, where <code>XSLTPROC</code> is the full
162        pathname to <command>xsltproc</command> (including
163        <command>xsltproc</command>):</para>
164
165<programlisting>using xsltproc : XSLTPROC ;</programlisting>
166      </section>
167
168      <section id="boostbook.setup.docbook">
169        <title>Configuring local DocBook XSL and DTD distributions</title>
170
171        <para>This section describes how to configure Boost.Build to
172        use local copies of the DocBook DTD and XSL stylesheets to
173        improve processing time. You will first need to download two
174        packages:
175
176        <itemizedlist>
177          <listitem><para>Norman Walsh's DocBook XSL stylesheets,
178          available at the <ulink
179          url="http://docbook.sourceforge.net">DocBook sourceforge
180          site</ulink>. Extract the DocBook XSL stylesheets to a
181          directory on your hard disk (which we'll refer to as the
182          <code>DOCBOOK_XSL_DIR</code>).</para>
183          </listitem>
184
185          <listitem><para>The DocBook DTD, available as a ZIP archive
186          at the <ulink
187          url="http://www.oasis-open.org/docbook/xml/4.2/">OASIS
188          DocBook site</ulink>. The package is called "DocBook XML
189          4.2". Extract the DocBook DTD to a directory on your hard
190          disk (which we'll refer to as the
191          <code>DOCBOOK_DTD_DIR</code>). You will want to extract this
192          archive in a subdirectory!</para></listitem>
193        </itemizedlist>
194        </para>
195
196        <para>Add the following directive telling BBv2 where to find
197        the DocBook DTD and XSL stylesheets:</para>
198
199        <programlisting>#  BoostBook configuration
200using boostbook
201  : DOCBOOK_XSL_DIR
202  : DOCBOOK_DTD_DIR
203  ;</programlisting>
204
205        <para>Whenever you change this directive, you will need to
206        remove the <code>bin.v2</code> directory that BBv2 generates.
207        This is due to longstanding bug we are trying to fix.</para>
208
209        <para>At this point, you should be able to build HTML
210        documentation for libraries that do not require Doxygen. To
211        test this, change into the directory <filename
212        class="directory">$BOOST_ROOT/libs/function/doc</filename> and
213        run the command <code>bjam</code>: it should produce HTML
214        documentation for the Boost.Function library in the
215        <code>html</code> subdirectory.</para>
216      </section>
217
218      <section id="boostbook.setup.doxygen">
219        <title>Configuring Doxygen for Documentation Extraction</title>
220
221        <para>Doxygen is required to build the documentation for
222        several Boost libraries. You will need a recent version of
223        <ulink url="http://www.doxygen.org">Doxygen</ulink> (most of
224        the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the
225        following directive to
226        <filename>user-config.jam</filename>:</para>
227
228        <programlisting>using doxygen : DOXYGEN ;</programlisting>
229
230        <para><filename>DOXYGEN</filename> should be replaced with the
231        name of the <command>doxygen</command> executable (with full
232        path name). If the right <command>doxygen</command> executable
233        can be found via the path, this parameter can be
234        omitted, e.g.</para>
235
236        <programlisting>using doxygen ;</programlisting>
237
238        <important>
239          <para>The relative order of declarations in
240          <filename>user-config.jam</filename> /
241          <filename>site-config.jam</filename> files is
242          significant. In particular, the <literal>using
243          doxygen</literal> line should come
244          <emphasis>after</emphasis> the <literal>using
245          boostbook</literal> declaration.
246          </para>
247        </important>
248      </section>
249
250      <section id="boostbook.setup.fop">
251      <title>Configuring Apache FOP</title>
252
253      <para>In order to generate PDF and PostScript output using
254      Apache FOP, you will need a <ulink
255      url="http://java.sun.com">Java interpreter</ulink> and <ulink
256      url="http://xml.apache.org/fop/download.html">Apache FOP</ulink>
257      (version 0.20.5 is best). Unpack Apache FOP to some
258      directory. The top level directory of the FOP tool should
259      contain a main script called <filename>fop.sh</filename> on Unix
260      and <filename>fop.bat</filename> on Windows. You need to specify
261      the location of that script and Java location to
262      Boost.Build. Add the following to your
263      <filename>user-config.jam</filename> or
264      <filename>site-config.jam</filename>:
265<programlisting>
266using fop : FOP_COMMAND
267          : JAVA_HOME
268          ;
269</programlisting> replacing
270      <code>FOP_COMMAND</code> with the full path to the FOP main script, and
271      replacing <code>JAVA_HOME</code> with the directory where Java is
272      installed. If the <envar>JAVA_HOME</envar> environment variable is
273      already set, you don't need to specify it above.
274      </para>
275
276      <para>
277        Proper generation of images in PDFs depends on the <ulink
278        url="http://java.sun.com/products/jimi/#">Jimi Image
279        Library</ulink>.  To get FOP to use Jimi, extract the
280        <filename>JimiProClasses.zip</filename> file from the Jimi SDK
281        and rename it—if on Windows, to
282        <filename>jimi-1.0.jar</filename>, or if on *nix, to
283        <filename>JimiProClasses.jar</filename>—and place it in the
284        <filename>lib/</filename> subdirectory of your FOP
285        installation.
286      </para>
287
288      <para>To test PDF generation, switch to the directory <filename
289      class="directory">$BOOST_ROOT/libs/function/doc</filename> and
290      execute the command <command>bjam pdf</command>. In the
291      absence of any errors, Apache FOP will be executed to transform
292      the XSL:FO output of DocBook into a PDF file.</para>
293    </section>
294  </section>
295
296  <section id="boostbook.setup.running">
297    <title>Running BoostBook</title>
298
299    <para>Once BoostBook has been configured, we can build some
300    documentation. First, change to the directory
301    <code>$BOOST_ROOT/doc</code> and remove (or make writable) the
302    <code>.html</code> files in
303    <code>$BOOST_ROOT/doc/html</code>. Then, run <code>bjam</code>
304    to build HTML documentation. You should see several
305    warnings like these while DocBook documentation is being built
306    from BoostBook documentation:</para>
307
308    <programlisting>Cannot find function named 'checked_delete'
309Cannot find function named 'checked_array_delete'
310Cannot find function named 'next'</programlisting>
311
312    <para>These warnings are emitted when the Boost documentation
313    tools cannot find documentation for functions, methods, or classes
314    that are referenced in the source, and are not harmful in any
315    way. Once Boost.Jam has completed its execution, HTML
316    documentation for Boost will be available in
317    <code>$BOOST_ROOT/doc/html</code>. You can also create HTML
318    documentation in a single (large!) HTML file with the command line
319    <code>bjam onehtml</code>, or Unix man pages with the command
320    line <code>bjam man</code>. The complete list of output
321    formats is listed in <xref
322    linkend="boostbook.output.formats"/>. Several output formats can
323    be passed to a single invocation of <code>bjam</code>, e.g.,
324    <code>bjam html man docbook</code> would generate HTML
325    (multiple files), man pages, and DocBook documentation.</para>
326
327    <table id="boostbook.output.formats">
328      <title>BoostBook Output Formats</title>
329      <tgroup cols="2">
330        <thead>
331          <row><entry>Format</entry><entry>Description</entry></row>
332        </thead>
333        <tbody>
334          <row>
335            <entry>html</entry>
336            <entry><simpara>HTML output (multiple files). This is the default</simpara></entry>
337          </row>
338          <row>
339            <entry>onehtml</entry>
340            <entry><simpara>HTML output in a single HTML file.</simpara></entry>
341          </row>
342          <row>
343            <entry>man</entry>
344            <entry><simpara>Unix man pages.</simpara></entry>
345          </row>
346          <row>
347            <entry>pdf</entry>
348            <entry><simpara>PDF. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
349          </row>
350          <row>
351            <entry>ps</entry>
352            <entry><simpara>Postscript. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
353          </row>
354          <row>
355            <entry>docbook</entry>
356            <entry><ulink url="http://www.docbook.org/">DocBook</ulink>.</entry>
357          </row>
358          <row>
359            <entry>fo</entry>
360            <entry><ulink url="http://www.w3.org/TR/xsl/">XSL Formatting Objects</ulink></entry>
361          </row>
362        </tbody>
363      </tgroup>
364    </table>
365    </section>
366
367    <section id="boostbook.setup.troubleshooting">
368      <title>Troubleshooting</title>
369
370      <para>The Boost documentation tools are still in their early phase of
371      development, and some things don't work as seamlessly as we would like
372      them to, yet. In particular, error messages can be somewhat
373      uninformative at times. If you find yourself in the situation when
374      you have double checked everything, and yet things still don't work as
375      expected, consider helping the tools by deleting
376      <literal>bin.v2</literal> build directory.
377      </para>
378
379    </section>
380  </chapter>
381
382  <xi:include href="documenting.xml"/>
383  <xi:include href="together.xml"/>
384  <xi:include href="reference.xml"/>
385</part>
386