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.
The "<>" angle brackets does not denote required. Not in git manpages,
They do group. "command [A|B]" means "command" or "command A" or
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
...
