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

From: Philip Oakley <philipoakley@iee.org>
Date: Aug 8, 2012, 22:11 UTC
Message-ID: <C64F75694EC040349CFE91CD69EDB2DC@PhilipOakley>
In-Reply-To: <20120808205456.GB29528@sigill.intra.peff.net>

----- 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

Show 57 quoted lines

> 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.

Show 13 quoted lines

>
> 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
> --