[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [PATCH] Move multiple targets

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2005-11-09 01:21:13 CET

Jim Blandy wrote:
>
> 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:
[...]
> So the notation's meaning is well-defined, and I believe it's been
> used throughout Subversion's code and internal docs.

Jim, yours may well have been the first use of an ellipsis within the
Subversion source code, and be widespread with the meaning you state, but I was
unaware of that use and meaning until now.

The meaning of "..." that was already in use in Subversion's help messages when
I rationalised them in 2003 is "occurring one or more times", like in the help
messages of typical GNU command-line programs:

   Usage: mkdir [OPTION] DIRECTORY...
   Usage: ls [OPTION]... [FILE]...

(Except we chose to put the ellipsis inside the brackets when both are used.)

> 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.

Indeed.

> 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'.

Well, we could put the appropriate explanation (not quite the above) somewhere,
along with the other rules such as that options can go anywhere, not just where
we write them in descriptions like:

   usage: 1. diff [-c M | -r N[:M]] [TARGET[@REV]...]

We wouldn't want this additional help appearing in the normal help messages for
each subcommand. "svn help help" would be a logical place.

> What I really want to know is: is 'ellipsis' singular or plural?

It's singular. Plural: "ellipses". It really means an omission; "..." is the
typical typographical symbol for an ellipsis, and has thus come to be called
"an ellipsis" itself.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Nov 9 01:22:17 2005

This is an archived mail posted to the Subversion Dev mailing list.