[PATCH V3 0/5] Git help option to list user guides

[PATCH V3 0/5] Git help option to list user guides

[Philip Oakley]

This is the re-roll of $gmane/217384. The series seeks to provide a help
option that will list the common git guides, and how to access them.

The series is rebased on top of V1.8.2 

Since V2, the OPT_BOOL is now used instead of OPT_COUNTUP.
The git_more_info_string has been further updated inline with Junio's
suggestions, and re-spaced so that command example are not split over
line ends.

Junio's suggestions in $gmane/217354/focus=217355 have been included.
Junio also asked about the `if (!argv[0])` test which is, correctly,
performed _after_ the -a and -g options are taken, as they overide any
remaining arguments.

The list of guides is spaced out in the same manner as the common
command list.

Philip Oakley (5):
  Show help: -a and -g option, and 'git help <concept>' usage.
  Help.c use OPT_BOOL and refactor logic
  Help.c add --guide option
  Help.c: add list_common_guides_help() function
  Help doc: Include --guide option description

 Documentation/git-help.txt | 30 ++++++++++++++++++++++--------
 builtin/help.c             | 17 +++++++++++++++--
 common-guides.h            | 11 +++++++++++
 git.c                      |  4 +++-
 help.c                     | 18 ++++++++++++++++++
 help.h                     |  1 +
 6 files changed, 70 insertions(+), 11 deletions(-)
 create mode 100644 common-guides.h

-- 
1.8.1.msysgit.1

[PATCH V3 1/5] Show help: -a and -g option, and 'git help <concept>' usage.

[Philip Oakley]

Prepare for the addition of the -g --guides option to git help
and show that help is available for both concept guides, and commands.

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 39ba6b1..2f8aa41 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_("'git help -a' and 'git help -g' lists available subcommands and some\n"
+	   "concept guides. See 'git help <command>' or 'git help <concept>'\n"
+	   "to read about a specific subcommand or concept.");
 
 static struct startup_info git_startup_info;
 static int use_pager = -1;
-- 
1.8.1.msysgit.1

Re: [PATCH V3 1/5] Show help: -a and -g option, and 'git help <concept>' usage.

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> Prepare for the addition of the -g --guides option to git help
> and show that help is available for both concept guides, and commands.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---

This should come at the end after you taught the "-g" option, I
think.  If we stopped with 1/5, then the message will promise "git
help -g" does something useful, while the code is not yet ready.

>  git.c | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/git.c b/git.c
> index 39ba6b1..2f8aa41 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_("'git help -a' and 'git help -g' lists available subcommands and some\n"
> +	   "concept guides. See 'git help <command>' or 'git help <concept>'\n"
> +	   "to read about a specific subcommand or concept.");
>  
>  static struct startup_info git_startup_info;
>  static int use_pager = -1;

[PATCH V3 2/5] Help.c use OPT_BOOL and refactor logic

[Philip Oakley]

Rename deprecated OPT_BOOLEAN option to OPT_BOOL in preparation for
'git help --guides'. The former OPT_BOOLEAN would now be OPT_COUNTUP,
but that capability is not required.

Separate out the show_all 'return(0)' and git_more_info_string logic
ready for inclusion of show_guides.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/builtin/help.c b/builtin/help.c
index d1d7181..8969d3b 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -39,7 +39,7 @@ static int show_all = 0;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;
 static struct option builtin_help_options[] = {
-	OPT_BOOLEAN('a', "all", &show_all, N_("print all available commands")),
+	OPT_BOOL('a', "all", &show_all, N_("print all available commands")),
 	OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
 	OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
 			HELP_FORMAT_WEB),
@@ -428,7 +428,13 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		git_config(git_help_config, NULL);
 		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
 		list_commands(colopts, &main_cmds, &other_cmds);
+	}
+
+	if (show_all) {
 		printf("%s\n", _(git_more_info_string));
+		/*
+		* We're done. Ignore any remaining args
+		*/
 		return 0;
 	}
 
