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

From: Jakub Narebski <jnareb@gmail.com>
Date: Feb 1, 2008, 13:35 UTC
Message-ID: <m33asc94xn.fsf@localhost.localdomain>
In-Reply-To: <1w7w966m.fsf@blue.sea.net>

Jari Aalto <jari.aalto@cante.net> writes:

Show 12 quoted lines

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

Show 8 quoted lines

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

Show 10 quoted lines

> 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