Subject: [boost] [1.38] Beta release of PDF documentation (and some help needed).
From: John Maddock (john_at_[hidden])
Date: 2009-02-08 13:09:50
SVN commit 51104 to trunk provides the basic support for building all the
Boost libraries that can be as PDF's:
* improved fo.xsl stylesheet,
* tweaked individual Jamfiles so they find their images etc when being built
as a PDF,
* adds doc/pdf/Jamfile.v2 to build all boost libraries that can be as
Beta builds of the PDF's are available for download from
http://boost.cowic.de/rc/pdf/ includes the libraries and tools:
Math/Special functions and Distributions
Numeric/Conversion (currently has a build problem, not on ftp site)
Optional (currently has a build problem, not on ftp site)
Thread (currently has a build problem, not on ftp site)
BoostBook (currently has a build problem, not on ftp site)
I'd be grateful if all the Boost library authors that are using
QuickBook/BoostBook/DocBook could take a look at their PDF's and check that
they're OK, users too if you're willing!
Also if anyone would rather that their library wasn't included in this build
please speak up now - eventually the plan is make these available as a
The following default build options have now been added to the fo.xsl
stylesheet customization layer, let me know if anyone is violently opposed
* No indent on body text (we need all the horizontal space we can get for
* Left and right page margins 0.5in - a little small, but as above we need
all the space we can get.
* Paper type is A4 - it's an ISO standard, and just a little smaller than US
letter, so should print OK on both.
* Draft mode is turned off so we don't try and download draft.png just in
* SVG graphics are used for admonishments.
* Default path to search for images (if not overridden in a library's
Jamfile) is the SVN repository: allows most (but not all) libraries to be
built as PDF's without having to change their Jamfiles.
* Some of the PDF's are badly named: for example the python tutorial is
simply "tutorial.pdf", Phoenix is "users_manual.pdf" and Boost.Build is
"standalone.pdf". Anyone know how to get Boost.Build to rename a file or
else change the name of Boostbook target?
* The libraries Conversion, Optional and Thread do not currently build as
PDF's - their XML is invalid, looks like an easy fix though - just tweak
their usage of hyperlinks at global (i.e. not in a section) scope. I think
I can make the changes for this one if their authors agree.
* The BoostBook documentation doesn't build as a PDF - Lots of invalid XML -
this one looks much harder to fix. I need some help with this one.
* Currently only RenderX's XEP FO processor will build all the docs
correctly, Apache FOP is *still* not mature enough :-(
* There is currently no way to detect overflow of content on the right
margin (usually caused by over-long code blocks), ideally this would be made
a build error. I've no idea how to achieve this - the things I've tried so
far don't seem to work :-(
Anyway thanks for your attention, and I'll look forward to your feedback, as
well as this list, there is a Wiki site here
https://svn.boost.org/trac/boost/wiki/BoostDocs/PDF to track progress,
Regards, John Maddock.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk