Jeff King <peff@xxxxxxxx> 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. -- 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