From: Junio C Hamano <gitster@pobox.com>
To: Philip Oakley <philipoakley@iee.org>
Cc: GitList <git@vger.kernel.org>
Subject: Re: [PATCH v2 1/5] Show 'git help <guide>' usage, with examples
Date: Sun, 03 Mar 2013 15:38:11 -0800 [thread overview]
Message-ID: <7v4ngs12cc.fsf@alter.siamese.dyndns.org> (raw)
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.
next prev parent reply other threads:[~2013-03-03 23:38 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-03-03 20:21 [PATCH v2 0/5] Git help option to list user guides Philip Oakley
2013-03-03 20:21 ` [PATCH v2 1/5] Show 'git help <guide>' usage, with examples Philip Oakley
2013-03-03 23:38 ` Junio C Hamano [this message]
2013-03-03 20:21 ` [PATCH v2 2/5] Help.c use OPT_COUNTUP Philip Oakley
2013-03-03 23:38 ` Junio C Hamano
2013-03-03 23:54 ` Philip Oakley
2013-03-04 0:05 ` Junio C Hamano
2013-03-04 0:31 ` Philip Oakley
2013-03-03 20:21 ` [PATCH v2 3/5] Help.c add --guide option Philip Oakley
2013-03-03 23:38 ` Junio C Hamano
2013-03-04 0:04 ` Philip Oakley
2013-03-03 20:21 ` [PATCH v2 4/5] Help.c: add list_common_guides_help() function Philip Oakley
2013-03-03 20:21 ` [PATCH v2 5/5] Help doc: Include --guide option description Philip Oakley
2013-03-03 23:39 ` Junio C Hamano
2013-03-04 0:18 ` Philip Oakley
-- strict thread matches above, loose matches on Subject: below --
2013-03-03 23:44 [PATCH v2 0/5] [RESEND with Cc:] Git help option to list user guides Philip Oakley
2013-03-03 23:44 ` [PATCH v2 1/5] Show 'git help <guide>' usage, with examples Philip Oakley
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7v4ngs12cc.fsf@alter.siamese.dyndns.org \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=philipoakley@iee.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).