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

* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
* Message-Id: m37iho9b70.fsf@localhost.localdomain

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.

Sure, Jari