doc/boost-doc-tools/install.qbk

[/
    Copyright 2013-2018 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 Installing Boostbook and Quickbook
[id boost_doc_tools.install]
[quickbook 1.5]
[source-mode teletype]
]

[section:intro Introduction]

This chapter describes how to install the basic documentation tools that make
up the Boost documentation toolchain. This isn't enough for building the full
Boost documentation, but it's enough to start using quickbook or boostbook.
The basic requirements are:

* Boost Build
* `xsltproc`, which is a part of [@http://xmlsoft.org/XSLT/ `libxslt`].
* [@http://docbook.sourceforge.net/ Norman Walsh's DocBook XSL
  stylesheets] - Note that sourceforge has organized these files so that
  the documentation for the stylesheets is the first set of files
  offered for download; you have to look farther down for the actual
  stylesheets.
* [@http://www.oasis-open.org/docbook/xml/4.2/ The DocBook DTD]

Installing all of these parts can be quite tricky, so the next section
contains recipes to set them up for [link install_windows Windows],
[link install_mac OS X], [link install_debian Debian and Ubuntu].
Other configurations are of course possible, but we've found these ones
effective.

They assume that you have already installed Boost.Build and are familiar with
the basics of using it, see [@boost:/more/getting_started/index.html the
getting started guide] for an introduction. It's generally a good idea to
install Boost.Build from source, the prebuilt packages are often out of date.

[endsect]

[section:recipes Installation Recipes]

[#install_windows]
[section:windows Windows]

Since most of these command line tools were developed for Unix, and Unix style,
platforms they are an awkward fit for windows and recipes requires more effort.
This leads to two possible techniques, firstly install with cygwin which
handles much of the complexity for you, but requires that you always use it
from within Cygwin. The other is to manually install the toolchain for use from
the windows command prompt. This gives a more integrated user experience but is
quite fiddly to get right.

[section:cygwin Cygwin Install]

These instruction assume that cygwin has been installed to [^c:\\cygwin].

Install these packages:

* [^ Libs/libxml2]
* [^ Libs/libxslt]
* [^ Text/docbook-xml42]
* [^ Text/docbook-xsl]
* [^ Devel/gcc4-g++] (optional, if you don't have a compiler).
* [^ Devel/doxygen] (optional, for generating reference documentation
  from C++ source files).

Now we need to configure Boost.Build to use these tools. This step is different
depending on whether you're using Boost.Build built with cygwin, or for native
windows. For cygwin you need to add to your `user-config.jam` file:

    using xsltproc ;

    using boostbook
        : /usr/share/docbook-xsl
        : /usr/share/xml/docbook/4.2
        ;

    using quickbook ;

    # If you installed doxygen:
    using doxygen ;

When using a native (non-Cygwin) Boost.Build, you'll need to specify the
windows paths to the various tools:

    # Adjust this path to the location of your cygwin install.
    CYGWIN_DIR = c:/cygwin ;

    using xsltproc
        : $(CYGWIN_DIR)/bin/xsltproc.exe ;

    using boostbook
        : $(CYGWIN_DIR)/usr/share/docbook-xsl
        : $(CYGWIN_DIR)/usr/share/xml/docbook/4.2
        ;

    using quickbook ;

    # If you installed doxygen:
    using doxygen
        : $(CYGWIN_DIR)/bin/doxygen.exe
        ;

[endsect] [/ cygwin ]

[section:manual Manually installing windows native tools]

In order to install the tools under windows, we need to create a directory
structure somewhat similar to the unix filesystem. We're going to place this
in [^c:\\boost-tools], if you want to put it elsewhere, just follow the
instructions, adjusting the paths accordingly. This is also a good location
to use as the prefix when installing Boost.Build.

* Create directory for boost tools, say [^ c:\\boost-tools].
* Create directory for binaries, [^ c:\\boost-tools\\bin].
* Add the [^bin] directory to the path (e.g. in Xp, right click on 'My
  Computer', click on 'Properties', then the 'Advanced' tab and click on
  'Environment variables' to open a dialog where you can edit the PATH
  variable).

Next you need to download several xml tools from
[@http://www.zlatkovic.com/pub/libxml/ Igor Zlatkovic].
You require: [^ iconv], [^ libxml2] and [^ libxslt], [^ zlib].
Then unzip these into the [^c:\\boost-tools] directory.
This should place the `xsltproc` exectuable in [^c:\\boost-tools\\bin].

Next make a directory for xml processing files at [^ c:\\boost-tools\\xml].

* [@http://docbook.sourceforge.net/ Norman Walsh's DocBook XSL
  stylesheets] from their
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&
  package_id=16608 Sourceforge download page] to
  [^ c:\\boost-tools\\xml\\docbook-xsl].
* [@http://www.oasis-open.org/docbook/xml/4.2/ The DocBook DTD] to
  [^ c:\\boost-tools\\xml\\docbook-xml].

[^ user-config.jam] in the boost build search path,
for most people this will be [^ C:\\Documents and Settings\\['username]].

    BOOST_TOOLS_DIR = c:/boost-tools ;
    using xsltproc
        : $(BOOST_TOOLS_DIR)/bin/xsltproc.exe"
        ;

    using boostbook
        : $(BOOST_TOOLS_DIR)/xml/docbook-xsl
        : $(BOOST_TOOLS_DIR)/xml/docbook-xml
        ;

    using quickbook ;

Also, if you wish to use doxygen to generate reference documentation from
C++ source headers, you'll need to install it. You can download it from
[@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc the doxygen
website]. The installer should add the executable to your path, so you just
need to add to your [^ user-config.jam]:

    using doxygen ;

[endsect] [/ manual ]

[endsect] [/ windows ]

[#install_mac]
[section:mac OS X]

If you're using Snow Leopard (OS X 10.6) or later, then you should already have
the xml tools installed, so you just need to install the docbook xml and xslt
files.  The easiest way to do that is probably to use macports, install them
with:

    sudo port install docbook-xml-4.2 docbook-xsl

For earlier versions of OS X, you'll also need to install `libxslt` to get
an up to date version of `xsltproc`:

    sudo port install libxslt docbook-xml-4.2 docbook-xsl

You can also install `doxygen`, for generating reference documentation from
C++ source files:

    sudo port install doxygen

Boost.Build knows the default install location for macports, so all you need
to add to your `user-config.jam` is an instruction to use them:

    using boostbook ;
    using quickbook ;

    # If you've installed doxygen:
    using doxygen ;

[endsect] [/ mac]

[#install_debian]
[section:debian Debian and Ubuntu]

Installing on Debian and Ubuntu is pretty easy, just install the packages using
`apt-get` (or an alternative, such as `aptitude`):

    sudo apt-get install xsltproc docbook-xsl docbook-xml

You can also install `doxygen`, for generating reference documentation from
C++ source files:

    sudo apt-get install doxygen

Boost.Build should be to find these packages without an explicit path, so just
add to your `user-config.jam`:

    using boostbook ;
    using quickbook ;

    # If you've installed doxygen:
    using doxygen ;

[endsect] [/ debian]

[endsect]

[section:quickbook Pre-build quickbook]

Boost.Build automatically builds Quickbook when required to build the
documentation, but as it
takes a little while to build you might prefer to build it in advance.
To do this, in the command line type (replacing [^$BOOST_ROOT] with the
root directory of boost):

    cd $BOOST_ROOT/tools/quickbook
    b2 dist-bin

Or for windows:

    cd $BOOST_ROOT\\tools\\quickbook
    b2 dist-bin

Change [^ using quickbook] in [^ user-config.jam] to (replacing [^
$BOOST_ROOT] with the root directory of boost, as before):

    using quickbook : $BOOST_ROOT/dist/bin/quickbook ;

Windows:

    using quickbook : $BOOST_ROOT\\dist\\bin\\quickbook ;

[endsect] [/quickbook]