From: Junio C Hamano <hidden> Date: 2016-06-15 22:54:27
Jeff King [off-list ref] 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 <redacted>
---
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.
From: Jeff King <hidden> Date: 2016-06-15 22:54:27
On Wed, Aug 08, 2012 at 12:24:29PM -0700, Junio C Hamano wrote:
Jeff King [off-list ref] writes:
quoted
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 <redacted>
---
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
From: Jeff King <hidden> Date: 2016-06-15 22:54:27
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 <redacted>
---
Makefile | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
From: Jeff King <hidden> Date: 2016-06-15 22:54:27
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 <redacted>
---
Makefile | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
From: Jeff King <hidden> Date: 2016-06-15 22:54:27
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 <redacted>
---
Makefile | 1 -
1 file changed, 1 deletion(-)
From: Jeff King <hidden> Date: 2016-06-15 22:54:27
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 <redacted>
---
Documentation/Makefile | 3 +++
Makefile | 26 ++------------------------
2 files changed, 5 insertions(+), 24 deletions(-)
From: Philip Oakley <hidden> Date: 2016-06-15 22:54:27
----- Original Message -----
From: "Jeff King" <redacted>
To: "Junio C Hamano" <redacted>
Cc: "Matthieu Moy" <redacted>; <redacted>
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:
quoted
Jeff King [off-list ref] writes:
quoted
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 <redacted>
---
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).
quoted
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.
quoted
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).
quoted
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
--