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.

7 files changed, 77 insertions, 67 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
diff --git a/etc/NEWS b/etc/NEWS
index c208533b2e1..f563dde0b0c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -247,9 +247,6 @@ Emacs.pane.menubar.font:  Courier-12
 Also, the first dash (which does not indicate anything) is just
 displayed as a space.
 
-** On Nextstep/OSX, the menu bar can be hidden by customizing
-ns-auto-hide-menu-bar.
-
 ** Basic SELinux support has been added.
 This requires Emacs to be linked with libselinux at build time.
 
@@ -305,10 +302,10 @@ scrolls the window so as to avoid positioning point inside the scroll
 margin.
 
 ** Trash changes
-
++++
 *** `delete-by-moving-to-trash' now only affects commands that specify
 trashing.  This avoids inadvertently trashing temporary files.
-
++++
 *** Calling `delete-file' or `delete-directory' with a prefix argument
 now forces true deletion, regardless of `delete-by-moving-to-trash'.
 
@@ -1006,7 +1003,8 @@ Emacs server instances.
 ** `call-process' allows a `(:file "file")' spec to redirect STDOUT to
 a file.
 
-** Removed the stack-trace-on-error variable.
+---
+** Variable `stack-trace-on-error' removed.
 Also the debugger can now "continue" from an error, which means it will jump
 to the error handler as if the debugger had not been invoked instead of
 jumping all the way to the top-level.
@@ -1019,8 +1017,8 @@ The variable is now used to load all kind of supported dynamic libraries,
 not just image libraries.  The previous name is still available as an
 obsolete alias.
 
-** New variable syntax-propertize-function to set syntax-table properties.
-Replaces font-lock-syntactic-keywords which are now obsolete.
+** New variable `syntax-propertize-function'.
+This replaces `font-lock-syntactic-keywords' which is now obsolete.
 This allows syntax-table properties to be set independently from font-lock:
 just call syntax-propertize to make sure the text is propertized.
 Together with this new variable come a new hook
@@ -1045,6 +1043,7 @@ programming modes.
 
 ** define-minor-mode accepts a new keyword :variable.
 
++++
 ** `delete-file' and `delete-directory' now accept optional arg TRASH.
 Trashing is performed if TRASH and `delete-by-moving-to-trash' are
 both non-nil.  Interactively, TRASH defaults to t, unless a prefix
@@ -1165,6 +1164,9 @@ with the USER_LIBS build variable.
 
 ** New make target `dist' to create binary distribution for MS Windows.
 
+** On Nextstep/OSX, the menu bar can be hidden by customizing
+ns-auto-hide-menu-bar.
+
 
 ----------------------------------------------------------------------
 This file is part of GNU Emacs.