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

From: Jeff King <peff@peff.net>
Date: Oct 25, 2010, 15:04 UTC
Message-ID: <20101025150405.GC28278@sigill.intra.peff.net>
In-Reply-To: <201010240324.42721.trast@student.ethz.ch>

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

Show 15 quoted lines

> 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