-- 
1.8.1.msysgit.1

Re: [PATCH V3 2/5] Help.c use OPT_BOOL and refactor logic

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> Rename deprecated OPT_BOOLEAN option to OPT_BOOL in preparation for
> 'git help --guides'. The former OPT_BOOLEAN would now be OPT_COUNTUP,
> but that capability is not required.
>
> Separate out the show_all 'return(0)' and git_more_info_string logic
> ready for inclusion of show_guides.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---

You are creating a gap in the output so that you can add some more
stuff in later patches, which is fine, but I do not think we call
that kind of change a "refactor" ;-).

The change looks fine.

>  builtin/help.c | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/builtin/help.c b/builtin/help.c
> index d1d7181..8969d3b 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -39,7 +39,7 @@ static int show_all = 0;
>  static unsigned int colopts;
>  static enum help_format help_format = HELP_FORMAT_NONE;
>  static struct option builtin_help_options[] = {
> -	OPT_BOOLEAN('a', "all", &show_all, N_("print all available commands")),
> +	OPT_BOOL('a', "all", &show_all, N_("print all available commands")),
>  	OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
>  	OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
>  			HELP_FORMAT_WEB),
> @@ -428,7 +428,13 @@ int cmd_help(int argc, const char **argv, const char *prefix)
>  		git_config(git_help_config, NULL);
>  		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
>  		list_commands(colopts, &main_cmds, &other_cmds);
> +	}
> +
> +	if (show_all) {
>  		printf("%s\n", _(git_more_info_string));
> +		/*
> +		* We're done. Ignore any remaining args
> +		*/
>  		return 0;
>  	}

Re: [PATCH V3 2/5] Help.c use OPT_BOOL and refactor logic

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> You are creating a gap in the output so that you can add some more
> stuff in later patches, which is fine, but I do not think we call
> that kind of change a "refactor" ;-).
>
> The change looks fine.

I'll queue what I suggested on 'pu' for now.

Thanks.

Re: [PATCH V3 2/5] Help.c use OPT_BOOL and refactor logic

[Philip Oakley]

Sent: Wednesday, April 03, 2013 2:13 AM
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> You are creating a gap in the output so that you can add some more
>> stuff in later patches, which is fine, but I do not think we call
>> that kind of change a "refactor" ;-).
>>
>> The change looks fine.
> 
> I'll queue what I suggested on 'pu' for now.

It looks good. I'm happy with your suggestions as queued.

Acked-by: Philip Oakley <philipoakley@iee.org>

Longer term I'd like to be able to show all the guides as a double -gg
option, but this is a great start.

> 
> Thanks.
> 
> 
> -----

[PATCH V3 3/5] Help.c add --guide option

[Philip Oakley]

Logic, but no actions, included.

The --all commands option, if given, will display first.
The --guide option's list will then be displayed.

The common commands list is only displayed if neither option,
nor a command or guide name, is given.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/builtin/help.c b/builtin/help.c
index 8969d3b..03d432b 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -36,10 +36,12 @@ enum help_format {
 static const char *html_path;
 
 static int show_all = 0;
+static int show_guides = 0;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;
 static struct option builtin_help_options[] = {
 	OPT_BOOL('a', "all", &show_all, N_("print all available commands")),
+	OPT_BOOL('g', "guides", &show_guides, N_("print list of useful guides")),
 	OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
 	OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
 			HELP_FORMAT_WEB),
@@ -49,7 +51,7 @@ static struct option builtin_help_options[] = {
 };
 
 static const char * const builtin_help_usage[] = {
-	N_("git help [--all] [--man|--web|--info] [command]"),
+	N_("git help [--all] [--guides] [--man|--web|--info] [command]"),
 	NULL
 };
 
@@ -430,7 +432,11 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		list_commands(colopts, &main_cmds, &other_cmds);
 	}
 
