On Feb 12, 2018, at 4:36 PM, Richard Hipp <d...@sqlite.org> wrote:
> On 2/12/18, Warren Young <war...@etr-usa.com> wrote:
>> The ?VERSION? parameters to some commands are underdocumented for lack of
>> space in “fossil help” output.
> ...
>> Then we can say something like this in the fossil help output:
>>    "The VERSION argument can take many forms, all documented
>>     at https://fossil-scm.org/names”
> I would prefer to create a documentation page that is built into the
> Fossil binary, so that (1) it is useful when off-line and (2) to avoid
> unnecessary traffic to the website.

I considered that before posting, but I've observed that most (all?) fossil 
help pages fit onto a single screen with modern terminal window heights.  If 
you keep your terminal windows at 64 lines high — near my average, probably — 
an elinks dump of the current page takes 4 screenfuls.

So, either we end up with an uncommonly long page — and reignites the old 
$PAGER battle — or someone needs to do a whole lot of prose tightening.  

> There is precedent for this in the /wiki_rules and /md_rules pages.

That makes me wonder what the prefix for such pages would be.  (Yes, plural: 
all common parameters should have a help page to factor out repeated material.) 
 Some ideas:

1. It’s already case-sensitive, so give different output for “fossil help 
version” and “fossil help VERSION”.  “fossil help -a” should list both 
“version” and “VERSION”.

2. Continue with the Tclish optional-parameter syntax: accept “fossil help 
?version?”, and list “?version?” in “fossil help -a” output.  There’s the 
awkwardness of the possible conflict with shell globbing here, but it can be 
escaped if need be.  Command abbreviation allows “fossil he \?v”.

3. Option 3 sucks.  Don’t do option 3. :)  (“param_” prefix.)

I’m not sure which of options 1 and 2 are quicker for me to type.  It’s 
probably roughly a wash.
fossil-users mailing list

Reply via email to