Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section
On Thu, May 21, 2015 at 9:55 AM, Sébastien Guimmara wrote: > On 05/21/2015 03:48 PM, Eric Sunshine wrote: >> On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara >> wrote: >>> 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 >>> --- >>> @@ -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 ? In my mind, the most logical point at which the documentation should start talking about the new "common coups" is when "common groups" actually comes into existence since the new documentation is directly related to birth of that new section of the file. The documentation update is, at best, only very peripherally related to removal of the old 'common' tag, so it doesn't really seem logical to tie the documentation update to 'common' removal in 4/5. But that's just my opinion... >> 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] Ah, right. Thanks for clarifying. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section
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.
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