-	if (show_all) {
+	if (show_guides) {
+		/* do action - next patch */
+	}
+
+	if (show_all || show_guides) {
 		printf("%s\n", _(git_more_info_string));
 		/*
 		* We're done. Ignore any remaining args
-- 
1.8.1.msysgit.1

[PATCH V3 4/5] Help.c: add list_common_guides_help() function

[Philip Oakley]

Re-use list_common_cmds_help but simply change the array name.
Candidate for future refactoring to pass a pointer to the array.

The common-guides.h list was generated with a simple variant of the
generate-cmdlist.sh and command-list.txt.

Do not list User-manual and Everday Git which not follow the naming
convention, nor gitrepository-layout which doesn't fit within the
name field size.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c  |  3 ++-
 common-guides.h | 11 +++++++++++
 help.c          | 18 ++++++++++++++++++
 help.h          |  1 +
 4 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 common-guides.h

diff --git a/builtin/help.c b/builtin/help.c
index 03d432b..91a6158 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -433,7 +433,8 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 	}
 
 	if (show_guides) {
-		/* do action - next patch */
+		list_common_guides_help();
+		printf("\n");
 	}
 
 	if (show_all || show_guides) {
diff --git a/common-guides.h b/common-guides.h
new file mode 100644
index 0000000..0e94fdc
--- /dev/null
+++ b/common-guides.h
@@ -0,0 +1,11 @@
+/* re-use struct cmdname_help in common-commands.h */
+
+static struct cmdname_help common_guides[] = {
+  {"attributes", "defining attributes per path"},
+  {"glossary", "A GIT Glossary"},
+  {"ignore", "Specifies intentionally untracked files to ignore"},
+  {"modules", "defining submodule properties"},
+  {"revisions", "specifying revisions and ranges for git"},
+  {"tutorial", "A tutorial introduction to git (for version 1.5.1 or newer)"},
+  {"workflows", "An overview of recommended workflows with git"},
+};
diff --git a/help.c b/help.c
index 1dfa0b0..e0368ca 100644
--- a/help.c
+++ b/help.c
@@ -4,6 +4,7 @@
 #include "levenshtein.h"
 #include "help.h"
 #include "common-cmds.h"
+#include "common-guides.h"
 #include "string-list.h"
 #include "column.h"
 #include "version.h"
@@ -240,6 +241,23 @@ void list_common_cmds_help(void)
 	}
 }
 
+void list_common_guides_help(void)
+{
+	int i, longest = 0;
+
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		if (longest < strlen(common_guides[i].name))
+			longest = strlen(common_guides[i].name);
+	}
+
+	puts(_("The common Git guides are:\n"));
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		printf("   %s   ", common_guides[i].name);
+		mput_char(' ', longest - strlen(common_guides[i].name));
+		puts(_(common_guides[i].help));
+	}
+}
+
 int is_in_cmdlist(struct cmdnames *c, const char *s)
 {
 	int i;
diff --git a/help.h b/help.h
index 0ae5a12..4ae1fd7 100644
--- a/help.h
+++ b/help.h
@@ -17,6 +17,7 @@ static inline void mput_char(char c, unsigned int num)
 }
 
 extern void list_common_cmds_help(void);
+extern void list_common_guides_help(void);
 extern const char *help_unknown_cmd(const char *cmd);
 extern void load_command_list(const char *prefix,
 			      struct cmdnames *main_cmds,
-- 
1.8.1.msysgit.1

Re: [PATCH V3 4/5] Help.c: add list_common_guides_help() function

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> Re-use list_common_cmds_help but simply change the array name.
> Candidate for future refactoring to pass a pointer to the array.
>
> The common-guides.h list was generated with a simple variant of the
> generate-cmdlist.sh and command-list.txt.
>
> Do not list User-manual and Everday Git which not follow the naming
> convention, nor gitrepository-layout which doesn't fit within the
> name field size.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>  builtin/help.c  |  3 ++-
>  common-guides.h | 11 +++++++++++
>  help.c          | 18 ++++++++++++++++++
>  help.h          |  1 +
>  4 files changed, 32 insertions(+), 1 deletion(-)
>  create mode 100644 common-guides.h
>
> diff --git a/builtin/help.c b/builtin/help.c
> index 03d432b..91a6158 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -433,7 +433,8 @@ int cmd_help(int argc, const char **argv, const char *prefix)
>  	}
>  
>  	if (show_guides) {
> -		/* do action - next patch */
> +		list_common_guides_help();
> +		printf("\n");
>  	}

