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

[Jeff King <peff@peff.net>]

On Fri, Jan 21, 2011 at 01:05:24AM +0100, Sebastian Pipping wrote:

> > 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.

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?

-Peff