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