From: Philip Oakley <philipoakley@iee.org>
Date: Sat, 16 May 2015 09:44:04 GMT
Subject: Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
Message-ID: <CF195F7BDDED481EA064C0C30098017C@PhilipOakley>
In-Reply-To: <1431714904-16599-2-git-send-email-sebastien.guimmara@gmail.com>

From: "Sébastien Guimmara" <sebastien.guimmara@gmail.com>
> Add a [commands] header before the actual command list, then make the
> following files ignore this header in their parsing:
>
> * cmd-list.perl
> * Makefile (check-docks target)

s/docks/docs/
or even fuller as "(the check-docs target)"?
I'd misunderstood this as (verb) check the doumentation targets within 
the Makefile, rather than the (definite article) 'check-docs' target 
within the Makefile ~#L2554.
--
Philip

>
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> Documentation/cmd-list.perl         | 4 ++++
> Documentation/howto/new-command.txt | 4 +++-
> Makefile                            | 3 ++-
> command-list.txt                    | 1 +
> 4 files changed, 10 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
> index 04f9977..06a5fd6 100755
> --- a/Documentation/cmd-list.perl
> +++ b/Documentation/cmd-list.perl
> @@ -38,6 +38,10 @@ sub format_one {
>  }
> }
>
> +while (<>) {
> + last if /^\[commands\]/;
> +}
> +
> 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].
>
> 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 25a453b..0cb2045 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,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
>  grep -q "^$$v[ ]" || \
>  case "$$v" in \
>  git) ;; \
> @@ -2463,6 +2463,7 @@ check-docs::
>  done; \
>  ( \
>  sed -e '/^#/d' \
> +     -e '1,/^\[commands\]/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..caed872 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,5 +1,6 @@
> # List of known git commands.
> # command name                          category [deprecated] [common]
> +[commands]
> git-add                                 mainporcelain common
> git-am                                  mainporcelain
> git-annotate                            ancillaryinterrogators
> -- 
> 2.4.0