Documentation structure (Was: [jamboost] Re: BBv1 / BBv2 thoughts/questions/comments)

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-08-12 04:51:57

On Saturday 23 July 2005 14:36, Alo Sarv wrote:

> >>5. Just a note about the manual from someone who just spent 4 days
> >>learning BB - BBv2 manual IS a lot better than v1 one, but the
> >>organization is bit rough, it's hard to find specific things in it, so
> >>you end up clicking through all the pages each time you need a specific
> >>thing. You can't just hop in there to look up a single thing, you'd have
> >>to read the entire manual in detail (at least once) to get the features
> >>overview ...
> >
> > Can you suggest the organization that would work better for you?
>
> 1. In the beginning of Tutorial, start out with something like is shown
.....

Noted, I've added your suggestons to
http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2/Documentation_Todo

> 7. Writing custom targets (I think I'm refering to "rules" actually
> here) - e.g. 'install' rule, which should copy files to system. Speaking
> of which - I don't see any reference of such commands, e.g. FileClone,
> SymLink, MkDir etc - in the manual.

That's because MkDir is not supported. Symlink is supported and deserves a mention.

> Overall, if you look at the manual index we currently see:
> * Tutorial
> * User documentation
> * Extended Manual
> * Detailed Reference
> * FAQ
>
> In tutorial section, it's normal to leave out feature listings, and
> focus on getting minimal examples running; altough I would recommend
> starting out with a full example (including all required files), and
> then explaining it line-by line, instead of showing snippets of code in
> each page.
>
> What exactly is the difference between UserDoc, ExtMan and DetRef ?
> Which one should I search if I want to do X ? Or Y ?

I agree this distinction does not work.

> What about hierarchy like this:
>
> 1. Getting Started
> [ includes installation and tutorial, with 1-2 small, but complete
> examples (points 1. and 2.) ]

What I'd prefer is this:

- "Hello world" -- a single Jamroot project
- Project structure. 
Some real-looking example with Jamroot and child Jamfiles
- Libraries -- how to declare and how to use
- Testing -- the "unit-test" rule
- Installing -- the "install" rule

So that this covers much of lifecycle of project.

> 2. Writing Jamfiles
> [ includes detailed reference of what you can do with Jamfiles, e.g
> targets, variables, dependencies, projects; starting simple, moving
> towards more complex things (3, 4, 5) ]
> 3. Invoking Bjam
> [ includes detailed reference on command-line arguments, how bjam
> scans Jamfiles in folders; how it works to achieve targets;
> multi-threaded compilations; what other black magic can one do from
> commandline (overriding compile-commands, etc) (6) ]
> 4. Extending Boost.Build
> [ includes overview of the tools/v2/ folder's contents; when/how to
> write custom jam code - e.g. new toolsets, OS features, custom
> targets (QT's uic / moc are good examples for this) (7, 8) ]

I think this organization is fine. The biggest question now is 
detailed structure of section 2. Topics should include:

- Language reference (current (just added) 
http://boost.org/boost-build2/doc/html/bbv2/advanced.html#bbv2.advanced.jam_language)
- Features and properties
- Configuration
- Declaring targets (current 
http://boost.org/boost-build2/doc/html/bbv2/advanced/targets.html)
- Builtin features
- Shared/static libraries
- testing rule
- install rules
- low-level rules (make and notfile)
- declaring project constants

Any additions?

> 5. Frequently Asked Questions
> [ no changes needed ]
>
> Another thing that I was unable to find in this manual was actual Jam
> language reference - had to do some googling around to find something on
> it; maybe there was a link somewhere in the manual, but I couldn't find
> it; anyway, shouldn't a build-system manual also include reference
> manual of the actual language used to extend the build system? External
> link would be sufficient.

I've just committed a change with jam langauge overview.

- Volodya

-- 
Vladimir Prus
http://vladimir_prus.blogspot.com
Boost.Build V2: http://boost.org/boost-build2