[PATCH] Documentation: list git-credential in plumbing commands

[PATCH] Documentation: list git-credential in plumbing commands

[Matthieu Moy]

Commit e30b2feb1b (Jun 24 2012, add 'git credential' plumbing command)
forgot to add git-credential to command-list.txt, hence the command was
not appearing in the documentation, making it hard for users to discover
it.

While we're there, capitalize the description line for git-crendential
for consistancy with other commands.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-credential.txt | 2 +-
 command-list.txt                 | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
index 53adee3..810e957 100644
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.txt
@@ -3,7 +3,7 @@ git-credential(1)
 
 NAME
 ----
-git-credential - retrieve and store user credentials
+git-credential - Retrieve and store user credentials
 
 SYNOPSIS
 --------
diff --git a/command-list.txt b/command-list.txt
index 14ea67a..ec64cac 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -25,6 +25,7 @@ git-commit                              mainporcelain common
 git-commit-tree                         plumbingmanipulators
 git-config                              ancillarymanipulators
 git-count-objects                       ancillaryinterrogators
+git-credential                          purehelpers
 git-cvsexportcommit                     foreignscminterface
 git-cvsimport                           foreignscminterface
 git-cvsserver                           foreignscminterface
-- 
1.7.12.rc1.183.gb94da76

Re: [PATCH] Documentation: list git-credential in plumbing commands

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> Commit e30b2feb1b (Jun 24 2012, add 'git credential' plumbing command)
> forgot to add git-credential to command-list.txt, hence the command was
> not appearing in the documentation, making it hard for users to discover
> it.
>
> While we're there, capitalize the description line for git-crendential
> for consistancy with other commands.

consistency?

>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>

Thanks.

There really should be an easier way for the maintainer to notice
this kind of glitch without being told (better yet, the submitter of
a new command to notice it).  Perhaps the check-docs target in the
Makefile needs some updating?

[PATCH v2] Documentation: list git-credential in plumbing commands

[Matthieu Moy]

Commit e30b2feb1b (Jun 24 2012, add 'git credential' plumbing command)
forgot to add git-credential to command-list.txt, hence the command was
not appearing in the documentation, making it hard for users to discover
it.

While we're there, capitalize the description line for git-crendential
for consistency with other commands.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
> > for consistancy with other commands.
> 
> consistency?

Yes, sorry. This one should be OK.

 Documentation/git-credential.txt | 2 +-
 command-list.txt                 | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
index 53adee3..810e957 100644
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.txt
@@ -3,7 +3,7 @@ git-credential(1)
 
 NAME
 ----
-git-credential - retrieve and store user credentials
+git-credential - Retrieve and store user credentials
 
 SYNOPSIS
 --------
diff --git a/command-list.txt b/command-list.txt
index 14ea67a..ec64cac 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -25,6 +25,7 @@ git-commit                              mainporcelain common
 git-commit-tree                         plumbingmanipulators
 git-config                              ancillarymanipulators
 git-count-objects                       ancillaryinterrogators
+git-credential                          purehelpers
 git-cvsexportcommit                     foreignscminterface
 git-cvsimport                           foreignscminterface
 git-cvsserver                           foreignscminterface
-- 
1.7.12.rc1.183.gb94da76

[PATCH 0/4] update "make check-docs"

[Jeff King]

On Wed, Aug 08, 2012 at 09:58:33AM -0700, Junio C Hamano wrote:

> There really should be an easier way for the maintainer to notice
> this kind of glitch without being told (better yet, the submitter of
> a new command to notice it).  Perhaps the check-docs target in the
> Makefile needs some updating?

Hmm. We have a check-docs command? :)

This patch series at least brings that up to date. It goes on top of
Matthieu's patch.

  [1/4]: check-docs: mention gitweb specially
  [2/4]: check-docs: update non-command documentation list
  [3/4]: command-list: add git-sh-i18n
  [4/4]: command-list: mention git-credential-* helpers

