[prev in list] [next in list] [prev in thread] [next in thread] 

List:       git
Subject:    Re: Parameter --color-words not documented for "git show"
From:       Sebastian Pipping <webmaster () hartwork ! org>
Date:       2011-01-21 0:05:24
Message-ID: 4D38CDC4.6010803 () hartwork ! org
[Download RAW message or body]

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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
[prev in list] [next in list] [prev in thread] [next in thread]