Re: [PATCH/RFC] Documentation/git-blame.txt, git-gui.txt: link SEE ALSOs

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

jidanni@jidanni.org 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 <jidanni@jidanni.org>
> ---
>  Documentation/git-blame.txt |    1 +
>  Documentation/git-gui.txt   |    3 +++
>  2 files changed, 4 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
> index fba374d..d71a2c3 100644
> --- a/Documentation/git-blame.txt
> +++ b/Documentation/git-blame.txt
> @@ -186,6 +186,7 @@ commit commentary), a blame viewer won't ever care.
>  
>  SEE ALSO
>  --------
> +linkgit:git-gui[1],
>  linkgit:git-annotate[1]
>  
>  AUTHOR
> diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt
> index d0bc98b..3a71074 100644
> --- a/Documentation/git-gui.txt
> +++ b/Documentation/git-gui.txt
> @@ -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.



diff --git i/Documentation/git-blame.txt w/Documentation/git-blame.txt
index fba374d..ff7bbfb 100644
--- i/Documentation/git-blame.txt
+++ w/Documentation/git-blame.txt
@@ -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[]