|
Home | Libraries | People | FAQ | More |
This section provides some guidelines on how to install and configure BoostBook
and Quickbook under several operating systems. Before installing you'll need
a local copy of boost, and to install the version of bjam which
comes with it (or a later version).
The simplest way to install on OS X is to use macports. If you don't want
to use macports and are using Snow Leopard or later, there are instructions
later. Earlier versions
of OS X need to use something like macports to install xsltproc
because the version they come with is very old, and doesn't have good enough
XSL support for boostbook's stylesheets.
First install the libxslt, docbook-xsl and docbook-xml-4.2
packages:
sudo port install libxslt docbook-xsl docbook-xml-4.2
Next, we need to configure Boost Build to compile BoostBook files. Add
the following to your user-config.jam file, which should be
in your home directory. If you don't have one, create a file containing
this text. For more information on setting up user-config.jam,
see the Boost
Build documentation.
using xsltproc
: /opt/local/bin/xsltproc
;
using boostbook
: /opt/local/share/xsl/docbook-xsl/
: /opt/local/share/xml/docbook/4.2
;
The above steps are enough to get a functional BoostBook setup. Quickbook will be automatically built when needed. If you want to avoid these rebuilds:
BOOST_ROOT/tools/quickbook).
bjam.
quickbook binary (located at BOOST_ROOT/dist/bin)
to a safe place. The traditional location is /usr/local/bin.
user-config.jam file, using
the full path of the quickbook executable:
using quickbook
: /usr/local/bin/quickbook
;
If you need to build documentation that uses Doxygen, you will need to install it as well:
sudo port install doxygen
And then add to your user-config.jam:
using doxygen ;
Alternatively, you can install from the official doxygen dmg.
This is described at the end of the
next section.
Section contributed by Julio M. Merino Vidal
The text below assumes you want to install all the necessary utilities
in a system-wide location, allowing any user in the machine to have access
to them. Therefore, all files will be put in the /usr/local
hierarchy. If you do not want this, you can choose any other prefix such
as ~/Applications for a single-user installation.
Snow Leopard comes with xsltproc and all related libraries
preinstalled, so you do not need to take any extra steps to set them up.
It is probable that future versions will include them too, but these instructions
may not apply to older versions.
To get started:
/usr/local/share/xml/docbook/4.2.
docbook-xsl-1.nn.n.tar.bz2, with no suffix
such as -ns.tar.bz2 or -doc.tar.bz2. Put
the results in /usr/local/share/xsl/docbook, thus effectively
removing the version number from the directory name (for simplicity).
user-config.jam file, which
should live in your home directory (/Users/<your_username>).
You must already have it somewhere or otherwise you could not be building
Boost (i.e. missing tools configuration).
using xsltproc ;
using boostbook
: "/usr/local/share/xsl/docbook"
: "/usr/local/share/xml/docbook/4.2"
;
The above steps are enough to get a functional BoostBook setup. Quickbook will be automatically built when needed. If you want to avoid these rebuilds and install a system-wide Quickbook instead:
BOOST_ROOT/tools/quickbook).
bjam.
quickbook binary (located at BOOST_ROOT/dist/bin)
to a safe place. Following our previous example, you can install it
into: /usr/local/bin.
user-config.jam file:
using quickbook
: "/usr/local/bin/quickbook" ;
;
Additionally, if you need to build documentation that uses Doxygen, you will need to install it too:
dmg file) for
Mac OS X.
Applications
folder to install it.
user-config.jam file:
using doxygen
: /Applications/Doxygen.app/Contents/Resources/doxygen
;
Section contributed by Julio M. Merino Vidal
The following instructions apply to any Windows system based on Windows 2000, including Windows XP, Windows 2003 Server and Windows Vista. The paths shown below are taken from a Windows Vista machine; you will need to adjust them to match your system in case you are running an older version.
xsltproc for Windows.
There are many ways to get this tool, but to keep things simple, use
the binary packages
made by Igor Zlatkovic. At the very least, you need to download the following
packages: iconv, zlib, libxml2
and libxslt.
bin, include and lib directories
within the hierarchy. These instructions use C:\Users\example\Documents\boost\xml
as the root for all files.
bin directory and launch
xsltproc.exe to ensure it works. You should get usage information
on screen.
C:\Users\example\Documents\boost\xml\docbook-xml.
docbook-xsl-1.nn.n.tar.bz2, with no suffix such as -ns.tar.bz2 or
-doc.tar.bz2. To make things easier, rename the directory
created during the extraction to docbook-xsl (bypassing
the version name): C:\Users\example\Documents\boost\xml\docbook-xsl.
user-config.jam file, which should
live in your home directory (%HOMEDRIVE%%HOMEPATH%). You
must already have it somewhere or otherwise you could not be building
Boost (i.e. missing tools configuration).
using xsltproc
: "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
;
using boostbook
: "C:/Users/example/Documents/boost/xml/docbook-xsl"
: "C:/Users/example/Documents/boost/xml/docbook-xml"
;
The above steps are enough to get a functional BoostBook setup. Quickbook will be automatically built when needed. If you want to avoid these rebuilds:
BOOST_ROOT\tools\quickbook).
bjam.
quickbook.exe binary (located at BOOST_ROOT\dist\bin)
to a safe place. Following our previous example, you can install it into:
C:\Users\example\Documents\boost\xml\bin.
user-config.jam file:
using quickbook
: "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
;
The following instructions apply to Debian and its derivatives. They are
based on a Ubuntu Edgy install but should work on other Debian based systems.
They assume you've already installed an appropriate version of bjam
for your copy of boost.
First install the xsltproc, docbook-xsl and docbook-xml
packages. For example, using apt-get:
sudo apt-get install xsltproc docbook-xsl docbook-xml
If you're planning on building boost's documentation, you'll also need to
install the doxygen package as well.
Next, we need to configure Boost Build to compile BoostBook files. Add the
following to your user-config.jam file, which should be in your
home directory. If you don't have one, create a file containing this text.
For more information on setting up user-config.jam, see the
Boost
Build documentation.
using xsltproc ;
using boostbook
: /usr/share/xml/docbook/stylesheet/nwalsh
: /usr/share/xml/docbook/schema/dtd/4.2
;
# Remove this line if you're not using doxygen
using doxygen ;
The above steps are enough to get a functional BoostBook setup. Quickbook will be automatically built when needed. If you want to avoid these rebuilds:
BOOST_ROOT/tools/quickbook).
bjam.
quickbook binary (located at BOOST_ROOT/dist/bin)
to a safe place. The traditional location is /usr/local/bin.
user-config.jam file, using the
full path of the quickbook executable:
using quickbook
: /usr/local/bin/quickbook
;