-Peff

[PATCH 1/4] check-docs: mention gitweb specially

[Jeff King]

Like gitk, gitweb is not listed in the usual Makefile
variables and must be fed to check-docs specially. Otherwise
check-docs thinks it is documented but removed.

Signed-off-by: Jeff King <peff@peff.net>
---
 Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 15d1319..5e773cd 100644
--- a/Makefile
+++ b/Makefile
@@ -2805,7 +2805,7 @@ endif
 ### Check documentation
 #
 check-docs::
-	@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \
+	@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb; \
 	do \
 		case "$$v" in \
 		git-merge-octopus | git-merge-ours | git-merge-recursive | \
@@ -2855,7 +2855,7 @@ check-docs::
 		documented,gitworkflows | \
 		sentinel,not,matching,is,ok ) continue ;; \
 		esac; \
-		case " $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk " in \
+		case " $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb " in \
 		*" $$cmd "*)	;; \
 		*) echo "removed but $$how: $$cmd" ;; \
 		esac; \
-- 
1.7.12.rc2.2.g584e0d9

[PATCH 2/4] check-docs: update non-command documentation list

[Jeff King]

The check-docs target looks at Documentation/git*txt and
complains if any entry does not have a matching command.
Therefore we need to explicitly ignore any entries which are
not meant to describe a command (like gitattributes.txt).
This list has grown stale over time, so let's bring it up to
date.

Signed-off-by: Jeff King <peff@peff.net>
---
I really wonder if we would do better to match git-*.txt, since most of
the ignores are gitfoo(7) types of pages. We'd probably want to add back
in "git", "gitweb" and "gitk" explicitly, but they are already handled
specially above and below.

 Makefile | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Makefile b/Makefile
index 5e773cd..41d9db8 100644
--- a/Makefile
+++ b/Makefile
@@ -2853,6 +2853,9 @@ check-docs::
 		documented,git-bisect-lk2009 | \
 		documented,git-remote-helpers | \
 		documented,gitworkflows | \
+		documented,gitcredentials | \
+		documented,gitnamespaces | \
+		documented,gitweb.conf | \
 		sentinel,not,matching,is,ok ) continue ;; \
 		esac; \
 		case " $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb " in \
-- 
1.7.12.rc2.2.g584e0d9

[PATCH 3/4] command-list: add git-sh-i18n

[Jeff King]

This is in the same category as git-sh-setup.

Signed-off-by: Jeff King <peff@peff.net>
---
 command-list.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/command-list.txt b/command-list.txt
index ec64cac..1da8f0d 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -114,6 +114,7 @@ git-show                                mainporcelain common
 git-show-branch                         ancillaryinterrogators
 git-show-index                          plumbinginterrogators
 git-show-ref                            plumbinginterrogators
+git-sh-i18n                             purehelpers
 git-sh-setup                            purehelpers
 git-stash                               mainporcelain
 git-status                              mainporcelain common
-- 
1.7.12.rc2.2.g584e0d9

[PATCH 4/4] command-list: mention git-credential-* helpers

[Jeff King]

These commands were never added to the command-list. Adding
them makes "make check-docs" run without complaint.
While we're at it, let's capitalize the first letter of
their one-line summaries to match the rest of the git
manpages.

The credential-cache--daemon command is somewhat special. It
is already ignored by check-docs because it contains a "--",
marking it as a non-interesting implementation detail. It
is, in fact, documented, but since the documentation
basically just redirects you to a more appropriate command
anyway, let's explicitly omit it so it is not mentioned in
git(1).

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-credential-cache--daemon.txt | 2 +-
 Documentation/git-credential-cache.txt         | 2 +-
 Documentation/git-credential-store.txt         | 2 +-
 command-list.txt                               | 2 ++
 4 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
index 11edc5a..d15db42 100644
--- a/Documentation/git-credential-cache--daemon.txt
+++ b/Documentation/git-credential-cache--daemon.txt
@@ -3,7 +3,7 @@ git-credential-cache--daemon(1)
 
 NAME
 ----
