From: Jakub Narebski <jnareb@gmail.com>
Date: Fri, 01 Feb 2008 13:35:01 GMT
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Message-ID: <m33asc94xn.fsf@localhost.localdomain>
In-Reply-To: <1w7w966m.fsf@blue.sea.net>

Jari Aalto <jari.aalto@cante.net> writes:

> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
> * Message-Id: m37iho9b70.fsf@localhost.localdomain
> >
> >
> > 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
> > 'git-stash' [save [<message>...]]
> >
> > Angle brackets if I understand correctly are meant to denote part
> > which you have to enter, the user supplied info (the reast ou have to
> > enter literally).
> 
> Nowhere I have seen "(" parenheses to mean "required". 

The "(" parentheses does not mean "required". They do mean "group",
just like for regular expressions. So "A (B | C)" means "A B" or
"A C".

> The angle brackets are commonly used to tell that the part is to be
> required:
> 
>     command <option> <file ...>
> 
> Reads:
> 
>     command -l file.txt

No, the "<" angle brackets are meant to denote: substitute your own
(user) input, and not use as literal value. So "command <option>"
mean select one of options ant put it in place of "<option>"

> Whereas this has no known meaning:
> 
>     command (option) <file ...>

It doesn't have meaning if there is no alternative in "("
parentheses. So it makes sense to use:

      command (subcmd1 | subcmd2) <file ...>

but not

      command (option) <file ...>

> But this does:
> 
>     command [option] <file ...>

The "[" brackets mean both "optional" and "group" (to reduce number of
parentheses-like operators).
 
> That's why I suggested to use:
> 
>     git stash <list | show [<stash>] | apply [<stash>] | clear>
>     git stash [save [<message>...]]

I hope that I have explained above why I think it is wrong. IMHO the
"<" angle brackets mean: substitute your own input, and are not meant
for grouping (limiting where alternates start and where end).

> NOTE:
> 
> There exists curly braces notation that is sometimes used for
> "required" part, but that not very common elsewhere other than
> printed books from commercial vendors.
> 
>     command {one|two|three}
> 
> I would hesitate to select parentheses notation, which is relatively unknown
> to mean "required" in the context of command syntax SYNOPSIS.

Lack of "[" brackets means required.


By the way, is the format used by SYNOPSIS in manpages somewhere
specified, for example in some RFC, like BNF notation and BNF-like
notation used by RFCs is?

-- 
Jakub Narebski
Poland
ShadeHawk on #git