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

merge only requires one <remote>, so "<remote>..." should be used in the synopsis (and not "<remote> <remote>...").

Signed-off-by: Paul Bolle <pebolle@tiscali.nl>
---
 Documentation/git-merge.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

The 11/08/09, Paul Bolle wrote:

<...>

Shoudn't be 

   [-m <msg>] <remote> [<remote>...]

or

   [-m <msg>] <remote>[...]

instead?

On Tue, 2009-08-11 at 16:42 +0200, Nicolas Sebrecht wrote:

No, since "<remote>..." means one or more instances of the "<remote>" option.

Is "<$something>[...]" used anywhere? It makes little sense to me.

Paul Bolle

Paul Bolle <pebolle@tiscali.nl> writes:

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

Junio C Hamano <gitster@pobox.com> writes:

I would have thought that it makes more sense to have

  <something>...

for one or more, and

  [<something>... ]

for zero or more (optional one or more).

Documentation/DocumentationLanguage, anyone? ;-))))

The 12/08/09, Jakub Narebski wrote:

This was my initial thought but...

...their sense is what Posix states:

  Ellipses ( "..." ) are used to denote that one or more occurrences of an
  operand are allowed. When an option or an operand followed by ellipses
  is enclosed in brackets, zero or more options or operands can be
  specified. The form:

  utility_name [-g option_argument]...[operand...]

http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_01 (& 12.1.9)

On Tue, 2009-08-11 at 19:48 -0700, Junio C Hamano wrote: 

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

Paul Bolle <pebolle@tiscali.nl> writes:

You are absolutely right.  We would want consistency.

I do not have any objection to make sure that we uniformly use ellipses for one-or-more (and enclose them in [] if we want zero-or-more). Are these two that your patch touched the only ones that need fixing?

On Wed, 2009-08-12 at 13:31 -0700, Junio C Hamano wrote:

I guess not (these two were the ones that annoyed me enough to write patches when I read them in order to learn more about the commands they described).

What is the best way to fix small issues like this: one set of patches that tries to fix as much as possible in one go or a stream of little patches whenever similar issues are found in one of the documents?