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

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

[Jari Aalto]

Change (list|...) to <list|...> to denote required command. Adjust
the 'save' command syntax to better reflect the call parameters:
[save] [message...] => [save [message...]].

Signed-off-by: Jari Aalto <jari.aalto AT cante.net>
---
 Documentation/git-stash.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 9889806..e713e48 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -8,8 +8,8 @@ git-stash - Stash the changes in a dirty working directory away
 SYNOPSIS
 --------
 [verse]
-'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
-'git-stash' [save] [message...]
+'git-stash' <list | show [<stash>] | apply [<stash>] | clear>
+'git-stash' [save [message...]]
 
 DESCRIPTION
 -----------
-- 
1.5.4-rc5.GIT-dirty


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

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

[Jakub Narebski]

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

> Change (list|...) to <list|...> to denote required command. Adjust
> the 'save' command syntax to better reflect the call parameters:
> [save] [message...] => [save [message...]].

While I agree with the second change, i.e. the "[save [message...]]"
part, I think that the first part is a mistake.  Parentheses does not
imply the optional part: brackets do; parentheses are meant to
delimit the alternatives.  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).

So IMVHO the SYNOPSIS for git-stash(1) should read:

SYNOPSIS
--------
[verse]
'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
'git-stash' [save [<message>...]]

or

'git-stash' [save [<message...>]]

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

Nice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Jari Aalto]

* 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 angle
brackets are commonly used to tell that the part is to be required:

    command <option> <file ...>

Reads:

    command -l file.txt

Whereas this has no known meaning:

    command (option) <file ...>

But this does:

    command [option] <file ...>

That's why I suggested to use:

    git stash <list | show [<stash>] | apply [<stash>] | clear>
    git stash [save [<message>...]]

The nesting of <'s is normal. The above reads:

    1st line: You have to select one command, one of the alternatives
    listed inside <...>: either "list", "show" ...

    2nd line: you can type 'git stash', 'git stash save' or supply
    additional message with the stash.

NOTE:

There exists curly braces notation that is sometimes used for
"required" part, but that not very common elsewhere other than
printed books from commercial vendors.

    command {one|two|three}

I would hesitate to select parentheses notation, which is relatively unknown
to mean "required" in the context of command syntax SYNOPSIS.

>> Welcome to FOSS revolution: we fix and modify until it shines
>
> Nice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?

Sure,
Jari

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

[Jakub Narebski]

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

> The angle brackets are commonly used to tell that the part is to be
> required:
> 
>     command <option> <file ...>
> 
> Reads:
> 
>     command -l file.txt

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

> Whereas this has no known meaning:
> 
>     command (option) <file ...>

It doesn't have meaning if there is no alternative in "("
parentheses. So it makes sense to use:

      command (subcmd1 | subcmd2) <file ...>

but not

      command (option) <file ...>

> But this does:
> 
>     command [option] <file ...>

The "[" brackets mean both "optional" and "group" (to reduce number of
parentheses-like operators).
 
> 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).

> NOTE:
> 
> There exists curly braces notation that is sometimes used for
> "required" part, but that not very common elsewhere other than
> printed books from commercial vendors.
> 
>     command {one|two|three}
> 
> I would hesitate to select parentheses notation, which is relatively unknown
> to mean "required" in the context of command syntax SYNOPSIS.

Lack of "[" brackets means required.


By the way, is the format used by SYNOPSIS in manpages somewhere
specified, for example in some RFC, like BNF notation and BNF-like
notation used by RFCs is?

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Jari Aalto]

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

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


>       command (subcmd1 | subcmd2) <file ...>

Tat is highly uncommon. 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.

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

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

The reason why angle angles are used is that they are shell redirection
metacharacters --- which never appear in that quality in standard manual
page SYNOPSIS. The angles cannot be understood in any other way than as
a "requirement" in the command definition.

Jari

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

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

[Junio C Hamano]

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?
>
>>> 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.
>
>>       command (subcmd1 | subcmd2) <file ...>
>
> Tat is highly uncommon. In angle bracket notation this is unabiguous:
>
>         command <parameter1|parameter2> <file ...>
>                 A                       B

Actually, I've never seen any less-than-greater-than used to
group alternates command description of traditional manual
pages.  So I'd say both may be unusual, but yours is a lot more
unusual.

For example, GNU 'tar' uses | for alternates, but it does not
mark grouping:

  SYNOPSIS
    tar  [ - ] A --catenate --concatenate | c --create | d --diff --compare
    | --delete | r --append | t --list | u --update | x --extract  --get  [
    options ] pathname [ pathname ... ]

