Re: [PATCH] Re: [TRIVIAL] Documentation: merge: one <remote> is required

[Paul Bolle <pebolle@tiscali.nl>]

On Tue, 2009-08-11 at 19:48 -0700, Junio C Hamano wrote: 
> Paul Bolle <pebolle@tiscali.nl> writes:
> > No, since "<remote>..." means one or more instances of the "<remote>"
> > option.  
> 
> Does it really?
> 
> After you brought up this "one or more", I re-read the docs your patches
> touched, thinking that the author might have meant 'zero or more of A'
> with these '<A>...'  notation.
> 
> And I realized that they made perfect sense.
> 
> In general, you can write:
> 
> 	<command> ...
> 
> and read this as "The <command> can be followed by nothing or something
> (zero or more) of unspecified kind".  If <command> takes only one type of
> zero or more things, you can _clarify the ellipses_ by prefixing them with
> what kind of "stuff" you are talking about:
> 
> 	<command> <remote>...
> 
> and read this as "The <command> can be followed by nothing or something
> (zero or more) of <remote>s".
> 
> On the other hand, you can also say (note that the ellipses stand on their
> own and are not associated with <remote>):
> 
> 	<command> <remote> ...
> 
> and read this as "It takes one <remote> followed by nothing or something
> (zero or more) of unspecified kind".

It is (now) clear to me that in these two documents the author(s) meant
"zero or more". Still, I find the "one or more" meaning more obvious.
The (GNU) manpages of "cp", "mv", "rm", and "ls" use the "one or more"
meaning. (Note that the explanation quoted above can easily be rewritten
with for "one or more" meaning and still make sense.) 

Anyway, I now see that "zero or more" is used quite a lot in git's
manpages. But, that meaning doesn't fit so well with the
"[<command>...]" syntax that is also used a lot in these manpages. (I
find "optionally one or more of <command>" more obvious as otherwise
"<command>..." and "[<command>...]" are basically identical.)

Confusingly, as far as I can see, the manpages of the following commands
seem to use the "one or more" meaning:
    git merge-base
    git mv
    git name-rev
    git rm
    git send-email
    git tag -d
    git tag -v
    git verify-tag

("git mv" uses both meanings in its synopsis. The two "git tag"
invocations seem to do nothing with zero arguments and do not return an
error.)

If the above commands really use the "one or more" meaning, that would
mean both versions are used in the documentation. I'd say it would be
better to stick to one meaning throughout the manpages.


Paul Bolle