On Tue, 08 Nov 2005, Julian Foad wrote:
> Daniel Rall wrote:
> >On Mon, 07 Nov 2005, Julian Foad wrote:
> >
> >>Daniel Rall wrote:
> >>
> >>>It's not obvious to me that style #2 can take multiple source
> >>>arguments. How about something like:
> >>>
> >>> 2. move SRC [SRC2 SRC3 ...] DIR\n"
> >>
> >>No; that would be ugly and inconsistent with the rest of our help. Get
> >>used to "..." meaning "possibly repeated" :-)
> >
> >In that case, why not change it across all help text?
>
> You're not serious, are you? If you are, why would I want to make all help
> text consistently ugly? (It's ugly because it's long-winded, unclear how
> many sources are allowed, and arbitrary how many repeats you write in the
> help.) See my old thread "PATCH: help text: presentation of
> optionally-repeated arguments"
> <http://svn.haxx.se/dev/archive-2003-06/1642.shtml>.
>
> There are times when verbosity is useful, such as in a tutorial section in
> the book, but not here. The online help is a concise reference.
Julian, thanks for the thread reference. I was -- and am -- completely
serious about usability.
The help form of:
command ARG [ARG ...]
trades minimal repetition for a signficant improvement in clarity over
today's form of:
command ARG ...
especially to a new user ramping up on the tool. Albeit consistent
with other utilities and man pages, the current form offers no
affordance that additional arguments are optional, and little
affordance that additional arguments of the same type are allowed.
Given that the user ramp-up use case has a significant weight, the
trade-off of an incidental amount of additional "noise" seen by users
already comfortable with a function who are using the help for
reference is quite reasonable.
Though I'm saddened to see this usability regression in the
command-line client's help, neither do I have a desire for the help
output to be flip-flopping back and forth.
--
Daniel Rall
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Nov 8 20:24:27 2005