Jeff King <peff@xxxxxxxx> writes: > On Mon, Jul 29, 2019 at 08:48:28AM -0700, Junio C Hamano wrote: > >> > Before this include let's add: >> > >> > The below documentation is the same as what’s found in >> > git-config(1): >> >> I actually do not think we would want to do that. I am all for the >> kind of 'include' proposed by this patch, and we should strive to >> make it easier for us to make sure the duplicated text are in sync. >> >> But that would mean that the readers will have to see the "is the >> same as the other one" over and over. If our documentation set is >> consistent, they should not have to. >> >> I think we *must* make such a note in a total opposite case, >> i.e. "here are the summary of the most often used options; for full >> list, see git-config(1)". > > I disagree. _We_ know that the content is the same, because we are > looking at the source that says "include". But as a user, how do I know > when I get to one section or the other that it is something I have > already read and can skip over? I want to raise the user expectation so that they would expect from our documentation, unless we say "these are different", we would never say conflicting things in two places. So,... I disagree.
