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

* Fri 2008-02-01 Jakub Narebski [off-list ref]
* 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 angle
brackets are commonly used to tell that the part is to be required:

    command <option> <file ...>

Reads:

    command -l file.txt

Whereas this has no known meaning:

    command (option) <file ...>

But this does:

    command [option] <file ...>

That's why I suggested to use:

    git stash <list | show [<stash>] | apply [<stash>] | clear>
    git stash [save [<message>...]]

The nesting of <'s is normal. The above reads:

    1st line: You have to select one command, one of the alternatives
    listed inside <...>: either "list", "show" ...

    2nd line: you can type 'git stash', 'git stash save' or supply
    additional message with the stash.

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.

quoted

Welcome to FOSS revolution: we fix and modify until it shines

Nice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?

Sure,
Jari