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@xxxxxxxxxxxxxxx > > 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html