Re: Documentation structure

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-22 10:36:17

Vladimir Prus <ghost_at_[hidden]> writes:

> On Saturday 23 July 2005 14:36, Alo Sarv wrote:
>
>> 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

Wait, wait! As Andrey recently wrote:

Also, at this point the user doesn't know what are toolsets and
projects. So we should restructure the documentation and put an
introductory chapter before the Installation chapter. It's
impossible to install BB without understanding the toolsets.

So clearly we need to lay some groundwork before we do "Hello World,"
don't we?

> - Project structure. 
> Some real-looking example with Jamroot and child Jamfiles

Okay, but we need to avoid descending into details like target
references, and we especially need to avoid the problems we currently
have of vague hints about these things -- even in later material

> - Libraries -- how to declare and how to use

Okay, but we need to resist the temptation to descend into details
like shared vs. static linking on Windows vs. Unix, PATH and
LD_LIBRARY_PATH, etc.

> - 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) ]
^^^^^^^
what do these mean?

I really dislike that title for a chapter. It encompasses too much,
including things that may be conceptually necessary for writing
Jamfiles, but are also conceptually necessary for understanding
Boost.Build as a whole. Things like targets and projects are highly
relevant to invoking bjam and extending Boost.Build. And separating
the command-line stuff from writing Jamfiles is artificial: you're
going to want to talk about the build request and how it interacts
with target requirements, about how a build of individual targets can
be requested from the command line.

I guess that "[Creating] Boost.Build Projects" might be an appropriate
title. For some reason, it seems to imply something more general than
just "writing jamfiles."

I think you ought to go back and think about the various things you're
talking about covering in this section and break each one down in more
detail into sub-elements, then see how they should be organized. In
fact, this whole outline needs more detail [I see you try to do that
below -- put that information in context]

>> 3. Invoking Bjam
>> [ includes detailed reference on command-line arguments, 

Okay...

>> how bjam scans Jamfiles in folders; how it works to achieve
>> targets; 

Those two are not about "invoking bjam" at all. I'm not sure what the
first one means. The second one has to -- at leaset to some extent --
be covered along with the previous chapter, or nobody will be able
understand what the Jamfiles they're writing mean.

>> multi-threaded compilations; what other black magic
>> can one do from commandline (overriding compile-commands, etc)
>> (6) ]

These are all good things to cover, but it's unclear that they're
properly organized. To tell, you'd have to do a more detailed
outline.

>> 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 makes a lot of sense as a separate section, but again you
need a more detailed outline.

> 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

I don't think that makes sense. Are we really going to introduce
people to features and properties in general as a separate topic
without showing them builtin features?

> - Shared/static libraries

The topic should be "libraries." Shared and static linkage issues
should be a subtopic.

> - testing rule
> - install rules
> - low-level rules (make and notfile)

Hmm, I'm not sure these should be in separate topics without an
overarching topic, "Globally Available Rules" or something. I don't
quite like the wording, but the point is to distinguish these rules,
which are automatically injected into Jamfiles for use without
qualification, from any old "builtin rule."

> - declaring project constants
>
> Any additions?

Explain target references early on.

Be sure to explain where target and project references are required
and clearly distinguish them from filesystem paths.

>> 5. Frequently Asked Questions
>> [ no changes needed ]

Well, we'll see about that :)

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

http://www.boost.org/tools/build/jam_src/index.html
http://www.boost.org/tools/build/jam_src/Jam.html

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com