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

[Thomas Rast <trast@student.ethz.ch>]

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

-- 
1.7.2.349.gd5452