From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 01 Feb 2008 23:26:17 GMT
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Message-ID: <7vejbw8die.fsf@gitster.siamese.dyndns.org>
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?
>
>>> 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.