bug#38575: 27.0.50; Document that `diff' arguments OLD and NEW can be buffers

[Phil Sainty <psainty@orcon.net.nz>]

[-- Attachment #1: Type: text/plain, Size: 128 bytes --]

I ended up adding a `diff-buffers' command to provide better user
support for this feature.

Patch attached for review.


-Phil

[-- Attachment #2: 0001-New-command-diff-buffers.patch --]
[-- Type: text/x-patch, Size: 4431 bytes --]

From 3a9ce101aa9046f3f54b01b5fb37f21077a0f221 Mon Sep 17 00:00:00 2001
From: Phil Sainty <psainty@orcon.net.nz>
Date: Sat, 14 Dec 2019 20:49:41 +1300
Subject: [PATCH] New command 'diff-buffers'

* lisp/vc/diff.el (diff-buffers): New command.
(diff, diff-no-select, diff-file-local-copy): Improve docstrings.
* doc/emacs/files.texi:
* etc/NEWS: Document new command, and the previously-undocumented
ability for 'diff' to compare buffers.
---
 doc/emacs/files.texi |  4 ++++
 etc/NEWS             |  8 ++++++++
 lisp/vc/diff.el      | 33 ++++++++++++++++++++++++++++++++-
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index c3ede18..7221edc 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1394,6 +1394,10 @@ Comparing Files
 buffer with its corresponding file.  This shows you what changes you
 would make to the file if you save the buffer.
 
+@findex diff-buffers
+  The command @kbd{M-x diff-buffers} compares the contents of two
+specified buffers.
+
 @findex compare-windows
   The command @kbd{M-x compare-windows} compares the text in the
 current window with that in the window that was the selected window
diff --git a/etc/NEWS b/etc/NEWS
index a7f3c3d..18ed8de 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1038,6 +1038,14 @@ is shown.)
 Set the new user option 'diff-font-lock-prettify' to t for that, see
 below under "Diff mode".
 
+---
+*** The 'diff' function arguments OLD and NEW may each be a buffer
+rather than a file, in non-interactive calls.  This change was made in
+Emacs 24.1, but wasn't documented until now.
+
++++
+*** New command 'diff-buffers' interactively diffs two buffers.
+
 ** Diff mode
 +++
 *** Hunks are now automatically refined by font-lock.
diff --git a/lisp/vc/diff.el b/lisp/vc/diff.el
index 9ece8bc..5b055a1 100644
--- a/lisp/vc/diff.el
+++ b/lisp/vc/diff.el
@@ -91,7 +91,10 @@ diff
 
 When called interactively with a prefix argument, prompt
 interactively for diff switches.  Otherwise, the switches
-specified in the variable `diff-switches' are passed to the diff command."
+specified in the variable `diff-switches' are passed to the
+diff command.
+
+Non-interactively, OLD and NEW may each be a file or a buffer."
   (interactive
    (let* ((newf (if (and buffer-file-name (file-exists-p buffer-file-name))
 		    (read-file-name
@@ -112,6 +115,9 @@ diff
    (diff-no-select old new switches no-async)))
 
 (defun diff-file-local-copy (file-or-buf)
+  "Like `file-local-copy' but also supports a buffer as the argument.
+When FILE-OR-BUF is a buffer, return the filename of a local
+temporary file with the buffer's contents."
   (if (bufferp file-or-buf)
       (with-current-buffer file-or-buf
         (let ((tempfile (make-temp-file "buffer-content-")))
@@ -139,6 +145,9 @@ diff-check-labels
 
 (defun diff-no-select (old new &optional switches no-async buf)
   ;; Noninteractive helper for creating and reverting diff buffers
+  "Compare the OLD and NEW file/buffer, and return a diff buffer.
+
+See `diff' for the meaning of the arguments."
   (unless (bufferp new) (setq new (expand-file-name new)))
   (unless (bufferp old) (setq old (expand-file-name old)))
   (or switches (setq switches diff-switches)) ; If not specified, use default.
@@ -243,6 +252,28 @@ diff-buffer-with-file
     (with-current-buffer (or (buffer-base-buffer buf) buf)
       (diff buffer-file-name (current-buffer) nil 'noasync))))
 
+;;;###autoload
+(defun diff-buffers (old new &optional switches no-async)
+  "Find and display the differences between OLD and NEW buffers.
+
+When called interactively, read NEW, then OLD, using the
+minibuffer.  The default for NEW is the current buffer, and the
+default for OLD is the most recently selected other buffer.
+If NO-ASYNC is non-nil, call diff synchronously.
+
+When called interactively with a prefix argument, prompt
+interactively for diff switches.  Otherwise, the switches
+specified in the variable `diff-switches' are passed to the
+diff command.
+
+OLD and NEW may each be a buffer or a buffer name."
+  (interactive
+   (let ((newb (read-buffer "Diff new buffer" (current-buffer) t))
+         (oldb (read-buffer "Diff original buffer"
+                            (other-buffer (current-buffer) t) t)))
+     (list oldb newb (diff-switches))))
+  (diff (get-buffer old) (get-buffer new) switches no-async))
+
 (provide 'diff)
 
 ;;; diff.el ends here
-- 
2.8.3