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

* Fri 2008-02-01 Jakub Narebski [off-list ref]
* Message-Id: m3y7a46vmf.fsf@localhost.localdomain

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.

That is another common syntax which I presented previously.

The traditional manpages use /italics/ (usually rendered as
_underlined_ text on terminals) to denote placeholders (user supplied
input).

That does not matter. The text should stand out as it it in environment,
which do not render termcap or other terminal capabilities.

From http://www.linux.com/articles/34212

Here are the POSIX/Susv guidelines for the manual pages, I've marked the
relevant points with **....**. We were both right: Angles mean required
and grouping.

I think Git's manual pages should follow standard notation. E.g. the
use of parentheses should be replaced with curly braces.

Jari

-----------------------------------------------------------------------
http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11

12.1 Utility Argument Syntax
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01

    [...]

    4. Frequently, names of parameters that **require** substitution by
    actual values are shown with embedded underscores. Alternatively,
    parameters are shown as follows:

        <parameter name>

    The angle brackets are used for the symbolic grouping of a phrase
    representing a single parameter and conforming applications shall
    not include them in data submitted to the utility.

    [...]
    7. Arguments or option-arguments enclosed in the '[' and ']'
    notation are **optional** and can be omitted. Conforming applications
    shall not include the '[' and ']' symbols in data submitted to the
    utility.

    8. Arguments separated by the '|' vertical bar notation are
    **mutually-exclusive.**

    9. Ellipses ( "..." ) are used to denote that one or **more**
    occurrences of an option or operand are allowed. When an option or
    an operand followed by ellipses is enclosed in brackets, **zero** or
    more options or operands can be specified.

        utility_name [-g option_argument]...[operand...]