Re: [PATCH] Move multiple targets

On 11/8/05, Daniel Rall <dlr@collab.net> wrote:
>
> 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.

I think the ellipsis notation got introduced to Subversion when I used
it to describe skel formats in the database, and in some other places.
The way we use it there, 'FOO ...' always means 'zero or more repetitions
of FOO'. So:

ARG [ARG ...]

means, unambiguously, 'one or more ARGs', whereas:

ARG ...

means 'zero or more ARGs'. Assuming we're trying to use this notation in the
help messages:

- If it's acceptable to pass 'command' no arguments, then
'ARG [ARG ...]' is wrong.

- If 'command' requires at least one argument, then 'ARG ...' is
wrong.

- The brackets in '[ARG ...]' are redundant; without the brackets, it
means 'zero or more ARGs', so it's already optional.

So the notation's meaning is well-defined, and I believe it's been
used throughout Subversion's code and internal docs.

That all avoids the real question of whether it's actually a good
notation to use in help messages. Defining notational conventions and
sticking to them within the code and internal docs is okay, because
you expect contributors to learn the project's conventions.

But I'm not sure it's effective to assume the same of people reading
help messages. It seems clear that not everybody jumps to the same
interpretation unprompted.

Are there other precise notations we could expect to be widely
understood?

Or, should we just explain what it means in the help messages, including
text like the following:

'ARG ...' means 'zero or more ARGs'.
'ARG ARG ...' means 'one or more ARGs'.

What I really want to know is: is 'ellipsis' singular or plural?
Received on Tue Nov 8 23:11:25 2005