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

[Junio C Hamano <gitster@pobox.com>]

Jeff King <peff@peff.net> writes:

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

We attempt to do 1 to solve it "nicely" in some manual pages, and indeed
there are many "exclude this option from the command X's manpage" magic
that causes the problem of subtle differences you mentioned (which I
agree).

One complication in either 3 or 4 is that they sometimes need to be
accompanied with "... except these diff options do not make sense in the
context of this command, so they are no-op".  That is probably a price
worth paying to be more helpful than 2 is.