Re: [boost] [Boost-docs] [1.35] Where to place PDF versions of docs?

From: John Maddock (john_at_[hidden])
Date: 2007-11-02 06:34:47

David Abrahams wrote:
>> How are the HTML docs handled? Are the generated HTML files checked
>> into the website's SVN?
>
> In some cases.
>
>> Seems odd to check generated files into version
>> control.
>
> Yeah, but can I count on whoever is generating docs to install
> docutils for my ReST documents?
>
> What about the GPL'd Makefile I used to generate PDFs of the iterator
> docs, which I can't include in the boost distro, but link to from the
> README?

Right, and the Math PDF can only be built with XEP not FOP (which mangles it 
up terribly even with the 0.9 release), and then the equations only display 
correctly if you have the right fonts configured for XEP....  it's not 
pretty and it's far from ideal, but there you go, that's PDF's for you.

Also building the HTML documentation as a single "book" from doc/ simply 
isn't viable anymore IMO: it doesn't scale well (takes an age to build, 
breaks at the drop of a hat etc).  It worked when we only had a few 
Boostbook libraries, but we have too many for this now.  So we IMO we need a 
more distributed system similar to the one Robert suggested: we can still 
have a central "build everything" script as well if desired, but that change 
is probably for 1.36.

For now I just want a location we can all point to for the PDF's, and that 
the user can browse to see what's available.

>> Maybe the Documentation link on the Boost's home page could take you
>> to a page that had links to automatically generated PDFs in addition
>> to the HTML.
>
> Would be nice, for sure.

100% agreed.

John.