Matthew Ogilvie <mmogilvi_git@xxxxxxxxxxxx> writes: > On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote: >> ... >> That kind of overfiew is what the tutorial (for concepts like the >> index, tree objects, commit objects, etc.) and the list of commands >> in git(1). Is there compelling reason other than "I didn't bother >> to look, and it is likely other people wouldn't" to apply patches >> like this? > > Not really. Certainly this is a low priority change. > > But why do many of the man pages have "SEE ALSO" > sections? Should we just get rid of such sections? Does anyone > have any guidelines/rules for what makes sense to be in a > "SEE ALSO" section? Two questions that sound similar, somewhat related to each other, but fundamentally different are [*1*]: - Does it help knowing B to make good use of A? - Do you need to know what is in the documentation for B in order to understand what is in the documentation for A? If the answer to either one is yes, it may be a good idea to have "See also B" in the documentation for A. The ls-files and ls-tree pair does not pass either of the above two tests. They both give list of paths (but so do "diff --name-only" and other things), but the similarity between them stops there, and more importantly, similarity does not play any role in the above two tests. If we had a third test: - Does it help knowing B to avoid wasting time attempting to use A for a task for which A is not a suitable tool? then ls-files and ls-tree pair would qualify. I however am not convinced it is particularly a good test. [Footnote] *1* Note that the latter is a sign that A is described in terms of B (i.e. "We assume you understand B; otherwise stop now, go there and learn B, and come back. Now we will describe A"); it is preferrable to avoid it if we can do so without duplication of the information at the source level. -- 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