Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/boostbook/getting/started.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 17.0 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Getting Started</title>
5<link rel="stylesheet" href="../../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../../boostbook.html" title="Chapter 22. The BoostBook Documentation Format">
9<link rel="prev" href="../../boostbook.html" title="Chapter 22. The BoostBook Documentation Format">
10<link rel="next" href="../documenting.html" title="Documenting libraries">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
15<td align="center"><a href="../../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="../../boostbook.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../../boostbook.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../documenting.html"><img src="../../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="boostbook.getting.started"></a>Getting Started</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="started.html#boostbook.setup.autounix">Automatic setup for Unix-like systems</a></span></dt>
30<dt><span class="section"><a href="started.html#boostbook.setup.manual">Manual setup for all systems</a></span></dt>
31<dt><span class="section"><a href="started.html#boostbook.setup.running">Running BoostBook</a></span></dt>
32<dt><span class="section"><a href="started.html#boostbook.setup.troubleshooting">Troubleshooting</a></span></dt>
33</dl></div>
34<p>To use the Boost documentation tools, you will need several tools:</p>
35<div class="itemizedlist"><ul type="disc">
36<li>
37<p><span><strong class="command">xsltproc</strong></span>:</p>
38<div class="itemizedlist"><ul type="circle">
39<li>Windows with <a href="http://www.cygwin.com/" target="_top">Cygwin</a>: select the libxml2 and libxslt packages.</li>
40<li>Windows without Cygwin: Download packages <a href="http://www.meta-comm.com/engineering/boost/xsltproc-win32.zip" target="_top">
41              here</a>.</li>
42<li>Mac OS X with Fink: Get the <code class="computeroutput">libxslt</code> package.</li>
43<li>Mac OS X without Fink: <a href="http://www.zveno.com/open_source/libxml2xslt.html" target="_top">Download the libxslt binaries</a>
44</li>
45<li>Any platform: <a href="http://xmlsoft.org/XSLT/" target="_top">libxslt source</a>.</li>
46</ul></div>
47</li>
48<li>
49<p><span><strong class="command">doxygen</strong></span>:</p> Available from <a href="http://www.doxygen.org" target="_top">http://www.doxygen.org</a>
50</li>
51</ul></div>
52<div class="section" lang="en">
53<div class="titlepage"><div><div><h3 class="title">
54<a name="boostbook.setup.autounix"></a>Automatic setup for Unix-like systems</h3></div></div></div>
55<p>BoostBook provides a nearly-automatic setup script. Once
56      you have downloaded and
57      installed <span><strong class="command">xsltproc</strong></span>, <span><strong class="command">doxygen</strong></span>,
58      and (optionally) <span><strong class="command">java</strong></span>, the setup script can
59      download the required DocBook stylesheets, DocBook DTD, and
60      (when Java is enabled) Apache FOP for PDF output. It will then
61      configure Boost.Build version 2 to build BoostBook
62      documentation. To perform the installation, execute the
63      script <span><strong class="command">tools/boostbook/setup_boostbook.sh</strong></span>
64      from a directory where you would like the resulting XSL, DTD,
65      and Apache FOP installations to occur. </p>
66</div>
67<div class="section" lang="en">
68<div class="titlepage"><div><div><h3 class="title">
69<a name="boostbook.setup.manual"></a>Manual setup for all systems</h3></div></div></div>
70<div class="toc"><dl>
71<dt><span class="section"><a href="started.html#boostbook.setup.xsltproc">Configuring <span><strong class="command">xsltproc</strong></span></a></span></dt>
72<dt><span class="section"><a href="started.html#boostbook.setup.docbook">Configuring local DocBook XSL and DTD distributions</a></span></dt>
73<dt><span class="section"><a href="started.html#boostbook.setup.doxygen">Configuring Doxygen for Documentation Extraction</a></span></dt>
74<dt><span class="section"><a href="started.html#boostbook.setup.fop">Configuring Apache FOP</a></span></dt>
75</dl></div>
76<p>This section describes how to manually configure Boost
77      Boost version 2 (BBv2) for BoostBook. If you can use the
78      automatic setup script, you should. All configuration will
79      happen in the BBv2 user configuration file,
80      <code class="filename">user-config.jam</code>. If you do not have a copy
81      of this file in your home directory, you should copy the one
82      that resides in <code class="computeroutput">tools/build/v2</code> to your home
83      directory. Alternatively, you can edit
84      <code class="filename">tools/build/v2/user-config.jam</code> directly or
85      a site-wide <code class="filename">site-config.jam</code> file.</p>
86<div class="section" lang="en">
87<div class="titlepage"><div><div><h4 class="title">
88<a name="boostbook.setup.xsltproc"></a>Configuring <span><strong class="command">xsltproc</strong></span></h4></div></div></div>
89<p>To configure <span><strong class="command">xsltproc</strong></span> manually, you
90        will need to add a directive to
91        <code class="filename">user-config.jam</code> telling it where to find
92        <span><strong class="command">xsltproc</strong></span>. If the program is in your path,
93        just add the following line to
94        <code class="filename">user-config.jam</code>:</p>
95<pre class="programlisting">using xsltproc ;</pre>
96<p>If <span><strong class="command">xsltproc</strong></span> is somewhere else, use
97        this directive, where <code class="computeroutput">XSLTPROC</code> is the full
98        pathname to <span><strong class="command">xsltproc</strong></span> (including
99        <span><strong class="command">xsltproc</strong></span>):</p>
100<pre class="programlisting">using xsltproc : XSLTPROC ;</pre>
101</div>
102<div class="section" lang="en">
103<div class="titlepage"><div><div><h4 class="title">
104<a name="boostbook.setup.docbook"></a>Configuring local DocBook XSL and DTD distributions</h4></div></div></div>
105<p>This section describes how to configure Boost.Build to
106        use local copies of the DocBook DTD and XSL stylesheets to
107        improve processing time. You will first need to download two
108        packages:
109
110        </p>
111<div class="itemizedlist"><ul type="disc">
112<li><p>Norman Walsh's DocBook XSL stylesheets,
113          available at the <a href="http://docbook.sourceforge.net" target="_top">DocBook sourceforge
114          site</a>. Extract the DocBook XSL stylesheets to a
115          directory on your hard disk (which we'll refer to as the
116          <code class="computeroutput">DOCBOOK_XSL_DIR</code>).</p></li>
117<li><p>The DocBook DTD, available as a ZIP archive
118          at the <a href="http://www.oasis-open.org/docbook/xml/4.2/index.1.shtml" target="_top">OASIS
119          DocBook site</a>. The package is called "DocBook XML
120          4.2". Extract the DocBook DTD to a directory on your hard
121          disk (which we'll refer to as the
122          <code class="computeroutput">DOCBOOK_DTD_DIR</code>). You will want to extract this
123          archive in a subdirectory!</p></li>
124</ul></div>
125<p>
126        </p>
127<p>Add the following directive telling BBv2 where to find
128        the DocBook DTD and XSL stylesheets:</p>
129<pre class="programlisting">#  BoostBook configuration
130using boostbook
131  : DOCBOOK_XSL_DIR
132  : DOCBOOK_DTD_DIR
133  ;</pre>
134<p>Whenever you change this directive, you will need to
135        remove the <code class="computeroutput">bin.v2</code> directory that BBv2 generates.
136        This is due to longstanding bug we are trying to fix.</p>
137<p>At this point, you should be able to build HTML
138        documentation for libraries that do not require Doxygen. To
139        test this, change into the directory <code class="filename">$BOOST_ROOT/libs/function/doc</code> and
140        run the command <code class="computeroutput">bjam</code>: it should produce HTML
141        documentation for the Boost.Function library in the
142        <code class="computeroutput">html</code> subdirectory. This documentation
143        will look a little strange, because the BoostBook stylesheet is
144        missing. You can copy the <code class="computeroutput">boostbook.css</code> stylesheet from
145        <code class="filename">$BOOST_ROOT/doc/html</code> to
146        fix this problem.</p>
147</div>
148<div class="section" lang="en">
149<div class="titlepage"><div><div><h4 class="title">
150<a name="boostbook.setup.doxygen"></a>Configuring Doxygen for Documentation Extraction</h4></div></div></div>
151<p>Doxygen is required to build the documentation for
152        several Boost libraries. You will need a recent version of
153        <a href="http://www.doxygen.org" target="_top">Doxygen</a> (most of
154        the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the
155        following directive to
156        <code class="filename">user-config.jam</code>:</p>
157<pre class="programlisting">using doxygen : DOXYGEN ;</pre>
158<p><code class="filename">DOXYGEN</code> should be replaced with the
159        name of the <span><strong class="command">doxygen</strong></span> executable (with full
160        path name). If the right <span><strong class="command">doxygen</strong></span> executable
161        can be found via the path, this parameter can be
162        omitted, e.g.</p>
163<pre class="programlisting">using doxygen ;</pre>
164<div class="important"><table border="0" summary="Important">
165<tr>
166<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../images/important.png"></td>
167<th align="left">Important</th>
168</tr>
169<tr><td align="left" valign="top"><p>The relative order of declarations in
170          <code class="filename">user-config.jam</code> /
171          <code class="filename">site-config.jam</code> files is
172          significant. In particular, the <code class="literal">using
173          doxygen</code> line should come
174          <span class="emphasis"><em>after</em></span> the <code class="literal">using
175          boostbook</code> declaration.
176          </p></td></tr>
177</table></div>
178</div>
179<div class="section" lang="en">
180<div class="titlepage"><div><div><h4 class="title">
181<a name="boostbook.setup.fop"></a>Configuring Apache FOP</h4></div></div></div>
182<p>In order to generate PDF and PostScript output using
183      Apache FOP, you will need a <a href="http://java.sun.com" target="_top">Java interpreter</a> and <a href="http://xml.apache.org/fop/download.html" target="_top">Apache FOP</a>
184      (version 0.20.5 is best). Unpack Apache FOP to some
185      directory. The top level directory of the FOP tool should
186      contain a main script called <code class="filename">fop.sh</code> on Unix
187      and <code class="filename">fop.bat</code> on Windows. You need to specify
188      the location of that script and Java location to
189      Boost.Build. Add the following to your
190      <code class="filename">user-config.jam</code> or
191      <code class="filename">site-config.jam</code>:
192</p>
193<pre class="programlisting">
194using fop : FOP_COMMAND
195          : JAVA_HOME
196          ;
197</pre>
198<p> replacing
199      <code class="computeroutput">FOP_COMMAND</code> with the full path to the FOP main script, and
200      replacing <code class="computeroutput">JAVA_HOME</code> with the directory where Java is
201      installed. If the <code class="envar">JAVA_HOME</code> environment variable is
202      already set, you don't need to specify it above.
203      </p>
204<p>
205        Proper generation of images in PDFs depends on the <a href="http://java.sun.com/products/jimi/#" target="_top">Jimi Image
206        Library</a>.  To get FOP to use Jimi, extract the
207        <code class="filename">JimiProClasses.zip</code> file from the Jimi SDK
208        and rename it&#8212;if on Windows, to
209        <code class="filename">jimi-1.0.jar</code>, or if on *nix, to
210        <code class="filename">JimiProClasses.jar</code>&#8212;and place it in the
211        <code class="filename">lib/</code> subdirectory of your FOP
212        installation.
213      </p>
214<p>To test PDF generation, switch to the directory <code class="filename">$BOOST_ROOT/libs/function/doc</code> and
215      execute the command <span><strong class="command">bjam --v2 pdf</strong></span>. In the
216      absence of any errors, Apache FOP will be executed to transform
217      the XSL:FO output of DocBook into a PDF file.</p>
218</div>
219</div>
220<div class="section" lang="en">
221<div class="titlepage"><div><div><h3 class="title">
222<a name="boostbook.setup.running"></a>Running BoostBook</h3></div></div></div>
223<p>Once BoostBook has been configured, we can build some
224    documentation. First, change to the directory
225    <code class="computeroutput">$BOOST_ROOT/doc</code> and remove (or make writable) the
226    <code class="computeroutput">.html</code> files in
227    <code class="computeroutput">$BOOST_ROOT/doc/html</code>. Then, run <code class="computeroutput">bjam
228    --v2</code> to build HTML documentation. You should see several
229    warnings like these while DocBook documentation is being built
230    from BoostBook documentation:</p>
231<pre class="programlisting">Cannot find function named 'checked_delete'
232Cannot find function named 'checked_array_delete'
233Cannot find function named 'next'</pre>
234<p>These warnings are emitted when the Boost documentation
235    tools cannot find documentation for functions, methods, or classes
236    that are referenced in the source, and are not harmful in any
237    way. Once Boost.Jam has completed its execution, HTML
238    documentation for Boost will be available in
239    <code class="computeroutput">$BOOST_ROOT/doc/html</code>. You can also create HTML
240    documentation in a single (large!) HTML file with the command line
241    <code class="computeroutput">bjam --v2 onehtml</code>, or Unix man pages with the command
242    line <code class="computeroutput">bjam --v2 man</code>. The complete list of output
243    formats is listed in <a href="started.html#boostbook.output.formats" title="Table 22.1. BoostBook Output Formats">Table 22.1, &#8220;BoostBook Output Formats&#8221;</a>. Several output formats can
244    be passed to a single invocation of <code class="computeroutput">bjam</code>, e.g.,
245    <code class="computeroutput">bjam --v2 html man docbook</code> would generate HTML
246    (multiple files), man pages, and DocBook documentation.</p>
247<div class="table">
248<a name="boostbook.output.formats"></a><p class="title"><b>Table 22.1. BoostBook Output Formats</b></p>
249<table class="table" summary="BoostBook Output Formats">
250<colgroup>
251<col>
252<col>
253</colgroup>
254<thead><tr>
255<th>Format</th>
256<th>Description</th>
257</tr></thead>
258<tbody>
259<tr>
260<td>html</td>
261<td><p>HTML output (multiple files). This is the default</p></td>
262</tr>
263<tr>
264<td>onehtml</td>
265<td><p>HTML output in a single HTML file.</p></td>
266</tr>
267<tr>
268<td>man</td>
269<td><p>Unix man pages.</p></td>
270</tr>
271<tr>
272<td>pdf</td>
273<td><p>PDF. Requires <a href="http://xml.apache.org/fop/index.html" target="_top">Apache FOP</a>.</p></td>
274</tr>
275<tr>
276<td>ps</td>
277<td><p>Postscript. Requires <a href="http://xml.apache.org/fop/index.html" target="_top">Apache FOP</a>.</p></td>
278</tr>
279<tr>
280<td>docbook</td>
281<td>
282<a href="http://www.docbook.org/" target="_top">DocBook</a>.</td>
283</tr>
284<tr>
285<td>fo</td>
286<td><a href="http://www.w3.org/TR/xsl/" target="_top">XSL Formatting Objects</a></td>
287</tr>
288</tbody>
289</table>
290</div>
291</div>
292<div class="section" lang="en">
293<div class="titlepage"><div><div><h3 class="title">
294<a name="boostbook.setup.troubleshooting"></a>Troubleshooting</h3></div></div></div>
295<p>The Boost documentation tools are still in their early phase of
296      development, and some things don't work as seamlessly as we would like
297      them to, yet. In particular, error messages can be somewhat
298      uninformative at times. If you find yourself in the situation when
299      you have double checked everything, and yet things still don't work as
300      expected, consider helping the tools by deleting
301      <code class="literal">bin.v2</code> build directory.
302      </p>
303</div>
304</div>
305<table width="100%"><tr>
306<td align="left"></td>
307<td align="right"><small>Copyright © 2003-2005 Douglas Gregor</small></td>
308</tr></table>
309<hr>
310<div class="spirit-nav">
311<a accesskey="p" href="../../boostbook.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../../boostbook.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../documenting.html"><img src="../../images/next.png" alt="Next"></a>
312</div>
313</body>
314</html>
Note: See TracBrowser for help on using the repository browser.