Re: [boost] thoughts on pdf doc generation (was: [ANN] New documentation style sheet)

From: Jeff Garland (jeff_at_[hidden])
Date: 2006-04-09 12:42:30

Arkadiy Vertleyb wrote:
> "Eric Niebler" <eric_at_[hidden]> wrote
>> Arkadiy Vertleyb wrote:
>>> "David Abrahams" <dave_at_[hidden]> wrote
>>>> Let's just be clear so that nobody is confused: BoostBook doesn't
>>>> generate anything.  It's a document format.  We need translators to
>>>> turn BoostBook format into PDF format.  Those translators exist, but
>>>> as usual, they could be improved.
>>> Actually I am still confused :-(
>>>
>>> We have the typeof.qbk file in CVS, and we updated several other files
>>> so that the typeof documentation is now generated by Metacomm's bulds.
>>>
>>> The question is -- is this all that needs to be done for the typeof
>>> documentation
>>> to appear in 1.34 in both HTML and PDF format?  If no, what else needs
>>> to be done?
>>
>> Yes, that's all that's needed. QuickBook is a BoostBook authoring tool.
>> It lets you write BoostBook documentation with simple mark-up syntax,
>> and without having to read, write, or worry about XML. But it's really
>> BoostBook under the covers, so you get the wholesome goodness of
>> HTML/fo/PDF/man generation.
> 
> Right, I understand, but my question really is -- do we get this
> "wholesome goodness" through some sort of centralized process,
> or are we supposed to build the PDF ourselves, an check it in?

The generation of pdf from Boostbook source is possible, but the open 
tools we are using to do this suffer from scalability issues.  That is, 
it's unlikely you'll be able to just follow the instructions and get it 
to work without fo or some other step failing.

And actually, the concept as applied to Boost as a whole has an issue 
with 'human scalability'.  Have a look at:

http://www.crystalclearsoftware.com/libraries/date_time/date_time.pdf

This is the date-time Boostbook docs generated into pdf.  You'll note 
that they weigh in at ~400 pages.  About 3/4 of this is reference -- so 
there are about 100 pages of hand-written docs.  There are currently 
about 20 Boostbook documented libs.  So if we conservatively assume that 
they have 50 pages per library of non-reference docs that makes over 
1000 pages for a unified Boost pdf file without ref docs.  Of course 
this assumes you want to live without the reference and the other libs 
don't get converted to Boostbook.  If all of Boost could be generated 
into pdf with all the references I believe you'd have conservatively 
over 5,000 pages -- and more likely over 10,000.  The file would be very 
large and difficult to use. So I think the only rational approach is to 
provide multiple pdfs -- one per library and perhaps some common pdfs of 
build documentation or other key Boost common subjects.

Trouble is that the current Boostbook build process is not really setup 
to generate per library pdfs.  So in my view we really need to do some 
work on the Boostbook build infrastructure before pdf's become a 
realistic option.  We also need to support Quickbook docs.  And then 
there's the fact that most Boost libraries are NOT using Boostbook.  So 
really there is a need for a massive documentation conversion project to 
get all of Boost uniformly available.

As much as I'd like to see all this happen, I'm not holding my breath. 
We really need an organizer and a bunch of new volunteers with some 
actual time to spend to help with this sort of project -- assuming we 
could get everyone to agree on the need, goals, and approach, etc.  We 
had alot of trouble recruiting for the original Boostbook project so I 
think Doug ended up doing the bulk of the work. So, I'm afraid that pdf 
boost docs will continue to be 'vaporware' for the time being.

Jeff