Document changes in 'compare-windows'

* lisp/vc/compare-w.el (compare-windows-removed)
(compare-windows-added): Doc fix.

* doc/emacs/files.texi (Comparing Files): Document the changes in
window selection by 'compare-windows'.

3 files changed, 17 insertions, 11 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 5752d02fe85..4f7596e058c 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1295,11 +1295,12 @@ would make to the file if you save the buffer.
 
 @findex compare-windows
   The command @kbd{M-x compare-windows} compares the text in the
-current window with that in the next window.  (For more information
-about windows in Emacs, @ref{Windows}.)  Comparison starts at point in
-each window, after pushing each initial point value on the mark ring
-in its respective buffer.  Then it moves point forward in each window,
-one character at a time, until it reaches characters that don't match.
+current window with that in the window that was the selected window
+before you selected the current one.  (For more information about
+windows in Emacs, @ref{Windows}.)  Comparison starts at point in each
+window, after pushing each initial point value on the mark ring in its
+respective buffer.  Then it moves point forward in each window, one
+character at a time, until it reaches characters that don't match.
 Then the command exits.
 
   If point in the two windows is followed by non-matching text when
diff --git a/etc/NEWS b/etc/NEWS
index ee56d23d174..2f3019edf86 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -831,12 +831,17 @@ back-end for the buffer's file, or remove it from version control.
 the color range from `vc-annotate-color-map' is applied to the
 background or to the foreground.
 
-*** `compare-windows' now compares text with the most recently used window
-instead of the next window.  The new option `compare-windows-get-window-function'
-allows to customize this.
++++
+*** `compare-windows' now compares text with the most recently selected window
+instead of the next window.  If you want the previous behavior of
+comparing with the next window, customize the new option
+`compare-windows-get-window-function' to the value
+`compare-windows-get-next-window'.
 
+---
 *** Two new faces `compare-windows-removed' and `compare-windows-added'
-replace the obsolete face `compare-windows'.
+replace the face `compare-windows', which is now an obsolete alias for
+`compare-windows-added'.
 
 ---
 *** `log-edit-insert-changelog' converts "(tiny change)" to
diff --git a/lisp/vc/compare-w.el b/lisp/vc/compare-w.el
index cec16446984..d6e3240eaf7 100644
--- a/lisp/vc/compare-w.el
+++ b/lisp/vc/compare-w.el
@@ -132,13 +132,13 @@ out all highlighting later with the command `compare-windows-dehighlight'."
 
 (defface compare-windows-removed
   '((t :inherit diff-removed))
-  "Face for highlighting of compare-windows removed regions."
+  "Face for highlighting `compare-windows' differing regions in the other window."
   :group 'compare-windows
   :version "25.1")
 
 (defface compare-windows-added
   '((t :inherit diff-added))
-  "Face for highlighting of compare-windows added regions."
+  "Face for highlighting `compare-windows' differing regions in current window."
   :group 'compare-windows
   :version "25.1")