From: Jari Aalto <jari.aalto@cante.net>
Date: Sat, 02 Feb 2008 02:00:34 GMT
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Message-ID: <tzks5d8d.fsf@blue.sea.net>
In-Reply-To: <m3y7a46vmf.fsf@localhost.localdomain>

* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
* 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...]