-git-credential-cache--daemon - temporarily store user credentials in memory
+git-credential-cache--daemon - Temporarily store user credentials in memory
 
 SYNOPSIS
 --------
diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt
index f3d09c5..eeff5fa 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.txt
@@ -3,7 +3,7 @@ git-credential-cache(1)
 
 NAME
 ----
-git-credential-cache - helper to temporarily store passwords in memory
+git-credential-cache - Helper to temporarily store passwords in memory
 
 SYNOPSIS
 --------
diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt
index 3109346..b27c03c 100644
--- a/Documentation/git-credential-store.txt
+++ b/Documentation/git-credential-store.txt
@@ -3,7 +3,7 @@ git-credential-store(1)
 
 NAME
 ----
-git-credential-store - helper to store credentials on disk
+git-credential-store - Helper to store credentials on disk
 
 SYNOPSIS
 --------
diff --git a/command-list.txt b/command-list.txt
index 1da8f0d..7e8cfec 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -26,6 +26,8 @@ git-commit-tree                         plumbingmanipulators
 git-config                              ancillarymanipulators
 git-count-objects                       ancillaryinterrogators
 git-credential                          purehelpers
+git-credential-cache                    purehelpers
+git-credential-store                    purehelpers
 git-cvsexportcommit                     foreignscminterface
 git-cvsimport                           foreignscminterface
 git-cvsserver                           foreignscminterface
-- 
1.7.12.rc2.2.g584e0d9

Re: [PATCH 0/4] update "make check-docs"

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, Aug 08, 2012 at 09:58:33AM -0700, Junio C Hamano wrote:
>
>> There really should be an easier way for the maintainer to notice
>> this kind of glitch without being told (better yet, the submitter of
>> a new command to notice it).  Perhaps the check-docs target in the
>> Makefile needs some updating?
>
> Hmm. We have a check-docs command? :)

Yes, and there also is a check-builtins target.  Perhaps the default
build target should depend on them, as they are fairly lightweight?

> This patch series at least brings that up to date. It goes on top of
> Matthieu's patch.
>
>   [1/4]: check-docs: mention gitweb specially
>   [2/4]: check-docs: update non-command documentation list
>   [3/4]: command-list: add git-sh-i18n
>   [4/4]: command-list: mention git-credential-* helpers

Thanks.

Re: [PATCH 2/4] check-docs: update non-command documentation list

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> The check-docs target looks at Documentation/git*txt and
> complains if any entry does not have a matching command.
> Therefore we need to explicitly ignore any entries which are
> not meant to describe a command (like gitattributes.txt).
> This list has grown stale over time, so let's bring it up to
> date.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> I really wonder if we would do better to match git-*.txt, since most of
> the ignores are gitfoo(7) types of pages. We'd probably want to add back
> in "git", "gitweb" and "gitk" explicitly, but they are already handled
> specially above and below.

Quite possibly, yes.

Also "git gitk gitweb" may want to be made into a Makefile variable
to be shared in the "above" and "below" (I do not know what to call
them offhand---they are programs with special build rules that are
not covered by ALL/SCRIPT_LIB/BUILTIN).

By the way, do we have a documentation for git-gui?  Perhaps it may
want to be added to that "git gitk gitweb" list as a reminder that
it lacks documentation.  One of the goals of the person who runs
"make check-docs" should be to reduce the special case that appears
at the beginning of that case statement.

I also wonder why "help" is not treated as a built-in?  Perhaps we
should throw it in to "git gitk gitweb" list?  After all, it is a
command that is available in "git foo" form, is documented, and is
listed in the command-list.txt file.

Thanks.

Re: [PATCH 0/4] update "make check-docs"

[Jeff King]

On Wed, Aug 08, 2012 at 12:13:11PM -0700, Junio C Hamano wrote:

