From: Christopher Currie (Christopher_at_[hidden])
Date: 2004-02-09 10:43:21
A lot of your comments I agree with; some of them are specific to
Boost.Build's docs, and others are more globally applicable to all
BoostBook documentation; I'll address the Boost.Build ones here and
direct you to the boost-docs list for the others.
> As I understood this would be the only documentation on Boost.Build2
> so it probably should not be called User Manual either.
Do you have a suggestion for a better name? Volodya has commented that
he thought that a "developer's manual" should be a separate document, so
if we broke those bits out would it be better?
> I can't help it, I find it to look too "computer generated" ;-) It is
> missing a human touch ;-) It looks like latex2html generated so it also shares
> its drawbacks. For example the arbitrary nesting: looking at the
> I cannot tell where I am in the document except looking at the url or jumping
> to the main toc (but that also does not help much).
There are several factors at work here. I think that some of the
*information* within the Boost.Build docs need to be reorganized. The
nesting is not arbitrary; it was based on the level of the header tags
in the original document (<h2> became a chapter, <h3> a first-level
There are probably some places where the flow of the documentation could
be improved by reworking where the section breaks are. The XML sources
are in v2/doc/src; the tutorual.xml file particularly has been cleaned
up enough to be readable to the Docbook uninitiated. Patches are welcome.
As for looking 'computer generated,' we welcome your help over on the
boost-docs list to make ALL of boost's documentation look more
professional. Information about the list is at:
I'll make a few comments about the suggestions below on that list.
> My personal preference
> is to add margins to the sides so the text does not run all the way from one
> border of the window to the other.
> the huge green
> navbar at the top. It totally does not fit in with the rest of the document.
> IMHO a navbar to be at each page have to be nonintrusive (small, not much
> colors) and usefull (something that you really need at each page) and it
> should have at least similar design as the rest of the document.
> I do not think it is a good idea to start with such a huge toc. Maybe a mix of
> condensed version and/or synopsis and/or "how to use this document" would be
> Also the local tocs kind of stand in the way of reading. I like them more
> out of the way (ie. on the right side where I've put them in my php version of
> the manual).
> Maybe it should have less
> separate files? Or maybe some top navbar that would highlight at least the
> chapter I am in? Maybe some "bread crumbs" navigation?
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk