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

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2005-07-06 10:33:52

Vladimir Prus wrote:
> On Wednesday 06 July 2005 18:39, Rene Rivera wrote:
>>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?

Yes.

> And if I run bjam in 
> libs/filesystem/build and Jamfile has no docs, will I see Boost-wide docs, or 
> not?

Yes, i.e. what I refer to below as "root/Jamfile".

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

No, I don't think it would hurt. We would have to move that explanation 
someplace else though, possibly into --help-command?

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

Possibly, but is it costing us anything at this point? There was a time 
when I had another module in options, for manipulating toolsets, it was 
lost in the sands of computer upgrades though.

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

Good question... Most to least specific might be the best choice to be 
consistent, i.e. subdir/Jamfile then root/Jamfile. But the other way 
might read better for people. I'd say we do it most-to-least and 
consider the other way when we can see the docs in action.

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

Very easy. Actually doc.jam doesn't know anything about finding files. 
All it does it given a file it will scan and print out the docs. The 
finding of files is currently done in options/help.jam and it just calls:

doc.do-scan ( modules-files + : action * )

So if we have the paths to the Jamfiles we can just call the do-scan 
rule: doc.do-scan path-to/Jamfile : print-help-module ; The 
print-help-module just prints the help docs at the top of the file.

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