mirror of
https://github.com/boostorg/boostbook.git
synced 2025-05-09 23:13:58 +00:00
edc06baa80
reference.xml: generated from reference.dtdxml reference_doc.xml: Useless now that we have reference.dtdxml boostbook.xml: Include reference.xml, not reference_doc.xml [SVN r18130]
355 lines
16 KiB
XML
355 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook"
|
|
last-revision="$Date$">
|
|
<chapterinfo>
|
|
<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>
|
|
</chapterinfo>
|
|
|
|
<title>The BoostBook Documentation Format</title>
|
|
|
|
<section>
|
|
<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>
|
|
<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>
|
|
</section>
|
|
|
|
<section 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 can at <ulink
|
|
url="http://www.zlatkovic.com/projects/libxml/binaries.html">download
|
|
the libxml2, libxslt, and iconv binaries</ulink>. Or, use
|
|
my <ulink
|
|
url="http://www.cs.rpi.edu/~gregod/boost/doc/xsltproc-win32.zip">minimal
|
|
repackaged version</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"/>.</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/new</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). This capability is under heavy development
|
|
(you've been warned). Requirements are:
|
|
<itemizedlist>
|
|
<listitem><simpara>Doxygen from CVS, described at <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#cvs"/></simpara></listitem>
|
|
<listitem><simpara>My monolithic XML file patch to Doxygen CVS, available at <ulink url="http://sourceforge.net/mailarchive/forum.php?thread_id=1886710&forum_id=1985"/></simpara></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>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
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<xi:include href="documenting.xml"/>
|
|
<xi:include href="together.xml"/>
|
|
<xi:include href="reference.xml"/>
|
|
</chapter> |