Re: [Boost-users] [Quickbook] How to create pdf file

Subject: Re: [Boost-users] [Quickbook] How to create pdf file
From: Max (loadcom_at_[hidden])
Date: 2009-01-29 06:01:02

> > Facing 'such a long toolchain', I was wandering why there's such a
> > grey corner in the boost world. :-) And, meanwhile, I'm humble with
> > lack of the experience of doc-making.
> >
> > Hearing what you've said, I feel now much more relaxed. :-)
> >
> > I have experience of Doxygen, Ghostscript(a long time ago), am aware
> > of that MikTeX is an implementaion of the famous system LaTEX by Knuth
> > (or I'm wrong?). But I'm quite unfamilar with other stuffs, such as
> > XSL style sheete, DocBook DTD, Iconv, libXslt, and so much.
> >
> > Perhaps finally I want to make clear that what raw materials, say
> > scripts in code or elsewhere, through what workflow, are rendered to
> > become a pdf file.
> 
> The transforms are:
> 
> quickbook -> BoostBook XML
> Doxygen -> Doxygen XML -> BoostBookXML
> 
> BoostBook XML -> Docbook XML
> 
> DocBook XML -> HTML
> DocBook XML -> FO XML -> PDF or PS

It's a big step for me to get this, to depict some of the basic conceptions
in my mind. Thanks.

> > Thanks for your help. And one more question: Is it possible to make
> > _one_ pdf doc file for all of the boost packages by one run? yes or
> > no? :-)
> 
> Well if you want it in black and white like that, then no :-(
> 

 Haha...  :-)

> In any case it's unlikely that a build of everything is what you really
> want: it would be one huge PDF!!!

IMO, that should not be a problem - for example, the doc of pdf format 
of the CGAL libs is about 3,000 pages. One doc as a whole will facilitate
easy
seaching of contents of interest. I  prefer pdf format, it makes user able
to 
markup.

> 
> To build a PDF for library X, then cd into libs/X/doc

I'm not aware of this before. That's why I was bjam'ing in the boost
root folder and could not get the desired result.

This time I select the ASIO for a trial. Things seems to work well and 
at last I get 
" ... updated 187 targets..."

I noticed that there created a new html folder under the asio/doc
folder, and the boost_1_37_0/bin/v2 also appears, but I just could not
find the pdf doc file. Am I still missing anything?

> 
> and do a:
> 
> bjam pdf
> 
> start with something small and easy like static_assert, or else there's a
"test
> everything" project in doc/test.
> 
> Also note that not all Boost libraries are documented with
> quickbook/boostbook/docbook so your mileage may vary.

Yes, this is a problem that I might be aware before. But is there a plan 
to impose more restrict/unified requirements on coding/docing of the
libs? With it, more uniform appearance/feeling, as well as higher
managability
and lower learning curve for user will be colser, I guess.

B/Rgds
Max