quickbook/doc/install.qbk

[/
    Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
    Copyright 2010-2011 Daniel James

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
]

[chapter Installation and configuration
    [quickbook 1.7]
    [compatibility-mode 1.5]
    [id quickbook.install]
    [source-mode teletype]
]

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).

[/ I don't think this is needed any more]
[/
Before continuing, it is very important that you keep this in mind: if you
try to build some documents and the process breaks due to misconfiguration,
be absolutely sure to delete any `bin` and `bin.v2` directories generated
by the build before trying again.  Otherwise your configuration fixes will
not take any effect.
]

[section:macosx Mac OS X]

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 [link quickbook.install.macosx.native 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.

[section:macports Mac OS X, using macports]

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
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html 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:

# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).

# Build the utility by issuing `bjam`.

# Copy the resulting `quickbook` binary (located at
  `BOOST_ROOT/dist/bin`) to a safe place.  The traditional location is
  `/usr/local/bin`.

# Add the following to your `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 [link osx-prebuilt-doxygen the end of the next section].

[endsect:macports]

[section:native Mac OS X, Snow Leopard (or later)]

[:['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:

# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
  4.2] and unpack it inside `/usr/local/share/xml/docbook/4.2`.

# Download the latest
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
  Docbook XSL] version and unpack it. Be careful that you download the correct
  file, sometimes the 'looking for the latest version' link often links to
  another file. The name should be of the form
  '''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''',
  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).

# Add the following to your `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:

# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).

# Build the utility by issuing `bjam`.

# Copy the resulting `quickbook` binary (located at
  `BOOST_ROOT/dist/bin`) to a safe place.  Following our previous
  example, you can install it into: `/usr/local/bin`.

# Add the following to your `user-config.jam` file:
  ```
 using quickbook
     : "/usr/local/bin/quickbook" ;
     ;
  ```

[# osx-prebuilt-doxygen]
Additionally, if you need to build documentation that uses
[@http://www.doxygen.org Doxygen], you will need to install it too:

# Go to the [@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
  downloads section] and get the disk image (`dmg` file) for Mac OS X.

# Open the disk image and drag the Doxygen application to your
  `Applications` folder to install it.

# Add the following to your `user-config.jam` file:
  ```
 using doxygen
     : /Applications/Doxygen.app/Contents/Resources/doxygen
     ;
  ```

[/ Removed this, since there are macports based instructions earlier.
   Instructions for pkgsrc welcome]
[/
Alternatively, you may want to install all the prerequistes through a
package system to avoid manual management of the installations.  In that
case, check out [@http://www.pkgsrc.org pkgsrc].
]

[endsect:native]

[endsect:macosx]

[section:windows Windows 2000, XP, 2003, Vista, 7]

[:['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, Windows Vista, and Windows 7. 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.

# First of all you need to have a copy of `xsltproc` for Windows.  There
  are many ways to get this tool, but to keep things simple, use the
  [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
  Zlatkovic.  At the very least, you need to download the following
  packages: `iconv`, `zlib`, `libxml2` and `libxslt`.

# Unpack all these packages in the same directory so that you get unique
  `bin`, `include` and `lib` directories within the hierarchy.  These
  instructions use `C:\Users\example\Documents\boost\xml` as the root for
  all files.

# From the command line, go to the `bin` directory and launch
  `xsltproc.exe` to ensure it works.  You should get usage information on
  screen.

# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
  4.2] and unpack it in the same directory used above.  That is:
  `C:\Users\example\Documents\boost\xml\docbook-xml`.

# Download the latest
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
  Docbook XSL] version and unpack it, again in the same directory
  used before. Be careful that you download the correct
  file, sometimes the 'looking for the latest version' link often links to
  another file. The name should be of the form
  '''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''',
  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`.

# Add the following to your `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:

# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).

# Build the utility by issuing `bjam`.

# Copy the resulting `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`.

# Add the following to your `user-config.jam` file:
  ```
 using quickbook
     : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
     ;
  ```

[endsect:windows]

[section:linux Debian, Ubuntu]

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
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html 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:

# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).

# Build the utility by issuing `bjam`.

# Copy the resulting `quickbook` binary (located at
  `BOOST_ROOT/dist/bin`) to a safe place.  The traditional location is
  `/usr/local/bin`.

# Add the following to your `user-config.jam` file, using the full path of the
  quickbook executable:
 ```
 using quickbook
     : /usr/local/bin/quickbook
     ;
 ```

[endsect:linux]