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

[Jeff King <peff@peff.net>]

On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:

> The 20/01/11, Junio C Hamano wrote:
> > Sebastian Pipping <webmaster@hartwork.org> writes:
> > 
> > > On 01/20/11 21:27, Thomas Rast wrote:
> > >> Quote from the latter:
> > >> 
> > >>        This manual page describes only the most frequently used options.
> > >
> > > Okay.  Is that a good a idea?
> > 
> > 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.

-Peff