Jari Aalto <jari.aalto@xxxxxxxxx> writes:
> * Fri 2008-02-01 Jakub Narebski <jnareb@xxxxxxxxx>
> * Message-Id: m33asc94xn.fsf@xxxxxxxxxxxxxxxxxxxxx
>> 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".
>
> In regexp language yes, but in describing the command syntaxes, I do not
> have come accross this. Would you have descriptive examples?
It seems that I was mistaken about that. Junio suggestion of following
others example and using "{}" curly brackets for grouping alternate
choices is IMHO a good solution.
...or perhaps not. For example synopsis for git-branch uses this syntax.
>>> 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.
The "<>" angle brackets does not denote required. Not in git manpages,
not in other manpages.
>> command (subcmd1 | subcmd2) <file ...>
>
> That is highly uncommon.
Perhaps, but is used in git manpages.
> 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.
THAT is highly uncommon.
>> 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.
They do group. "command [A|B]" means "command" or "command A" or
"command B".
>>> 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.
In our (git) manual pages "<text>" denotes placeholders.
The traditional manpages use /italics/ (usually rendered as
_underlined_ text on terminals) to denote placeholders (user supplied
input).
I think we better decide on syntax used in SYNOPSIS section, and
perhaps even document it CodingGuidelines
-- >8 --
>From http://www.linux.com/articles/34212
The SYNOPSIS section describes the usage of the command. In general,
it should look very much like a traditional usage message. [...]
By convention, optional arguments are surrounded by square brackets.
>From man(7)
SYNOPSIS briefly describes the command or function's interface. For
commands, this shows the syntax of the command and its argu-
ments (including options); boldface is used for as-is text
and italics are used to indicate replaceable arguments.
Brackets ([]) surround optional arguments, vertical bars (|)
separate choices, and ellipses (...) can be repeated.
>From manpages(5), Darwin documentation
MANUAL PAGE SYNTAX
In manual page syntax, anything in a normal text font is required
text. Anything in a boldface font is a flag or a subcommand.
Anything underlined is a user-specified argument such as a
filename.
Any argument surrounded by brackets is considered to be optional.
For example, [ filename ] would indicate an optional filename
argument.
Flags, arguments, or subcommands separated by a vertical
separator (|) are mutually exclusive. For example, if -a turns
on an option and -b turns off the option, the syntax for this
command might be -a | -b.
In some cases, you may even see entire groups of arguments
wrapped with brackets and separated by a vertical separator. This
is one way of show-ing showing ing that a command has more than
one valid syntax. In other manual pages, this is expressed by
having multiple lines in the synopsis, each of which begins with
the command name. The separated format is more com-mon common
mon (and more readable), but is not always possible for commands
with particularly complex syntax.
Finally, the most important notational convention is the use of
the ellipsis (...). This indicates that additional arguments may
be added at this point. Depending on the author, you may see
this written in one of two ways:
argument [ argument... ]
argument...
Some SYNOPSIS examples (where we use the following convention:
*bold*, _underlined_):
*patch* [_options_] [_originalfile_ [_patchfile_]] (shows nesting)
wget [_option_]... [_URL_]... (shows ellipsis)
rpm {-q|--query} [select-options] [query-options] (shows grouping)
date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]] (alt + grouping)
*kill [ -s* _signal_ *| -p ] [ -a ] [ -- ]* _pid_ ... (as above)
Inside yum(8), shows alternate which is also grouping
* clean [ packages | headers | metadata | cache | dbcache | all ]
Some SYNOPISIS examples from git manpages, in AsciiDoc syntax (sources):
'git-add' [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh]
[--] <filepattern>...
'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8]
[--3way] [--interactive] [--binary]
[--whitespace=<option>] [-C<n>] [-p<n>]
<mbox>|<Maildir>...
'git-apply' [--stat] [--numstat] [--summary] [--check] [--index]
[--apply] [--no-add] [--build-fake-ancestor <file>] [-R | --reverse]
[--allow-binary-replacement | --binary] [--reject] [-z]
[-pNUM] [-CNUM] [--inaccurate-eof] [--cached]
[--whitespace=<nowarn|warn|fix|error|error-all>]
[--exclude=PATH] [--verbose] [<patch>...]
'git-branch' [--color | --no-color] [-r | -a]
[-v [--abbrev=<length> | --no-abbrev]]
[--contains <commit>]
'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
'git-branch' (-m | -M) [<oldbranch>] <newbranch>
'git-branch' (-d | -D) [-r] <branchname>...
--
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
