Re: [PATCH 8/8] Docs: config: send-email config options included

[Michael Witten <mfwitten@MIT.EDU>]

On 27 Sep 2008, at 10:24 PM, Jeff King wrote:

> On Sat, Sep 27, 2008 at 08:09:56PM -0500, Michael Witten wrote:
>
>> I just copied what is in the send-email man text.
>
> NAK, this makes things much worse by creating two places which must be
> updated with any changes. Shouldn't doing it the right way be as  
> simple
> as something like the patch below?

I also think it is stupid, but I didn't quite understand what you
meant before (I must have been skimming).

Also, the surrounding config variable definitions didn't really make
it clear that I could (or should) include a file (I didn't even think
about it, especially given that I didn't understand your original
suggestion).

> Though it looks like imap.* simply says "See git-imap-send(1)" in
> config.txt, which would also be OK by me (and makes sense especially  
> if
> we drop most of the sendemail.* description in favor of just  
> mentioning
> the config option near the matching command-line option).

I agree! I think these separate config variable descriptions are
superfluous and dangerously subject to obsolescence; consider
what config.txt says:

> Note that this list is non-comprehensive and not necessarily complete.
> For command-specific variables, you will find a more detailed  
> description
> in the appropriate manual page. You will find a description of non- 
> core
> porcelain configuration variables in the respective porcelain  
> documentation.

I think config.txt is not the place to put this stuff (though I've only
given it a quick glance), and include:: will just cause us to litter
the place with tool-config.txt include files, which looks yucky and is
subject to neglect.