bug#3036: 23.0.91; Manual doesn't mention diff-buffer-with-file

[Magnus Henoch <mange@freemail.hu>]

I recently needed M-x diff-buffer-with-file, but I didn't know what it
was called, or even whether it existed.  I couldn't find anything in the
manual, despite looking at the "Comparing files" section.  I propose
something like the following: (feel free to improve wording)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index aad2b4a..c332018 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1276,6 +1276,11 @@ most recent backup.  If you specify the name of a backup file,
 @code{diff-backup} compares it with the source file that it is a
 backup of.  In all other respects, this behaves like @kbd{M-x diff}.
 
+@findex diff-buffer-with-file
+  The command @kbd{M-x diff-buffer-with-file} compares the a buffer
+with its corresponding file, in effect displaying what you would
+change if you would 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


If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
If you would like to further debug the crash, please read the file
/usr/local/share/emacs/23.0.91/etc/DEBUG for instructions.


In GNU Emacs 23.0.91.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4)
 of 2009-03-02 on linux-b2a3
Windowing system distributor `The X.Org Foundation', version 11.0.10502000
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: C
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=local
  locale-coding-system: utf-8-unix
  default-enable-multibyte-characters: t

Major mode: Diff

Minor modes in effect:
  diff-auto-refine-mode: t
  shell-dirtrack-mode: t
  jabber-activity-mode: t
  jabber-mode-line-mode: t
  show-paren-mode: t
  server-mode: t
  icomplete-mode: t
  display-time-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
<down> <down> <down> <down> <down> <down> <down> M-! 
l a s t <return> C-x C-j C-l C-x b * G <return> g C-x 
b C o m <backspace> <backspace> <backspace> f i l e 
<return> C-o <return> @ f i n d e x SPC d i f f - b 
u f f e r - w i t h - f i l e <return> SPC SPC T h 
e SPC c o m m a n d SPC @ k b d { M - x SPC d i f - 
<backspace> f - b u f f e r - w i t h - f i l e } SPC 
c o m p a r e s SPC C-c a M-x a u t o - i f <backspace> 
<backspace> f i l l <tab> <return> t h e SPC c o n 
t e n t s SPC o f SPC a SPC b u C-a C-d C-d C-e f f 
e r SPC w i t h SPC t h e SPC M-b M-b M-b M-b <M-backspace> 
<M-backspace> M-q <down> <M-backspace> i t s SPC c 
o r r e s p o n d i n g SPC f i l e , SPC i n SPC e 
f f e c t SPC d i s p l a y i n g SPC w h a t SPC y 
o u SPC w o u l d SPC c h a n g e SPC i f SPC y o u 
SPC w o u l d SPC s a v e SPC t h e SPC b u f f e r 
. C-x C-s C-x v = M-x r e p o r t - <tab> <return>

Recent messages:
nnimap: Checking mailboxes...done
Reading active file from news.gmane.org via nntp...
Reading active file from archive via nnfolder...done
Checking new news...
Opening nndoc server on gnus-help...done
Checking new news...done
Saving file /home/magnus/src/emacs/doc/emacs/files.texi...
Wrote /home/magnus/src/emacs/doc/emacs/files.texi
Finding changes in /home/magnus/src/emacs/doc/emacs/files.texi...done