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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jul 26, 2010, 19:51 UTC
Message-ID: <20100726195144.GC1043@burratino>
In-Reply-To: <049043aa444288fd9409a3706fe3190fd679cb7d.1280169048.git.trast@student.ethz.ch>

Thomas Rast wrote:

Show 13 quoted lines

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

Show 12 quoted lines

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