Document diff-remove-trailing-whitespace

* doc/emacs/files.texi (Diff Mode): Trailing whitespace updates.

* lisp/vc/diff-mode.el (diff-remove-trailing-whitespace): Doc fix.

* etc/NEWS: Related markup.

5 files changed, 34 insertions, 15 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 7ffb22daf30..3893e3c6513 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+2012-11-08  Glenn Morris  <rgm@gnu.org>
+
+        * files.texi (Diff Mode): Trailing whitespace updates.
+
 2012-11-07  Chong Yidong  <cyd@gnu.org>
 
         * misc.texi (Terminal emulator): Document Term mode faces.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 36cd3658e2d..e2a85c6d138 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1470,11 +1470,19 @@ name from the patch itself.  This is useful for making log entries for
 functions that are deleted by the patch.
 @end table
 
-  By default, Diff mode highlights trailing whitespace on modified
-lines, so that they are more obvious.  This is done by enabling
-Whitespace mode in the Diff buffer (@pxref{Useless Whitespace}).  Diff
-mode buffers are set up so that Whitespace mode avoids highlighting
-trailing whitespace occurring in the diff context.
+@c Trailing whitespace is NOT shown by default.
+@c Emacs's dir-locals file enables this (for some reason).
+@cindex trailing whitespace, in diffs
+@findex diff-remove-trailing-whitespace
+  Diff mode has various features for dealing with trailing whitespace
+on modified lines, since this is often an unintentional and unwanted
+change.  If you enable Whitespace mode in a Diff buffer, trailing
+whitespace is highlighted (@pxref{Useless Whitespace}).  The command
+@kbd{M-x diff-remove-trailing-whitespace} searches for trailing
+whitespace in the lines modified or added by a diff.  If it finds any,
+it tries to visit the associated file(s) and remove it.  It does not
+save the modifications, rather it lists any buffers that were modified
+so you can decide for yourself what to do.
 
 @node Misc File Ops
 @section Miscellaneous File Operations
diff --git a/etc/NEWS b/etc/NEWS
index 275e33d8026..5fa57ac23bd 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -392,18 +392,21 @@ details.
 
 ** Diff mode
 
+---
 *** Changes are now highlighted using the same color scheme as in
 modern VCSes.  Deletions are displayed in red (new faces
-`diff-refine-removed' and `smerge-refined-removed' and new definition
+`diff-refine-removed' and `smerge-refined-removed', and new definition
 of `diff-removed'), insertions in green (new faces `diff-refine-added'
-and `smerge-refined-added' and new definition of `diff-added').
+and `smerge-refined-added', and new definition of `diff-added').
 
+---
 *** The variable `diff-use-changed-face' defines whether to use the
 face `diff-changed', or `diff-removed' and `diff-added' to highlight
 changes in context diffs.
 
-*** The new command `diff-remove-trailing-whitespace' fixes trailing
-whitespace problems introduced by the diff.
++++
+*** The new command `diff-remove-trailing-whitespace' removes trailing
+whitespace introduced by a diff.
 
 ** Dired
 +++
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 6a574f4b26d..b141afe67e6 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-11-08  Glenn Morris  <rgm@gnu.org>
+
+        * vc/diff-mode.el (diff-remove-trailing-whitespace): Doc fix.
+
 2012-11-08  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * emacs-lisp/gv.el (gv-define-simple-setter): Fix last change
diff --git a/lisp/vc/diff-mode.el b/lisp/vc/diff-mode.el
index 49b76a8e3bc..daf43c5c167 100644
--- a/lisp/vc/diff-mode.el
+++ b/lisp/vc/diff-mode.el
@@ -2049,12 +2049,12 @@ I.e. like `add-change-log-entry-other-window' but applied to all hunks."
       (error nil))))
 
 (defun diff-remove-trailing-whitespace ()
-  "When on a buffer that contains a diff, inspects the
-differences and removes trailing whitespace (spaces, tabs) from
-the lines modified or introduced by this diff. Shows a message
-with the name of the altered buffers, which are unsaved.  If a
-file referenced on the diff has no buffer and needs to be fixed,
-a buffer visiting that file is created."
+  "Remove trailing whitespace from the lines modified/added by a diff.
+Called from a buffer containing a diff, this searches for trailing
+whitespace (spaces, tabs) in the modified/added lines.  If the
+file that such a line refers to can be found, it visits it and
+removes the associated whitespace, if it is present.  It does not
+save any changed buffers, it just gives a message naming them."
   (interactive)
   ;; We assume that the diff header has no trailing whitespace.
   (let ((modified-buffers nil))