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

Jari Aalto [off-list ref] writes:

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

quoted

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.

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

quoted

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