From: Sebastian Pipping <webmaster@hartwork.org>
Date: Fri, 21 Jan 2011 00:05:24 GMT
Subject: Re: Parameter --color-words not documented for "git show"
Message-ID: <4D38CDC4.6010803@hartwork.org>
In-Reply-To: <20110120233429.GB9442@sigill.intra.peff.net>

On 01/21/11 00:34, Jeff King wrote:
>>> Yes; the alternative is to list everything.
>>
>> Would it be bad? I tend to think that a manual page is the good place to
>> list everything the program accepts as parameters and how to use them.
>> FMHO, Manual page is not where newcomers look to learn but it should
>> help everybody to find and understand all of the available options.
> 
> The problem is that we have a bazillion diff options that appear in many
> manpages, so you are stuck with one of:
> 
>   1. repeat them all in each manpage (usually via some automagic
>      include), which dwarfs the original content, and makes it hard for
>      users to see subtle differences between commands
> 
>   2. Say "this describes only the most frequently used options", which
>      leaves the user wondering which infrequently used options exist.
> 
>   3. Say "we also take diff options, and you can find out more about
>      diff options in git-diff(1)." This at least points the user in the
>      right direction, but you can't search for "--color-words" in the
>      page.
> 
>   4. Do (3), but also list the all (or common) diff options in a succint
>      list without descriptions, and refer the user to git-diff(1). Then
>      they can grep if they like, and while they won't get the immediate
>      answer, they will get referred to the right place.
> 
> As you can probably guess, I favor option (4), though we already do (3)
> in some places.

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.

Best,



Sebastian