which is horribly confusing to read.

GNU 'cpio' makes it somewhat easier to read by listing
subcommands separately:

  SYNOPSIS
    cpio  {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O
    [[user@]host:]archive]            [-F            [[user@]host:]archive]
    [--file=[[user@]host:]archive]   [--format=format]  [--message=message]
    [--null] [--reset-access-time] [--verbose] [--dot] [--append] [--block-
    size=blocks]      [--dereference]      [--io-size=bytes]      [--quiet]
    [--force-local] [--rsh-command=command] [--help]  [--version]  <  name-
    list [> archive]

    cpio  {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]
    ...

But when they have alternates, they use braces {} to group them.

Solaris 'tar' lists subcommand separately, and seems to use
braces {} for grouping alternates:

  SYNOPSIS
    tar  c   [   bBeEfFhiklnopPqvwX   [  0-7  ]  ]  [ block ]  [
    tarfile ]  [ exclude-file ]  { -I include-file  |  -C direc-
    tory  | file  | file }  ...


In our manual pages, less-than-greater-than around names are
very often used to mark placeholders.  If you want to say zero
or more files, you would typically say:

	command <file>...

Using something other than less-than-greater-than to group
alternates would make things easier to differentiate.  If we
used braces {} it _might_ have been more similar to what other
people have traditionally done.

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

[Jari Aalto]

* Fri 2008-02-01 Junio C Hamano <gitster@pobox.com>
* Message-Id: 7vejbw8die.fsf@gitster.siamese.dyndns.org
> GNU 'cpio' makes it somewhat easier to read by listing
> subcommands separately:
>
>   SYNOPSIS
>     cpio  {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O
>     [[user@]host:]archive]            [-F            [[user@]host:]archive]
>     [--file=[[user@]host:]archive]   [--format=format]  [--message=message]
>     [--null] [--reset-access-time] [--verbose] [--dot] [--append] [--block-
>     size=blocks]      [--dereference]      [--io-size=bytes]      [--quiet]
>     [--force-local] [--rsh-command=command] [--help]  [--version]  <  name-
>     list [> archive]
>
>     cpio  {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]

Yes, I previously presented that the other common syntax was using curly
braces, like here. I think we shoudl select it.

Jari

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

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

[Jari Aalto]

* Fri 2008-02-01 Junio C Hamano <gitster@pobox.com>
* Message-Id: 7vejbw8die.fsf@gitster.siamese.dyndns.org

> If we used braces {} it _might_ have been more similar to what other
> people have traditionally done.

I concur with { ... } (as earlier), I'll submit patches for those.

Jari

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

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

[Jakub Narebski]

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

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

[Jari Aalto]

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

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

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

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

Jari

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

    [...]
    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.**

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

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

[Jakub Narebski]

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

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

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

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

>     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

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

[Jari Aalto]

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

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

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

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

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

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

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

[Jakub Narebski]

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

> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>
> * Message-Id: m3tzks6qfm.fsf@localhost.localdomain
> 
>>> 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)

Errr... I'm not sure if it is generic enough.  Although the POSIX/Susv
you have quoted. together with man(7) / manpage(5) pages I have quoted
seems to tell that it is so: POSIX/Susv talks about using angle
brackets to denote placeholders (to be substituted), man/manpage talks
about using italics/underline to denote placeholders.

So to say: I'm interested what AsciiDoc maintainers would say to that.
I have added asciidoc-discuss to Cc:, but please cull it (and the
asciidoc maintainer) from the Cc: list when replying.

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

Excuse me, but item is "required" if it is not marked (by brackets, or
by listing it as one of alternate calling conventions in separate
lines) as "optional". So both in "cmd -A" and in "cmd <file>"
parameters '-A' (literal) and '<file>' (to be substituted by filename)
are required parameters, while both in "cmd [-A]" and in 
"cmd [<file>]" appropriate parameters are optional.

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.

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

Perhaps. This I guess needs some discussion.

Nevertheless if / when we decide to change to this notation to delimit
parts of alternates / mutually exclusive parts, we would want to do
this in patch which changes only that, but changes it everywhere.

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

I have checked a bit of manual pages (in Linux), and only very few use
this convention. Do you have any statistics?

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

