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

[Eric Sunshine <sunshine@sunshineco.com>]

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.

Also, it's now spelled "### common groups" rather than "[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