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

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

[Phil Sainty]

The docstring for `diff' is:

     (diff OLD NEW &optional SWITCHES NO-ASYNC)

     Find and display the differences between OLD and NEW files.
     When called interactively, read NEW, then OLD, using the
     minibuffer.  The default for NEW is the current buffer’s file
     name, and the default for OLD is a backup file for NEW, if one
     exists.  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.


However either (or both) of OLD and NEW may alternatively be buffers,
with temporary files automatically created as necessary.  This happens
via `diff-file-local-copy' called by `diff-no-select'.

This feature is utilised by `diff-buffer-with-file', and is far too
useful to be undocumented by `diff'.

I suggest the following additional paragraph:

     Non-interactively, OLD and NEW may each be buffers, in which
     case a temporary file will be used.


If that wording is ok, I can commit the change.


-Phil

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

[Phil Sainty]

This feature dates to the following commit, which I believe was
first released in 24.1.

Because this seems such a useful feature, I'm inclined to add a
NEWS entry as well, with the note "This change was made in Emacs
24.1, but wasn't documented until now."


-Phil



commit b2e4481906ec08e2c6072b6fe14dd1efca4784b9
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Date:   Mon Nov 22 14:22:03 2010 -0500

     Cleanup diff-buffer-with-file.
     * lisp/vc/diff.el (diff-old-temp-file, diff-new-temp-file): Remove.
     (diff-sentinel): Get them as arguments instead.
     (diff-old-file, diff-new-file, diff-extra-args): Remove.
     (diff-file-local-copy, diff-better-file-name): New funs.
     (diff-no-select): Rename from diff-into-buffer.
     Support buffers additionally to files.  Move `buf' arg.  Don't 
display buf.
     Prefer closures to buffer-local variables.
     (diff): Adjust accordingly.
     (diff-buffer-with-file): Move from files.el.
     * lisp/files.el (diff-buffer-with-file): Move to vc/diff.el.
     (diff-buffer-internal): Remove.
     (diff-buffer-buffer): Remove.
     (save-some-buffers-action-alist): Use diff-no-select so as not to 
guess
     the buffer name used, and so as not to mess up windows and frames.

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

[Eli Zaretskii]

> Date: Thu, 12 Dec 2019 20:44:15 +1300
> From: Phil Sainty <psainty@orcon.net.nz>
> 
> This feature dates to the following commit, which I believe was
> first released in 24.1.
> 
> Because this seems such a useful feature, I'm inclined to add a
> NEWS entry as well, with the note "This change was made in Emacs
> 24.1, but wasn't documented until now."

Fine with me, thanks.

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

[Eli Zaretskii]

> Date: Thu, 12 Dec 2019 19:46:40 +1300
> From: Phil Sainty <psainty@orcon.net.nz>
> 
> This feature is utilised by `diff-buffer-with-file', and is far too
> useful to be undocumented by `diff'.

Agreed.

> I suggest the following additional paragraph:
> 
>      Non-interactively, OLD and NEW may each be buffers, in which
>      case a temporary file will be used.

Why is it important to mention the fact that we use temporary files in
this case?  It sounds like an implementation detail.

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

[Phil Sainty]

On 12/12/19 10:21 PM, Eli Zaretskii wrote:
>> I suggest the following additional paragraph:
>>
>>      Non-interactively, OLD and NEW may each be buffers, in which
>>      case a temporary file will be used.
> 
> Why is it important to mention the fact that we use temporary files
> in this case?  It sounds like an implementation detail.

It is, but I think it's a helpful detail to include, to eliminate
potential confusion regarding how a buffer can be a valid input, when
the rest of the description is about files.

The user might otherwise wonder whether Emacs is actually using the
external diff program in this case (vs using some internal functions
to process the buffer text directly to produce a diff).

I'm ok with omitting it if you're not convinced.


-Phil

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

[Eli Zaretskii]

> Cc: 38575@debbugs.gnu.org
> From: Phil Sainty <psainty@orcon.net.nz>
> Date: Thu, 12 Dec 2019 23:15:37 +1300
> 
> The user might otherwise wonder whether Emacs is actually using the
> external diff program in this case (vs using some internal functions
> to process the buffer text directly to produce a diff).

They have the sources to solve this confusion.

> I'm ok with omitting it if you're not convinced.

I'd prefer to omit that, because we may one day find a way of running
programs with input redirected from a buffer, or something.  Not a
strong opinion, though.

Thanks.

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

[Phil Sainty]

[-- 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

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

[Eli Zaretskii]

> Cc: 38575@debbugs.gnu.org
> From: Phil Sainty <psainty@orcon.net.nz>
> Date: Sat, 14 Dec 2019 21:22:13 +1300
> 
> I ended up adding a `diff-buffers' command to provide better user
> support for this feature.
> 
> Patch attached for review.

LGTM, thanks.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> I ended up adding a `diff-buffers' command to provide better user
>> support for this feature.
>> 
>> Patch attached for review.
>
> LGTM, thanks.

Looks like this patch was applied at the time, but the bug report
remains open, so I'm closing it now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no