diff options
Diffstat (limited to 'tools/quickbook/doc/install.qbk')
| -rw-r--r-- | tools/quickbook/doc/install.qbk | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/tools/quickbook/doc/install.qbk b/tools/quickbook/doc/install.qbk new file mode 100644 index 0000000000..5515fd9b74 --- /dev/null +++ b/tools/quickbook/doc/install.qbk @@ -0,0 +1,317 @@ +[/ + 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.6] + [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]
\ No newline at end of file |