From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 03 Mar 2013 23:38:11 GMT
Subject: Re: [PATCH v2 1/5] Show 'git help <guide>' usage, with examples
Message-ID: <7v4ngs12cc.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1362342072-1412-2-git-send-email-philipoakley@iee.org>

Philip Oakley <philipoakley@iee.org> writes:

> The git(1) man page must be accessed via 'git help git' on Git for Windows
> as it has no 'man' command. And it prompts users to read the git(1) page,
> rather than hoping they follow a subsidiary link within another
> documentation page. The 'tutorial' is an obvious guide to suggest.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>  git.c | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/git.c b/git.c
> index b10c18b..d9b71c1 100644
> --- a/git.c
> +++ b/git.c
> @@ -13,7 +13,9 @@ const char git_usage_string[] =
>  	"           <command> [<args>]";
>  
>  const char git_more_info_string[] =
> -	N_("See 'git help <command>' for more information on a specific command.");
> +	N_("See 'git help <command>' for more information on a specific command.\n"
> +	   "While 'git help <guide>', will show the selected Git concept guide.\n"
> +	   "Examples: 'git help git', 'git help branch', 'git help tutorial'...");

While I think it is a good idea to mention that the argument to
"help" does not have to be the name of a subcommand, I have two
issues with this patch.

 * A free-standing "While" looks strange.  I would expect a sentence
   that begins with "While 'git help <guide>' shows X" to end with
   something negative like "it is not recommended". Perhaps it is
   just me.

 * It took me two readings to realize that "selected" in "selected
   Git concept guide" refers to "what the user chose to see by
   naming the <guide>".  It looked as if the command will give users
   only a selected few among 47 available ones, chosen by the
   implementors.

How about doing it this way if you are adding two lines anyway?

	'git help -a' and 'git help -g' lists available subcommands
	and concept guides. See 'git help <command>' or 'git help
	<concept>' to read about a specific subcommand or concept.

Replacing "Examples:" that has to stay incomplete for brevity with
the way to get the list of subcommands and concepts would a better
approach, I think.  Teach them how to fish, instead of giving them
fish.