> > Hmm. We have a check-docs command? :)
> 
> Yes, and there also is a check-builtins target.  Perhaps the default
> build target should depend on them, as they are fairly lightweight?

I think they would want some refactoring. Right now the target does not
fail if there are errors. Any output it generates would typically scroll
by in the mass of other build data, so it would be easy to miss.

-Peff

Re: [PATCH 2/4] check-docs: update non-command documentation list

[Jeff King]

On Wed, Aug 08, 2012 at 12:24:29PM -0700, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > The check-docs target looks at Documentation/git*txt and
> > complains if any entry does not have a matching command.
> > Therefore we need to explicitly ignore any entries which are
> > not meant to describe a command (like gitattributes.txt).
> > This list has grown stale over time, so let's bring it up to
> > date.
> >
> > Signed-off-by: Jeff King <peff@peff.net>
> > ---
> > I really wonder if we would do better to match git-*.txt, since most of
> > the ignores are gitfoo(7) types of pages. We'd probably want to add back
> > in "git", "gitweb" and "gitk" explicitly, but they are already handled
> > specially above and below.
> 
> Quite possibly, yes.

Actually, my "already handled specially" is not quite accurate. That
special list is "things that are commands but are not necessarily
mentioned in the Makefile variables". But this list is "things that are
documented but do not begin with git-". The two should mostly be the
same, but the whole point of this exercise is to make sure they _are_
the same.

A better solution is to simply ask the Documentation directory what the
commands are, since it already knows (in the form of MAN1_TXT).

> Also "git gitk gitweb" may want to be made into a Makefile variable
> to be shared in the "above" and "below" (I do not know what to call
> them offhand---they are programs with special build rules that are
> not covered by ALL/SCRIPT_LIB/BUILTIN).

I couldn't think of a special name, either, but I think it is sufficient
to just create a new ALL_COMMANDS variable that includes those other
things, and then add to it.

> By the way, do we have a documentation for git-gui?  Perhaps it may
> want to be added to that "git gitk gitweb" list as a reminder that
> it lacks documentation.  One of the goals of the person who runs
> "make check-docs" should be to reduce the special case that appears
> at the beginning of that case statement.

Yes, it should be checked (and git-citool, too).

> I also wonder why "help" is not treated as a built-in?  Perhaps we
> should throw it in to "git gitk gitweb" list?  After all, it is a
> command that is available in "git foo" form, is documented, and is
> listed in the command-list.txt file.

Historically it was part of git.c, but these days it is a built-in and
does not need any special treatment from check-docs.

Patches for all to follow (on top of my previous 4).

  [5/4]: check-docs: factor out command-list
  [6/4]: check-docs: list git-gui as a command
  [7/4]: check-docs: drop git-help special-case
  [8/4]: check-docs: get documented command list from Makefile

-Peff

[PATCH 5/4] check-docs: factor out command-list

[Jeff King]

The check-docs command list is composed from several
Makefile variables plus some special cases. Let's make the
meaning of the list more obvious and avoid repeating
ourselves by factoring it out.

Signed-off-by: Jeff King <peff@peff.net>
---
 Makefile | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 41d9db8..6ae868d 100644
--- a/Makefile
+++ b/Makefile
@@ -2804,8 +2804,12 @@ endif
 
 ### Check documentation
 #
+ALL_COMMANDS = $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS)
+ALL_COMMANDS += git
+ALL_COMMANDS += gitk
+ALL_COMMANDS += gitweb
 check-docs::
-	@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb; \
+	@(for v in $(ALL_COMMANDS); \
 	do \
 		case "$$v" in \
 		git-merge-octopus | git-merge-ours | git-merge-recursive | \
@@ -2858,7 +2862,7 @@ check-docs::
 		documented,gitweb.conf | \
 		sentinel,not,matching,is,ok ) continue ;; \
 		esac; \
