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

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2005-07-06 09:39:38

Vladimir Prus wrote:
> On Sunday 19 June 2005 02:12, David Abrahams wrote:
> 
>>It seems a bit weird that --help-usage shows me the options and
>>--help-options shows me... something else. Am I missing something?
> 
> I don't understand this either. I think the --help output should be no longer 
> than this:
> 
> Boost.Build V2 Milestone whatever.
> 
> For basic command line syntax use:
> 
> --help-command-line
> 
> For information on building this project use:
> 
> --help-project
> 
> For Boost.Build internal documentation use:
> 
> --help-internals
> 
> The --help-project would print the value of 'project-help' constant in the 
> current Jamfile, and the output of --help-command-line will be:
> 
> Command line syntax:
> 
> bjam [options] [properties] [targets]
> 
> Options, properties and targets can be specified in any order.
> 
> To build all targets in current Jamfile:
> 
> bjam
> 
> 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.

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.

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

And no I don't mind that the initial help is long. I'd rather err on the 
side of too much information rather than have users be discouraged.

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

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

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.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - Grafik/jabber.org