Document trash changes in manual.

* doc/emacs/dired.texi (Dired Deletion): Shorten description of Trash.

* doc/emacs/files.texi (Misc File Ops): Document new
delete-by-moving-to-trash behavior.

* doc/lispref/files.texi (Changing Files, Create/Delete Dirs): Document TRASH
argument.

1 files changed, 26 insertions, 21 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 793a11e62e..d337ed3694 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1272,11 +1272,11 @@ this, it runs the program specified by
   The command @kbd{M-x delete-directory} prompts for a directory name
 using the minibuffer, and deletes the directory if it is empty.  If
 the directory is not empty, you will be asked whether you want to
-delete it recursively.  On systems that have a ``Trash'' or ``Recycle
-Bin'' feature, you can make this command move the specified directory
-to the Trash or Recycle Bin, instead of deleting it outright, by
-changing the variable @code{delete-by-moving-to-trash} to @code{t}.
-@xref{Misc File Ops}, for more information about using the Trash.
+delete it recursively.  On systems that have a ``Trash'' (or ``Recycle
+Bin'') feature, you can make this command move the specified directory
+to the Trash instead of deleting it outright, by changing the variable
+@code{delete-by-moving-to-trash} to @code{t}.  @xref{Misc File Ops},
+for more information about using the Trash.
 
 @node Comparing Files
 @section Comparing Files
@@ -1546,25 +1546,30 @@ as saving files; see @ref{Customize Save}.
 
 @findex delete-file
 @cindex deletion (of files)
-@vindex delete-by-moving-to-trash
-  @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
-command in the shell.  If you are deleting many files in one
-directory, it may be more convenient to use Dired rather than
-@code{delete-file}.  @xref{Dired}.
+  @kbd{M-x delete-file} prompts for a file and deletes it.  If you are
+deleting many files in one directory, it may be more convenient to use
+Dired rather than @code{delete-file}.  @xref{Dired}.
 
 @cindex trash
 @cindex recycle bin
-  On some systems, there is a facility called the ``Trash'' (or
-``Recycle Bin''); ``deleting'' a file normally means moving it into
-the Trash, and you can bring the file back from the Trash if you later
-change your mind.  By default, Emacs does @emph{not} use the Trash for
-file deletion---when Emacs deletes a file, it is gone forever.  You
-can tell Emacs to use the Trash by changing the variable
-@code{delete-by-moving-to-trash} to @code{t}.  This applies to file
-deletion via @kbd{M-x delete-file}, as well as @kbd{M-x
-delete-directory} (@pxref{Directories}) and file deletion in Dired
-(@pxref{Dired Deletion}).  In addition, you can explicitly move a file
-into the Trash with the command @kbd{M-x move-file-to-trash}.
+  @kbd{M-x move-file-to-trash} moves a file into the operating
+system's @dfn{Trash} (or @dfn{Recycle Bin}).  This is a facility
+available on most operating systems; files that are moved into the
+Trash can be brought back later if you change your mind.
+
+@vindex delete-by-moving-to-trash
+  By default, Emacs deletion commands do @emph{not} use the Trash.  To
+use the Trash (when it is available) for common deletion commands,
+change the variable @code{delete-by-moving-to-trash} to @code{t}.
+This affects the commands @kbd{M-x delete-file} and @kbd{M-x
+delete-directory} (@pxref{Directories}), as well as the deletion
+commands in Dired (@pxref{Dired Deletion}).  Supplying a prefix
+argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes
+them delete outright, instead of using the Trash, regardless of
+@code{delete-by-moving-to-trash}.  The variable
+@code{delete-by-moving-to-trash} does not affect file deletions that
+happen as a side-effect of other Emacs commands (e.g. deletions of
+temporary files); those are always true deletions.
 
 @findex rename-file
   @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using