Jari Aalto <jari.aalto@xxxxxxxxx> writes:
> * Fri 2008-02-01 Jakub Narebski <jnareb@xxxxxxxxx>
> * Message-Id: m37iho9b70.fsf@xxxxxxxxxxxxxxxxxxxxx
> >
> >
> > '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".
> 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).
> 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
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
