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

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

[Matthew Ogilvie]

Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
---

I could have used these references when I was looking at git-ls-files
documentation and trying to figure out how to make it list files
from a specific commit like git-ls-tree.

(This is a resend.  I sent this patch a couple of weeks ago,
but it apparently slipped through the cracks.)

 Documentation/git-ls-files.txt |    2 +-
 Documentation/git-ls-tree.txt  |    4 ++++
 2 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 4b28292..8ce3c3b 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -207,7 +207,7 @@ pattern file appears in.
 
 SEE ALSO
 --------
-linkgit:git-read-tree[1], linkgit:gitignore[5]
+linkgit:git-ls-tree[1], linkgit:git-read-tree[1], linkgit:gitignore[5]
 
 GIT
 ---
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 16e87fd..1cd52cc 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -95,6 +95,10 @@ Object size identified by <object> is given in bytes, and right-justified
 with minimum width of 7 characters.  Object size is given only for blobs
 (file) entries; for other entries `-` character is used in place of size.
 
+SEE ALSO
+--------
+linkgit:git-ls-files[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 

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

[Junio C Hamano]

Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:

> Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
> ---
>
> I could have used these references when I was looking at git-ls-files
> documentation and trying to figure out how to make it list files
> from a specific commit like git-ls-tree.

I do not like this kind of patches in general.  Where will it end?

"I wanted to know how to list objects recorded in a commit, and I
could have used a reference to git-ls-tree from git-commit, so here
is a patch to make them refer to each other"?

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?

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

[Matthew Ogilvie]

On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote:
> Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:
> 
> > Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
> > ---
> >
> > I could have used these references when I was looking at git-ls-files
> > documentation and trying to figure out how to make it list files
> > from a specific commit like git-ls-tree.
> 
> I do not like this kind of patches in general.  Where will it end?
> 
> "I wanted to know how to list objects recorded in a commit, and I
> could have used a reference to git-ls-tree from git-commit, so here
> is a patch to make them refer to each other"?
> 
> 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?

My personal impression is that git-ls-files (which lists files
in the working directory or index) and git-ls-tree (which lists files in
a commit or tree object) are so similar that they could almost be
merged into a single command.  Linking them together in the 
documentation seemed obvious, but maybe that's just me.

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

[Junio C Hamano]

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.

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

[Matthew Ogilvie]

I wanted this pointer when I was looking at git-ls-files documentation
and trying to figure out how to make it list files from a specific commit
like git-ls-tree.

Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
---
 Documentation/git-ls-files.txt |    2 +-
 Documentation/git-ls-tree.txt  |    4 ++++
 2 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 4b28292..8ce3c3b 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -207,7 +207,7 @@ pattern file appears in.
 
 SEE ALSO
 --------
-linkgit:git-read-tree[1], linkgit:gitignore[5]
+linkgit:git-ls-tree[1], linkgit:git-read-tree[1], linkgit:gitignore[5]
 
 GIT
 ---
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 16e87fd..1cd52cc 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -95,6 +95,10 @@ Object size identified by <object> is given in bytes, and right-justified
 with minimum width of 7 characters.  Object size is given only for blobs
 (file) entries; for other entries `-` character is used in place of size.
 
+SEE ALSO
+--------
+linkgit:git-ls-files[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
1.7.5.rc1