From: Jakub Narebski <jnareb@gmail.com>
Date: Sat, 02 Feb 2008 15:25:45 GMT
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Message-ID: <m38x23753j.fsf@localhost.localdomain>
In-Reply-To: <k5ln4eef.fsf@blue.sea.net>

Jari Aalto <jari.aalto@cante.net> writes:

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

No, I would not.  The fact that the parameter _requires substitution_
(is placeholder) is orthogonal (independent) of the fact if the
parameter is required or optional.  Angle brackets (and italic or
underline) means "placeholder", while lack of angle brackets (and
bold) means "literal".  Square brackets means "optional", while lack
of brackets means "required"

> SYNOPSIS syntax:
> 
>     command option
> 
> Is inherently same as by spelling it more stronger:
> 
>     command <option>
> 
> But different from
> 
>     command "option"

I would say that in

      command option

the 'option' string is literal, while in

      command <option>

you have to substitute actual option in the place of '<option>'.
I don't think that "option" for literals is used in SYNOPSIS in
manpages, even if this notation is used elsewhere (BNF, RFC).

>>>> 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 manual 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 frequently used angle curlies:
> 
>     command [<options>] {save|load}

>From what I can see in Linux manuals usually this is dealt by either
relying on generic placeholders, and describing optional parts in
detailed description, e.g.

      tar <operation> [options]

or by splitting synopsis into separate lines, each line dealing with
alternate syntax, e.g.

       install [OPTION]... SOURCE DEST           (1st format)
       install [OPTION]... SOURCE... DIRECTORY   (2nd format)
       install -d [OPTION]... DIRECTORY...       (3rd format)

But in some cases using alternates which are not optional (i.e. not 
[ A | B | C ]) is a better solution. In some cases grouping is natural
and does not need delimiters, for example "--opt=A|B", but in some
cases delimiters are required, either "(-d | -D)" or "{-d | -D}"

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

I'm just more used to "(a | b)" from regular expressions, and AFAIK
also BNFs, and "{a,b}", with comma ',' instead of vertical bar '|' to
denote alternates (mutually exclusive parts), like in [some] shell
globing, and in above documentation example.

This will be last post from me in this sub-thread. I think we have
exhausted this part of discussion...

-- 
Jakub Narebski
Poland
ShadeHawk on #git