bug#32991: 27.0.50; diff-auto-refine-mode a no-op

[Charles A. Roelli]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: Mon, 18 Feb 2019 15:44:09 -0500
> 
> Yes, it's better to avoid it.  But in this case, it's just a temporary
> situation in order to cut the patch into two chunks, so it's perfectly fine.

Right, here is the first part.  I noticed another use of
diff-auto-refine-mode (in admin/gitmerge.el) and its info
documentation, so I've updated those too.


>From 2f393b95ad8912dc1f7908365766b200fc59cfe9 Mon Sep 17 00:00:00 2001
From: "Charles A. Roelli" <charles@aurox.ch>
Date: Sun, 24 Feb 2019 16:13:13 +0100
Subject: [PATCH] Merge diff-font-lock-refine and diff-auto-refine-mode into
 diff-refine

This change was discussed in Bug#32991.

* admin/gitmerge.el (gitmerge-resolve): Bind 'diff-refine'
instead of 'diff-auto-refine-mode' to nil.
* doc/emacs/files.texi (Diff Mode): Explain 'diff-refine'
instead of 'diff-auto-refine-mode' in the documentation of
'diff-hunk-next' and 'diff-hunk-prev'.  Mention in the
documentation of 'diff-refine-hunk' that refining is already
done by default.
* etc/NEWS (Diff mode): Explain renamed 'diff-refine' variable
and mention deprecation and disabling of
'diff-auto-refine-mode'.
* lisp/vc/diff-mode.el (diff-font-lock-refine): Rename to
'diff-refine' and allow choices nil, 'font-lock' and 'navigation'.
(diff-auto-refine-mode): Disable it by default, make it
obsolete and make it set 'diff-refine' appropriately to keep
backward compatibility.
(diff-hunk-next, diff-hunk-prev): Adapt to rename of
diff-auto-refine-mode and ensure that refining only happens
when calling these commands interactively.
(diff--font-lock-refined): Adapt to rename of
diff-font-lock-refine.
* lisp/vc/smerge-mode.el (smerge-next, smerge-prev): Check
that 'diff-refine' is set instead of checking
'diff-auto-refine-mode' when deciding whether to refine a
conflict.
---
 admin/gitmerge.el      |  2 +-
 doc/emacs/files.texi   | 28 +++++++++++++---------------
 etc/NEWS               | 11 +++++++++--
 lisp/vc/diff-mode.el   | 30 ++++++++++++++++++++++--------
 lisp/vc/smerge-mode.el |  4 ++--
 5 files changed, 47 insertions(+), 28 deletions(-)

