From: Mark Lodato <lodatom@gmail.com>
Date: Fri, 29 Oct 2010 02:56:14 GMT
Subject: Re: [PATCH] CodingGuidelines: Add a section on writing documentation
Message-ID: <AANLkTimpJbuZAPfvVOedstV7=UiLiDMnDaYWQLVNQ+Yc@mail.gmail.com>
In-Reply-To: <20101024155121.GA9503@headley>

On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec <stepnem@gmail.com> wrote:
> Provide a few examples on argument and option notation in usage strings
> and command synopses.

I think this is a great idea.

> + Specific number of occurences is indicated as follows:
> +   <commit>{0,2}
> +   (Up to two <commit>s.)

I suggest removing this notation - it is confusing and is only used by
git-diff.txt and git-difftool.txt.  We already have notation to serve
this purpose:

    [<commit> [<commit>]]

> + Parentheses are used for grouping, often combined with vertical bar
> + to indicate alternatives:
> +   [(<rev>|<range>)...]
> +   (Any number of either <rev> or <range>.  Parens are needed to make
> +   it clear that "..." pertains to both <rev> and <range>.)

You could also mention that parentheses are not needed if square
brackets will do:
    [-q | --quiet]

Also, should there be a standard for spacing and for whether the short
or the long option comes first?

git-add.txt:
    [--patch | -p]
git-commit.txt:
    [-a | --interactive]
git-stash.txt:
    [-q|--quiet]

Otherwise, I think this patch looks good.