Subject: Re: Parameter --color-words not documented for "git show"

From: Sebastian Pipping <[email-masked]>
Date: Fri, 21 Jan 2011 01:27:54 +0100

On 01/21/11 01:20, Jeff King wrote:
>> I agree with Thomas here.  (1) is the only option I find acceptable,
>> personally.  If you'd rather not do that, then at least know I now.
>> Great to have --color-words around btw.
> 
> I'm curious why (4) doesn't work for you. I assumed you came to the
> problem by one of:
> 
>   - you wanted to know which options "git show" had, so you looked in
>     the manpage. Nothing told you about "--color-words", nor referred
>     you to a list of diff options. With (4), you would find that it
>     accepted all diff options, and then go read the list of diff options
>     (if you weren't already familiar with it).
> 
>   - you knew about --color-words, and wondered if "git show" supported
>     it. In the current case, searching the page turns up nothing. In
>     option (4), a search would find it (with a reference to diff options
>     if you wanted more details).
> 
> The downside is that you sometimes have to be referred. The upside to me
> is that it becomes explicit that there is a concept of "diff options"
> that you can look up easily and which we can refer to easily in other
> parts of the manual. That helps establish a mental model of how git's
> options work.
> 
> So is it just that being referred is annoying, or something else?

Actually that approach is perfect.  I misunderstood (4) on the first
read somehow.  Really not my day today, sorry.  I would love to see you
push (4) forward.

Best,

Sebastian