[boost] [1.38] Beta release of PDF documentation (and some help needed).

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

Folks,

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 
individual PDF's.

Beta builds of the PDF's are available for download from 
http://boost.cowic.de/rc/pdf/ includes the libraries and tools:

Accumulators
Algorithm/String
Asio
Bimap
Bind
ConceptCheck
Config
DateTime
ForEach
Function
Functional/Hash
Interprocess
Intrusive
Iterator
Lambda
Logic
Math/Complex
Math/Octonion
Math/Quaternion
Math/GCD
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)
Proto
PtrContainer
Pythod/Tutorial
Range
Regex
ScopeExit
Signals
Spirit/Phoenix
StaticAssert
Thread (currently has a build problem, not on ftp site)
TR1
TypeTraits
Typeof
Units
Unordered
Variant
Xpressive
BoostBook (currently has a build problem, not on ftp site)
Boost.Jam
Boost.Build
Quickbook.

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 
sourceforge download.

The following default build options have now been added to the fo.xsl 
stylesheet customization layer, let me know if anyone is violently opposed 
to these:

* No indent on body text (we need all the horizontal space we can get for 
code blocks).
* 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 
case.
* 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.

Known TODO's
~~~~~~~~~~~

* 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.