-		case " $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb " in \
+		case " $(ALL_COMMANDS) " in \
 		*" $$cmd "*)	;; \
 		*) echo "removed but $$how: $$cmd" ;; \
 		esac; \
-- 
1.7.12.rc2.36.gb1dc81b

[PATCH 6/4] check-docs: list git-gui as a command

[Jeff King]

git-gui is already documented and mentioned in command-list,
but adding it to the Makefile makes sure it is so. We also
add its alias git-citool (which is also documented).

As a result, we can drop them from the special case
statement that avoids them being listed as "documented but
does not exist".

Signed-off-by: Jeff King <peff@peff.net>
---
 Makefile | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 6ae868d..4b3c366 100644
--- a/Makefile
+++ b/Makefile
@@ -2808,6 +2808,7 @@ ALL_COMMANDS = $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS)
 ALL_COMMANDS += git
 ALL_COMMANDS += gitk
 ALL_COMMANDS += gitweb
+ALL_COMMANDS += git-gui git-citool
 check-docs::
 	@(for v in $(ALL_COMMANDS); \
 	do \
@@ -2837,8 +2838,6 @@ check-docs::
 	) | while read how cmd; \
 	do \
 		case "$$how,$$cmd" in \
-		*,git-citool | \
-		*,git-gui | \
 		*,git-help | \
 		documented,gitattributes | \
 		documented,gitignore | \
-- 
1.7.12.rc2.36.gb1dc81b

[PATCH 7/4] check-docs: drop git-help special-case

[Jeff King]

The check-docs target special-cases git-help to avoid
mentioning it as "documented but removed". This dates back
to the early implementation of git-help, when its code was
simply included inside git.c.

These days it is a full-fledged builtin (in builtin/help.c)
and does not need special-casing.

Signed-off-by: Jeff King <peff@peff.net>
---
 Makefile | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Makefile b/Makefile
index 4b3c366..b9da511 100644
--- a/Makefile
+++ b/Makefile
@@ -2838,7 +2838,6 @@ check-docs::
 	) | while read how cmd; \
 	do \
 		case "$$how,$$cmd" in \
-		*,git-help | \
 		documented,gitattributes | \
 		documented,gitignore | \
 		documented,gitmodules | \
-- 
1.7.12.rc2.36.gb1dc81b

[PATCH 8/4] check-docs: get documented command list from Makefile

[Jeff King]

The current code tries to get a list of documented commands
by doing "ls Documentation/git*txt" and culling a bunch of
special cases from the result. Looking for "git-*.txt" would
be more accurate, but would miss a few commands like
"gitweb" and "gitk".

Fortunately, Documentation/Makefile already knows what this
list is, so we can just ask it. Annoyingly, we still have to
post-process its output a little, since make will print
extra cruft like "GIT-VERSION-FILE is up to date" to stdout.

Now that our list is accurate, we can remove all of the ugly
special-cases.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/Makefile |  3 +++
 Makefile               | 26 ++------------------------
 2 files changed, 5 insertions(+), 24 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 063fa69..cf5916f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -344,4 +344,7 @@ require-htmlrepo::
 quick-install-html: require-htmlrepo
 	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir)
 
+print-man1:
+	@for i in $(MAN1_TXT); do echo $$i; done
+
 .PHONY: FORCE
diff --git a/Makefile b/Makefile
index b9da511..51b3c6f 100644
--- a/Makefile
+++ b/Makefile
@@ -2832,34 +2832,12 @@ check-docs::
 		sed -e '/^#/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
-		ls -1 Documentation/git*txt | \
+		$(MAKE) -C Documentation print-man1 | \
+		grep '\.txt$$' | \
 		sed -e 's|Documentation/|documented |' \
 		    -e 's/\.txt//'; \
 	) | while read how cmd; \
 	do \
