Re: [boost] [Range] Proposal: a sub-maintainer of Boost.Range

Subject: Re: [boost] [Range] Proposal: a sub-maintainer of Boost.Range
From: Michel Morin (mimomorin_at_[hidden])
Date: 2012-12-02 11:20:23

Below is a description of the Boost documentation.

I attached a patch for typos in Boost.Range documentation.
Fixing these typos and rebuild docs might be a good start-up.

[Documentation]
Some library distributes both QuickBook docs (in libs/XXXX/doc) and
HTML docs (in libs/XXXX/doc/html), and other library only distributes
QuickBook docs.

Here is how to update docs and commit them for the libraries
with both qbk and html docs.
1. Update quickbook docs.
2. Regenerate HTML docs.
3. Commit them.

[Build QuickBook docs]
Building QuickBook docs is done by running b2 (bjam) at libs/XXXX/doc
directory.
  cd PATH_TO_BOOST_ROOT_DIR/libs/XXXX/doc
  PATH_TO_BOOST_ROOT_DIR/b2 (or just b2 if the path is accessible)

So, first, one needs to build b2 (bjam) binary by running
bootstrap script at the boost root directory.
  cd PATH_TO_BOOST_ROOT_DIR
  ./bootstrap.sh (or ./bootstrap.bat on Windows)

Then, one needs to add documentation tools:
xsltproc, docbook-xsl and docbook-xml-4.2.
Here is a how-to for this step.
1. Install xsltproc and add the following to user-config.jam:
  using xsltproc : PATH_TO_XSLTPROC ;

2. Download Docbook XSL
( http://sourceforge.net/projects/docbook/files/docbook-xsl/ )
The latest version seems work fine.
If you'd be more conservative, then use the same version
as your target library. For example, Boost.Range uses V1.75.2.

3. Download Docbook XML 4.2
( http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip )

4. Add the following to user-config.jam:
  using boostbook
      : PATH_TO_DOCBOOK_XSL_DIR
      : PATH_TO_DOCBOOK_XML_DIR
      ;

A few libraries needs Doxygen to build qbk docs.
For those libraries, one needs to install Doxygen and
add `using doxygen : PATH_TO_DOXYGEN ;` to user-config.jam.

For more information, please consult the installation guide in
QuickBook documentation:
  http://www.boost.org/doc/html/quickbook/install.html

Regards,
Michel