Re: [PATCH v2] Documentation: Document diff.<tool>.* and filter.<driver>.* in config

[Michael J Gruber <git@drmicha.warpmail.net>]

Ramkumar Ramachandra venit, vidit, dixit 01.04.2011 12:43:
> Although the gitattributes page contains comprehensive information
> about these configuration options, they should be included in the
> config documentation for completeness.
> 
> Helped-by: Jakub Narebski <jnareb@gmail.com>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
> The first iteration of this patch contained completely wrong
> descriptions for diff.<tool>.* options. Thanks to Jakub for pointing
> them out, and for pointing out that I left out a a few options
> undocumented (found in userdiff.c).
> 
>  Documentation/config.txt |   46 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 46 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 8ea55d4..b2ec4e1 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -875,6 +875,42 @@ diff.tool::
>  	the same valid values as `merge.tool` minus "tortoisemerge"
>  	and plus "kompare".
>  
> +diff.<tool>.command::
> +	Defines command to be called to generate diff for files with
> +	`diff=<tool>` gitattribute.  See linkgit:gitattributes[5] for
> +	details.
> +
> +diff.<tool>.funcname::
> +	Specifies a regular expression that matches a line to use as
> +	the hunk header for files with `diff=<tool>` gitattribute. A
> +	built-in pattern may also be used.  See
> +	linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.xfuncname::
> +	Same as 'diff.<tool>.funcname', except that an extended
> +	regular expression can be specified in this case.
> +
> +diff.<tool>.binary::
> +	Set to true to treat files files with `diff=<tool>`
> +	gitattribute as binary for the purposes of diff.  See
> +	linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.textconv::
> +	Defines command to be called to generate text-converted version
> +	of a binary file with `diff=<tool>` gitattribute.  The result of
> +	the conversion is used to generate human-readable diff.  See
> +	linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.wordregex::
> +	Specifies the regular expression to use to customize the rules
> +	that `git diff --word-diff` uses to split words in a line.
> +	See linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.cachetextconv::
> +	Set to true to enable caching of text conversion outputs for
> +	files with `diff=<tool>` gitattribute.  See
> +	linkgit:gitattributes[5] for details.
> +

I am sorry, but I dislike this for several reasons. First, the wording:
"to use to customize" and the like are no fun to read, and there are
several articles missing.

More importantly: Those config options are not about difftools! Having
diff.<tool>.* before difftool.* is grossly misleading. The options above
are all about external diff drivers. So, diff.<driver>.* would be
appropriate here, esp. when looking at merge.*

>  difftool.<tool>.path::
>  	Override the path for the given tool.  This is useful in case
>  	your tool is not in the PATH.
> @@ -973,6 +1009,16 @@ format.signoff::
>      the rights to submit this work under the same open source license.
>      Please see the 'SubmittingPatches' document for further discussion.
>  
> +filter.<driver>.clean::
> +	Defines the command to be used to convert the contents of
> +	worktree file upon checkin.  See linkgit:gitattributes[5] for
> +	details.
> +
> +filter.<driver>.smudge::
> +	Defines the command to be used to convert the blob object to
> +	worktree file upon checkout.  See linkgit:gitattributes[5] for
> +	details.
> +
>  gc.aggressiveWindow::
>  	The window size parameter used in the delta compression
>  	algorithm used by 'git gc --aggressive'.  This defaults