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

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.

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

Thomas Rast (3):
  Documentation: Move variables from config.txt to separate file
  Documentation: Add variable-substitution script
  Documentation: include configuration options in manpages

 Documentation/Makefile             |   14 +-
 Documentation/config-vars.txt      | 1761 ++++++++++++++++++++++++++++++++++++
 Documentation/config.txt           | 1693 +----------------------------------
 Documentation/git-add.txt          |    6 +-
 Documentation/git-am.txt           |   18 +
 Documentation/git-archive.txt      |    8 +-
 Documentation/git-branch.txt       |    8 +
 Documentation/git-checkout.txt     |    8 +
 Documentation/git-clean.txt        |    6 +
 Documentation/git-commit.txt       |    7 +
 Documentation/git-diff.txt         |   12 +
 Documentation/git-fetch.txt        |   12 +
 Documentation/git-format-patch.txt |   22 +-
 Documentation/git-grep.txt         |    7 +
 Documentation/git-gui.txt          |   16 +
 Documentation/git-log.txt          |   38 +-
 Documentation/git-merge.txt        |   15 +-
 Documentation/git-pull.txt         |   14 +
 Documentation/git-push.txt         |   19 +
 Documentation/git-rebase.txt       |    5 +-
 Documentation/git-shortlog.txt     |    6 +
 Documentation/git-status.txt       |   18 +-
 Documentation/git-submodule.txt    |    8 +
 Documentation/git-tag.txt          |   11 +-
 Documentation/gitk.txt             |    8 +
 Documentation/merge-config.txt     |   49 -
 Documentation/subst-config.perl    |   74 ++
 27 files changed, 2042 insertions(+), 1821 deletions(-)
 create mode 100644 Documentation/config-vars.txt
 delete mode 100644 Documentation/merge-config.txt
 create mode 100755 Documentation/subst-config.perl