Re: [PATCH] standardize usage info string format

From: Scott Schmit <i.grok@comcast.net>
Date: Jan 13, 2015, 05:29 UTC
Message-ID: <20150113052901.GA10126@odin.ulthar.us>
In-Reply-To: <1420698501-15393-1-git-send-email-alexhenrie24@gmail.com>

On Wed, Jan 07, 2015 at 11:28:21PM -0700, Alex Henrie wrote:

Show 11 quoted lines

> This patch puts the usage info strings that were not already in docopt-
> like format into docopt-like format, which will be a litle easier for
> end users and a lot easier for translators. Changes include:
> 
> - Placing angle brackets around fill-in-the-blank parameters
> - Putting dashes in multiword parameter names
> - Adding spaces to [-f|--foobar] to make [-f | --foobar]
> - Replacing <foobar>* with [<foobar>...]
> 
> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
> ---

Show 10 quoted lines

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

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.

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

Hope this helps.

-- 
Scott Schmit