This looks funny.  If you look at list_commands() that this patch is
mimicking, you will notice that the "trailing blank for clarity" is
done as part of the function, not done by the caller.  I think it is
better done the same way.

> diff --git a/common-guides.h b/common-guides.h
> new file mode 100644
> index 0000000..0e94fdc
> --- /dev/null
> +++ b/common-guides.h
> @@ -0,0 +1,11 @@
> +/* re-use struct cmdname_help in common-commands.h */
> +
> +static struct cmdname_help common_guides[] = {
> +  {"attributes", "defining attributes per path"},
> +  {"glossary", "A GIT Glossary"},
> +  {"ignore", "Specifies intentionally untracked files to ignore"},
> +  {"modules", "defining submodule properties"},
> +  {"revisions", "specifying revisions and ranges for git"},
> +  {"tutorial", "A tutorial introduction to git (for version 1.5.1 or newer)"},
> +  {"workflows", "An overview of recommended workflows with git"},
> +};

The _only_ reason we have common-cmds.h as a separat file even
though it defines data (hence should not be included in more than
one *.c file) is because it is a generated file.

For this array, there is no reason to have it in a separate header
file.  Just define it immediately before list_common_guies_help()
function that is the sole user of the array.

The function can live in builtin/help.c as a static, without
touching global help.c nor help.h, no?  Is there a reason why it
should be callable from other places?

> diff --git a/help.c b/help.c
> index 1dfa0b0..e0368ca 100644
> --- a/help.c
> +++ b/help.c
> @@ -4,6 +4,7 @@
>  #include "levenshtein.h"
>  #include "help.h"
>  #include "common-cmds.h"
> +#include "common-guides.h"
>  #include "string-list.h"
>  #include "column.h"
>  #include "version.h"
> @@ -240,6 +241,23 @@ void list_common_cmds_help(void)
>  	}
>  }
>  
> +void list_common_guides_help(void)
> +{
> +	int i, longest = 0;
> +
> +	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
> +		if (longest < strlen(common_guides[i].name))
> +			longest = strlen(common_guides[i].name);
> +	}
> +
> +	puts(_("The common Git guides are:\n"));
> +	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
> +		printf("   %s   ", common_guides[i].name);
> +		mput_char(' ', longest - strlen(common_guides[i].name));
> +		puts(_(common_guides[i].help));
> +	}
> +}
> +
>  int is_in_cmdlist(struct cmdnames *c, const char *s)
>  {
>  	int i;
> diff --git a/help.h b/help.h
> index 0ae5a12..4ae1fd7 100644
> --- a/help.h
> +++ b/help.h
> @@ -17,6 +17,7 @@ static inline void mput_char(char c, unsigned int num)
>  }
>  
>  extern void list_common_cmds_help(void);
> +extern void list_common_guides_help(void);
>  extern const char *help_unknown_cmd(const char *cmd);
>  extern void load_command_list(const char *prefix,
>  			      struct cmdnames *main_cmds,

Re: [PATCH V3 4/5] Help.c: add list_common_guides_help() function

[Eric Sunshine]

On Tue, Apr 2, 2013 at 6:39 PM, Philip Oakley <philipoakley@iee.org> wrote:
> Re-use list_common_cmds_help but simply change the array name.
> Candidate for future refactoring to pass a pointer to the array.
>
> The common-guides.h list was generated with a simple variant of the
> generate-cmdlist.sh and command-list.txt.
>
> Do not list User-manual and Everday Git which not follow the naming

s/which not/which do not/

> convention, nor gitrepository-layout which doesn't fit within the
> name field size.

[PATCH] help: mark common_guides[] as translatable

[Simon Ruderich]

Signed-off-by: Simon Ruderich <simon@ruderich.org>
---
On Tue, Apr 02, 2013 at 11:39:51PM +0100, Philip Oakley wrote:
> --- a/help.c
> +++ b/help.c
> @@ -240,6 +241,23 @@ void list_common_cmds_help(void)
>  	}
>  }
>
> +void list_common_guides_help(void)
> +{
> +	int i, longest = 0;
> +
> +	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
> +		if (longest < strlen(common_guides[i].name))
> +			longest = strlen(common_guides[i].name);
> +	}
> +
> +	puts(_("The common Git guides are:\n"));
> +	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
> +		printf("   %s   ", common_guides[i].name);
> +		mput_char(' ', longest - strlen(common_guides[i].name));
> +		puts(_(common_guides[i].help));

