~ubuntu-branches/debian/sid/boost1.49/sid

<li class="listitem">Mac OS X without Fink: <a href="http://www.zveno.com/open_source/libxml2xslt.html" target="_top">Download the libxslt binaries</a>

</li>

<li class="listitem">Any platform: <a href="http://xmlsoft.org/XSLT/" target="_top">libxslt source</a>.</li>

</ul></div>

</li>

<p class="simpara"><span class="command"><strong>doxygen</strong></span>:</p> Available from <a href="http://www.doxygen.org" target="_top">http://www.doxygen.org</a>

</li>

</ul></div>

<a name="boostbook.setup.autounix"></a>Automatic setup for Unix-like systems</h3></div></div></div>

<p>BoostBook provides a nearly-automatic setup script. Once

you have downloaded and

installed <span class="command"><strong>xsltproc</strong></span>, <span class="command"><strong>doxygen</strong></span>,

and (optionally) <span class="command"><strong>java</strong></span>, the setup script can

download the required DocBook stylesheets, DocBook DTD, and

(when Java is enabled) Apache FOP for PDF output. It will then

configure Boost.Build version 2 to build BoostBook

documentation.</p>

<p>The script requires: <span class="command"><strong>sh</strong></span>,

<span class="command"><strong>curl</strong></span> and <span class="command"><strong>gunzip</strong></span>.

To perform the installation, execute the

script <span class="command"><strong>tools/boostbook/setup_boostbook.sh</strong></span>

from a directory where you would like the resulting XSL, DTD,

and Apache FOP installations to occur. </p>

</div>

<a name="boostbook.setup.manual"></a>Manual setup for all systems</h3></div></div></div>

<dt><span class="section"><a href="started.html#boostbook.setup.xsltproc">Configuring <span class="command"><strong>xsltproc</strong></span></a></span></dt>

<dt><span class="section"><a href="started.html#boostbook.setup.docbook">Configuring local DocBook XSL and DTD distributions</a></span></dt>

<dt><span class="section"><a href="started.html#boostbook.setup.doxygen">Configuring Doxygen for Documentation Extraction</a></span></dt>

<dt><span class="section"><a href="started.html#boostbook.setup.fop">Configuring Apache FOP</a></span></dt>

</dl></div>

<p>This section describes how to manually configure Boost

Boost version 2 (BBv@) for BoostBook. If you can use the

automatic setup script, you should. All configuration will

happen in the BBv2 user configuration file,

<code class="filename">user-config.jam</code>. If you do not have a copy

of this file in your home directory, you should copy the one

that resides in <code class="computeroutput">tools/build/v2</code> to your home

directory. Alternatively, you can edit

<code class="filename">tools/build/v2/user-config.jam</code> directly or

a site-wide <code class="filename">site-config.jam</code> file.</p>

<a name="boostbook.setup.xsltproc"></a>Configuring <span class="command"><strong>xsltproc</strong></span>

</h4></div></div></div>

<p>To configure <span class="command"><strong>xsltproc</strong></span> manually, you

will need to add a directive to

<code class="filename">user-config.jam</code> telling it where to find

<span class="command"><strong>xsltproc</strong></span>. If the program is in your path,

just add the following line to

<code class="filename">user-config.jam</code>:</p>

<pre class="programlisting">using xsltproc ;</pre>

100

<p>If <span class="command"><strong>xsltproc</strong></span> is somewhere else, use

101

this directive, where <code class="computeroutput">XSLTPROC</code> is the full

102

pathname to <span class="command"><strong>xsltproc</strong></span> (including

103

<span class="command"><strong>xsltproc</strong></span>):</p>

104

<pre class="programlisting">using xsltproc : XSLTPROC ;</pre>

105

</div>

106

107

108

<a name="boostbook.setup.docbook"></a>Configuring local DocBook XSL and DTD distributions</h4></div></div></div>

109

<p>This section describes how to configure Boost.Build to

110

use local copies of the DocBook DTD and XSL stylesheets to

111

improve processing time. You will first need to download two

