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

[Junio C Hamano <gitster@pobox.com>]

Matthew Ogilvie <mmogilvi_git@miniinfo.net> 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.