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

* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
* Message-Id: m33asc94xn.fsf@localhost.localdomain
> 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".

In regexp language yes, but in describing the command syntaxes, I do not
have come accross this. Would you have descriptive examples?

>> The angle brackets are commonly used to tell that the part is to be
>> required:
>> 
>>     command <option> <file ...>
> 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>"

The angles primarily denote "required", and secondarily that you put
there there the asked input.


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

Tat is highly uncommon. In angle bracket notation this is unabiguous:

        command <parameter1|parameter2> <file ...>
                A                       B

In angles, it's clear that both A and B are required; in A, you must
choose one.

> The "[" brackets mean both "optional" and "group" (to reduce number of
> parentheses-like operators).

The bracket's primary meaning is to say "optional" in command
definitions. They do not "group"; they nest -- saying that there are
more "optionality" included.

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

Angle brackets do not mean "substitute your own input", but they deonote
a requirement; how the requirement is filled is done according to the
description in the documentation.

    command <"save"|"load">

In unabiguous way to say that the choices for words are "save" and
"load" of which one of them must be supplied.

The reason why angle angles are used is that they are shell redirection
metacharacters --- which never appear in that quality in standard manual
page SYNOPSIS. The angles cannot be understood in any other way than as
a "requirement" in the command definition.

Jari

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