From: Jonathan Nieder <jrnieder@gmail.com>
Date: Mon, 26 Jul 2010 19:51:44 GMT
Subject: Re: [PATCH 2/24] Documentation: Add variable-substitution script
Message-ID: <20100726195144.GC1043@burratino>
In-Reply-To: <049043aa444288fd9409a3706fe3190fd679cb7d.1280169048.git.trast@student.ethz.ch>

Thomas Rast wrote:

>   ./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>.

Neat.  Thanks for picking this up.  

I would like to make the git-config(1) man page more like the command
list in git(1) and less like a concatenation of CONFIGURATION
sections, but regardless, this is a good first step.

> 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`;;

Does this have an effect on the resulting markup?  It looks like an
independent syntax fix.

> +++ b/Documentation/subst-config.perl
> @@ -0,0 +1,74 @@
[...]
> +if (!$rc or (!-r $varlist or !-r $input)) {
> +    print "$0 --varlist=<varlist> --input=<in> --output=<out>\n";
> +    exit 1;
> +}

So the commit message is out of date (the new usage is more clear,
anyway).

> +%.txt.cv : %.txt subst-config.perl config-vars.txt

The asciidoc markup is supposed to itself be suitable documentation.
Maybe eventually we will have to drop that pretence and generate .txt
files at build time.

Acked-by: Jonathan Nieder <jrnieder@gmail.com>