Re: [jamboost] Re: Documentation structure

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-09-23 10:06:45

On Thursday 22 September 2005 19:36, David Abrahams wrote:

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

Well, I tend to dislike documentation that don't have a simple example right 
away. We can remove "project" and everything else from "Hello, world" 
section.
In fact, version of "Hello, World" what Alexey has posted:

http://article.gmane.org/gmane.comp.lib.boost.build/10507

seems pretty good to me.

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

Agreed.

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

Agreed, that will be given in user manual in section about libraries.

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

Those are points that were raised by Alo Sarv in:
http://article.gmane.org/gmane.comp.lib.boost.build/9752

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

In fact, I'm now thinking that we should try flat structure for the whole 
"User manual section". 

> > 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.j
> >am_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?

All builting features? There's a lot of them.

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

Agreed.

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

Ok, I'll try to prepare a more detailed outline and post it on Monday.

- Volodya

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