[Emacs-diffs] /srv/bzr/emacs/trunk r105603: Document trash changes in manual.

[Chong Yidong]

------------------------------------------------------------
revno: 105603
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2011-08-28 16:22:10 -0400
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/dired.texi
  doc/emacs/files.texi
  doc/lispref/ChangeLog
  doc/lispref/debugging.texi
  doc/lispref/files.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-08-28 18:49:59 +0000
+++ b/doc/emacs/ChangeLog       2011-08-28 20:22:10 +0000
@@ -1,5 +1,10 @@
 2011-08-28  Chong Yidong  <address@hidden>
 
+       * 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  <address@hidden>

=== modified file 'doc/emacs/dired.texi'
--- a/doc/emacs/dired.texi      2011-08-25 15:38:49 +0000
+++ b/doc/emacs/dired.texi      2011-08-28 20:22:10 +0000
@@ -201,12 +201,10 @@
 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
address@hidden, 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

=== modified file 'doc/emacs/files.texi'
--- a/doc/emacs/files.texi      2011-06-03 18:47:14 +0000
+++ b/doc/emacs/files.texi      2011-08-28 20:22:10 +0000
@@ -1272,11 +1272,11 @@
   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}.
address@hidden 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
address@hidden to @code{t}.  @xref{Misc File Ops},
+for more information about using the Trash.
 
 @node Comparing Files
 @section Comparing Files
@@ -1546,25 +1546,30 @@
 
 @findex delete-file
 @cindex deletion (of files)
address@hidden 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
address@hidden  @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
address@hidden 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.
+
address@hidden 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
address@hidden  The variable
address@hidden 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

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-08-28 18:49:59 +0000
+++ b/doc/lispref/ChangeLog     2011-08-28 20:22:10 +0000
@@ -1,5 +1,8 @@
 2011-08-28  Chong Yidong  <address@hidden>
 
+       * 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.
 

=== modified file 'doc/lispref/debugging.texi'
--- a/doc/lispref/debugging.texi        2011-07-15 13:16:11 +0000
+++ b/doc/lispref/debugging.texi        2011-08-28 20:22:10 +0000
@@ -596,25 +596,6 @@
 @end smallexample
 @end deffn
 
address@hidden @c Not worth mentioning
address@hidden stack-trace-on-error
address@hidden 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 address@hidden 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
address@hidden or @code{debug-on-error} is also address@hidden, 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.
address@hidden defopt
address@hidden ignore
-
 @defvar debug-on-next-call
 @cindex @code{eval}, and debugging
 @cindex @code{apply}, and debugging

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2011-06-06 19:43:39 +0000
+++ b/doc/lispref/files.texi    2011-08-28 20:22:10 +0000
@@ -1529,19 +1529,26 @@
 links.
 @end deffn
 
address@hidden Command delete-file filename
address@hidden trash
address@hidden delete-by-moving-to-trash
address@hidden Command delete-file filename &optional trash
 @pindex rm
-This command deletes the file @var{filename}, like the shell command
address@hidden @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
address@hidden 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 address@hidden and the
+variable @code{delete-by-moving-to-trash} is address@hidden, this
+command moves the file into the system Trash instead of deleting it.
address@hidden 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 @@
 this happens by default.
 @end deffn
 
address@hidden Command delete-directory dirname &optional recursive
address@hidden trash
address@hidden delete-by-moving-to-trash
address@hidden 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 @@
 
 @code{delete-directory} only follows symbolic links at the level of
 parent directories.
+
+If the optional argument @var{trash} is address@hidden and the
+variable @code{delete-by-moving-to-trash} is address@hidden, this
+command moves the file into the system Trash instead of deleting it.
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-08-28 18:49:59 +0000
+++ b/etc/NEWS  2011-08-28 20:22:10 +0000
@@ -247,9 +247,6 @@
 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 @@
 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 @@
 ** `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 @@
 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 @@
 
 ** 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 @@
 
 ** 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.