Re: [jamboost] Re: V2 documentation format: a resolution?

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-02-10 02:38:31

Christopher Currie wrote:

> 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?

Actually, I though about separate chapters/parts/whatever, not necessary 
separate documentation. Answering Zbynek's question: user is someone who 
writes Jamfiles, extender is someone who either adds new toolset modules or 
declares new generators/feature/new target types and developer is one who 
hacks on Boost.Build internals.

> > 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
> > http://zigzag.lvk.cs.msu.su/~ghost/Boost.Build.docs2/bbv2.tutorial.hierar
> >chy.html 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
> section, etc.).

That's for sure. But it's hard to expect that any rearrangment will leave us 
with only chapters and first-level sections. There always will be 
second-level sections.

I actually think that nagivation link at the top will help even with current 
nesting.

- Volodya