Re: [jamboost] --help-options / --help-usage

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-07-06 09:48:30

On Wednesday 06 July 2005 18:39, Rene Rivera wrote:

> > To build target 'foo' in directory 'sub' in debug and release
> > variants:
> >
> > bjam variant=release variant=debug sub//foo
> >
> > To rebuild a single file in current project:
> >
> > bjam -a foo.o
> >
> > Important options:
> >
> > --clean Remove the named targets
> > -a Rebuild everything
> > -n Don't execute the command, only print them
> > -d+2 Show all executed commands
> > -q Stop at first error
> >
> >
> > The idea is that --help should not list too many information that's no
> > needed for ordinary users. Comments?
>
> I think that right there you have a problem. I would consider the "-a"
> and "-n", options that ordinary users would be interested in. And given
> that you labeled them under "Important options:" also points to you
> thinking the same. Also using "--help-project" just adds another step
> for the user to what I would consider *very* important information which
> I would put ahead of all others.
>
> Ideally what we want to do is show information from most to least
> important. The least important information can be hidden behind
> additional --help-* invocations. I would prefer that --help show
> something like:
>
> ====
> Project:
>
> [scanned Jamfile docs here]
>
> You can use "--help-project" to obtain additional information
> on this project.

What would --help-project produce in addition to 'scanned Jamfile docs'? Whole 
site-config.jam/user-config.jam/.... hierarchy? And if I run bjam in 
libs/filesystem/build and Jamfile has no docs, will I see Boost-wide docs, or 
not?

> Important Options:
>
> * --clean; Remove the named targets
> * -a; Rebuild everything
> * -n; Don't execute the command, only print them
> * -d+2; Show all executed commands
> * -q; Stop at first error
>
> Available Help:
>
> These are the available options for obtaining documentation. Some
> options have additional instructions on how to get more detailed
> information. Multiple options are allowed and sometimes required.
> For example, the options that configure the help system still
> require a regular help request option for any output to be
> generated.

Probably this text is too long. Will it hurt much if we retain just the first 
sentence?

> * --help; This help message.
> * --help-project; Information on building for this project.
> * --help-command; Command line syntax and available options.
> * --help-doc; How to control the output of this help text.
> * --help-internal; Boost.Build implementation details.

Ok, this looks fine.

> > BTW, I don't like the current way options are handled. In
> > kernel/bootstrap.jam, we loop over all ARGV elements. If it matches --.*
> > we look for a module in the "options" directory. If found we load it and
> > call the 'process' methods.
> >
> > Two problems:
> > 1. Given that there's a single module in the 'options' dir, the above
> > look like overgeneralization.
>
> But what happens when we have more than one module in the 'options' dir?
> We did it that way precisely because we wanted to support adding option
> handling modules as needed.

I think that since we don't have any other modules, this is premature 
generalization. 

> > 2. I need to handle --help-project after user-config.jam is loaded, and
> > that happens only in build-system.jam. The only approach I see is
> > handling --help in build-system.jam, and that will make the logic in
> > 'kernel/bootstrap.jam' just unused.
>
> I just don't see the point of having the 'project-help' rule. It goes
> against the current design of the 'doc' module and does not have
> anything that the 'doc' module can't already do with the file scanning.
> What I said before is still what I think is most flexible and fits with
> the current 'doc' design. Once upon a time I wrote:
>
> [ ] Make --help produce any help docs in the "boost-root.jam",
> "site-config.jam", "user-config.jam", "boost-build.jam", root/Jamfile,
> and subdir/Jamfile in that order.
>
> And by "help docs" I mean the regular scanning for docs in comments that
> we already do. 

Ah, I did not understood this part of your suggestion.

> No new rules required, and makes for consistent handling 
> of the docs. The only amendment I would now make to the above given the
> context of this thread would be to split that into two parts:
>
> a) Make --help produce any help docs in root/Jamfile and subdir/Jamfile,
> integrated into the rest of the docs printed by the '--help' option as
> above.

In what order?

> b) Make --help-project produce any help docs in boost-root.jam,
> site-config.jam, user-config.jam, boost-build.jam, root/Jamfile, and
> subdir/Jamfile in that order.

Ok, this suggestion seem OK with me. The only issue (and that's why I've 
suggested separate rule in Jamfile), is that I don't yet quite understand the 
scanning of docs. Is it easy to add scanning of Jamfiles to doc.jam?

- Volodya

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