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

[Jeff King <peff@peff.net>]

On Sun, Oct 24, 2010 at 03:24:42AM +0200, Thomas Rast wrote:

> Jeff King wrote:
> >   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).
> 
> I figured for consistency and ease of lookup *all* configuration docs
> should name the variables in the same format.  It can still be helpful
> to mention them elsewhere, e.g. in the option documentations, but the
> main docs should be a CONFIGURATION section formatted like this.
> 
> Or do you think that would be a bad thing?

No, I think everything should be in a CONFIGURATION section. So checking
for that is probably enough. I was more concerned about false positives
creeping in. Checking just the CONFIGURATION section would probably make
that unlikely, though.

-Peff