diff --git a/admin/gitmerge.el b/admin/gitmerge.el
index 4854862..edf4379 100644
--- a/admin/gitmerge.el
+++ b/admin/gitmerge.el
@@ -294,7 +294,7 @@ gitmerge-resolve
            ((derived-mode-p 'change-log-mode)
             ;; Fix up dates before resolving the conflicts.
             (goto-char (point-min))
-            (let ((diff-auto-refine-mode nil))
+            (let ((diff-refine nil))
               (while (re-search-forward smerge-begin-re nil t)
                 (smerge-match-conflict)
                 (smerge-ensure-match 3)
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index d12d1ed..a574282 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1461,26 +1461,19 @@ Diff Mode
 Move to the next hunk-start (@code{diff-hunk-next}).  With prefix
 argument @var{n}, move forward to the @var{n}th next hunk.
 
-@findex diff-auto-refine-mode
-@cindex mode, Diff Auto-Refine
-@cindex Diff Auto-Refine mode
-This command has a side effect: it @dfn{refines} the hunk you move to,
-highlighting its changes with better granularity.  To disable this
-feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor
-mode Diff Auto-Refine mode.  To disable Diff Auto-Refine mode by
-default, add this to your init file (@pxref{Hooks}):
-
-@example
-(add-hook 'diff-mode-hook
-          (lambda () (diff-auto-refine-mode -1)))
-@end example
+@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}.
 
 @item M-p
 @findex diff-hunk-prev
 Move to the previous hunk-start (@code{diff-hunk-prev}).  With prefix
 argument @var{n}, move back to the @var{n}th previous hunk.  Like
-@kbd{M-n}, this has the side-effect of refining the hunk you move to,
-unless you disable Diff Auto-Refine mode.
+@kbd{M-n}, this command refines the hunk you move to if you set
+@code{diff-refine} to the symbol @code{navigation}.
 
 @item M-@}
 @findex diff-file-next
@@ -1518,6 +1511,11 @@ Diff Mode
 (@code{diff-refine-hunk}).  This allows you to see exactly which parts
 of each changed line were actually changed.
 
+@vindex diff-refine
+By default, Diff mode refines hunks as Emacs displays them, so you may
+find this command useful if you customize @code{diff-refine} to a
+non-default value.
+
 @item C-c C-c
 @findex diff-goto-source
 @vindex diff-jump-to-old-file
diff --git a/etc/NEWS b/etc/NEWS
index 253da49..653ea43 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -458,8 +458,15 @@ and compares their entire trees.
 to hg revert.
 
 ** Diff mode
-*** Hunks are now automatically refined by default.
-To disable it, set the new defcustom 'diff-font-lock-refine' to nil.
++++
+*** Hunks are now automatically refined by font-lock.
+To disable refinement, set the new defcustom 'diff-refine' to nil.
+To get back the old behavior where hunks are refined as you navigate
+through a diff, set 'diff-refine' to the symbol 'navigate'.
++++
+*** 'diff-auto-refine-mode' is deprecated in favor of 'diff-refine'.
+It is no longer enabled by default and binding it no longer has any
+effect.
 
 +++
 *** Better syntax highlighting of Diff hunks.
diff --git a/lisp/vc/diff-mode.el b/lisp/vc/diff-mode.el
index bad5639..b5ef209 100644
--- a/lisp/vc/diff-mode.el
+++ b/lisp/vc/diff-mode.el
@@ -94,10 +94,18 @@ diff-mode-hook
   :type 'hook
   :options '(diff-delete-empty-files diff-make-unified))
 
-(defcustom diff-font-lock-refine t
-  "If non-nil, font-lock highlighting includes hunk refinement."
+(defcustom diff-refine 'font-lock
+  "If non-nil, enable hunk refinement.
+
+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'."
   :version "27.1"
-  :type 'boolean)
+  :type '(choice (const :tag "Don't refine hunks" nil)
+                 (const :tag "Refine hunks during font-lock" font-lock)
+                 (const :tag "Refine hunks during navigation" navigation)))
 
 (defcustom diff-font-lock-prettify nil
   "If non-nil, font-lock will try and make the format prettier."
@@ -262,9 +270,15 @@ diff-auto-refine-mode
 changes in detail as the user visits hunks.  When transitioning
 from disabled to enabled, it tries to refine the current hunk, as
 well."
-  :group 'diff-mode :init-value t :lighter nil ;; " Auto-Refine"
-  (when diff-auto-refine-mode
-    (condition-case-unless-debug nil (diff-refine-hunk) (error nil))))
+  :group 'diff-mode :init-value nil :lighter nil ;; " Auto-Refine"
+  (if diff-auto-refine-mode
+      (progn
+        (customize-set-variable 'diff-refine 'navigation)
+        (condition-case-unless-debug nil (diff-refine-hunk) (error nil)))
+    (customize-set-variable 'diff-refine nil)))
+(make-obsolete 'diff-auto-refine-mode "set `diff-refine' instead." "27.1")
+(make-obsolete-variable 'diff-auto-refine-mode
+                        "set `diff-refine' instead." "27.1")
 
 ;;;;
 ;;;; font-lock support
@@ -622,7 +636,7 @@ diff--auto-refine-data
 ;; Define diff-{hunk,file}-{prev,next}
 (easy-mmode-define-navigation
  diff-hunk diff-hunk-header-re "hunk" diff-end-of-hunk diff-restrict-view
- (when diff-auto-refine-mode
+ (when (and (eq diff-refine 'navigation) (called-interactively-p 'interactive))
    (unless (prog1 diff--auto-refine-data
              (setq diff--auto-refine-data
                    (cons (current-buffer) (point-marker))))
@@ -2145,7 +2159,7 @@ diff--iterate-hunks
 
 (defun diff--font-lock-refined (max)
   "Apply hunk refinement from font-lock."
-  (when diff-font-lock-refine
+  (when (eq diff-refine 'font-lock)
     (when (get-char-property (point) 'diff--font-lock-refined)
       ;; Refinement works over a complete hunk, whereas font-lock limits itself
       ;; to highlighting smallish chunks between point..max, so we may be
diff --git a/lisp/vc/smerge-mode.el b/lisp/vc/smerge-mode.el
index 02cee44..6b1df66 100644
--- a/lisp/vc/smerge-mode.el
+++ b/lisp/vc/smerge-mode.el
@@ -44,7 +44,7 @@
 ;;; Code:
 
 (eval-when-compile (require 'cl-lib))
-(require 'diff-mode)                    ;For diff-auto-refine-mode.
+(require 'diff-mode)                    ;For diff-refine.
 (require 'newcomment)
 
 ;;; The real definition comes later.
@@ -264,7 +264,7 @@ font-lock-keywords
 
 ;; Define smerge-next and smerge-prev
 (easy-mmode-define-navigation smerge smerge-begin-re "conflict" nil nil
-  (if diff-auto-refine-mode
+  (if diff-refine
       (condition-case nil (smerge-refine) (error nil))))
 
 (defconst smerge-match-names ["conflict" "upper" "base" "lower"])
-- 
2.9.4

> As I said, I don't care much about this restriction "feature" of
> diff-hunk-prev/diff-hunk-next, so I think it's OK to just drop it.
> If some users then complain, we can see how to re-add it.
> 
> > defcustom for it in a second patch (ditto for the re-centering).
> 
> But the recentering is more important, IMO.  And I don't quite see why
> you'd need a defcustom for it (I can see why you might only do the
> recentering when the function is called interactively, tho).

Okay, I'm fine with removing the re-narrowing too if there are no
objections.  I'd still like to add a defcustom for the recentering, to
allow navigation in Diff mode buffers that respects scroll-related
variables.  But I think I will open a different bug for these issues,
since this one is nearly fixed.