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?
>
>>> 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
Actually, I've never seen any less-than-greater-than used to
group alternates command description of traditional manual
pages. So I'd say both may be unusual, but yours is a lot more
unusual.
For example, GNU 'tar' uses | for alternates, but it does not
mark grouping:
SYNOPSIS
tar [ - ] A --catenate --concatenate | c --create | d --diff --compare
| --delete | r --append | t --list | u --update | x --extract --get [
options ] pathname [ pathname ... ]
which is horribly confusing to read.
GNU 'cpio' makes it somewhat easier to read by listing
subcommands separately:
SYNOPSIS
cpio {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O
[[user@]host:]archive] [-F [[user@]host:]archive]
[--file=[[user@]host:]archive] [--format=format] [--message=message]
[--null] [--reset-access-time] [--verbose] [--dot] [--append] [--block-
size=blocks] [--dereference] [--io-size=bytes] [--quiet]
[--force-local] [--rsh-command=command] [--help] [--version] < name-
list [> archive]
cpio {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]
...
But when they have alternates, they use braces {} to group them.
Solaris 'tar' lists subcommand separately, and seems to use
braces {} for grouping alternates:
SYNOPSIS
tar c [ bBeEfFhiklnopPqvwX [ 0-7 ] ] [ block ] [
tarfile ] [ exclude-file ] { -I include-file | -C direc-
tory | file | file } ...
In our manual pages, less-than-greater-than around names are
very often used to mark placeholders. If you want to say zero
or more files, you would typically say:
command <file>...
Using something other than less-than-greater-than to group
alternates would make things easier to differentiate. If we
used braces {} it _might_ have been more similar to what other
people have traditionally done.
-
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
