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

[Thomas Rast <trast@student.ethz.ch>]

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?

As for false positives, we could do the CONFIGURATION but in any case
I was hoping to avoid a special markup by using an asciidoc markup to
mark false positives if they arise (there currently aren't any).
E.g., it should be possible to make a {noconfig} attribute that
expands to nothing or so.  [Then again the same trick could be used
for all configs...]

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

True, you said that.  I'll hack it into this format, since it's easy
to do once the parsers are stable and can then just say something like
"herein" for all the ones actually in git-config(1).

-- 
Thomas Rast
trast@{inf,student}.ethz.ch