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

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

[Paul Bolle]

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(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index c04ae73..af68d69 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
-	[-m <msg>] <remote> <remote>...
+	[-m <msg>] <remote>...
 'git merge' <msg> HEAD <remote>...
 
 DESCRIPTION
-- 
1.6.4

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

[Nicolas Sebrecht]

The 11/08/09, Paul Bolle wrote:
> merge only requires one <remote>, so "<remote>..." should be used in the
> synopsis (and not "<remote> <remote>...").
> 

<...>

>  'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
> -	[-m <msg>] <remote> <remote>...
> +	[-m <msg>] <remote>...
>  'git merge' <msg> HEAD <remote>...

Shoudn't be 

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

or

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

instead?

-- 
Nicolas Sebrecht

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

[Paul Bolle]

On Tue, 2009-08-11 at 16:42 +0200, Nicolas Sebrecht wrote:
> The 11/08/09, Paul Bolle wrote:
> >  'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
> > -	[-m <msg>] <remote> <remote>...
> > +	[-m <msg>] <remote>...
> >  'git merge' <msg> HEAD <remote>...
> 
> Shoudn't be 
> 
>    [-m <msg>] <remote> [<remote>...]

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

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

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

> instead?

Paul Bolle

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

[Junio C Hamano]

Paul Bolle <pebolle@tiscali.nl> writes:

>> Shoudn't be 
>> 
>>    [-m <msg>] <remote> [<remote>...]
>
> 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".

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

[Jakub Narebski]

Junio C Hamano <gitster@pobox.com> writes:
> Paul Bolle <pebolle@tiscali.nl> writes:
> 
>>> Shoudn't be 
>>> 
>>>    [-m <msg>] <remote> [<remote>...]
>>
>> 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".

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? ;-))))

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Nicolas Sebrecht]

The 12/08/09, Jakub Narebski wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
> > 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.

This was my initial thought but...

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

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


-- 
Nicolas Sebrecht

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

[Paul Bolle]

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

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

[Junio C Hamano]

Paul Bolle <pebolle@tiscali.nl> writes:

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

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?

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

[Paul Bolle]

On Wed, 2009-08-12 at 13:31 -0700, Junio C Hamano wrote:
> Paul Bolle <pebolle@tiscali.nl> writes:
> 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?

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?