[Boost-commit] svn:boost r68557 - trunk/tools/quickbook/doc

Subject: [Boost-commit] svn:boost r68557 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-01-30 05:51:04

Author: danieljames
Date: 2011-01-30 05:51:02 EST (Sun, 30 Jan 2011)
New Revision: 68557
URL: http://svn.boost.org/trac/boost/changeset/68557

Log:
Update the quickbook installation instructions.
Text files modified: 
   trunk/tools/quickbook/doc/quickbook.qbk |   132 +++++++++++++++++++++++++++++++++------ 
   1 files changed, 109 insertions(+), 23 deletions(-)

Modified: trunk/tools/quickbook/doc/quickbook.qbk
==============================================================================
--- trunk/tools/quickbook/doc/quickbook.qbk	(original)
+++ trunk/tools/quickbook/doc/quickbook.qbk	2011-01-30 05:51:02 EST (Sun, 30 Jan 2011)
@@ -1948,23 +1948,86 @@
 [section:install Installation and configuration]
 
 This section provides some guidelines on how to install and configure
-BoostBook and Quickbook under several operating systems.
+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]
 
-[:['Section contributed by Julio M. Merino Vidal]]
+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 have an old version of `xsltproc` which can't
+handle boostbook's xsl 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].
 
-The following instructions explain how to install Docbook XML, Docbook XSL
-and Doxygen in a Mac OS X system, how to configure Boost.Build v2 to
-recognize them and how to build and install Quickbook.  They were taken
-from a 10.4 (Tiger) machine so it is likely that they also apply to future
-versions; they may not work with older ones, though.
+    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
@@ -1972,7 +2035,7 @@
 you do not want this, you can choose any other prefix such as
 `~/Applications` for a single-user installation.
 
-Mac OS X comes with `xsltproc` and all related libraries preinstalled, so
+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.
@@ -1984,7 +2047,12 @@
 
 # Download the latest
   [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
-  Docbook XSL] version and unpack it.  Put the results in
+  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).
 
@@ -1992,13 +2060,14 @@
   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
@@ -2008,16 +2077,18 @@
 
 # Build the utility by issuing `bjam`.
 
-# Copy the resulting `quickbook` binary (located under the
-  `BOOST_ROOT/bin.v2` hierarchy) to a safe place.  Following our previous
+# 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:
 
@@ -2028,16 +2099,23 @@
   `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] [/Mac OS X]
+[endsect] [/ native]
+
+[endsect] [/ macosx]
 
 [section:windows Windows 2000, XP, 2003, Vista]
 
@@ -2072,7 +2150,12 @@
 # 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.  To make things easier, rename the directory created
+  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`.
 
@@ -2098,25 +2181,28 @@
 
 # Build the utility by issuing `bjam`.
 
-# Copy the resulting `quickbook.exe` binary (located under the
-  `BOOST_ROOT\bin.v2` hierarchy) to a safe place.  Following our previous
+# 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.
+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 `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
+First install the `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
 For example, using `apt-get`:
 
     sudo apt-get install xsltproc docbook-xsl docbook-xml
@@ -2149,8 +2235,8 @@
 
 # Build the utility by issuing `bjam`.
 
-# Copy the resulting `quickbook` binary (located under the
-  `BOOST_ROOT/bin.v2` hierarchy) to a safe place.  The traditional location is
+# 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