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

From: Jakub Narebski <jnareb@gmail.com>
Date: Feb 2, 2008, 02:30 UTC
Message-ID: <m3tzks6qfm.fsf@localhost.localdomain>
In-Reply-To: <tzks5d8d.fsf@blue.sea.net>

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

Show 7 quoted lines

> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
> * Message-Id: m3y7a46vmf.fsf@localhost.localdomain
> > It seems that I was mistaken about that. Junio suggestion of following
> > others example and using "{}" curly brackets for grouping alternate
> > choices is IMHO a good solution.
> 
> That is another common syntax which I presented previously.

Well, at least rpm and cpio manpages uses it.

Show 6 quoted lines

> > The traditional manpages use /italics/ (usually rendered as
> > _underlined_ text on terminals) to denote placeholders (user supplied
> > input).
> 
> That does not matter. The 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.

Show 5 quoted lines

> > From http://www.linux.com/articles/34212
> 
> 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.

> I think Git's manual pages should follow standard notation. E.g. the
> use of parentheses should be replaced with curly braces.

It is used quite frequently in git manpages. Using parentheses to delimit required alternate parts seems quite sensible.

Examples of usage:

  'git-branch' (-m | -M) [<oldbranch>] <newbranch>
  'git-branch' (-d | -D) [-r] <branchname>...
  'git-commit' ... [(-c | -C) <commit> | -F <file> | -m <msg> | --amend]
  'git-name-rev' ... ( --all | --stdin | <committish>... )
  'git-show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
  'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>])

and even stranger

  'git-ls-files' ... (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*

Note that in the POSIX/SUSV below parentheses / curly braces are not mentioned.

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

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

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

I'm not for or against any form.

-- 
Jakub Narebski
Poland
ShadeHawk on #git