From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Mon, 21 Sep 2009 06:50:45 GMT
Subject: Re: [PATCH] Remove '< >' from [<options>] since it's not necessary.
Message-ID: <vpq7hvssse2.fsf@bauges.imag.fr>
In-Reply-To: <auto-000020523806@sci.utah.edu>

tom fogal <tfogal@alumni.unh.edu> writes:

> Thiago Farina <tfransosi@gmail.com> writes:
>> -	"git log [<options>] [<since>..<until>] [[--] <path>...]\n"
>> +	"git log [options] [<since>..<until>] [[--] <path>...]\n"
>>  	"   or: git show [options] <object>...";
>
> To me, "<blah>" implies to me that the author meant, "something which
> is sort-of `blah'-ish but is not actually the string literal, `blah'",
> whereas `blah' means, "the string literal, `blah'."

Strictly speaking, you're right, but in the particular case of
[options], it's rather well established that it means "one or several
options", and not the litteral "option". In any case, we should be
consistant:

Documentation$ grep -n '\[<options>\]' *.txt
git-log.txt:11:'git log' [<options>] [<since>..<until>] [[\--] <path>...]
git-stash.txt:11:'git stash' list [<options>]
git-stash.txt:67:list [<options>]::
Documentation$ grep -n '\[options\]' *.txt
git-annotate.txt:10:'git annotate' [options] file [revision]
gitcli.txt:84:usage: git-describe [options] <committish>*
git-cvsserver.txt:25:'git cvsserver' [options] [pserver|server] [<directory> ...]
git-fast-export.txt:11:'git fast-export [options]' | 'git fast-import'
git-fast-import.txt:11:frontend | 'git fast-import' [options]
git-rebase.txt:11:'git rebase' [-i | --interactive] [options] [--onto <newbase>]
git-rebase.txt:13:'git rebase' [-i | --interactive] [options] --onto <newbase>
git-rev-parse.txt:405:some-command [options] <args>...
git-send-email.txt:11:'git send-email' [options] <file|directory|rev-list options>...
git-show.txt:11:'git show' [options] <object>...
git-svn.txt:10:'git svn' <command> [options] [arguments]

=> either get rid of the 3 occurences of [<options>], not just one, or
get rid of all the [options]. My vote goes for the first.

--
Matthieu Moy
http://www-verimag.imag.fr/~moy/