Again: it is required if it is not optional. There is no notation for
required parts, except that they are not marked as optional. In the
"cmd <file>" it is not angle brackets around <file> that denotes that
this parameter is requires, it is lacks of "[" "]" brackets around
parameter that tells it.

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

All true. And all what I wanted to tell.

>> Note that is natural that '[' and ']' also are limits of mutualy
>> exclusive parameters: "cmd [ A | B ]" means "cmd" or "cmd A" or "cmd B".
> 
> We are in all agreement on this one.

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

Ooops. Sorry. This time *I* haven't read this carefully enough.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Jari Aalto]

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

SYNOPSIS dyntax:

    command option

Is inherently same as by spelling it more stronger:

    command <option>

But different from

    command "option"

The reason why I might be inclined to be on for angles is that they are
commonly used in BNF, and thus familiar to many:

    <A> ::= <B> <C>

>>> 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.
>
> 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 feruently used angle curlies:

    command [<options>] {save|load}

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

>>>> -----------------------------------------------------------------------
>>>> 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.
>>>
> Again: it is required if it is not optional. There is no notation for
> required parts, except that they are not marked as optional. In the
> "cmd <file>" it is not angle brackets around <file> that denotes that
> this parameter is requires, it is lacks of "[" "]" brackets around
> parameter that tells it.
>
>>     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".
>
> All true. And all what I wanted to tell.

I think we both read the instructions the same way. Perhaps our views do
not differ. I'd be surprised, because that's the convention people are
used to having read the notations so long.

Jari

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

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

[Jakub Narebski]

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

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

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

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

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

[Jari Aalto]

Change (list|...) to {list|...} to denote required commands. Adjust
the 'save' command syntax to better reflect the call parameters:
[save] [message...] => [save [message...]].

Signed-off-by: Jari Aalto <jari.aalto AT cante.net>
---
 ***********************************************************************
 This is reworked patch (No. 1)
 ***********************************************************************

 Documentation/git-stash.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 9889806..8e343d8 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -8,8 +8,8 @@ git-stash - Stash the changes in a dirty working directory away
 SYNOPSIS
 --------
 [verse]
-'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
-'git-stash' [save] [message...]
+'git-stash' {list | show [<stash>] | apply [<stash>] | clear}
+'git-stash' [save [message...]]
 
 DESCRIPTION
 -----------
-- 
1.5.4-rc5.GIT-dirty

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

[Junio C Hamano]

You know that I am not taking patches that are not fixes this
deep into the release freeze, don't you?

I do not take patches early, and certainly I'll not take a patch
that changes a single page to make it the _first and only_ user
of the convention to use curly brace to delimit required
alternates.  It means now the whole manual set is less
consistent.

Please let the discussion brew for a while, and after reaching a
consensus on the list, send in a patch that changes parentheses
to curly braces for _ALL_ manual pages (and does nothing else).

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

[Jakub Narebski]

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

I think it would beb better if you split this patch in two,
as it deals with two separate issues, and in one case it doesn't
deal with the issue fully

> Change (list|...) to {list|...} to denote required commands.

This is one thing, and I think when you are resubmitting this patch
for discussion (with Cc: to the authors that introduced the (-a|-b)
syntax) you should change (list|...) to {list|...} *everywhere* in the
git manpages.

> Adjust
> the 'save' command syntax to better reflect the call parameters:
> [save] [message...] => [save [message...]].

This is just simple bugfix in git-stash synopsis, and I think this
patch would be accepted (especially now that it is after 1.5.4
released, and after feature freeze) without doubt.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

[PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax (2)

[Jari Aalto]

Adjust the command syntax to better reflect the call parameters:
[save] [message...] => [save [<message>]].

Signed-off-by: Jari Aalto <jari.aalto AT cante.net>
---
 > [Jakub Narebski] I think it would beb better if you split this patch
 > in two,

 ***********************************************************************
 This is reworked patch (No. 2)
 ***********************************************************************

 Documentation/git-stash.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 9889806..cd0dc1b 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
-'git-stash' [save] [message...]
+'git-stash' [save [<message>]]
 
 DESCRIPTION
 -----------
@@ -36,11 +36,12 @@ is also possible).
 OPTIONS
 -------
 
-save::
+save [<message>]::
 
 	Save your local modifications to a new 'stash', and run `git-reset
 	--hard` to revert them.  This is the default action when no
-	subcommand is given.
+	subcommand is given. The <message> part is optional and gives
+	the description along with the stashed state.
 
 list::
 
-- 
1.5.4-rc5.GIT-dirty