Subject: [RFC PATCH v2 0/3] Documentation: refactor config variable descriptions

From: Thomas Rast <[email-masked]>
Date: Fri, 22 Oct 2010 07:02:28 +0200

This resurrects (finally) the earlier attempt at

  http://mid.gmane.org/[email-masked]

It tries the inverse approach: teaching the script how to find config
variable blocks in each manpage, and then linking them from the main
list.  (Obviously just inserting them into the main list could also
work.)

In other words, it attempts to push out the "original" documentation
of each variable from the main list to the individual manpage, which
is exactly opposite from v1.

This has the advantage that it does not make the source .txt for each
manpage "unreadable by themselves", as the earlier approach did (and
Jonathan noticed).

It also has the advantage that it will shrink config-vars.txt over
time.

Instead of going through all manpages again, I just tacked on a sample
patch as 3/3 that shows what the use/effect could be.  Once we settle
on the direction (v1 or v2) of the refactoring, I'll make more patches
or resurrect the old ones.

I'm afraid 1/3 (semantically unchanged from the equivalent patch in
v1) will again not make it through, so I again pushed this out:

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

(incidentally v1 is still there as t/doc-config-extraction).  I based
it on master; 1/3 is prone to conflicts but can easily be recreated
from scratch.

Thomas Rast (3):
  Documentation: Move variables from config.txt to separate file
  Documentation: complete config list from other manpages
  Documentation: move format.* documentation to format-patch

 Documentation/Makefile              |    9 +-
 Documentation/config-vars-src.txt   | 1691 +++++++++++++++++++++++++++++++++
 Documentation/config.txt            | 1748 +----------------------------------
 Documentation/git-format-patch.txt  |   65 ++-
 Documentation/make-config-list.perl |  131 +++
 5 files changed, 1892 insertions(+), 1752 deletions(-)
 create mode 100644 Documentation/config-vars-src.txt
 create mode 100755 Documentation/make-config-list.perl

-- 
1.7.3.1.281.g5da0b