[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:       Jeff King <peff () peff ! net>
Date:       2011-01-21 16:16:46
Message-ID: 20110121161646.GA21840 () sigill ! intra ! peff ! net
[Download RAW message or body]

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