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

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

> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
> * Message-Id: m33asc94xn.fsf@localhost.localdomain
>> Jari Aalto <jari.aalto@cante.net> writes:
>>
>>> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
>>> * Message-Id: m37iho9b70.fsf@localhost.localdomain
>>>>
>>>>
>>>> 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
>>>> 'git-stash' [save [<message>...]]
>>>>
>>>> Angle brackets if I understand correctly are meant to denote part
>>>> which you have to enter, the user supplied info (the reast ou have to
>>>> enter literally).
>>> 
>>> Nowhere I have seen "(" parenheses to mean "required". 
>>
>> The "(" parentheses does not mean "required". They do mean "group",
>> just like for regular expressions. So "A (B | C)" means "A B" or
>> "A C".
> 
> In regexp language yes, but in describing the command syntaxes, I do not
> have come accross this. Would you have descriptive examples?

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.

...or perhaps not. For example synopsis for git-branch uses this syntax.

>>> The angle brackets are commonly used to tell that the part is to be
>>> required:
>>> 
>>>     command <option> <file ...>
>>
>> No, the "<" angle brackets are meant to denote: substitute your own
>> (user) input, and not use as literal value. So "command <option>"
>> mean select one of options ant put it in place of "<option>"
> 
> The angles primarily denote "required", and secondarily that you put
> there there the asked input.

The "<>" angle brackets does not denote required. Not in git manpages,
not in other manpages.

>>       command (subcmd1 | subcmd2) <file ...>
> 
> That is highly uncommon. 

Perhaps, but is used in git manpages.

> In angle bracket notation this is unabiguous:
> 
>         command <parameter1|parameter2> <file ...>
>                 A                       B
> 
> In angles, it's clear that both A and B are required; in A, you must
> choose one.

THAT is highly uncommon.

>> The "[" brackets mean both "optional" and "group" (to reduce number of
>> parentheses-like operators).
> 
> The bracket's primary meaning is to say "optional" in command
> definitions. They do not "group"; they nest -- saying that there are
> more "optionality" included.

They do group. "command [A|B]" means "command" or "command A" or
"command B".

>>> That's why I suggested to use:
>>> 
>>>     git stash <list | show [<stash>] | apply [<stash>] | clear>
>>>     git stash [save [<message>...]]
>>
>> I hope that I have explained above why I think it is wrong. IMHO the
>> "<" angle brackets mean: substitute your own input, and are not meant
>> for grouping (limiting where alternates start and where end).
> 
> Angle brackets do not mean "substitute your own input", but they deonote
> a requirement; how the requirement is filled is done according to the
> description in the documentation.
> 
>     command <"save"|"load">
> 
> In unabiguous way to say that the choices for words are "save" and
> "load" of which one of them must be supplied.

In our (git) manual pages "<text>" denotes placeholders.

The traditional manpages use /italics/ (usually rendered as
_underlined_ text on terminals) to denote placeholders (user supplied
input).

I think we better decide on syntax used in SYNOPSIS section, and
perhaps even document it CodingGuidelines


-- >8 --

>From http://www.linux.com/articles/34212

  The SYNOPSIS section describes the usage of the command. In general,
  it should look very much like a traditional usage message. [...]
  By convention, optional arguments are surrounded by square brackets.

>From man(7)

  SYNOPSIS    briefly describes the command or function's  interface.   For
              commands,  this shows the syntax of the command and its argu-
              ments (including options); boldface is used  for  as-is  text
              and  italics  are  used  to  indicate  replaceable arguments.
              Brackets ([]) surround optional arguments, vertical bars  (|)
              separate  choices,  and  ellipses (...) can be repeated.

>From manpages(5), Darwin documentation

 MANUAL PAGE SYNTAX
     In manual page syntax, anything in a normal text font is required
     text.  Anything in a boldface font is a flag or a subcommand.
     Anything underlined is a user-specified argument such as a
     filename.

     Any argument surrounded by brackets is considered to be optional.
     For example, [ filename ] would indicate an optional filename
     argument.

     Flags, arguments, or subcommands separated by a vertical
     separator (|) are mutually exclusive.  For example, if -a turns
     on an option and -b turns off the option, the syntax for this
     command might be -a | -b.

     In some cases, you may even see entire groups of arguments
     wrapped with brackets and separated by a vertical separator. This
     is one way of show-ing showing ing that a command has more than
     one valid syntax.  In other manual pages, this is expressed by
     having multiple lines in the synopsis, each of which begins with
     the command name.  The separated format is more com-mon common
     mon (and more readable), but is not always possible for commands
     with particularly complex syntax.

     Finally, the most important notational convention is the use of
     the ellipsis (...).  This indicates that additional arguments may
     be added at this point.  Depending on the author, you may see
     this written in one of two ways:

     argument [ argument... ]

     argument...


Some SYNOPSIS examples (where we use the following convention:
*bold*, _underlined_):

  *patch* [_options_] [_originalfile_ [_patchfile_]]    (shows nesting)
  wget [_option_]... [_URL_]...                         (shows ellipsis)
  rpm {-q|--query} [select-options] [query-options]     (shows grouping)
  date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]   (alt + grouping)
  *kill [ -s* _signal_ *| -p ] [ -a ] [ -- ]* _pid_ ... (as above)

Inside yum(8), shows alternate which is also grouping
  * clean [ packages | headers | metadata | cache | dbcache | all ]


Some SYNOPISIS examples from git manpages, in AsciiDoc syntax (sources):

'git-add' [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh]
          [--] <filepattern>...

'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8]
         [--3way] [--interactive] [--binary]
         [--whitespace=<option>] [-C<n>] [-p<n>]
         <mbox>|<Maildir>...

'git-apply' [--stat] [--numstat] [--summary] [--check] [--index]
	  [--apply] [--no-add] [--build-fake-ancestor <file>] [-R | --reverse]
	  [--allow-binary-replacement | --binary] [--reject] [-z]
	  [-pNUM] [-CNUM] [--inaccurate-eof] [--cached]
	  [--whitespace=<nowarn|warn|fix|error|error-all>]
	  [--exclude=PATH] [--verbose] [<patch>...]

'git-branch' [--color | --no-color] [-r | -a]
	   [-v [--abbrev=<length> | --no-abbrev]]
	   [--contains <commit>]
'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
'git-branch' (-m | -M) [<oldbranch>] <newbranch>
'git-branch' (-d | -D) [-r] <branchname>...
-- 
Jakub Narebski
Poland
ShadeHawk on #git