{"thread":{"id":"33060","subject":"[PATCH v2 1/5] Show 'git help <guide>' usage, with examples","startedAt":"2013-03-03T20:21:07Z","lastAt":"2013-03-04T00:12:44Z","messageCount":15,"participants":["Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":5},"messages":[{"id":"210534","messageId":"1362342072-1412-1-git-send-email-philipoakley@iee.org","threadId":"33060","inReplyTo":null,"subject":"[PATCH v2 0/5] Git help option to list user guides","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-03-03T20:21:07Z","receivedAt":"2013-03-03T20:21:07Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This is the much truncated (was 0/13] and updated series for\nnoting that 'git help' can display the existing guides that are\nformatted as man pages, and providing a 'git help' option to list\na few of the most useful guides.\n\nThe series is rebased on top of V1.8.2-rc1\n\nDifferences relative to V1 numbering\nPatch 1: Use 'Git' in help messages\nDropped.\na. the 'git version' string is used in the wild for version checking,\nin particular Git Gui checks the string is 'git version'.\nb. a recent patch series fixed on lower case messages for 'usage:',\nrespect that.\nc. many consider that the 'git' reference was to the 'git <cmd>' format\nrather than (the system) Git's commands.\n\nPatch 2 (now 1/5): Show 'git help <guide>' usage, with examples\nCorrect elipsis dots for unterminated list of examples.\n\nPatch 2 (now 2/5): Help.c use OPT_COUNTUP\nUnchanged.\n\nPatch 4 (now 3/5): Help.c add --guide option\nUpdate commit message to explain the -g|--guide logic.\n\nPatch 5 (now 4/5): Help.c: add list_common_guides_help() function\nRemoved the 'build artefact' /* */ comment line.\nNote that these are just the common guides and used in a usage message.\nThe data was generated by a script variant of generate-cmdlist.sh\n\nPatch (new 5/5): Help doc: Include --guide option description\nUpdate the documentation/git-help.txt - I had been caught out by\nthe same 'focus on the code' mistake made by many and forgot\nthe documenation ;-)\n\nPatch 6 - 13: \nAll dropped.\nDrop the separate guide list.txt and extraction script, which was\ncopied from the common command list and script. If the guide usage\nlist is useful, extend the command-list.txt and generate-cmdlist.sh\nat a later date.\n\nDrop the rename of user-manual and everyday because they are not\nformatted as manuals. They can't be started by help's call to 'man'\n(and possibly other paths) anyway.\n\nPhilip Oakley (5):\n  Show 'git help <guide>' usage, with examples\n  Help.c use OPT_COUNTUP\n  Help.c add --guide option\n  Help.c: add list_common_guides_help() function\n  Help doc: Include --guide option description\n\n Documentation/git-help.txt | 28 +++++++++++++++++++++-------\n builtin/help.c             | 11 ++++++++---\n common-guides.h            | 11 +++++++++++\n git.c                      |  4 +++-\n help.c                     | 18 ++++++++++++++++++\n help.h                     |  1 +\n 6 files changed, 62 insertions(+), 11 deletions(-)\n create mode 100644 common-guides.h\n\n-- \n1.8.1.msysgit.1\n"},{"id":"210532","messageId":"1362342072-1412-2-git-send-email-philipoakley@iee.org","threadId":"33060","inReplyTo":"1362342072-1412-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v2 1/5] Show 'git help <guide>' usage, with examples","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-03-03T20:21:08Z","receivedAt":"2013-03-03T20:21:08Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The git(1) man page must be accessed via 'git help git' on Git for Windows\nas it has no 'man' command. And it prompts users to read the git(1) page,\nrather than hoping they follow a subsidiary link within another\ndocumentation page. The 'tutorial' is an obvious guide to suggest.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n git.c | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/git.c b/git.c\nindex b10c18b..d9b71c1 100644\n--- a/git.c\n+++ b/git.c\n@@ -13,7 +13,9 @@ const char git_usage_string[] =\n \t\"           <command> [<args>]\";\n \n const char git_more_info_string[] =\n-\tN_(\"See 'git help <command>' for more information on a specific command.\");\n+\tN_(\"See 'git help <command>' for more information on a specific command.\\n\"\n+\t   \"While 'git help <guide>', will show the selected Git concept guide.\\n\"\n+\t   \"Examples: 'git help git', 'git help branch', 'git help tutorial'...\");\n \n static struct startup_info git_startup_info;\n static int use_pager = -1;\n-- \n1.8.1.msysgit.1\n"},{"id":"210536","messageId":"1362342072-1412-3-git-send-email-philipoakley@iee.org","threadId":"33060","inReplyTo":"1362342072-1412-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v2 2/5] Help.c use OPT_COUNTUP","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-03-03T20:21:09Z","receivedAt":"2013-03-03T20:21:09Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"rename deprecated option in preparation for 'git help --guides'.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n builtin/help.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/help.c b/builtin/help.c\nindex d1d7181..d10cbed 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -39,7 +39,7 @@ static int show_all = 0;\n static unsigned int colopts;\n static enum help_format help_format = HELP_FORMAT_NONE;\n static struct option builtin_help_options[] = {\n-\tOPT_BOOLEAN('a', \"all\", &show_all, N_(\"print all available commands\")),\n+\tOPT_COUNTUP('a', \"all\", &show_all, N_(\"print all available commands\")),\n \tOPT_SET_INT('m', \"man\", &help_format, N_(\"show man page\"), HELP_FORMAT_MAN),\n \tOPT_SET_INT('w', \"web\", &help_format, N_(\"show manual in web browser\"),\n \t\t\tHELP_FORMAT_WEB),\n-- \n1.8.1.msysgit.1\n"},{"id":"210535","messageId":"1362342072-1412-4-git-send-email-philipoakley@iee.org","threadId":"33060","inReplyTo":"1362342072-1412-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v2 3/5] Help.c add --guide option","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-03-03T20:21:10Z","receivedAt":"2013-03-03T20:21:10Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Logic, but no actions, included.\n\nThe --all commands option, if given, will display first.\nThe --guide option's list will then be displayed.\n\nThe common commands list is only displayed if neither option,\nnor a command or guide name, is given.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n builtin/help.c | 8 ++++++--\n 1 file changed, 6 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/help.c b/builtin/help.c\nindex d10cbed..6089d72 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -36,10 +36,12 @@ enum help_format {\n static const char *html_path;\n \n static int show_all = 0;\n+static int show_guides = 0;\n static unsigned int colopts;\n static enum help_format help_format = HELP_FORMAT_NONE;\n static struct option builtin_help_options[] = {\n \tOPT_COUNTUP('a', \"all\", &show_all, N_(\"print all available commands\")),\n+\tOPT_COUNTUP('g', \"guides\", &show_guides, N_(\"print list of useful guides\")),\n \tOPT_SET_INT('m', \"man\", &help_format, N_(\"show man page\"), HELP_FORMAT_MAN),\n \tOPT_SET_INT('w', \"web\", &help_format, N_(\"show manual in web browser\"),\n \t\t\tHELP_FORMAT_WEB),\n@@ -49,7 +51,7 @@ static struct option builtin_help_options[] = {\n };\n \n static const char * const builtin_help_usage[] = {\n-\tN_(\"git help [--all] [--man|--web|--info] [command]\"),\n+\tN_(\"git help [--all] [--guides] [--man|--web|--info] [command]\"),\n \tNULL\n };\n \n@@ -429,9 +431,11 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\tprintf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n \t\tlist_commands(colopts, &main_cmds, &other_cmds);\n \t\tprintf(\"%s\\n\", _(git_more_info_string));\n+\t\tif (!show_guides) return 0;\n+\t}\n+\tif (show_guides) {\n \t\treturn 0;\n \t}\n-\n \tif (!argv[0]) {\n \t\tprintf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n \t\tlist_common_cmds_help();\n-- \n1.8.1.msysgit.1\n"},{"id":"210533","messageId":"1362342072-1412-5-git-send-email-philipoakley@iee.org","threadId":"33060","inReplyTo":"1362342072-1412-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v2 4/5] Help.c: add list_common_guides_help() function","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-03-03T20:21:11Z","receivedAt":"2013-03-03T20:21:11Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Re-use list_common_cmds_help but simply change the array name.\nCandidate for future refactoring to pass a pointer to the array.\n\nThe common-guides.h list was generated with a simple variant of the\ngenerate-cmdlist.sh and command-list.txt.\n\nDo not list User-manual and Everday Git which not follow the naming\nconvention, nor gitrepository-layout which doesn't fit within the\nname field size.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n builtin/help.c  |  1 +\n common-guides.h | 11 +++++++++++\n help.c          | 18 ++++++++++++++++++\n help.h          |  1 +\n 4 files changed, 31 insertions(+)\n create mode 100644 common-guides.h\n\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 6089d72..e21ffa5 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -434,6 +434,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\tif (!show_guides) return 0;\n \t}\n \tif (show_guides) {\n+\t\tlist_common_guides_help();\n \t\treturn 0;\n \t}\n \tif (!argv[0]) {\ndiff --git a/common-guides.h b/common-guides.h\nnew file mode 100644\nindex 0000000..0e94fdc\n--- /dev/null\n+++ b/common-guides.h\n@@ -0,0 +1,11 @@\n+/* re-use struct cmdname_help in common-commands.h */\n+\n+static struct cmdname_help common_guides[] = {\n+  {\"attributes\", \"defining attributes per path\"},\n+  {\"glossary\", \"A GIT Glossary\"},\n+  {\"ignore\", \"Specifies intentionally untracked files to ignore\"},\n+  {\"modules\", \"defining submodule properties\"},\n+  {\"revisions\", \"specifying revisions and ranges for git\"},\n+  {\"tutorial\", \"A tutorial introduction to git (for version 1.5.1 or newer)\"},\n+  {\"workflows\", \"An overview of recommended workflows with git\"},\n+};\ndiff --git a/help.c b/help.c\nindex 1dfa0b0..f4de407 100644\n--- a/help.c\n+++ b/help.c\n@@ -4,6 +4,7 @@\n #include \"levenshtein.h\"\n #include \"help.h\"\n #include \"common-cmds.h\"\n+#include \"common-guides.h\"\n #include \"string-list.h\"\n #include \"column.h\"\n #include \"version.h\"\n@@ -240,6 +241,23 @@ void list_common_cmds_help(void)\n \t}\n }\n \n+void list_common_guides_help(void)\n+{\n+\tint i, longest = 0;\n+\n+\tfor (i = 0; i < ARRAY_SIZE(common_guides); i++) {\n+\t\tif (longest < strlen(common_guides[i].name))\n+\t\t\tlongest = strlen(common_guides[i].name);\n+\t}\n+\n+\tputs(_(\"The common Git guides are:\"));\n+\tfor (i = 0; i < ARRAY_SIZE(common_guides); i++) {\n+\t\tprintf(\"   %s   \", common_guides[i].name);\n+\t\tmput_char(' ', longest - strlen(common_guides[i].name));\n+\t\tputs(_(common_guides[i].help));\n+\t}\n+}\n+\n int is_in_cmdlist(struct cmdnames *c, const char *s)\n {\n \tint i;\ndiff --git a/help.h b/help.h\nindex 0ae5a12..4ae1fd7 100644\n--- a/help.h\n+++ b/help.h\n@@ -17,6 +17,7 @@ static inline void mput_char(char c, unsigned int num)\n }\n \n extern void list_common_cmds_help(void);\n+extern void list_common_guides_help(void);\n extern const char *help_unknown_cmd(const char *cmd);\n extern void load_command_list(const char *prefix,\n \t\t\t      struct cmdnames *main_cmds,\n-- \n1.8.1.msysgit.1\n"},{"id":"210537","messageId":"1362342072-1412-6-git-send-email-philipoakley@iee.org","threadId":"33060","inReplyTo":"1362342072-1412-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v2 5/5] Help doc: Include --guide option description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-03-03T20:21:12Z","receivedAt":"2013-03-03T20:21:12Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Note that the ability to display an individual guide was\nalways possible. Include this in the update.\n\nAlso tell readers how git(1) can be accessed, especially for\nGit for Windows users who do not have the 'man' command.\nLikewise include a commentary on how to access this page (Catch 22).\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n Documentation/git-help.txt | 28 +++++++++++++++++++++-------\n 1 file changed, 21 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex e07b6dc..498a94e 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -8,31 +8,45 @@ git-help - Display help information about Git\n SYNOPSIS\n --------\n [verse]\n-'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND]\n+'git help' [-a|--all] [-g|--guide]\n+\t   [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]\n \n DESCRIPTION\n -----------\n \n-With no options and no COMMAND given, the synopsis of the 'git'\n+With no options and no COMMAND|GUIDE given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n If the option '--all' or '-a' is given, then all available commands are\n printed on the standard output.\n \n-If a Git subcommand is named, a manual page for that subcommand is brought\n-up. The 'man' program is used by default for this purpose, but this\n-can be overridden by other options or configuration variables.\n+If the option '--guide' or '-g' is given then, a list of the useful\n+Git guides is also printed on the standard output.\n \n-Note that `git --help ...` is identical to `git help ...` because the\n+If a Git subcommand, or a Git guide, is given, a manual page for that\n+subcommand is brought up. The 'man' program is used by default for this\n+purpose, but this can be overridden by other options or configuration\n+variables.\n+\n+Note that 'git --help ...' is identical to 'git help ...' because the\n former is internally converted into the latter.\n \n+To display the linkgit:git[1] man page use 'git help git'.\n+\n+This page can be displayed with 'git help help' or 'git help --help'\n+\n OPTIONS\n -------\n -a::\n --all::\n \tPrints all the available commands on the standard output. This\n-\toption supersedes any other option.\n+\toption overides any given command or guide name.\n+\n+-g::\n+--guides::\n+\tPrints a list of useful guides on the standard output. This\n+\toption overides any given command or guide name.\n \n -i::\n --info::\n-- \n1.8.1.msysgit.1\n"},{"id":"210548","messageId":"7v4ngs12cc.fsf@alter.siamese.dyndns.org","threadId":"33060","inReplyTo":"1362342072-1412-2-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH v2 1/5] Show 'git help <guide>' usage, with examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-03T23:38:11Z","receivedAt":"2013-03-03T23:38:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.org> writes:\n\n> The git(1) man page must be accessed via 'git help git' on Git for Windows\n> as it has no 'man' command. And it prompts users to read the git(1) page,\n> rather than hoping they follow a subsidiary link within another\n> documentation page. The 'tutorial' is an obvious guide to suggest.\n>\n> Signed-off-by: Philip Oakley <philipoakley@iee.org>\n> ---\n>  git.c | 4 +++-\n>  1 file changed, 3 insertions(+), 1 deletion(-)\n>\n> diff --git a/git.c b/git.c\n> index b10c18b..d9b71c1 100644\n> --- a/git.c\n> +++ b/git.c\n> @@ -13,7 +13,9 @@ const char git_usage_string[] =\n>  \t\"           <command> [<args>]\";\n>  \n>  const char git_more_info_string[] =\n> -\tN_(\"See 'git help <command>' for more information on a specific command.\");\n> +\tN_(\"See 'git help <command>' for more information on a specific command.\\n\"\n> +\t   \"While 'git help <guide>', will show the selected Git concept guide.\\n\"\n> +\t   \"Examples: 'git help git', 'git help branch', 'git help tutorial'...\");\n\nWhile I think it is a good idea to mention that the argument to\n\"help\" does not have to be the name of a subcommand, I have two\nissues with this patch.\n\n * A free-standing \"While\" looks strange.  I would expect a sentence\n   that begins with \"While 'git help <guide>' shows X\" to end with\n   something negative like \"it is not recommended\". Perhaps it is\n   just me.\n\n * It took me two readings to realize that \"selected\" in \"selected\n   Git concept guide\" refers to \"what the user chose to see by\n   naming the <guide>\".  It looked as if the command will give users\n   only a selected few among 47 available ones, chosen by the\n   implementors.\n\nHow about doing it this way if you are adding two lines anyway?\n\n\t'git help -a' and 'git help -g' lists available subcommands\n\tand concept guides. See 'git help <command>' or 'git help\n\t<concept>' to read about a specific subcommand or concept.\n\nReplacing \"Examples:\" that has to stay incomplete for brevity with\nthe way to get the list of subcommands and concepts would a better\napproach, I think.  Teach them how to fish, instead of giving them\nfish.\n"},{"id":"210549","messageId":"7vwqtoyryp.fsf@alter.siamese.dyndns.org","threadId":"33060","inReplyTo":"1362342072-1412-3-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH v2 2/5] Help.c use OPT_COUNTUP","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-03T23:38:22Z","receivedAt":"2013-03-03T23:38:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.org> writes:\n\n> rename deprecated option in preparation for 'git help --guides'.\n\ns/rename/Rename/;\n\n>\n> Signed-off-by: Philip Oakley <philipoakley@iee.org>\n> ---\n\nHrm, I do not recall anybody ever declared that \"--all\" is deprecated.\n\nI do not think we want --all and --all --all to be different, and we\ncertainly do not want --all --no-all to be not-all, so I cannot tell\nwhat you want to achieve with this change at all, either from the\npatch or the proposed log message.\n\n>  builtin/help.c | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/builtin/help.c b/builtin/help.c\n> index d1d7181..d10cbed 100644\n> --- a/builtin/help.c\n> +++ b/builtin/help.c\n> @@ -39,7 +39,7 @@ static int show_all = 0;\n>  static unsigned int colopts;\n>  static enum help_format help_format = HELP_FORMAT_NONE;\n>  static struct option builtin_help_options[] = {\n> -\tOPT_BOOLEAN('a', \"all\", &show_all, N_(\"print all available commands\")),\n> +\tOPT_COUNTUP('a', \"all\", &show_all, N_(\"print all available commands\")),\n>  \tOPT_SET_INT('m', \"man\", &help_format, N_(\"show man page\"), HELP_FORMAT_MAN),\n>  \tOPT_SET_INT('w', \"web\", &help_format, N_(\"show manual in web browser\"),\n>  \t\t\tHELP_FORMAT_WEB),\n"},{"id":"210550","messageId":"7vk3poyryc.fsf@alter.siamese.dyndns.org","threadId":"33060","inReplyTo":"1362342072-1412-4-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH v2 3/5] Help.c add --guide option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-03T23:38:35Z","receivedAt":"2013-03-03T23:38:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.org> writes:\n\n> Logic, but no actions, included.\n\nI am not sure what you mean.  Is that to break \"bisect\"?\n\nAhh, you meant \"command line is parsed but we do not actually show\nguides yet, which is done by later patches in this series\".  OK.\n\n> The --all commands option, if given, will display first.\n> The --guide option's list will then be displayed.\n>\n> The common commands list is only displayed if neither option,\n> nor a command or guide name, is given.\n>\n> Signed-off-by: Philip Oakley <philipoakley@iee.org>\n> ---\n>  builtin/help.c | 8 ++++++--\n>  1 file changed, 6 insertions(+), 2 deletions(-)\n>\n> diff --git a/builtin/help.c b/builtin/help.c\n> index d10cbed..6089d72 100644\n> --- a/builtin/help.c\n> +++ b/builtin/help.c\n> @@ -36,10 +36,12 @@ enum help_format {\n>  static const char *html_path;\n>  \n>  static int show_all = 0;\n> +static int show_guides = 0;\n>  static unsigned int colopts;\n>  static enum help_format help_format = HELP_FORMAT_NONE;\n>  static struct option builtin_help_options[] = {\n>  \tOPT_COUNTUP('a', \"all\", &show_all, N_(\"print all available commands\")),\n> +\tOPT_COUNTUP('g', \"guides\", &show_guides, N_(\"print list of useful guides\")),\n>  \tOPT_SET_INT('m', \"man\", &help_format, N_(\"show man page\"), HELP_FORMAT_MAN),\n>  \tOPT_SET_INT('w', \"web\", &help_format, N_(\"show manual in web browser\"),\n>  \t\t\tHELP_FORMAT_WEB),\n> @@ -49,7 +51,7 @@ static struct option builtin_help_options[] = {\n>  };\n>  \n>  static const char * const builtin_help_usage[] = {\n> -\tN_(\"git help [--all] [--man|--web|--info] [command]\"),\n> +\tN_(\"git help [--all] [--guides] [--man|--web|--info] [command]\"),\n>  \tNULL\n>  };\n>  \n> @@ -429,9 +431,11 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n>  \t\tprintf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n>  \t\tlist_commands(colopts, &main_cmds, &other_cmds);\n>  \t\tprintf(\"%s\\n\", _(git_more_info_string));\n> +\t\tif (!show_guides) return 0;\n> +\t}\n> +\tif (show_guides) {\n>  \t\treturn 0;\n>  \t}\n> -\n\nUgly.\n\n\tif (show_all) {\n        \t... do not touch anything here ...\n\t\t... but remove \"return 0;\" ...\n\t}\n\n\tif (show_guides) {\n        \t... show guides but do not \"return 0\" ...\n\t}\n\n\tif (show_all || show_guides) {\n\t\t... we were asked to do either/or --all/--guides ...\n                ... and have done what we were asked to do ...\n\t\treturn 0;\n\t}\n\nThis is a tangent, but before all of the above, cmd_help() should\nverify that it got no arguments (when show_all/show_guides is in\neffect) or it got one argument (otherwise), I think.\n\n>  \tif (!argv[0]) {\n>  \t\tprintf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n>  \t\tlist_common_cmds_help();\n"},{"id":"210551","messageId":"7vd2vgyrxh.fsf@alter.siamese.dyndns.org","threadId":"33060","inReplyTo":"1362342072-1412-6-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH v2 5/5] Help doc: Include --guide option description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-03T23:39:06Z","receivedAt":"2013-03-03T23:39:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.org> writes:\n\n> Note that the ability to display an individual guide was\n> always possible. Include this in the update.\n>\n> Also tell readers how git(1) can be accessed, especially for\n> Git for Windows users who do not have the 'man' command.\n> Likewise include a commentary on how to access this page (Catch 22).\n>\n> Signed-off-by: Philip Oakley <philipoakley@iee.org>\n> ---\n>  Documentation/git-help.txt | 28 +++++++++++++++++++++-------\n>  1 file changed, 21 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\n> index e07b6dc..498a94e 100644\n> --- a/Documentation/git-help.txt\n> +++ b/Documentation/git-help.txt\n> @@ -8,31 +8,45 @@ git-help - Display help information about Git\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND]\n> +'git help' [-a|--all] [-g|--guide]\n> +\t   [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]\n>  \n>  DESCRIPTION\n>  -----------\n>  \n> -With no options and no COMMAND given, the synopsis of the 'git'\n> +With no options and no COMMAND|GUIDE given, the synopsis of the 'git'\n\nPlease avoid BNF in the prose meant for human consumption unless\nnecessary.  I think you can just say \" or \" here.\n\n>  command and a list of the most commonly used Git commands are printed\n>  on the standard output.\n>\n>  If the option '--all' or '-a' is given, then all available commands are\n>  printed on the standard output.\n>  \n> -If a Git subcommand is named, a manual page for that subcommand is brought\n> -up. The 'man' program is used by default for this purpose, but this\n> -can be overridden by other options or configuration variables.\n> +If the option '--guide' or '-g' is given then, a list of the useful\n> +Git guides is also printed on the standard output.\n\ns/given then,/given, then/ or just s/ then// make it easier to\nfollow?  I personally would vote for doing s/given, then/given, /\nfor the previous paragraph on \"--all\" as well.\n\n> -Note that `git --help ...` is identical to `git help ...` because the\n> +If a Git subcommand, or a Git guide, is given, a manual page for that\n\n\"If the name of a command or a guide is given\" without \"Git/git\"\nwould be much easier to read, especially when the first paragraph\ntalks about \"COMMAND or GUIDE\".  I also think s/command/subcommand/\nin the synopsis and in the first paragraph may be good for consistency\nwith this part.\n\n> +subcommand is brought up. The 'man' program is used by default for this\n> +purpose, but this can be overridden by other options or configuration\n> +variables.\n> +\n> +Note that 'git --help ...' is identical to 'git help ...' because the\n>  former is internally converted into the latter.\n>  \n> +To display the linkgit:git[1] man page use 'git help git'.\n\ns/man page use/man page, use/;\n\n> +\n> +This page can be displayed with 'git help help' or 'git help --help'\n> +\n>  OPTIONS\n>  -------\n>  -a::\n>  --all::\n>  \tPrints all the available commands on the standard output. This\n> -\toption supersedes any other option.\n> +\toption overides any given command or guide name.\n> +\n> +-g::\n> +--guides::\n> +\tPrints a list of useful guides on the standard output. This\n> +\toption overides any given command or guide name.\n\nThanks. Overall this round looks a lot more manageable than the\nprevious one.\n"},{"id":"210559","messageId":"EE36F065A5DA4769989FC7345DF7BCE6@PhilipOakley","threadId":"33060","inReplyTo":"7vwqtoyryp.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 2/5] Help.c use OPT_COUNTUP","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-03-03T23:44:18Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"[Sorry if the resend with Cc: crossed over]\nFrom: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Sunday, March 03, 2013 11:38 PM\nSubject: Re: [PATCH v2 2/5] Help.c use OPT_COUNTUP\n\n\n> Philip Oakley <philipoakley@iee.org> writes:\n>\n>> rename deprecated option in preparation for 'git help --guides'.\n>\n> s/rename/Rename/;\n\nOK.\n>\n>>\n>> Signed-off-by: Philip Oakley <philipoakley@iee.org>\n>> ---\n>\n> Hrm, I do not recall anybody ever declared that \"--all\" is deprecated.\n\nNo, it was the use OPT_COUNTUP rather than OPT_BOOLEAN that the \n'deprecated' was refering to.\nMaybe be I should have extended what option was being refered to.\n\n>\n> I do not think we want --all and --all --all to be different, and we\n> certainly do not want --all --no-all to be not-all, so I cannot tell\n> what you want to achieve with this change at all, either from the\n> patch or the proposed log message.\n>\n>>  builtin/help.c | 2 +-\n>>  1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/builtin/help.c b/builtin/help.c\n>> index d1d7181..d10cbed 100644\n>> --- a/builtin/help.c\n>> +++ b/builtin/help.c\n>> @@ -39,7 +39,7 @@ static int show_all = 0;\n>>  static unsigned int colopts;\n>>  static enum help_format help_format = HELP_FORMAT_NONE;\n>>  static struct option builtin_help_options[] = {\n>> - OPT_BOOLEAN('a', \"all\", &show_all, N_(\"print all available \n>> commands\")),\n>> + OPT_COUNTUP('a', \"all\", &show_all, N_(\"print all available \n>> commands\")),\n>>  OPT_SET_INT('m', \"man\", &help_format, N_(\"show man page\"), \n>> HELP_FORMAT_MAN),\n>>  OPT_SET_INT('w', \"web\", &help_format, N_(\"show manual in web \n>> browser\"),\n>>  HELP_FORMAT_WEB),\n"},{"id":"210560","messageId":"667B2BF898CC4491BE02C1142472A833@PhilipOakley","threadId":"33060","inReplyTo":"7vk3poyryc.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 3/5] Help.c add --guide option","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-03-03T23:44:18Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Sunday, March 03, 2013 11:38 PM\n> Philip Oakley <philipoakley@iee.org> writes:\n>\n>> Logic, but no actions, included.\n>\n> I am not sure what you mean.  Is that to break \"bisect\"?\n>\n> Ahh, you meant \"command line is parsed but we do not actually show\n> guides yet, which is done by later patches in this series\".  OK.\nTrue. I can add to the commit message.\n\n>\n>> The --all commands option, if given, will display first.\n>> The --guide option's list will then be displayed.\n>>\n>> The common commands list is only displayed if neither option,\n>> nor a command or guide name, is given.\n>>\n>> Signed-off-by: Philip Oakley <philipoakley@iee.org>\n>> ---\n>>  builtin/help.c | 8 ++++++--\n>>  1 file changed, 6 insertions(+), 2 deletions(-)\n>>\n>> diff --git a/builtin/help.c b/builtin/help.c\n>> index d10cbed..6089d72 100644\n>> --- a/builtin/help.c\n>> +++ b/builtin/help.c\n>> @@ -36,10 +36,12 @@ enum help_format {\n>>  static const char *html_path;\n>>\n>>  static int show_all = 0;\n>> +static int show_guides = 0;\n>>  static unsigned int colopts;\n>>  static enum help_format help_format = HELP_FORMAT_NONE;\n>>  static struct option builtin_help_options[] = {\n>>  OPT_COUNTUP('a', \"all\", &show_all, N_(\"print all available \n>> commands\")),\n>> + OPT_COUNTUP('g', \"guides\", &show_guides, N_(\"print list of useful \n>> guides\")),\n>>  OPT_SET_INT('m', \"man\", &help_format, N_(\"show man page\"), \n>> HELP_FORMAT_MAN),\n>>  OPT_SET_INT('w', \"web\", &help_format, N_(\"show manual in web \n>> browser\"),\n>>  HELP_FORMAT_WEB),\n>> @@ -49,7 +51,7 @@ static struct option builtin_help_options[] = {\n>>  };\n>>\n>>  static const char * const builtin_help_usage[] = {\n>> - N_(\"git help [--all] [--man|--web|--info] [command]\"),\n>> + N_(\"git help [--all] [--guides] [--man|--web|--info] [command]\"),\n>>  NULL\n>>  };\n>>\n>> @@ -429,9 +431,11 @@ int cmd_help(int argc, const char **argv, const \n>> char *prefix)\n>>  printf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n>>  list_commands(colopts, &main_cmds, &other_cmds);\n>>  printf(\"%s\\n\", _(git_more_info_string));\n>> + if (!show_guides) return 0;\n>> + }\n>> + if (show_guides) {\n>>  return 0;\n>>  }\n>> -\n>\n> Ugly.\n\nI was trying to minimise the apparent changes, but like you say...\n\n>\n> if (show_all) {\n>        ... do not touch anything here ...\n> ... but remove \"return 0;\" ...\n> }\n>\n> if (show_guides) {\n>        ... show guides but do not \"return 0\" ...\n> }\n>\n> if (show_all || show_guides) {\n> ... we were asked to do either/or --all/--guides ...\n>                ... and have done what we were asked to do ...\n> return 0;\n> }\n\nNeater.\n\n>\n> This is a tangent, but before all of the above, cmd_help() should\n> verify that it got no arguments (when show_all/show_guides is in\n> effect) or it got one argument (otherwise), I think.\n>\n>>  if (!argv[0]) {\n>>  printf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n>>  list_common_cmds_help();\n\nSeems reasonable. Should that be a separate preparatory patch (likely), \nor joined in with the rest?\n\nPhilip \n"},{"id":"210562","messageId":"7v4ngsyqpx.fsf@alter.siamese.dyndns.org","threadId":"33060","inReplyTo":"EE36F065A5DA4769989FC7345DF7BCE6@PhilipOakley","subject":"Re: [PATCH v2 2/5] Help.c use OPT_COUNTUP","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-04T00:05:14Z","receivedAt":"2013-03-04T00:05:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" <philipoakley@iee.org> writes:\n\n>> Hrm, I do not recall anybody ever declared that \"--all\" is deprecated.\n>\n> No, it was the use OPT_COUNTUP rather than OPT_BOOLEAN that the\n> deprecated' was refering to.\n\nOh, no OPT_BOOLEAN was deprecated because too many people rightfully\nthought it was about 0/1 choice and got burned by its count-up\nbehaviour.  When you want to count-up, OPT_COUNTUP is the right\nthing to do and replacing deprecated BOOLEAN with it is a correct\nthing to do.  But for this optoin, I do not think you want to count\nup in the first place.  You want a 0/1 choice, which is written as\nOPT_BOOL these days.\n"},{"id":"210564","messageId":"FF19719A7F4946ADA3FA4E1BD8075AE2@PhilipOakley","threadId":"33060","inReplyTo":"7vd2vgyrxh.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 5/5] Help doc: Include --guide option description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-03-04T00:06:08Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Sunday, March 03, 2013 11:39 PM\n> Philip Oakley <philipoakley@iee.org> writes:\n>\n>> Note that the ability to display an individual guide was\n>> always possible. Include this in the update.\n>>\n>> Also tell readers how git(1) can be accessed, especially for\n>> Git for Windows users who do not have the 'man' command.\n>> Likewise include a commentary on how to access this page (Catch 22).\n>>\n>> Signed-off-by: Philip Oakley <philipoakley@iee.org>\n>> ---\n>>  Documentation/git-help.txt | 28 +++++++++++++++++++++-------\n>>  1 file changed, 21 insertions(+), 7 deletions(-)\n>>\n>> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\n>> index e07b6dc..498a94e 100644\n>> --- a/Documentation/git-help.txt\n>> +++ b/Documentation/git-help.txt\n>> @@ -8,31 +8,45 @@ git-help - Display help information about Git\n>>  SYNOPSIS\n>>  --------\n>>  [verse]\n>> -'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND]\n>> +'git help' [-a|--all] [-g|--guide]\n>> +    [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]\n>>\n>>  DESCRIPTION\n>>  -----------\n>>\n>> -With no options and no COMMAND given, the synopsis of the 'git'\n>> +With no options and no COMMAND|GUIDE given, the synopsis of the \n>> 'git'\n>\n> Please avoid BNF in the prose meant for human consumption unless\n> necessary.  I think you can just say \" or \" here.\n\nOK\n>\n>>  command and a list of the most commonly used Git commands are \n>> printed\n>>  on the standard output.\n>>\n>>  If the option '--all' or '-a' is given, then all available commands \n>> are\n>>  printed on the standard output.\n>>\n>> -If a Git subcommand is named, a manual page for that subcommand is \n>> brought\n>> -up. The 'man' program is used by default for this purpose, but this\n>> -can be overridden by other options or configuration variables.\n>> +If the option '--guide' or '-g' is given then, a list of the useful\n>> +Git guides is also printed on the standard output.\n>\n> s/given then,/given, then/ or just s/ then// make it easier to\n> follow?  I personally would vote for doing s/given, then/given, /\n> for the previous paragraph on \"--all\" as well.\n\nAgreed.\n>\n>> -Note that `git --help ...` is identical to `git help ...` because \n>> the\n>> +If a Git subcommand, or a Git guide, is given, a manual page for \n>> that\n>\n> \"If the name of a command or a guide is given\" without \"Git/git\"\n> would be much easier to read, especially when the first paragraph\n> talks about \"COMMAND or GUIDE\".  I also think s/command/subcommand/\n> in the synopsis and in the first paragraph may be good for consistency\n> with this part.\n\nOK\n>\n>> +subcommand is brought up. The 'man' program is used by default for \n>> this\n>> +purpose, but this can be overridden by other options or \n>> configuration\n>> +variables.\n>> +\n>> +Note that 'git --help ...' is identical to 'git help ...' because \n>> the\n>>  former is internally converted into the latter.\n>>\n>> +To display the linkgit:git[1] man page use 'git help git'.\n>\n> s/man page use/man page, use/;\n\nYes.\n>\n>> +\n>> +This page can be displayed with 'git help help' or 'git help --help'\n>> +\n>>  OPTIONS\n>>  -------\n>>  -a::\n>>  --all::\n>>  Prints all the available commands on the standard output. This\n>> - option supersedes any other option.\n>> + option overides any given command or guide name.\n>> +\n>> +-g::\n>> +--guides::\n>> + Prints a list of useful guides on the standard output. This\n>> + option overides any given command or guide name.\n>\n> Thanks. Overall this round looks a lot more manageable than the\n> previous one.\n>\n\nThanks. It'll be a few days (or maybe more) for the update.\n\n[My Linux laptop (for checking everything) was just pressed into service \nfor my son's university studies while his regular one is in repair]\n\nPhilip \n"},{"id":"210566","messageId":"F455D17A40C2498C84F85E2937B732AC@PhilipOakley","threadId":"33060","inReplyTo":"7v4ngsyqpx.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 2/5] Help.c use OPT_COUNTUP","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-03-04T00:12:44Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Monday, March 04, 2013 12:05 AM\n> \"Philip Oakley\" <philipoakley@iee.org> writes:\n>\n>>> Hrm, I do not recall anybody ever declared that \"--all\" is \n>>> deprecated.\n>>\n>> No, it was the use OPT_COUNTUP rather than OPT_BOOLEAN that the\n>> deprecated' was refering to.\n>\n> Oh, no OPT_BOOLEAN was deprecated because too many people rightfully\n> thought it was about 0/1 choice and got burned by its count-up\n> behaviour.  When you want to count-up, OPT_COUNTUP is the right\n> thing to do and replacing deprecated BOOLEAN with it is a correct\n> thing to do.  But for this optoin, I do not think you want to count\n> up in the first place.  You want a 0/1 choice, which is written as\n> OPT_BOOL these days.\n\nAh, I missed that.\n\nThough, for the longer term --guides usage, I'd envisaged that having it \na second time could be used to invoke some extra search code that would \nlist all guides, rather than just the short list of common guides. But \nI'm not sure how best to determine what are valid guides, including \nMsysgit/Git4Windows which only uses the html versions (no man command), \nso I'll use OPT_BOOL initially.\n\nPhilip \n"}]}