From: Sébastien Guimmara Date: Thu, 21 May 2015 13:55:39 GMT Subject: Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section Message-ID: <555DE3DB.1000406@gmail.com> In-Reply-To: On 05/21/2015 03:48 PM, Eric Sunshine wrote: > On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara > wrote: >> From: Eric Sunshine >> >> The ultimate goal is for "git help" to classify common commands by >> group. Toward this end, a subsequent patch will add a new "common >> groups" section to command-list.txt preceding the actual command list. >> As preparation, teach existing command-list.txt parsing machinery, which >> doesn't care about grouping, to skip over this upcoming "common groups" >> section. >> >> Signed-off-by: Eric Sunshine >> Signed-off-by: Sébastien Guimmara >> --- >> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl >> index 04f9977..5aa73cf 100755 >> --- a/Documentation/cmd-list.perl >> +++ b/Documentation/cmd-list.perl >> @@ -38,6 +38,10 @@ sub format_one { >> } >> } >> >> +while (<>) { >> + last if /^### command list/; >> +} >> + >> my %cmds = (); >> for (sort <>) { >> next if /^#/; >> diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt >> index d7de5a3..6d772bd 100644 >> --- a/Documentation/howto/new-command.txt >> +++ b/Documentation/howto/new-command.txt >> @@ -95,7 +95,9 @@ your language, document it in the INSTALL file. >> that categorizes commands by type, so they can be listed in appropriate >> subsections in the documentation's summary command list. Add an entry >> for yours. To understand the categories, look at git-commands.txt >> -in the main directory. >> +in the main directory. If the new command is part of the typical Git >> +workflow and you believe it common enough to be mentioned in 'git help', >> +map this command to a common group in the column [common]. > > I think you meant to squash the documentation update into patch 2/5 > where the "common groups" block is actually introduced. It doesn't > really belong in this patch which is about updating machinery in > preparation for the new block. I don't mind squashing it with another commit, but in this case, wouldn't it make more sense to squash it with 4/5, when the 'common' tag is removed and the file is in its final form ? > > Also, it's now spelled "### common groups" rather than "[common]". > actually, this [common] is not the one I added in a previous series, but the one that was already present: # command name category [deprecated] [common] >> 7. Give the maintainer one paragraph to include in the RelNotes file >> to describe the new feature; a good place to do so is in the cover >> diff --git a/Makefile b/Makefile >> index 323c401..655740d 100644 >> --- a/Makefile >> +++ b/Makefile >> @@ -2455,7 +2455,7 @@ check-docs:: >> esac ; \ >> test -f "Documentation/$$v.txt" || \ >> echo "no doc: $$v"; \ >> - sed -e '/^#/d' command-list.txt | \ >> + sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \ >> grep -q "^$$v[ ]" || \ >> case "$$v" in \ >> git) ;; \ >> @@ -2463,7 +2463,8 @@ check-docs:: >> esac ; \ >> done; \ >> ( \ >> - sed -e '/^#/d' \ >> + sed -e '1,/^### command list/d' \ >> + -e '/^#/d' \ >> -e 's/[ ].*//' \ >> -e 's/^/listed /' command-list.txt; \ >> $(MAKE) -C Documentation print-man1 | \ >> diff --git a/command-list.txt b/command-list.txt >> index 54d8d21..181a9c2 100644 >> --- a/command-list.txt >> +++ b/command-list.txt >> @@ -1,4 +1,4 @@ >> -# List of known git commands. >> +### command list (do not change this line) >> # command name category [deprecated] [common] >> git-add mainporcelain common >> git-am mainporcelain >> -- >> 2.4.0.GIT