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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Jul 26, 2010 at 18:48, Thomas Rast <trast@student.ethz.ch> 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 <avarab@gmail.com>

> 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.