112

packages:

113

114

</p>

115

116

<li class="listitem"><p>Norman Walsh's DocBook XSL stylesheets,

117

available at the <a href="http://docbook.sourceforge.net" target="_top">DocBook sourceforge

118

site</a>. Extract the DocBook XSL stylesheets to a

119

directory on your hard disk (which we'll refer to as the

120

<code class="computeroutput">DOCBOOK_XSL_DIR</code>).</p></li>

121

<li class="listitem"><p>The DocBook DTD, available as a ZIP archive

122

at the <a href="http://www.oasis-open.org/docbook/xml/4.2/" target="_top">OASIS

123

DocBook site</a>. The package is called "DocBook XML

124

4.2". Extract the DocBook DTD to a directory on your hard

125

disk (which we'll refer to as the

126

<code class="computeroutput">DOCBOOK_DTD_DIR</code>). You will want to extract this

127

archive in a subdirectory!</p></li>

128

</ul></div>

129

<p>

130

</p>

131

<p>Add the following directive telling BBv2 where to find

132

the DocBook DTD and XSL stylesheets:</p>

133

<pre class="programlisting"># BoostBook configuration

134

using boostbook

135

: DOCBOOK_XSL_DIR

136

: DOCBOOK_DTD_DIR

137

;</pre>

138

<p>Whenever you change this directive, you will need to

139

remove the <code class="computeroutput">bin.v2</code> directory that BBv2 generates.

140

This is due to longstanding bug we are trying to fix.</p>

141

<p>At this point, you should be able to build HTML

142

documentation for libraries that do not require Doxygen. To

143

test this, change into the directory <code class="filename">$BOOST_ROOT/libs/function/doc</code> and

144

run the command <code class="computeroutput">bjam</code>: it should produce HTML

145

documentation for the Boost.Function library in the

146

<code class="computeroutput">html</code> subdirectory.</p>

147

</div>

148

149

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 class="command"><strong>doxygen</strong></span> executable (with full

160

path name). If the right <span class="command"><strong>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

165

<tr>

166

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

180

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

194

using 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—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>—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 class="command"><strong>bjam 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

221

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</code>

228

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'

232

Cannot find function named 'checked_array_delete'

233

Cannot 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 onehtml</code>, or Unix man pages with the command

242

line <code class="computeroutput">bjam man</code>. The complete list of output

243

formats is listed in <a class="xref" href="started.html#boostbook.output.formats" title="Table 36.1. BoostBook Output Formats">Table 36.1, “BoostBook Output Formats”</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 html man docbook</code> would generate HTML

246

(multiple files), man pages, and DocBook documentation.</p>

247

248

<a name="boostbook.output.formats"></a><p class="title"><b>Table 36.1. BoostBook Output Formats</b></p>

249

250

251

<col>

252

<col>

253

</colgroup>

254

255

<th>Format</th>

256

<th>Description</th>

257

</tr></thead>

258

<tbody>

259

<tr>

260

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

269

<td><p>Unix man pages.</p></td>

270

</tr>

271

<tr>

272

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

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

286

<td><a href="http://www.w3.org/TR/xsl/" target="_top">XSL Formatting Objects</a></td>

287

</tr>

288

</tbody>

289

</table></div>

290

</div>

291

292

</div>

293

294

295

<a name="boostbook.setup.troubleshooting"></a>Troubleshooting</h3></div></div></div>

296

<p>The Boost documentation tools are still in their early phase of

297

development, and some things don't work as seamlessly as we would like

298

them to, yet. In particular, error messages can be somewhat

299

uninformative at times. If you find yourself in the situation when

300

you have double checked everything, and yet things still don't work as

301

expected, consider helping the tools by deleting

302

<code class="literal">bin.v2</code> build directory.

303

</p>

304

</div>

305

</div>

306

307

308

309

(See accompanying file LICENSE_1_0.txt or copy at

310

<a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).

311

</p>

312

</div></td>

313

</tr></table>

314

<hr>

315

316

317

</div>

318

</body>

319

</html>

Older »