Re: [PATCH/RFC v3 2/4] git-am.txt: add configuration section in git am documentation

[Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>]

Remi Lespinet <remi.lespinet@ensimag.grenoble-inp.fr> writes:

> Prepare a configuration section for the git am documentation.

Most git-*.txt do not have this CONFIGURATION section.

In an ideal world, we would have such section automatically generated
(i.e. the description for each variable would exist in one place, and we
would make sure that both "man git-config" and "man git-<command>" show
it). In a really ideal world, it would also be propagated to the code
and we would have a "git config --describe am.keepcr" or so that would
return the doc.

I'm a bit worried to see documentation cut-and-pasted from config.txt to
git-*.txt for maintainability: if the text on one side is modified,
we're likely to forget the other and the text will diverge with time.

Not a strong objection, but I have the feeling that the more we do this
kind of patches, the harder it will be if ever we decide to do the above.

> +CONFIGURATION
> +-------------
> +
> +am.keepcr::
> +	If true, git-am will call git-mailsplit for patches in mbox format

`git am`
`git mailsplit`

> +	with parameter '--keep-cr'. In this case git-mailsplit will

Likewise

> +	not remove `\r` from lines ending with `\r\n`. Can be overridden
> +	by giving '--no-keep-cr' from the command line.

That should be backquote, not forward-quote, right?

I know it's not your code since it's a cut-and-paste from config.txt,
but that illustrates my point above: we used to have one place with
wrong quotes, and we'd have two after the patch.

>  OPTIONS
>  -------
>  (<mbox>|<Maildir>)...::
> @@ -43,11 +53,11 @@ OPTIONS
>  --keep-non-patch::
>  	Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
>  
> ---[no-]keep-cr::
> +--keep-cr::
> +--no-keep-cr::
>  	With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])
>  	with the same option, to prevent it from stripping CR at the end of
> -	lines. `am.keepcr` configuration variable can be used to specify the
> -	default behaviour.

I don't think it's a good idea to remove this part. If I look for a way
to make --keep-cr the default, the first place I'd look would be the doc
for --keep-cr, and I'd appreciate a link to am.keepcr.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/