[PATCH 2/24] Documentation: Add variable-substitution script

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

The new subst-config.perl is run by the Makefile as

  ./subst-config.perl <vars> <in> <out>

It first reads <vars> for variable-documenting blocks.  A line
consisting of '<name>::' starts the block for <name>, except inside a
'--' delimited block (which is used to generate sub-lists).  A block
extends until the first blank line, which is what asciidoc also looks
for.

Then it copies from <in> to <out>, substituting lines of the form

  @@CONFIG(<name>)@@

with the documentation block for <name>.

Ævar kindly implemented the following, squashed into this patch:

 - Print a usage message when argument prerequisites aren't met
 - Use Getopt::Long instead of manually looking at @ARGV
 - use warnings, not -w
 - Split the parsing & substituting functionality into subroutines

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---
 Documentation/Makefile          |   14 +++++---
 Documentation/config-vars.txt   |    1 +
 Documentation/subst-config.perl |   74 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+), 5 deletions(-)
 create mode 100755 Documentation/subst-config.perl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index a4c4063..c20d580 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -239,12 +239,16 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
 clean:
 	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
+	$(RM) *.txt.cv
 	$(RM) howto-index.txt howto/*.html doc.dep
 	$(RM) technical/api-*.html technical/api-index.txt
 	$(RM) $(cmds_txt) *.made
 	$(RM) manpage-base-url.xsl
 
-$(MAN_HTML): %.html : %.txt
+%.txt.cv : %.txt subst-config.perl config-vars.txt
+	$(QUIET_GEN) ./subst-config.perl --varlist=config-vars.txt --input=$< --output=$@
+
+$(patsubst %.txt,%.txt.cv,$(MAN_HTML)): %.html : %.txt.cv
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
@@ -257,13 +261,13 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_XMLTO)$(RM) $@ && \
 	xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
-%.xml : %.txt
+%.xml : %.txt.cv
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
 	mv $@+ $@
 
-user-manual.xml: user-manual.txt user-manual.conf
+user-manual.xml: user-manual.txt.cv user-manual.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \
 	mv $@+ $@
@@ -320,8 +324,8 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
 	'$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \
 	mv $@+ $@
 
-$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
-	$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt
+$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt.cv
+	$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt.cv
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
diff --git a/Documentation/config-vars.txt b/Documentation/config-vars.txt
index b82fada..3fcefe9 100644
--- a/Documentation/config-vars.txt
+++ b/Documentation/config-vars.txt
@@ -689,6 +689,7 @@ diff.mnemonicprefix::
 	standard "a/" and "b/" depending on what is being compared.  When
 	this configuration is in effect, reverse diff output also swaps
 	the order of the prefixes:
+
 diff.noprefix::
 	If set, 'git diff' does not show any source or destination prefix.
 `git diff`;;
diff --git a/Documentation/subst-config.perl b/Documentation/subst-config.perl
new file mode 100755
index 0000000..a981670
--- /dev/null
+++ b/Documentation/subst-config.perl
@@ -0,0 +1,74 @@
+#!/usr/bin/perl
+use 5.006002;
+use strict;
+use warnings;
+use Getopt::Long;
+
+Getopt::Long::Configure qw/ pass_through /;
+
+my $rc = GetOptions(
+    "varlist=s" => \my $varlist,
+    "input=s"   => \my $input,
+    "output=s"  => \my $output,
+);
+
+if (!$rc or (!-r $varlist or !-r $input)) {
+    print "$0 --varlist=<varlist> --input=<in> --output=<out>\n";
+    exit 1;
+}
+
+my $vars = read_varlist($varlist);
+substitute_variables($vars, $input, $output);
+exit 0;
+
+sub read_varlist {
+    my ($file) = @_;
+
+    open my $fh, "<", $varlist or die "cannot open $varlist: $!";
+    my %vars;
+
+    my ($v, $last_v);
+    my $in_block = 0;
+    while (<$fh>) {
+        if (/^(\S+)::/) {
+            $v = lc $1;
+            $in_block = 0;
+            push @{$vars{$v}}, $_;
+        } elsif (/^$/ && !$in_block) {
+            if (defined $last_v && !$#{$vars{$last_v}}) {
+                $vars{$last_v} = $vars{$v};
+            }
+            $last_v = $v;
+        } elsif (defined $v) {
+            push @{$vars{$v}}, $_;
+            $in_block = !$in_block if /^--$/;
+        }
+    }
+
+    close $fh or die "eh? close failed: $!";
+
+    return \%vars
+}
+
+sub substitute_variables {
+    my ($varlist, $in, $out) = @_;
+
+    open my $infh, "<", $input or die "Can't open $in for reading: $!";
+    open my $outfh, ">", $output or die "Can't open $out for reading: $!";
+
+    while (<$infh>) {
+        if (/^\@\@CONFIG\((\S+)\)\@\@$/) {
+            my $v = lc $1;
+            die "Key $v not documented" unless exists $varlist->{$v};
+            print $outfh @{$varlist->{$v}};
+            print $outfh "\n";
+        } else {
+            print $outfh $_;
+        }
+    }
+
+    close $infh or die "closing input failed: $!";
+    close $outfh or die "closing output failed: $!";
+
+    return;
+}
-- 
1.7.2.349.gd5452