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