boost_mirror/boostbook
1
0
Fork 0
mirror of https://github.com/boostorg/boostbook.git synced 2025-05-09 15:03:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added sections on Apache FOP and Doxygen

Browse Source 
[SVN r18100]
This commit is contained in:
Douglas Gregor 2003-03-27 05:18:39 +00:00
parent add1fe71fb
commit 849d01f41d
1 changed files with 96 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
doc/boostbook.xml
View File

@ -230,6 +230,102 @@ Cannot find function named 'next'</programlisting>
</tbody>
</tgroup>
</table>
<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"/>.</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&amp;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"/>