Re: [PATCH v2] standardize usage info string format

From: Alex Henrie <alexhenrie24@gmail.com>
Date: Jan 13, 2015, 07:49 UTC
Message-ID: <CAMMLpeReN_X5+RR8XrxRmt6HQo_Wikv8Ac_xG_mKxmiWdF7GrA@mail.gmail.com>
In-Reply-To: <1421135087-7284-1-git-send-email-alexhenrie24@gmail.com>

2015-01-12 22:29 GMT-07:00 Scott Schmit <i.grok@comcast.net>:

Show 17 quoted lines

>
> On Wed, Jan 07, 2015 at 11:28:21PM -0700, Alex Henrie wrote:
> >
> > diff --git a/builtin/diff-files.c b/builtin/diff-files.c
> > index 9200069..1abeba6 100644
> > --- a/builtin/diff-files.c
> > +++ b/builtin/diff-files.c
> > @@ -11,7 +11,7 @@
> >  #include "submodule.h"
> >
> >  static const char diff_files_usage[] =
> > -"git diff-files [-q] [-0/-1/2/3 |-c|--cc] [<common diff options>] [<path>...]"
> > +"git diff-files [-q] [-0/-1/2/3 | -c | --cc] [<common-diff-options>] [<path>...]"
>                          ^^^^^^^^^
> This deserves cleanup too (the man page shows it as "[-0|-1|-2|-3|-c|--cc]").
>
> ...which makes me think the man pages need to be modified to match.

Patch v2 cleans up this usage string, but I think the man pages' inconsistencies should be addressed separately. The man pages don't appear to be translated, so their inconsistencies are unlikely to cause translators any headaches.

> Also, it looks like items 1 & 4 are already codified in
> CodingGuidelines, but items 2 & 3 are new.  If we care to make the
> changes in 2 & 3, we should document the new conventions there.

Patch v2 modifies the documentation to match. By the way, CodingGuidelines was inconsistent before. It had this example without spaces:

   [(<rev>|<range>)...]

And this example with spaces:

   git remote set-head <name> (-a | -d | <branch>)

> Bike-shedding, I'm sure: I find "[-0|-1|-2|-3|-c|--cc]" more
> readable/logical than "[-0 | -1 | -2 | -3 | -c | --cc]" (which I admit
> seems counter-intuitive), but I wouldn't be surprised if opinions on
> that are about as split as the existing usage lines are :-).

I counted 29 usage strings that used spaces in this case, and 16 that did not. Since spaces seem to be the more prevalent choice, I'd like to use them consistently.

Thanks for the feedback!

-Alex