From: Ævar Arnfjörð Bjarmason Date: Mon, 26 Jul 2010 19:05:51 GMT Subject: Re: [RFC PATCH 0/24] Documentation: refactor config variable descriptions Message-ID: In-Reply-To: On Mon, Jul 26, 2010 at 18:48, Thomas Rast 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 > 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.