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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 5, 2012, 15:03 UTC
Message-ID: <7v62b5reb9.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20120605062935.GA4683@comcast.net>

Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:

Show 14 quoted lines

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