-		case "$$how,$$cmd" in \
-		documented,gitattributes | \
-		documented,gitignore | \
-		documented,gitmodules | \
-		documented,gitcli | \
-		documented,git-tools | \
-		documented,gitcore-tutorial | \
-		documented,gitcvs-migration | \
-		documented,gitdiffcore | \
-		documented,gitglossary | \
-		documented,githooks | \
-		documented,gitrepository-layout | \
-		documented,gitrevisions | \
-		documented,gittutorial | \
-		documented,gittutorial-2 | \
-		documented,git-bisect-lk2009 | \
-		documented,git-remote-helpers | \
-		documented,gitworkflows | \
-		documented,gitcredentials | \
-		documented,gitnamespaces | \
-		documented,gitweb.conf | \
-		sentinel,not,matching,is,ok ) continue ;; \
-		esac; \
 		case " $(ALL_COMMANDS) " in \
 		*" $$cmd "*)	;; \
 		*) echo "removed but $$how: $$cmd" ;; \
-- 
1.7.12.rc2.36.gb1dc81b

Re: [PATCH 8/4] check-docs: get documented command list from Makefile

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> The current code tries to get a list of documented commands
> by doing "ls Documentation/git*txt" and culling a bunch of
> special cases from the result. Looking for "git-*.txt" would
> be more accurate, but would miss a few commands like
> "gitweb" and "gitk".
>
> Fortunately, Documentation/Makefile already knows what this
> list is, so we can just ask it. Annoyingly, we still have to
> post-process its output a little, since make will print
> extra cruft like "GIT-VERSION-FILE is up to date" to stdout.

Yeah, traditional way to do this is to give special markers around
what you want your Makefile to tell you, e.g.

	sayit:
        	echo "@@@ $(FOO) ###"
	useit:
        	$(MAKE) sayit | \
                sed -ne 's/^@@@ \(.*\) ###$/\1/p' | \
                ... use it ...

but in this case we know we want "*.txt", so the way you filtered
the output is sufficient.

> Now that our list is accurate, we can remove all of the ugly
> special-cases.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/Makefile |  3 +++
>  Makefile               | 26 ++------------------------

Yay, maintainability comes with a large line reduction bonus ;-)

Thanks.

Re: [PATCH 2/4] check-docs: update non-command documentation list

[Philip Oakley]

----- Original Message ----- 
From: "Jeff King" <peff@peff.net>
To: "Junio C Hamano" <gitster@pobox.com>
Cc: "Matthieu Moy" <Matthieu.Moy@imag.fr>; <git@vger.kernel.org>
Sent: Wednesday, August 08, 2012 9:54 PM
Subject: Re: [PATCH 2/4] check-docs: update non-command documentation 
list


> On Wed, Aug 08, 2012 at 12:24:29PM -0700, Junio C Hamano wrote:
>
>> Jeff King <peff@peff.net> writes:
>>
>> > The check-docs target looks at Documentation/git*txt and
>> > complains if any entry does not have a matching command.
>> > Therefore we need to explicitly ignore any entries which are
>> > not meant to describe a command (like gitattributes.txt).
>> > This list has grown stale over time, so let's bring it up to
>> > date.
>> >
>> > Signed-off-by: Jeff King <peff@peff.net>
>> > ---
>> > I really wonder if we would do better to match git-*.txt, since 
>> > most of
>> > the ignores are gitfoo(7) types of pages. We'd probably want to add 
>> > back
>> > in "git", "gitweb" and "gitk" explicitly, but they are already 
>> > handled
>> > specially above and below.
>>
>> Quite possibly, yes.
>
> Actually, my "already handled specially" is not quite accurate. That
> special list is "things that are commands but are not necessarily
> mentioned in the Makefile variables". But this list is "things that 
> are
> documented but do not begin with git-". The two should mostly be the
> same, but the whole point of this exercise is to make sure they _are_
> the same.
>
> A better solution is to simply ask the Documentation directory what 
> the
> commands are, since it already knows (in the form of MAN1_TXT).
>
>> Also "git gitk gitweb" may want to be made into a Makefile variable
>> to be shared in the "above" and "below" (I do not know what to call
>> them offhand---they are programs with special build rules that are
>> not covered by ALL/SCRIPT_LIB/BUILTIN).
>
> I couldn't think of a special name, either, but I think it is 
> sufficient
> to just create a new ALL_COMMANDS variable that includes those other
> things, and then add to it.
>
>> By the way, do we have a documentation for git-gui?  Perhaps it may
>> want to be added to that "git gitk gitweb" list as a reminder that
>> it lacks documentation.  One of the goals of the person who runs
>> "make check-docs" should be to reduce the special case that appears
>> at the beginning of that case statement.
>
> Yes, it should be checked (and git-citool, too).
>
>> I also wonder why "help" is not treated as a built-in?  Perhaps we
>> should throw it in to "git gitk gitweb" list?  After all, it is a
>> command that is available in "git foo" form, is documented, and is
>> listed in the command-list.txt file.

