On 01/21/11 00:34, Jeff King wrote: >>> 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. 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. Best, Sebastian -- 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