Re: [RFC PATCH v2 0/3] Documentation: refactor config variable descriptions
- From
Thomas Rast <trast@student.ethz.ch>
- Date
- Oct 24, 2010, 01:24 UTC
- Message-ID
- <201010240324.42721.trast@student.ethz.ch>
- In-Reply-To
- <20101022155307.GB5554@sigill.intra.peff.net>
Jeff King wrote:
Show 7 quoted lines
> 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...]
Show 7 quoted lines
> [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