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

From: Jakub Narebski <jnareb@gmail.com>
Date: Feb 2, 2008, 15:25 UTC
Message-ID: <m38x23753j.fsf@localhost.localdomain>
In-Reply-To: <k5ln4eef.fsf@blue.sea.net>

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

Show 18 quoted lines

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

Show 11 quoted lines

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

Show 13 quoted lines

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

Show 6 quoted lines

> 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