show value requirement and plurality of option in online help
FUJIWARA Katsunori
fujiwara at ascade.co.jp
Sat Feb 14 04:06:59 CST 2009
Hi.
Thanks for your comments.
At Fri, 13 Feb 2009 23:41:40 +0100,
Martin Geisler wrote:
>
> FUJIWARA Katsunori <fujiwara at ascade.co.jp> writes:
>
> > # HG changeset patch
> > # User FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
> > # Date 1234550162 -32400
> > # Node ID a836bf2f40f206bc475660f2b6fad27806cc8b57
> > # Parent 935be00913b190e1a954b5b72f68a23a48f0b979
> > show value requirement and plurality of option in online help
> >
> > this helps users to know what kind of option is:
> >
> > - no value is required(flag option)
> > - value is required
> > - value is required, and plurality is allowed
> >
> > each kinds are shown as below:
> >
> > -f --force force push
> > -e --ssh VAL specify ssh command to use
> > -r --rev VAL ... a specific revision up to which you would like to push
>
> Nice... I think the 'VAL' should somehow be changeable per option. So it
> could be:
>
> -e --ssh CMD specify ssh command to use
> -r --rev REV ... a specific revision up to which you would like to push
>
> instead. The 'REV' string can be made by taking the long option, but
> 'CMD' would have to be yet another argument in the tuples that specify
> the commandline flags. I don't know if we want this...
I think that 'CMD' is more suitable than 'VAL', too.
But auto-abbreviation in short length is difficult for:
- some options have very long name: e.g. 'files-with-matches'
- some options have name not suitable as value name(like --ssh, above)
And adding 'metavar' to tuples in option table does not seems to be
good.
> > diff -r 935be00913b1 -r a836bf2f40f2 mercurial/commands.py
> > --- a/mercurial/commands.py Sat Feb 14 03:35:52 2009 +0900
> > +++ b/mercurial/commands.py Sat Feb 14 03:36:02 2009 +0900
> > @@ -1490,8 +1490,13 @@
> > opt_output.append(("\n%s" % title, None))
> > for shortopt, longopt, default, desc in options:
> > if "DEPRECATED" in desc and not ui.verbose: continue
> > - opt_output.append(("%2s%s" % (shortopt and "-%s" % shortopt,
> > - longopt and " --%s" % longopt),
> > + addendum = ((isinstance(default, list) and ' VAL ...') or
> > + (((default is not None) and
> > + not isinstance(default, bool)) and ' VAL') or
> > + '')
>
> The strings need to be translatable, so they must be run through the _()
> function like the others. And 'VAL' is not so nice to translate, maybe
> 'VALUE' would be better.
Ok. I'll change it.
At Fri, 13 Feb 2009 16:27:51 -0800,
John Coomes wrote:
>
> Martin Geisler (mg at daimi.au.dk) wrote:
> > FUJIWARA Katsunori <fujiwara at ascade.co.jp> writes:
> > Also, I would remove the space before the '...', so it becomes
> >
> > -r --rev REV... a specific revision up to which you would like to push
>
> The elipsis (...) syntax, particularly without the space, suggests you
> can add an abitrary number of arguments (VALs) after the option. If I
> saw
>
> -I --include VAL...
>
> I would think this was allowed
>
> hg st -I *.c *.h *.py
>
> But mercurial requires this
>
> hg st -I *.c -I *.h -I *.py
I also think so, so place whitespace between option and 'VAL'.
> The distinction is that if an option is repeated, the arguments (VALs)
> are somehow added or combined, instead of the later argument replacing
> the earlier one. E.g.,
>
> hg st -R foo -R bar -I *.c -I *.h
>
> where bar replaces foo, but both *.c and *.h are kept. A possible
> alternative for the help text is
>
> -R --repository VAL repository root directory or symbolic path name
> -q --quiet suppress output
> -v --verbose enable additional output
> --config VAL [+] set/override config option
> -I --include VAL [+] include names matching the given patterns
>
> or a variation:
>
> -R --repository VAL repository root directory or symbolic path name
> -q --quiet suppress output
> -v --verbose enable additional output
> --config VAL [+] set/override config option
> -I --include VAL [+] include names matching the given patterns
>
> A one-line note at the bottom would provide a big clue.
>
> [+] multiple occurrences of this option are additive
It seems to be better than mine !
# my favorite is later :-)
Now, I think decision points are:
1. fixed ('VALUE') or meaning-full(e.g.: 'CMD') metavar:
1-1. fixed('VALUE')
1-2. meaning-full
How to get metavar name:
1-2-1. generate from long form
1-2-2. force implementor to add it to tuple in option table
2. How to notate multiple occurence handling type:
2-1. "--option VAL..."
2-2. "--option VAL ..."
2-3. "--option VAL [+]" and footnote
3. omit metavar for short form, or not
3-1. omit
3-2. not omit
# there is no missing one, isn't it ?
I like 1-1, 2-3 and 3-1.
--------------------
[FUJIWARA Katsunori] fujiwara at ascade.co.jp(foozy at lares.dti.ne.jp)
More information about the Mercurial-devel
mailing list