common_guides[] is used here, but without N_() not picked up by
xgettext when creating the pot file.

Regards
Simon

 builtin/help.c | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/builtin/help.c b/builtin/help.c
index 034c36c..062957f 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -419,13 +419,13 @@ static struct {
 	const char *name;
 	const char *help;
 } common_guides[] = {
-	{ "attributes", "Defining attributes per path" },
-	{ "glossary", "A Git glossary" },
-	{ "ignore", "Specifies intentionally untracked files to ignore" },
-	{ "modules", "Defining submodule properties" },
-	{ "revisions", "Specifying revisions and ranges for Git" },
-	{ "tutorial", "A tutorial introduction to Git (for version 1.5.1 or newer)" },
-	{ "workflows", "An overview of recommended workflows with Git"},
+	{ "attributes", N_("Defining attributes per path") },
+	{ "glossary", N_("A Git glossary") },
+	{ "ignore", N_("Specifies intentionally untracked files to ignore") },
+	{ "modules", N_("Defining submodule properties") },
+	{ "revisions", N_("Specifying revisions and ranges for Git") },
+	{ "tutorial", N_("A tutorial introduction to Git (for version 1.5.1 or newer)") },
+	{ "workflows", N_("An overview of recommended workflows with Git") },
 };
 
 static void list_common_guides_help(void)
-- 
1.8.2.481.g0d034d4

-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

Re: [PATCH] help: mark common_guides[] as translatable

[Philip Oakley]

From: "Simon Ruderich" <simon@ruderich.org>
Sent: Friday, April 12, 2013 2:51 PM
> Signed-off-by: Simon Ruderich <simon@ruderich.org>
> ---
> On Tue, Apr 02, 2013 at 11:39:51PM +0100, Philip Oakley wrote:
>> --- a/help.c
>> +++ b/help.c
>> @@ -240,6 +241,23 @@ void list_common_cmds_help(void)
>>  }
>>  }
>>
>> +void list_common_guides_help(void)
>> +{
>> + int i, longest = 0;
>> +
>> + for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
>> + if (longest < strlen(common_guides[i].name))
>> + longest = strlen(common_guides[i].name);
>> + }
>> +
>> + puts(_("The common Git guides are:\n"));
>> + for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
>> + printf("   %s   ", common_guides[i].name);
>> + mput_char(' ', longest - strlen(common_guides[i].name));
>> + puts(_(common_guides[i].help));
>
> common_guides[] is used here, but without N_() not picked up by
> xgettext when creating the pot file.

Yes. I mucked that up when I hacked the generate-cmdlist.sh to create 
this list.

Acked-by: Philip Oakley <philipoakley@iee.org>

At some point it is on my TODO list to extend the guide list mechanism 
to all the community generated guides (option -gg) by extending the 
command-list.txt file and the shell script.

