From: Jeff King <peff@peff.net>
Date: Fri, 21 Jan 2011 16:16:46 GMT
Subject: Re: Parameter --color-words not documented for "git show"
Message-ID: <20110121161646.GA21840@sigill.intra.peff.net>
In-Reply-To: <7vy66epz4r.fsf@alter.siamese.dyndns.org>

On Thu, Jan 20, 2011 at 10:08:36PM -0800, Junio C Hamano wrote:

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

Yeah, I took a quick look at diff-options.txt. I think many of those
special cases can be handled by just mentioning the exceptions in the
text. They are usually simple and obvious special cases, like "for -M,
if you are in a command which is traversing, you might be interested in
--follow". I don't think it will hurt people to read that, even if they
are looking at the diff-options because they want to know about "git
diff".

I'll this to my documentation cleanup todo list. It's lower priority
than many other things, but believe it or not I am working towards it.
:)

-Peff