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

From: Jari Aalto <jari.aalto@cante.net>
Date: Feb 2, 2008, 09:07 UTC
Message-ID: <ejbv6813.fsf@blue.sea.net>
In-Reply-To: <m3tzks6qfm.fsf@localhost.localdomain>

* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
* Message-Id: m3tzks6qfm.fsf@localhost.localdomain

Show 7 quoted lines

>> he text should stand out as it it in environment,
>> which do not render termcap or other terminal capabilities.
>
> Nevertheless it would be nice if our AsciiDoc configuration generated
> italics or underline ...for manpage, and italics for HTML output for
> placeholders, *in addition* to using angle parentheses (angle braces)
> as delimites for placeholder parameters.

Sure, let's notify the asciidoc maintainer know about the wishes (CC'd)

Show 9 quoted lines

>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
>>
>> Here are the POSIX/Susv guidelines for the manual pages, I've marked the
>> relevant points with **....**. We were both right: Angles mean required
>> and grouping.
>
> Errr... as far as I understand angles means placeholders, i.e. user
> supplied input. You can use "[<file>...]" for optional placeholder;
> everything which is not inside brackets is required.

If you choose to use the "optional", then you are _required_ to fill in the mentioned item. The "[....]" is applied in your example as well. The angles always keep it's nature, which is a requirement:

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

        <parameter name>

> It is used quite frequently in git manpages. Using parentheses to
> delimit required alternate parts seems quite sensible.
>
>   'git-branch' (-m | -M) [<oldbranch>] <newbranch>

The change is small, but important. People look at the manual paged any will get the wrong impression on "the standard notation"

    git-branch {-m | -M} [<oldbranch>] <newbranch>
               =       =
               Change to use curlies

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

Show 22 quoted lines

>> -----------------------------------------------------------------------
>> 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.
>
> This means that <param> denotes placeholder: parameter that requires
> **subsititution** (this part should be emphasized!). Such parameter
> might have multi-word name. Such parameter might be required, but
> might be optional.

It's never optional. For optionality, there is specific notation. Everybody knows how to read these; what is required and what is not:

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

Show 14 quoted lines

>>     [...]
>>     7. Arguments or option-arguments enclosed in the '[' and ']'
>>     notation are **optional** and can be omitted. Conforming applications
>>     shall not include the '[' and ']' symbols in data submitted to the
>>     utility.
>> 
>>     8. Arguments separated by the '|' vertical bar notation are
>>     **mutually-exclusive.**
>
> Note that is natural that '[' and ']' also are limits of mutualy
> exclusive parameters: "cmd [ A | B ]" means "cmd" or "cmd A" or "cmd B".
> It is not specified explicitely, but IMHO is quite natural. And it is
> what is used in different manpages, see examples I have provided in my
> previous post in this subthread.

We are in all agreement on this one.

Show 11 quoted lines

>>     9. Ellipses ( "..." ) are used to denote that one or **more**
>>     occurrences of an option or operand are allowed. When an option or
>>     an operand followed by ellipses is enclosed in brackets, **zero** or
>>     more options or operands can be specified.
>> 
>>         utility_name [-g option_argument]...[operand...]
>
> Note that one is not followed strictly, and one should take note of
> that. For example to make sure that everybody knows that it is zero or
> more one would use [<param>...], and to make use that it is one or
> more one would use "<param> [<param>...]", just to be sure.

That's what it says. Outside of "[]" the ellipses mean (1+), indiside "[]", by rules of the brackets, it means (0+). I forgot to paste the two examples. Here:

    utility_name -f option_argument...[operand...]
    utility_name [-g option_argument]...[operand...]

Jari

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