emacs-31 ad60eb855d2: ; Improve documentation of "shadow cursor"

branch: emacs-31
commit ad60eb855d21d2977c545c6682c53aa803e2d747
Author: Eli Zaretskii <[email protected]>
Commit: Eli Zaretskii <[email protected]>

    ; Improve documentation of "shadow cursor"
    
    * etc/NEWS:
    * doc/emacs/files.texi (Diff Mode):
    * lisp/vc/diff-mode.el (diff-refine): Improve the documentation of
    the "shadow cursor" shown by Diff mode.
---
 doc/emacs/files.texi | 22 ++++++++++++++++------
 etc/NEWS             |  8 ++++++++
 lisp/vc/diff-mode.el |  5 ++++-
 3 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index b223540b97d..c271da15a1a 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1808,11 +1808,20 @@ Move to the next hunk-start (@code{diff-hunk-next}).  With prefix
 argument @var{n}, move forward to the @var{n}th next hunk.
 
 @vindex diff-refine
-By default, Diff mode @dfn{refines} hunks as Emacs displays them,
-highlighting their changes with better granularity.  Alternatively, if
-you set @code{diff-refine} to the symbol @code{navigation}, Diff mode
-only refines the hunk you move to with this command or with
-@code{diff-hunk-prev}.
+By default, Diff mode automatically @dfn{refines} hunks as Emacs
+displays them, highlighting their changes with better granularity.
+Alternatively, if you set @code{diff-refine} to the symbol
+@code{navigation}, Diff mode only refines the hunk you move to with this
+command or with @code{diff-hunk-prev}.  Finally, you can set
+@code{diff-refine} to @code{nil} and manually refine hunks using
+@kbd{C-c C-b} (@code{diff-refine-hunk}), described below.
+
+@cindex shadow cursor (Diff mode)
+@vindex smerge-refine-shadow-cursor
+By default, refining a hunk in any way displays a @dfn{shadow cursor} at
+one of the two edges of the refined region, to better show where the
+refined region starts or ends.  This can be controlled by customizing
+the variable @code{smerge-refine-shadow-cursor}.
 
 @findex diff-hunk-prev
 @item M-p
@@ -1895,7 +1904,8 @@ parts of the buffer where the hunks' file names are specified.
 @item C-c C-b
 Highlight the changes of the hunk at point with a finer granularity
 (@code{diff-refine-hunk}).  This allows you to see exactly which parts
-of each changed line were actually changed.
+of each changed line were actually changed.  Refining a hunk by default
+shows a ``shadow cursor'' at one of the two edges of the refined region.
 
 @vindex diff-refine
 By default, Diff mode refines hunks as Emacs displays them, so you may
diff --git a/etc/NEWS b/etc/NEWS
index 1270b95e622..d71204b6be0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2566,6 +2566,14 @@ started inside Emacs.
 *** 'diff-mode' now refrains from automatically refining big hunks.
 What is big is defined by the new 'diff-refine-threshold' user option.
 
++++
+*** Refining a hunk shows a "shadow cursor" at the beginning/end of region.
+By default, the shadow cursor looks like an empty rectangle the size of
+a character cell.  It is displayed at the beginning or the end of the
+refined region, to better show where the refined region starts or ends.
+This can be controlled by the new user option
+'smerge-refine-shadow-cursor', which also affects SMerge mode, see below.
+
 ---
 *** New command 'diff-kill-ring-save'.
 This command copies to the 'kill-ring' a region of text modified
diff --git a/lisp/vc/diff-mode.el b/lisp/vc/diff-mode.el
index c1227573351..3189f658ba0 100644
--- a/lisp/vc/diff-mode.el
+++ b/lisp/vc/diff-mode.el
@@ -107,7 +107,10 @@ The value `font-lock' means to refine during font-lock.
 The value `navigation' means to refine each hunk as you visit it
 with `diff-hunk-next' or `diff-hunk-prev'.
 
-You can always manually refine a hunk with `diff-refine-hunk'."
+You can always manually refine a hunk with `diff-refine-hunk'.
+
+By default, refining a hunk in any way displays the \"shadow cursor\"
+at one end of the refined region.  See `smerge-refine-shadow-cursor'."
   :version "27.1"
   :type '(choice (const :tag "Don't refine hunks" nil)
                  (const :tag "Refine hunks during font-lock" font-lock)