Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section

["Sébastien Guimmara" <sebastien.guimmara@gmail.com>]

On 05/21/2015 03:48 PM, Eric Sunshine wrote:
> On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> From: Eric Sunshine <sunshine@sunshineco.com>
>>
>> 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>
>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>> 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