On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:
> The 20/01/11, Junio C Hamano wrote:
> > Sebastian Pipping <webmaster@xxxxxxxxxxxx> 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html