From: Jari Aalto <jari.aalto@cante.net>
Date: Fri, 01 Feb 2008 13:06:57 GMT
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Message-ID: <1w7w966m.fsf@blue.sea.net>
In-Reply-To: <m37iho9b70.fsf@localhost.localdomain>

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

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