Re: [RFC PATCH v2 0/3] Documentation: refactor config variable descriptions

[Jeff King <peff@peff.net>]

On Fri, Oct 22, 2010 at 07:02:28AM +0200, Thomas Rast wrote:

> This resurrects (finally) the earlier attempt at
> 
>   http://mid.gmane.org/cover.1280169048.git.trast@student.ethz.ch
> 
> It tries the inverse approach: teaching the script how to find config
> variable blocks in each manpage, and then linking them from the main
> list.  (Obviously just inserting them into the main list could also
> work.)
> 
> In other words, it attempts to push out the "original" documentation
> of each variable from the main list to the individual manpage, which
> is exactly opposite from v1.

Thanks for working on this.

I think this approach is much saner for writers and readers of the
source files, and I think the output is much better (in particular, the
giant list having "see X" pointers instead of the actual description
blocks).

Your 2/3 doesn't seem to have made it through to the list, but I pulled
from your repository and looked at it. I have two comments on the
approach:

  1. It looks like you're more or less just parsing "::" list keys from
     all of the manpages. This seems somewhat fragile, as there could be
     other non-config lists. Can we at least restrict it to
     CONFIGURATION sections? It would be nice if we could put in some
     kind of semantic markup, but I'm not sure how painful that would be
     with asciidoc (we could always resort to comments in the source,
     but that would probably get unreadable quickly).

  2. You recursively follow includes via include::. This means that the
     make rule is not accurate. E.g., try:

       rm cmds-mainporcelain.txt config-vars.txt
       make config-vars.txt

     which should fail, as we actually depend on cmds-mainporcelain.txt.
     Doing it accurately and automatically would mean making .depend
     files for make.

     But I wonder if the recursive lookup is really required. Some of
     the includes with config files can just go away (e.g.,
     merge-config.txt is included only by config-vars-src.txt and
     git-merge.txt; it can just be merged straight into git-merge.txt
     once this system exists). Others, like pretty-formats.txt, should,
     IMHO, get their own user-visible page. Right now with your script
     you get[1]:

       format.pretty::
               The default pretty format for log/show/whatchanged command,
               See linkgit:git-log[1], linkgit:git-show[1],
               linkgit:git-whatchanged[1].

     but I would rather see[2]:

       format.pretty::
               See linkgit:gitpretty[7].

     [1]: I assume the single line of block description is an error in
          your script.

     [2]: Actually, as I mentioned a long time ago, I think it would be
          nicer to have a table like:

             format.attach         linkgit:git-format-patch[1]
             format.cc             linkgit:git-format-patch[1]
             format.headers        linkgit:git-format-patch[1]
             format.pretty         linkgit:gitpretty[7]

> I'm afraid 1/3 (semantically unchanged from the equivalent patch in
> v1) will again not make it through, so I again pushed this out:
> 
>   git://repo.or.cz/git/trast.git t/doc-config-extraction-v2

Yeah, I saw neither 1/3 nor 2/3 on the list.

-Peff