One issue I notice a few weeks ago is that `git help --all` does not 
list all of the available git help pages, rather it just limits itself 
to the available command pages.

This means that new users can't discover those additional help pages in 
any easy manner.

I had an initial look at what might be involved in adding a --guides 
option, shifting the current --all to --cmd (or --command) and then 
make --all list both commands and guides.

The need for help to list all the guides is parallel to these patches. I 
didn't get that far in working out how to approach such a patch which 
would discovere the available guides - I'm on GfW-msysgit which normally 
uses web display.

>
> Historically it was part of git.c, but these days it is a built-in and
> does not need any special treatment from check-docs.
>
> Patches for all to follow (on top of my previous 4).
>
>  [5/4]: check-docs: factor out command-list
>  [6/4]: check-docs: list git-gui as a command
>  [7/4]: check-docs: drop git-help special-case
>  [8/4]: check-docs: get documented command list from Makefile
>
> -Peff
> --

Re: [PATCH 2/4] check-docs: update non-command documentation list

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> One issue I notice a few weeks ago is that `git help --all` does not
> list all of the available git help pages, rather it just limits itself
> to the available command pages.
>
> This means that new users can't discover those additional help pages
> in any easy manner.

That would be a problem _only_ if these "additional help pages" are
of importance for new users.  I do not think things that come from
Documentation/technical and ARTICLES (in Documentation/Makefile)
qualify as such.

I'd be perfectly happy as long as all documents are reachable from
git.html in html-fied documentation (the man pages have equivalent
cross references, I think).

Re: [PATCH 2/4] check-docs: update non-command documentation list

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> One issue I notice a few weeks ago is that `git help --all` does not
>> list all of the available git help pages, rather it just limits 
>> itself
>> to the available command pages.
>>
>> This means that new users can't discover those additional help pages
>> in any easy manner.
>
> That would be a problem _only_ if these "additional help pages" are
> of importance for new users.  I do not think things that come from
> Documentation/technical and ARTICLES (in Documentation/Makefile)
> qualify as such.

I'd generally agree with that. I wasn't aware of ARTICLES (in 
Documentation/Makefile), so that's something to I'll need to look at.

>
> I'd be perfectly happy as long as all documents are reachable from
> git.html in html-fied documentation (the man pages have equivalent
> cross references, I think).
>

That is generally the tack I was looking of taking. Part of the task is 
making sure the 'right' pages are found from the 'right' places. So 
that, for the beginner needing help (git help --all),  even the 
'everyday  git in 20 commands' and 'User manual' would be listed in the 
available guides section.

>
> -----

Re: [PATCH 4/4] command-list: mention git-credential-* helpers

[Matthieu Moy]

Jeff King <peff@peff.net> writes:

> These commands were never added to the command-list. Adding
> them makes "make check-docs" run without complaint.
> While we're at it, let's capitalize the first letter of
> their one-line summaries to match the rest of the git
> manpages.

You may want to squash my patch in this one, since they really do the
same thing.

In any case, thanks for taking care of this, the patches sound good.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/