From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-12-30 06:49:00
> I am now confident that I know how the docs should be structured. The
> tutorial is pretty good (or will be as soon as soon as you go through
> our edits), but there's a terrible amount of redundancy with the next
> chapter. The tutorial should become the beginning of that chapter, and
> the redundancy should be removed.
Do you mean that the tutorial and current "User manual" should form one
section? Or simply that they should form a logical sequence with no
duplication? Either variant is OK, I'm just trying to clarify.
> The chapter should be renamed to "User Guide."
Or, you mean "User Guide" chapter, starting with "Tutorial" section.
> It will be a narrative
> description of how to use Boost.Build that deepens progressively,
> beginning with the material you need to know in order to get started
> using it effectively.
I though about this too and decided this would be a good thing. The current
User manual has too many subsections.
> The current scope of the chapter is not bad, but
> given that the chapter will *not* attempt to provide complete coverage,
> some things should probably be pruned or moved to another area. For
> example, there's no need to cover "variant" as a feature. I would move
> the tiny bit of coverage of testing, and all mentions of
> hardcode-dll-paths, to a special section or separate chapter called
> "Testing and Debugging Software with Boost.Build."
Maybe hardcode-dll-paths deserves a tip in user manual but testing can be
moved to separate section. The only question I have is what other section
there will be. Say, where the overview of build process:
What I'd like to avoid is a manual in style of SCons. The problem with it is
that the structure is very flat, and it's very hard to find anything (at
least for me). Of course, section names like "Less Simple things to do with
Builds" contribute to the problem ;-)
We already have user/extender docs separation -- which is good, but I think we
should strive to avoid the user manual becoming a set of 30 sections without
> The "Detailed Reference" is mostly on target and correctly focused, but
> you should take care to keep "HowTo" information out of it. For
> example, the coverage of generated headers belongs in the User Guide.
I agree to this.
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