Re: [PATCH] Documentation: have ls-files and ls-tree "see also" each other

Matthew Ogilvie [off-list ref] writes:

On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote:

quoted

...
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.