Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes

Jari Aalto [off-list ref] writes:

* Fri 2008-02-01 Jakub Narebski [off-list ref]
* Message-Id: m37iho9b70.fsf@localhost.localdomain

quoted

'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