Re: [jamboost] V2 : documenting more rules in the docus

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2004-02-03 12:22:04

Samuel Krempp wrote:

> the online-help system is a good thing, but I don't think it's suited for
> the basic facilities a new typically will be looking for.
> I have a hard time guessing what module to look in for some rule I want info
> on, I'd much rather have an html page list most of the rules..
> 
> finding the right module where to look is not always intuitive, and just
> getting the list of modules as a starting point is :
> 1. slow to run (more than 20s on my system)
> 2. too detailed (so many modules you just can't expect the user to find the
> right module in which to look for the rule he wants help on)
> and the modules descriptions are not homogenous at all for now.
> 3. not as convenient for the user as a html page would be
> (clicking a link is so much better than copy-pasting to a command-line and
> running a help command)
> 
> Having the online-help system generate static docs once after each update
> would probably be ideal, but simply copying the most important rules to a
> page would already be an improvement.
> 
> IMO there should be a full page describing available rules, rather than a
> paragraph with a ew rules mentionned like it is at the moment in 
> http://zigzag.lvk.cs.msu.su/~ghost/Boost.Build.docs/advanced.html

The inline-help can generate that complete page of documentation for you. Try 
this...

cd boost-root/tools/build/v2
bjam --help-enable-detailed --help-output html --help-output-file reference 
--help-all

Which should produce a "reference.html" file. The generated docs are in 
alphabetical order. It includes modules, their variables, and rules.

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