Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header

[Eric Sunshine <sunshine@sunshineco.com>]

On Fri, May 15, 2015 at 03:26:52PM -0700, Junio C Hamano wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote:
> >> I was just pointing out that you did not even have to have patch
> >> 1/5.
> >
> > Is that entirely accurate? The machinery (Makefiles, cmd-list.perl)
> > does have to be updated at some point to skip the "common" block which
> > get added in patch 2/5.
> 
> That is true, but if "# List of known git commands" instead of
> [commands] were used as the separator line, 1/5 wouldn't have needed
> any change to the Makefile.
> 
> Of course, if you need to add lines that would appear as junk to the
> old parser (e.g. the grouping info), at that point you would of
> course need to tell the parser to skip them.

Right. Preparing the machinery for the the upcoming "common" group
was actually the intent of patch 1/5 in the proposal[1]. Introducing
the [commands] header at that stage was merely a rather ugly
implementation detail of that goal, and I wasn't particularly happy
about suggesting it due to its ugliness. Unfortunately, the 1/5
commit message didn't clarify the matter. So, your observation of the
seeming pointlessness of patch 1/5 (which adds the [commands] header
for apparently no good reason) is quite understandable.

A more properly focused commit message (along with your suggestion to
scan for a comment or other separator) might help to salvage 1/5.
Perhaps something like this:

--- >8 ---
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH 1/5] command-list: prepare machinery for upcoming "common
 groups" section

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 <sunshine@sunshineco.com>
---
 Documentation/cmd-list.perl | 4 ++++
 Makefile                    | 5 +++--
 command-list.txt            | 3 ++-
 3 files changed, 9 insertions(+), 3 deletions(-)

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/Makefile b/Makefile
index 25a453b..5ed0acf 100644
--- a/Makefile
+++ b/Makefile
@@ -2454,7 +2454,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) ;; \
@@ -2462,7 +2462,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..609b344 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,5 @@
-# List of known git commands.
+# do not molest the next line
+### command list
 # command name                          category [deprecated] [common]
 git-add                                 mainporcelain common
 git-am                                  mainporcelain
-- 
2.4.1.260.ga2776d4

--- >8 ---

[1]: http://article.gmane.org/gmane.comp.version-control.git/268756