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.

6 files changed, 67 insertions, 59 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index b3330022cb3..7b940ba7b5a 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,5 +1,10 @@
 2011-08-28  Chong Yidong  <cyd@stupidchicken.com>
 
+        * files.texi (Misc File Ops): Document new
+        delete-by-moving-to-trash behavior.
+
+        * dired.texi (Dired Deletion): Shorten description of Trash.
+
         * misc.texi (emacsclient Options): Document server-port.
 
 2011-08-27  Eli Zaretskii  <eliz@gnu.org>
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index d536547e293..eb2bcc109e8 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -201,12 +201,10 @@ delete nonempty directories including all their contents.  That can
 be somewhat risky.
 
 @vindex delete-by-moving-to-trash
-  On some systems, there is a facility called the ``Trash'' or
-``Recycle Bin'', but Emacs does @emph{not} use it by default.  Thus,
-when you delete a file in Dired, it is gone forever.  However, you can
-tell Emacs to use the Trash for file deletion, by changing the
-variable @code{delete-by-moving-to-trash} to @code{t}.  @xref{Misc
-File Ops}, for more information about the Trash.
+  If you change the variable @code{delete-by-moving-to-trash} to
+@code{t}, the above deletion commands will move the affected files or
+directories into the operating system's Trash, instead of deleting
+them outright.  @xref{Misc File Ops}.
 
 @node Flagging Many Files
 @section Flagging Many Files at Once
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 793a11e62ed..d337ed3694e 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
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 2d46ad3f774..a778cd92518 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,8 @@
 2011-08-28  Chong Yidong  <cyd@stupidchicken.com>
 
+        * files.texi (Changing Files, Create/Delete Dirs): Document TRASH
+        argument.
+
         * frames.texi (Layout Parameters): The defaults for the
         menu-bar-lines and tool-bar-lines parameters depend on the mode.
 
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index d9e807afb88..757906f286e 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -596,25 +596,6 @@ forms are elided.
 @end smallexample
 @end deffn
 
-@ignore @c Not worth mentioning
-@defopt stack-trace-on-error
-@cindex stack trace
-This variable controls whether Lisp automatically displays a
-backtrace buffer after every error that is not handled.  A quit signal
-counts as an error for this variable.  If it is non-@code{nil} then a
-backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
-error.  If it is @code{nil}, then a backtrace is not shown.
-
-When a backtrace is shown, that buffer is not selected.  If either
-@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
-a backtrace is shown in one buffer, and the debugger is popped up in
-another buffer with its own backtrace.
-
-We consider this feature to be obsolete and superseded by the debugger
-itself.
-@end defopt
-@end ignore
-
 @defvar debug-on-next-call
 @cindex @code{eval}, and debugging
 @cindex @code{apply}, and debugging
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 4d992bd2c51..c83defb433c 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1529,19 +1529,26 @@ This function is not available on systems that don't support symbolic
 links.
 @end deffn
 
-@deffn Command delete-file filename
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-file filename &optional trash
 @pindex rm
-This command deletes the file @var{filename}, like the shell command
-@samp{rm @var{filename}}.  If the file has multiple names, it continues
-to exist under the other names.
-
-A suitable kind of @code{file-error} error is signaled if the file does
-not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
-deletable if its directory is writable.)
-
-If @var{filename} is a symbolic link, @code{delete-file} does not
-replace it with its target, but it does follow symbolic links at all
-levels of parent directories.
+This command deletes the file @var{filename}.  If the file has
+multiple names, it continues to exist under the other names.  If
+@var{filename} is a symbolic link, @code{delete-file} deletes only the
+symbolic link and not its target (though it does follow symbolic links
+at all levels of parent directories).
+
+A suitable kind of @code{file-error} error is signaled if the file
+does not exist, or is not deletable.  (On Unix and GNU/Linux, a file
+is deletable if its directory is writable.)
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}.  When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
 
 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
 @end deffn
@@ -2524,7 +2531,9 @@ create parent directories if they don't exist.  Interactively,
 this happens by default.
 @end deffn
 
-@deffn Command delete-directory dirname &optional recursive
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-directory dirname &optional recursive trash
 This command deletes the directory named @var{dirname}.  The function
 @code{delete-file} does not work for files that are directories; you
 must use @code{delete-directory} for them.  If @var{recursive} is
@@ -2533,6 +2542,13 @@ must use @code{delete-directory} for them.  If @var{recursive} is
 
 @code{delete-directory} only follows symbolic links at the level of
 parent directories.
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}.  When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
 @end deffn
 
 @node Magic File Names