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

* Sat 2008-02-02 Jakub Narebski <jnareb@gmail.com>
* Message-Id: m3prvf7ku2.fsf@localhost.localdomain
>>>> 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>

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

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