ceph/src/boost/tools/quickbook/doc/install.qbk

   1 [/
   2     Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
   3     Copyright 2010-2011 Daniel James
   4
   5     Distributed under the Boost Software License, Version 1.0.
   6     (See accompanying file LICENSE_1_0.txt or copy at
   7     http://www.boost.org/LICENSE_1_0.txt)
   8 ]
   9
  10 [chapter Installation and configuration
  11     [quickbook 1.6]
  12     [compatibility-mode 1.5]
  13     [id quickbook.install]
  14     [source-mode teletype]
  15 ]
  16
  17 This section provides some guidelines on how to install and configure
  18 BoostBook and Quickbook under several operating systems. Before installing
  19 you'll need a local copy of boost, and to install the version of `bjam`
  20 which comes with it (or a later version).
  21
  22 [/ I don't think this is needed any more]
  23 [/
  24 Before continuing, it is very important that you keep this in mind: if you
  25 try to build some documents and the process breaks due to misconfiguration,
  26 be absolutely sure to delete any `bin` and `bin.v2` directories generated
  27 by the build before trying again.  Otherwise your configuration fixes will
  28 not take any effect.
  29 ]
  30
  31 [section:macosx Mac OS X]
  32
  33 The simplest way to install on OS X is to use macports.
  34 If you don't want to use macports and are using Snow Leopard or later,
  35 there are instructions [link quickbook.install.macosx.native later].
  36 Earlier versions of OS X need to use something like macports to install
  37 `xsltproc` because the version they come with is very old, and doesn't have
  38 good enough XSL support for boostbook's stylesheets.
  39
  40 [section:macports Mac OS X, using macports]
  41
  42 First install the `libxslt`, `docbook-xsl` and `docbook-xml-4.2`
  43 packages:
  44
  45     sudo port install libxslt docbook-xsl docbook-xml-4.2
  46
  47 Next, we need to configure Boost Build to compile BoostBook files. Add the
  48 following to your `user-config.jam` file, which should be in your home
  49 directory. If you don't have one, create a file containing this text. For more
  50 information on setting up `user-config.jam`, see the
  51 [@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
  52 Build documentation].
  53
  54     using xsltproc
  55         : /opt/local/bin/xsltproc
  56         ;
  57
  58     using boostbook
  59         : /opt/local/share/xsl/docbook-xsl/
  60         : /opt/local/share/xml/docbook/4.2
  61         ;
  62
  63 The above steps are enough to get a functional BoostBook setup.  Quickbook
  64 will be automatically built when needed.  If you want to avoid these
  65 rebuilds:
  66
  67 # Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
  68
  69 # Build the utility by issuing `bjam`.
  70
  71 # Copy the resulting `quickbook` binary (located at
  72   `BOOST_ROOT/dist/bin`) to a safe place.  The traditional location is
  73   `/usr/local/bin`.
  74
  75 # Add the following to your `user-config.jam` file, using the full path of the
  76   quickbook executable:
  77   ```
  78  using quickbook
  79      : /usr/local/bin/quickbook
  80      ;
  81   ```
  82
  83 If you need to build documentation that uses Doxygen, you will need to install it as well:
  84
  85     sudo port install doxygen
  86
  87 And then add to your `user-config.jam`:
  88
  89     using doxygen ;
  90
  91 Alternatively, you can install from the official doxygen `dmg`.
  92 This is described at [link osx-prebuilt-doxygen the end of the next section].
  93
  94 [endsect] [/ macports]
  95
  96 [section:native Mac OS X, Snow Leopard (or later)]
  97
  98 [:['Section contributed by Julio M. Merino Vidal]]
  99
 100 The text below assumes you want to install all the necessary utilities in a
 101 system-wide location, allowing any user in the machine to have access to
 102 them. Therefore, all files will be put in the `/usr/local` hierarchy.  If
 103 you do not want this, you can choose any other prefix such as
 104 `~/Applications` for a single-user installation.
 105
 106 Snow Leopard comes with `xsltproc` and all related libraries preinstalled, so
 107 you do not need to take any extra steps to set them up.  It is probable
 108 that future versions will include them too, but these instructions may not
 109 apply to older versions.
 110
 111 To get started:
 112
 113 # Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
 114   4.2] and unpack it inside `/usr/local/share/xml/docbook/4.2`.
 115
 116 # Download the latest
 117   [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
 118   Docbook XSL] version and unpack it. Be careful that you download the correct
 119   file, sometimes the 'looking for the latest version' link often links to
 120   another file. The name should be of the form
 121   '''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''',
 122   with no suffix such as `-ns.tar.bz2` or `-doc.tar.bz2`.
 123   Put the results in
 124   `/usr/local/share/xsl/docbook`, thus effectively removing the version
 125   number from the directory name (for simplicity).
 126
 127 # Add the following to your `user-config.jam` file, which should live in
 128   your home directory (`/Users/<your_username>`).  You must already have it
 129   somewhere or otherwise you could not be building Boost (i.e. missing
 130   tools configuration).
 131   ```
 132  using xsltproc ;
 133
 134  using boostbook
 135      : "/usr/local/share/xsl/docbook"
 136      : "/usr/local/share/xml/docbook/4.2"
 137      ;
 138   ```
 139
 140 The above steps are enough to get a functional BoostBook setup.  Quickbook
 141 will be automatically built when needed.  If you want to avoid these
 142 rebuilds and install a system-wide Quickbook instead:
 143
 144 # Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
 145
 146 # Build the utility by issuing `bjam`.
 147
 148 # Copy the resulting `quickbook` binary (located at
 149   `BOOST_ROOT/dist/bin`) to a safe place.  Following our previous
 150   example, you can install it into: `/usr/local/bin`.
 151
 152 # Add the following to your `user-config.jam` file:
 153   ```
 154  using quickbook
 155      : "/usr/local/bin/quickbook" ;
 156      ;
 157   ```
 158
 159 [# osx-prebuilt-doxygen]
 160 Additionally, if you need to build documentation that uses
 161 [@http://www.doxygen.org Doxygen], you will need to install it too:
 162
 163 # Go to the [@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
 164   downloads section] and get the disk image (`dmg` file) for Mac OS X.
 165
 166 # Open the disk image and drag the Doxygen application to your
 167   `Applications` folder to install it.
 168
 169 # Add the following to your `user-config.jam` file:
 170   ```
 171  using doxygen
 172      : /Applications/Doxygen.app/Contents/Resources/doxygen
 173      ;
 174   ```
 175
 176 [/ Removed this, since there are macports based instructions earlier.
 177    Instructions for pkgsrc welcome]
 178 [/
 179 Alternatively, you may want to install all the prerequistes through a
 180 package system to avoid manual management of the installations.  In that
 181 case, check out [@http://www.pkgsrc.org pkgsrc].
 182 ]
 183
 184 [endsect] [/ native]
 185
 186 [endsect] [/ macosx]
 187
 188 [section:windows Windows 2000, XP, 2003, Vista, 7]
 189
 190 [:['Section contributed by Julio M. Merino Vidal]]
 191
 192 The following instructions apply to any Windows system based on Windows
 193 2000, including Windows XP, Windows 2003 Server, Windows Vista, and Windows 7. The
 194 paths shown below are taken from a Windows Vista machine; you will need to
 195 adjust them to match your system in case you are running an older version.
 196
 197 # First of all you need to have a copy of `xsltproc` for Windows.  There
 198   are many ways to get this tool, but to keep things simple, use the
 199   [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
 200   Zlatkovic.  At the very least, you need to download the following
 201   packages: `iconv`, `zlib`, `libxml2` and `libxslt`.
 202
 203 # Unpack all these packages in the same directory so that you get unique
 204   `bin`, `include` and `lib` directories within the hierarchy.  These
 205   instructions use `C:\Users\example\Documents\boost\xml` as the root for
 206   all files.
 207
 208 # From the command line, go to the `bin` directory and launch
 209   `xsltproc.exe` to ensure it works.  You should get usage information on
 210   screen.
 211
 212 # Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
 213   4.2] and unpack it in the same directory used above.  That is:
 214   `C:\Users\example\Documents\boost\xml\docbook-xml`.
 215
 216 # Download the latest
 217   [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
 218   Docbook XSL] version and unpack it, again in the same directory
 219   used before. Be careful that you download the correct
 220   file, sometimes the 'looking for the latest version' link often links to
 221   another file. The name should be of the form
 222   '''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''',
 223   with no suffix such as `-ns.tar.bz2` or `-doc.tar.bz2`.
 224   To make things easier, rename the directory created
 225   during the extraction to `docbook-xsl` (bypassing the version name):
 226   `C:\Users\example\Documents\boost\xml\docbook-xsl`.
 227
 228 # Add the following to your `user-config.jam` file, which should live in
 229   your home directory (`%HOMEDRIVE%%HOMEPATH%`).  You must already have it
 230   somewhere or otherwise you could not be building Boost (i.e. missing
 231   tools configuration).
 232  ```
 233  using xsltproc
 234      : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
 235      ;
 236
 237  using boostbook
 238      : "C:/Users/example/Documents/boost/xml/docbook-xsl"
 239      : "C:/Users/example/Documents/boost/xml/docbook-xml"
 240      ;
 241  ```
 242
 243 The above steps are enough to get a functional BoostBook setup.  Quickbook
 244 will be automatically built when needed.  If you want to avoid these
 245 rebuilds:
 246
 247 # Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).
 248
 249 # Build the utility by issuing `bjam`.
 250
 251 # Copy the resulting `quickbook.exe` binary (located at
 252   `BOOST_ROOT\dist\bin`) to a safe place.  Following our previous
 253   example, you can install it into:
 254   `C:\Users\example\Documents\boost\xml\bin`.
 255
 256 # Add the following to your `user-config.jam` file:
 257   ```
 258  using quickbook
 259      : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
 260      ;
 261   ```
 262
 263 [endsect] [/Windows]
 264
 265 [section:linux Debian, Ubuntu]
 266
 267 The following instructions apply to Debian and its derivatives. They are based
 268 on a Ubuntu Edgy install but should work on other Debian based systems. They
 269 assume you've already installed an appropriate version of `bjam` for your
 270 copy of boost.
 271
 272 First install the `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
 273 For example, using `apt-get`:
 274
 275     sudo apt-get install xsltproc docbook-xsl docbook-xml
 276
 277 If you're planning on building boost's documentation, you'll also need to
 278 install the `doxygen` package as well.
 279
 280 Next, we need to configure Boost Build to compile BoostBook files. Add the
 281 following to your `user-config.jam` file, which should be in your home
 282 directory. If you don't have one, create a file containing this text. For more
 283 information on setting up `user-config.jam`, see the
 284 [@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
 285 Build documentation].
 286
 287     using xsltproc ;
 288
 289     using boostbook
 290         : /usr/share/xml/docbook/stylesheet/nwalsh
 291         : /usr/share/xml/docbook/schema/dtd/4.2
 292         ;
 293
 294     # Remove this line if you're not using doxygen
 295     using doxygen ;
 296
 297 The above steps are enough to get a functional BoostBook setup.  Quickbook
 298 will be automatically built when needed.  If you want to avoid these
 299 rebuilds:
 300
 301 # Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
 302
 303 # Build the utility by issuing `bjam`.
 304
 305 # Copy the resulting `quickbook` binary (located at
 306   `BOOST_ROOT/dist/bin`) to a safe place.  The traditional location is
 307   `/usr/local/bin`.
 308
 309 # Add the following to your `user-config.jam` file, using the full path of the
 310   quickbook executable:
 311  ```
 312  using quickbook
 313      : /usr/local/bin/quickbook
 314      ;
 315  ```
 316
 317 [endsect] [/Linux]