From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-31 03:17:28
On Friday 28 January 2005 19:32, David Abrahams wrote:
> > http://boost.org/boost-build2/doc/html/bbv2/advanced/jamfiles.html#bbv2.a
> > It mentions:
> > 1. "Common syntax" for declaring main targets
> > 2. Conditional requirements and alternatives
> > 3. Inline targets
> > 4. The glob rule
> > Essentially, it mentions almost everything you might need when declaring
> > a main target, so that user can know the list of features without reading
> > all of the docs.
> What you're getting at by saying "overview" still seems rather
> amorphous to me. I could interpret this as meaning "docs that cover
> everything in full detail." Try to figure out how to say what you
> mean more precisely; it will help both of us.
Try 2: "overview" is a combination of:
- fundamental concepts and how they relate together
- quick mention of all features
(e.g. all the various details of defining a main target).
> > This adds "installing" and "testing" and rearranges other sections a bit.
> > Will that work?
> I'm not sure installing and testing belong in the toutorial. By the
> time you're reading about those topics you should surely have learned
> the fundamentals!
The same can be said about any other topic, except for "Hello, world". I think
putting a large "Fundamentals" section too early will scare away the user.
> > I intended the structure of "Detailed reference" to mirror the
> > structure of "User documentation". That's why both have "Writing
> > Jamfiles" and "Build process" sections.
> It's confusing; at least it was for me. Unless the mirroring is
> perfect and your intentions are spelled out, I think it's best
> > I don't like that much. Guess we need to decide what is the role of
> > tutorial. Can we assume that user can read tutorial, start using
> > Boost.Build, and never need to look at the "Fundamental" section?
> No! The tutorial should be enough to get started, but not enough to
> really understand the system. For that you need fundamentals and
> deeper/broader information about the system that puts those
> fundamentals into play.
Then, I'll try to make tutorial into a short tour, starting from first project
and ending with installing.
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