----- Original Message -----
From: "Jeff King" <p...@peff.net>
To: "Junio C Hamano" <gits...@pobox.com>
Cc: "Matthieu Moy" <matthieu....@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 <p...@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 <p...@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
--
--
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
