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

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

quoted

he text should stand out as it it in environment,
which do not render termcap or other terminal capabilities.

Nevertheless it would be nice if our AsciiDoc configuration generated
italics or underline ...for manpage, and italics for HTML output for
placeholders, *in addition* to using angle parentheses (angle braces)
as delimites for placeholder parameters.

Sure, let's notify the asciidoc maintainer know about the wishes (CC'd)

quoted

http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html

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.

Errr... as far as I understand angles means placeholders, i.e. user
supplied input. You can use "[<file>...]" for optional placeholder;
everything which is not inside brackets is required.

If you choose to use the "optional", then you are _required_ to fill in
the mentioned item. The "[....]" is applied in your example as well. The
angles always keep it's nature, which is a requirement:

    4. Frequently, names of parameters that _require_ substitution(...)

        <parameter name>

It is used quite frequently in git manpages. Using parentheses to
delimit required alternate parts seems quite sensible.

  'git-branch' (-m | -M) [<oldbranch>] <newbranch>

The change is small, but important. People look at the manual paged any
will get the wrong impression on "the standard notation"

    git-branch {-m | -M} [<oldbranch>] <newbranch>
               =       =
               Change to use curlies

Note that in the POSIX/SUSV below parentheses / curly braces are not
mentioned.

True. The precedence of curlies has however been set long ago in
software books and in other Unix manaul pages.

quoted

-----------------------------------------------------------------------
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.

This means that <param> denotes placeholder: parameter that requires
**subsititution** (this part should be emphasized!). Such parameter
might have multi-word name. Such parameter might be required, but
might be optional.

It's never optional. For optionality, there is specific notation.
Everybody knows how to read these; what is required and what is not:

    command <arg> <arg>
    command <arg> [<message>]
    command <arg> [-lbc]

The <message> here is symbolic and not to be taken literally, whereas
text that is not eclosed inside angles, "-lbc", is to be taken
literally and interpreted by the rules of "set of options".

quoted

    [...]
    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.**

Note that is natural that '[' and ']' also are limits of mutualy
exclusive parameters: "cmd [ A | B ]" means "cmd" or "cmd A" or "cmd B".
It is not specified explicitely, but IMHO is quite natural. And it is
what is used in different manpages, see examples I have provided in my
previous post in this subthread.

We are in all agreement on this one.

quoted

    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...]

Note that one is not followed strictly, and one should take note of
that. For example to make sure that everybody knows that it is zero or
more one would use [<param>...], and to make use that it is one or
more one would use "<param> [<param>...]", just to be sure.

That's what it says. Outside of "[]" the ellipses mean (1+), indiside
"[]", by rules of the brackets, it means (0+). I forgot to paste the
two examples. Here:

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

Jari

-- 
Welcome to FOSS revolution: we fix and modify until it shines