Re: [Boost-docs] questions about boost documentation

Subject: Re: [Boost-docs] questions about boost documentation
From: John Maddock (john_at_[hidden])
Date: 2007-08-14 17:10:14

Robert Ramey wrote:
> In the beginning ....
>
> It was pretty simple.  Each library had a directory,
> In each library there was a directory named "docs".
> and in that subdirectory there was a bunch of linked html files.
>
> Now in the improved system - I don't know what there is.
> Sometimes I get bumped over to www.boost.org/...

Right the idea was that boostbook/quickbook generated docs would have only 
the doc source in SVN, and generated docs would be put online, and/or 
generated when preparing the zip for distribution.

> I find a directory in the boost_root/doc/html .. and ...
>
> When I look at a quickbook document chapter - very
> nice looking - but it starts out with chapter 24 or something.
> What's up with that?
>
> And generating local documentation for your system - like you
> need if you want to have it available if you're not near a wi-fi
> connections is a fragil process that takes a huge amount of time.
> And the recommended way to do it doesn't permit one to do it
> for just one or the other library - or test the process on just one
> library.

Yep, the current system doesn't scale to a large number of libraries: the 
docs take too long to build, and if one lib's docs are temporarily broken 
then they are all broken :-(

> Note that I've only spent some time looking at this.
>
> Wouldn't it be much, much easier to organize things in
> the following way?
>
> boost_root
>    libs
>        serialization
>            build...
>            src...
>            test...
>            example...
>            performance ...
>            doc
>                 html
>                      files written by hand or generated by boost book
>                 pdf
>                      files made by ? some method or by boost book
>                 boost book
>                      Jamfile.v2
>                      files made by hand or by quickbook
>                 quickbook
>                       Jamfile.v2
>                       quickbook files
>
> boost entry webpage
> boost document navigator - frame with links to all library
> documentation.

Chuckle... well some libraries using quickbook/boostbook are organised that 
way: see regex in SVN/trunk for example.

The down side is that we don't have a way to automatically generate docs 
that are organised this way for "all of boost", so that we can avoid putting 
generated html in SVN.

Note that since the regex docs have only one "chapter" they are organised as 
an "article" doctype rather than a "library" or "book".  Likewise this 
organisation lets you set up TOC depth and other preferences to suite the 
particular libraries docs.

Hopefully the IDB folks will get this even better organised in time... but 
you're on the right track, the current "all in one" approach isn't going to 
be viable in the long run.

John.