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

* Sat 2008-02-02 Jakub Narebski [off-list ref]
* Message-Id: m3prvf7ku2.fsf@localhost.localdomain

quoted

quoted

quoted

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

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

        <parameter name>

Excuse me, but item is "required" if it is not marked (...)
Angle brackets does not mean required parameters. Please read
carefully; they denote parameters which _require substitution_ (note
those _two_ words together), i.e. parameters that the user need to
replace with appropriate input.

We're talking about the same subject. You emphasize the "substitution"
aspect, which by nature of the context, is inherently present. If you
read your paragraph, you also conclude "required" -- which I emphasised
initially.

SYNOPSIS dyntax:

    command option

Is inherently same as by spelling it more stronger:

    command <option>

But different from

    command "option"

The reason why I might be inclined to be on for angles is that they are
commonly used in BNF, and thus familiar to many:

    <A> ::= <B> <C>

quoted

quoted

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.

I have checked a bit of manual pages (in Linux), and only very few use
this convention. Do you have any statistics?

If you have ever skimmed Unix program book manuals, say before Linux, in
the Unix era, the industry quite feruently used angle curlies:

    command [<options>] {save|load}

Even today the braces are used to say "you must choose". E.g. in Oracle's
SQL manuals. This is quite self explanatory for the basic SQL:

    SELECT [DISTINCT] {*, column [AS ["<alias>"]], ...}
    FROM   <table>
    ;

quoted

quoted

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.

Again: it is required if it is not optional. There is no notation for
required parts, except that they are not marked as optional. In the
"cmd <file>" it is not angle brackets around <file> that denotes that
this parameter is requires, it is lacks of "[" "]" brackets around
parameter that tells it.

quoted

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

All true. And all what I wanted to tell.

I think we both read the instructions the same way. Perhaps our views do
not differ. I'd be surprised, because that's the convention people are
used to having read the notations so long.

Jari

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