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

From: Stefan Seefeld (seefeld_at_[hidden])
Date: 2007-11-01 15:03:36

Eric Niebler wrote:

> How are the HTML docs handled? Are the generated HTML files checked into 
> the website's SVN?

The boost.python tutorial's html is in fact checked into the
boost.python repository itself. I don't know about other libraries.

> Seems odd to check generated files into version 
> control. Maybe the Documentation link on the Boost's home page could 

Not only odd, but error-prone. (I was just asked to check conflicts in
an attempted merge from the last release branch to trunk, because the
html in trunk was generated by a different tool than the one on the
branch, resulting in many benign conflicts.

> take you to a page that had links to automatically generated PDFs in 
> addition to the HTML.

I see multiple issues here:

1) The packages are even bigger than necessary as they bundle
documentation. IMO it would be good to split packages on that axis, too,
i.e. provide documentation separately, as an add-on.

2) Since developers are not expected to have all the required tools
installed, the produced docs are in the repository, too. The way I have
seen this handled in other cases is that docs are only to be built (by
default) on previleged hosts that have all the right tools set up. The
results of such builds are then made available through the common website.

(Of course authors *can* build html and pdf themselves, if they make
sure they have the proper build environment set up first.)

Regards,
                Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...