Arkadiy Vertleyb wrote:
"Eric Niebler" <eric@boost-consulting.com> wrote
Arkadiy Vertleyb wrote:
"David Abrahams" <dave@boost-consulting.com> 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