From: Remi Lespinet <remi.lespinet@ensimag.grenoble-inp.fr>
Date: Wed, 03 Jun 2015 17:33:33 GMT
Subject: Re: [PATCH/RFC v3 2/4] git-am.txt: add configuration section in git am documentation
Message-ID: <840759634.89013.1433352813283.JavaMail.zimbra@ensimag.grenoble-inp.fr>
In-Reply-To: <vpq4mmoep9y.fsf@anie.imag.fr>


Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes

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

I've seen occurences of this (mainly git-rebase.txt and
git-grep), but I agree, I think I'll remove the configuration
section.

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

Ok I'll correct it in a minor patch