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

On Mon, Jul 26, 2010 at 18:48, Thomas Rast [off-list ref] wrote:

This little series is a bit of a spinoff from

 http://article.gmane.org/gmane.comp.version-control.git/146696
and
 http://article.gmane.org/gmane.comp.version-control.git/145139

Since I didn't want to spam the list with 24 RFC emails, I squashed
all the manpage-specific patches into one for this submission.  You
can find the originals at

 git://repo.or.cz/git/trast.git t/doc-config-extraction

Judging from its size it's quite possible that

 [1/24] Documentation: Move variables from config.txt to separate file

won't make it through to the list, either, and -M doesn't help, so you
may have to look it up at the above repository too.


Work so far:

I moved the variables from config.txt and merge-config.txt to a new
file, and made a little helper script that expands @@CONFIG(key)@@ in
the asciidoc files, driven by the Makefile of course.

I then went over the manpages in the "Main Porcelain Commands" list of
git(1) and either (easy case) added a "CONFIGURATION" section with the
relevant variables or (hard case) tried to refactor the descriptions
so that they are only kept in one place.

Ævar kindly rewrote the Perl script in a more readable and error-safe
style, which I squashed for this posting.  It's still a separate patch
at the above link, too.

This whole series does some much needed improvement on config documentation.

Acked-by: Ævar Arnfjörð Bjarmason <redacted>

Further directions:

I'm a bit hesitant to go in Peff's suggested direction of outright
removing all variables from git-config(1).  I would prefer to both
have the short list and group them by some category system, if that
happens to work out.  Perhaps the categorized list can eventually be
removed once we can verify that all variables are documented in
another manpage.


Known omissions/todos:

* git-gc has an elaborate prose section to the same effect that I
 wasn't quite ready to tear apart yet

* git-notes has excellent custom descriptions from Jonathan's series
 that I didn't want to refactor

* The description of format.pretty in git-log.txt is unsatisfactory

* check-docs or some other make target should verify that no manpage
 links to itself

All these can be done later.