Documentation/git-blame.txt, git-gui.txt: link SEE ALSOs
As git gui is heavily blame focused, we link its SEE ALSO to git-blame, and add a link back while we're at it.
--- Documentation/git-blame.txt | 1 + Documentation/git-gui.txt | 3 +++ 2 files changed, 4 insertions(+), 0 deletions(-)
Documentation/git-blame.txt +1 -0
@@ -186,6 +186,7 @@ commit commentary), a blame viewer won't ever care. SEE ALSO -------- +linkgit:git-gui[1], linkgit:git-annotate[1] AUTHOR
Documentation/git-gui.txt +3 -0
@@ -105,6 +105,9 @@ linkgit:gitk[1]:: and file differences. gitk is the utility started by 'git-gui''s Repository Visualize actions. +linkgit:git-blame[1]:: + Command-line blame viewer. + Other ----- 'git-gui' is actually maintained as an independent project, but stable
Signature · 1 line
1.6.0.6
Quoted 26 lines · [email protected] writes:
As git gui is heavily blame focused, we link its SEE ALSO to git-blame, and add a link back while we're at it.
Signed-off-by jidanni <[email protected]>--- Documentation/git-blame.txt | 1 + Documentation/git-gui.txt | 3 +++ 2 files changed, 4 insertions(+), 0 deletions(-)Documentation/git-blame.txt +1
-0@@ -186,6 +186,7 @@ commit commentary), a blame viewer won't ever care. SEE ALSO -------- +linkgit:git-gui[1], linkgit:git-annotate[1] AUTHORDocumentation/git-gui.txt +0
-0
Documentation/git-gui.txt linkgit:gitk[1]:: · line 113
Quoted 9 lines
Documentation/git-gui.txt +3
-0@@ -105,6 +105,9 @@ linkgit:gitk[1]:: and file differences. gitk is the utility started by 'git-gui''s Repository Visualize actions. +linkgit:git-blame[1]:: + Command-line blame viewer. + Other ----- 'git-gui' is actually maintained as an independent project, but stable
As a general principle, I tend to refrain from referring to X from the description of Y only because X happens to use Y heavily.
Referring people who heavily use Y to an alternative, which is X, hoping that X may give a better user experience in certain environments is a different matter, but in such a case, I'd rather see not just link but in-text description as well (study the way "log -S" is suggested in the description part for an example). The attached patch shows you how.
On the other hand, what X does using Y sometimes may be easier to understand if the reader is familiar with the way how Y works. Even in such a case, I think the documentation of X should be self contained enough and ideally it shouldn't have to refer to Y. And in the case of git-gui documentation, I think it is.
So I am moderately negative about the first hunk of this patch as-is, and I'll leave the decision on the second hunk to Shawn.
Documentation/git-blame.txt +5 -0
@@ -36,6 +36,11 @@ $ git log --pretty=oneline -S'blame_usage' ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output ----------------------------------------------------------------------------- +People working in GUI environment may find linkgit:git-gui[1] an useful +alternative that provides an interactive interface to the history of +each line. It uses this command as an underlying engine. + + OPTIONS ------- include::blame-options.txt[]
OK, JCH's (and Shawn's, if any forthcoming :-)) patches look better than mine. Please apply them. Thanks.