>
> Regards
> Simon
>
> builtin/help.c | 14 +++++++-------
> 1 file changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/builtin/help.c b/builtin/help.c
> index 034c36c..062957f 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -419,13 +419,13 @@ static struct {
>  const char *name;
>  const char *help;
> } common_guides[] = {
> - { "attributes", "Defining attributes per path" },
> - { "glossary", "A Git glossary" },
> - { "ignore", "Specifies intentionally untracked files to ignore" },
> - { "modules", "Defining submodule properties" },
> - { "revisions", "Specifying revisions and ranges for Git" },
> - { "tutorial", "A tutorial introduction to Git (for version 1.5.1 or 
> newer)" },
> - { "workflows", "An overview of recommended workflows with Git"},
> + { "attributes", N_("Defining attributes per path") },
> + { "glossary", N_("A Git glossary") },
> + { "ignore", N_("Specifies intentionally untracked files to 
> ignore") },
> + { "modules", N_("Defining submodule properties") },
> + { "revisions", N_("Specifying revisions and ranges for Git") },
> + { "tutorial", N_("A tutorial introduction to Git (for version 1.5.1 
> or newer)") },
> + { "workflows", N_("An overview of recommended workflows with 
> Git") },
> };
>
> static void list_common_guides_help(void)
> -- 
> 1.8.2.481.g0d034d4
>
> -- 
> + privacy is necessary
> + using gnupg http://gnupg.org
> + public key id: 0x92FEFDB7E44C32F9

[PATCH V3 5/5] Help doc: Include --guide option description

[Philip Oakley]

Note that the ability to display an individual guide was
always possible. Include this in the update.

Also tell readers how git(1) can be accessed, especially for
Git for Windows users who do not have the 'man' command.
Likewise include a commentary on how to access this page (Catch 22).

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/git-help.txt | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index e07b6dc..442d941 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -8,31 +8,45 @@ git-help - Display help information about Git
 SYNOPSIS
 --------
 [verse]
-'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND]
+'git help' [-a|--all] [-g|--guide]
+	   [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]
 
 DESCRIPTION
 -----------
 
-With no options and no COMMAND given, the synopsis of the 'git'
+With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
 command and a list of the most commonly used Git commands are printed
 on the standard output.
 
-If the option '--all' or '-a' is given, then all available commands are
+If the option '--all' or '-a' is given, all available commands are
 printed on the standard output.
 
-If a Git subcommand is named, a manual page for that subcommand is brought
-up. The 'man' program is used by default for this purpose, but this
-can be overridden by other options or configuration variables.
+If the option '--guide' or '-g' is given, a list of the useful
+Git guides is also printed on the standard output.
 
-Note that `git --help ...` is identical to `git help ...` because the
+If a command, or a guide, is given, a manual page for that command or
+guide is brought up. The 'man' program is used by default for this
+purpose, but this can be overridden by other options or configuration
+variables.
+
+Note that 'git --help ...' is identical to 'git help ...' because the
 former is internally converted into the latter.
 
+To display the linkgit:git[1] man page, use 'git help git'.
+
+This page can be displayed with 'git help help' or 'git help --help'
+
 OPTIONS
 -------
 -a::
 --all::
 	Prints all the available commands on the standard output. This
-	option supersedes any other option.
+	option overides any given command or guide name.
+
+-g::
+--guides::
+	Prints a list of useful guides on the standard output. This
+	option overides any given command or guide name.
 
 -i::
 --info::
-- 
1.8.1.msysgit.1

Re: [PATCH V3 5/5] Help doc: Include --guide option description

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> +To display the linkgit:git[1] man page, use 'git help git'.

Good to see that somebody remembers that we discussed this ;-)

Re: [PATCH V3 5/5] Help doc: Include --guide option description

[Eric Sunshine]

On Tue, Apr 2, 2013 at 6:39 PM, Philip Oakley <philipoakley@iee.org> wrote:
>  OPTIONS
>  -------
>  -a::
>  --all::
>         Prints all the available commands on the standard output. This
> -       option supersedes any other option.
> +       option overides any given command or guide name.

s/overides/overrides/

> +
> +-g::
> +--guides::
> +       Prints a list of useful guides on the standard output. This
> +       option overides any given command or guide name.

Ditto: s/overides/overrides/