xemacs-beta: man/dired.texi comparison

comparison man/dired.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14

author	cvs
date	Mon, 13 Aug 2007 08:45:50 +0200
parents
children	ac2d302a0011

comparison

equal deleted inserted replaced

--1:000000000000
+:376386a54a3c
+\input texinfo    @c -*-texinfo-*-
+@comment !Date: 1993/12/21 22:31:56 ! !Revision: 1.1 !
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename ../info/dired.info
+@settitle Tree Dired Version 6
+@c @setchapternewpage odd
+@comment %**end of header (This is for running Texinfo on a region.)
+@iftex
+@finalout
+@end iftex
+@ifinfo
+This file documents Tree Dired, the GNU Emacs Directory Browser, and
+most of the extra features available as an option.
+Copyright (C) 1991, 1992 Free Software Foundation
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this one.
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the author instead of in the
+original English.
+@end ifinfo
+@titlepage
+@sp 6
+@center @titlefont{Tree Dired}
+@sp 2
+@center @titlefont{The GNU Emacs}
+@sp 1
+@center @titlefont{Directory Editor}
+@sp 4
+@c @@center !Date: 1993/12/21 22:31:56 !
+@sp 1
+@c @@center !Revision: 1.1 !
+@sp 5
+@center Sebastian Kremer
+@center sk@@thp.uni-koeln.de
+@page
+@noindent
+!Date: 1993/12/21 22:31:56 !
+@noindent
+!Revision: 1.1 !
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991, 1992 Free Software Foundation
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this one.
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the author instead of in the
+original English.
+@end titlepage
+@ifinfo
+@node Top, Dired, (dir), (dir)
+This file documents Tree Dired (version 6), the GNU Emacs Directory
+Editor, including the optional ``Dired Extra'' features.
+Tree Dired is an enhanced version of the Classic (18.xx Emacs) Dired and
+will be the Dired of Emacs 19.  It is known to work with Emacs 18.55 and
+18.57 (and probably most earlier versions).
+@c and also with prerelease versions of Emacs 19, but I don't write that
+@c since I don't want to be bombarded with questions like `when it will
+@c be ready'...
+@noindent
+Revision of this manual:
+@noindent
+!Id: dired.texinfo,v 1.1 1993/12/21 22:31:56 jwz Exp !
+@noindent
+Report bugs to:
+@example
+Sebastian Kremer <sk@@thp.uni-koeln.de>
+@end example
+@menu
+* Dired::			Dired, the Directory Editor
+* Tree Dired Extra::		Tree Dired Extra features
+* Dired Internals::		Dired Internals
+* Dired Known Problems::	Known Problems with Dired
+--- Indices ---
+* Dired Variable Index::
+* Dired Function Index::
+* Dired Key Index::
+* Dired Concept Index::
+--- The Detailed Node Listing ---
+Dired, the Directory Editor
+* Entering Dired::
+* Editing in Dired::
+* Listing Files in Dired::
+* Marking Files in Dired::
+* Mark-using Commands::
+* Commands That Do Not Use Marks::
+* Subdirectories in Dired::
+* Hiding Directories in Dired::
+* Acknowledgement::
+* Dired Customization::
+Mark-using Commands
+* Copy and Move Into a Directory::
+* Renaming and More With Regexps::
+* Other File Creating Commands::
+* Deleting Files With Dired::
+* Dired Shell Commands::
+* Compressing and Uncompressing::
+* Changing File Attributes::
+* Loading and Byte-compiling Emacs Lisp Files::
+* Printing the Marked Files::
+Dired Customization
+* Dired User Options::
+* Dired Configuration::
+* Dired Hooks::
+Tree Dired Extra features
+* Tree Dired Extra Features::
+* Dired Minibuffer History::
+* Inserting All Marked Subdirectories::
+* Dynamic Dired Markers::
+* Omitting Files in Dired::
+* Advanced Dired Mark Commands::
+* Virtual Dired::
+* Multiple Dired Directories::
+* Dired Local Variables::
+* Making Relative Symbolic Links in Dired::
+* Letting Dired Guess What Shell Command to Apply::
+* dired-trns.el::		Filename Transformers for Dired Shell Commands
+* dired-cd.el::			Changing the Working Directory for Dired Shell Commands
+* dired-nstd.el::		Nested Dired format
+* find-dired.el::		Feeding Find Output to Dired
+Dired Internals
+* Tree Dired Internals::
+* Dired Mark Internals::
+@end menu
+@end ifinfo
+@node Dired, Tree Dired Extra, Top, Top
+@chapter Dired, the Directory Editor
+@cindex Dired
+@cindex Deletion (of files)
+Dired makes it easy to delete or visit many of the files in a single
+directory (and possibly its subdirectories) at once.  It makes an Emacs
+buffer containing a listing of the directories, in the format of
+@code{ls -lR}.  You can use the normal Emacs commands to move around in
+this buffer, and special Dired commands to operate on the files.  You
+can run shell commands on files, visit, compress, load or byte-compile
+them, change their file attributes and insert subdirectories into the
+same buffer.  You can ``mark'' files for later commands or ``flag'' them
+for deletion, either file by file or all files matching certain
+criteria.
+@menu
+* Entering Dired::
+* Editing in Dired::
+* Listing Files in Dired::
+* Marking Files in Dired::
+* Mark-using Commands::
+* Commands That Do Not Use Marks::
+* Subdirectories in Dired::
+* Hiding Directories in Dired::
+* Acknowledgement::
+* Dired Customization::
+@end menu
+@node Entering Dired, Editing in Dired, Dired, Dired
+@section Entering Dired
+@findex Dired
+@kindex C-x d
+@vindex dired-listing-switches
+@noindent
+To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}.  The command reads a
+directory name or wildcard file name pattern as a minibuffer argument
+just like the @code{list-directory} command, @kbd{C-x C-d}. Invoking
+Dired with a prefix argument lets you enter the listing switches for the
+directory.
+Dired assumes you meant to use a wildcard if the last component of the
+name is not an existing file.  Note that only the last pathname
+component may contain wildcards.  With wildcards it uses the shell to do
+the filename globbing, whereas usually it calls @samp{ls} directly.
+Because of this, you might have to quote characters that are special to
+the shell.  For example, to dired all auto-save files in your
+@file{~/mail/} directory, use @samp{~/mail/\#*} as argument to Dired.
+Note the backslash needed to quote @samp{#} (at the beginning of a word)
+to the shell.
+Where @code{dired} differs from @code{list-directory} is in naming the
+buffer after the directory name or the wildcard pattern used for the
+listing, and putting the buffer into Dired mode so that the special
+commands of Dired are available in it.  The variable
+@code{dired-listing-switches} is a string used as an argument to
+@code{ls} in making the directory; this string @i{must} contain
+@samp{-l}.  Most other switches are also allowed, especially @samp{-F},
+@samp{-i} and @samp{-s}.  For the @samp{-F} switch to work you may have
+to set the variable @code{dired-ls-F-marks-symlinks}, depending on what
+kind of @samp{ls} program you are using.
+@xref{Dired Configuration}.
+@refill
+When a Dired buffer for the given directory already exists, it is simply
+selected without refreshing it.  You can type @kbd{g} if you suspect it
+is out of date.
+@findex dired-other-window
+@kindex C-x 4 d
+To display the Dired buffer in another window rather than in the
+selected window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead
+of @kbd{C-x d}.@refill
+@node Editing in Dired, Listing Files in Dired, Entering Dired, Dired
+@section Editing in Dired
+@noindent
+Once the Dired buffer exists, you can switch freely between it and other
+Emacs buffers.  Whenever the Dired buffer is selected, certain special
+commands are provided that operate on files that are listed.  The Dired
+buffer is ``read-only'', and inserting text in it is not useful, so
+ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired
+commands, and digits are prefix arguments.@refill
+@cindex Current file (in Dired)
+The file described by the line that point is on is called the
+@dfn{current file}.  The directory this file is in is the @dfn{current
+Dired directory}.  Note that there may be several directories in one
+Dired buffer as long as they belong to the same tree.  The top level
+directory, the @dfn{root} of the tree, is used as the working directory
+of the buffer.@refill
+Some or all directories can be @dfn{hidden}, leaving only their
+headerlines visible, and exlcuding their files from Dired operations.
+@cindex Marking files (in Dired)
+Files can be @dfn{marked} for later commands.  Marking means putting a
+special character, usually @samp{*}, in the first column of the file
+line.  To @dfn{flag} a file means to mark it for later deletion.  This
+special case of ``marking'' is distinguished so that you do not delete
+files accidentally.  Internally, the only difference between marking and
+flagging is the character used to mark the file: @samp{*} (an asterisk)
+for a marked file, and @samp{D} for files flagged for deletion.
+@cindex Mark-using commands
+Most Dired commands operate on the ``marked'' files and default to the
+current file.  They are the @dfn{mark-using} commands.  Deleting is the
+only mark-using command that does not default to the current file.
+Dired buffers ``know'' about each other.  For example, copying from
+@var{dir1} into @var{dir2} will update @var{dir2}'s Dired buffer(s).
+When you move files or directories, file and dired buffers are kept up
+to date and refer to the new location.  But Dired only knows about files
+changed by itself, not by other parts of Emacs or programs outside
+Emacs.
+All the usual Emacs cursor motion commands are available in Dired
+buffers.  Some special purpose commands are also provided.  The keys
+@kbd{C-n} and @kbd{C-p} are redefined so that they try to position the
+cursor at the beginning of the filename on the line, rather than at the
+beginning of the line.
+For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to
+@kbd{C-n}.  @kbd{p} is equivalent to @kbd{C-p}.  Moving by lines is also
+done so often in Dired that it deserves to be easy to type.  @key{DEL}
+(move up and unflag) is often useful simply for moving up.@refill
+@node Listing Files in Dired, Marking Files in Dired, Editing in Dired, Dired
+@section Listing Files in Dired
+@cindex Headerline
+@cindex Non-file line
+@cindex File line
+@noindent
+Initially the Dired buffer shows the directory you selected.  The first
+line shows the full directory name.  It is an example of a
+@dfn{headerline} of a directory.  Note that it is terminated by a colon
+(@samp{:}) that is not part of the directory name.  The second line
+usually displays the total size of all files in the directory or
+the wildcard used.  Both are examples of @dfn{non-file lines}.
+Applying a command to a non-file line signals an error.  The other lines
+of the directory, called the @dfn{file lines}, show information about
+each file such as permission bits, size and date of last modification,
+and the name of the file.@refill
+For example, the listing
+@example
+/home/sk/lib/emacs/lisp:
+total 4973
+-rw-r--r--   1 sk       users      231608 Feb  6 16:58 ChangeLog
+drwxr-sr-x   2 sk       users        2048 Feb  6 11:07 RCS
+-r--r--r--   1 sk       users      141389 Feb  6 10:45 dired.el
+-r--r--r--   1 sk       users      113033 Feb  5 16:21 dired.texi
+@dots{}
+/home/sk/lib/emacs/lisp/RCS:
+total 4798
+-r--r--r--   1 sk       users      231748 Feb  6 16:59 dired.texi,v
+-r--r--r--   1 sk       users      763898 Feb  6 10:45 dired.el,v
+@dots{}
+@end example
+has a headerline for the @file{lisp} directory, a total line saying
+there are 4973 K in all the files of that directory (your @samp{ls}
+program may use units of blocks instead), and several file lines.  After
+that, a headerline for the @file{RCS} subdirectory with its total line
+and its files follows.
+Here is an example of a wildcard listing:
+@example
+/home/sk/lib/emacs/lisp:
+wildcard dired*
+-rw-r--r--   1 sk       users      113036 Feb  6 16:59 dired.texi
+-r--r--r--   1 sk       users       81267 Feb  6 16:29 dired.elc
+-r--r--r--   1 sk       users       38436 Feb  6 16:28 dired-x.elc
+-r--r--r--   1 sk       users       60258 Feb  6 16:27 dired-x.el
+-r--r--r--   1 sk       users      141389 Feb  6 10:45 dired.el
+@dots{}
+@end example
+Since @samp{ls} does not provide a total count when called with a wildcard
+argument, the second line now gives instead the wildcard used, here
+@samp{dired*}.  If there would have been a directory matching the
+wildcard, e.g. a @samp{dired/} subdirectory, its file line would be
+shown, but it would not have been expanded automatically.
+Filenames may have embedded and trailing (but not leading) spaces.
+Leading spaces are not recognized because different @samp{ls} programs
+differ in the amount of whitespace the insert before the filename.
+Filenames may @emph{not} contain newlines or @samp{^M}'s.  You can get
+away with @samp{^M}'s in filenames if you do
+@example
+(setq selective-display nil)
+@end example
+@noindent
+in the Dired buffer (inside @code{dired-mode-hook}, @xref{Dired
+Hooks}.). But this also disables the @kbd{=} and @kbd{$} hiding
+commands, @xref{Hiding Directories in Dired}.@refill
+Other unprintable characters than @samp{^M} or newline (@samp{^J}) in
+filenames are no problem for Dired.  But your @samp{ls} program may not
+output them correctly (e.g., replacing all unprintable characters with a
+question mark @samp{?}).  Dired can do nothing if @samp{ls} suppresses
+information about the filenames.  But some (System V derived) @samp{ls}
+programs have a @samp{-b} switch to quote control characters, e.g.
+@samp{\n} for a newline character, or @samp{\007} for a ASCII bell
+character (@kbd{C-g}), so you might want to add @samp{b} to your
+switches (see below).  Dired translates the quoted control character
+escapes when a @samp{-b} switch was used.  The @samp{-b} switch is the
+recommended method to cope with funny filenames containing newlines or
+leading spaces.  But check if your @samp{ls} understands @samp{-b} and really
+quotes newlines and spaces.  Dired is known to work with GNU @samp{ls
+-b}, but other @samp{ls -b} don't quote spaces, so leading spaces still
+don't work with these @samp{ls} programs.
+@refill
+The appearance of the listing is determined by the listing switches
+used, for example whether you display or suppress @samp{.} files with
+the @samp{-a} and @samp{-A} switches, use the @samp{-F} switch to tag
+filenames etc.  It may additionally be restricted to certain files if you
+used wildcards to display only those files matching a shell file
+wildcard.@refill
+@cindex Dired listing switches
+Dired has commands that change the listing switches for this buffer.
+They are mainly used to set the sort mode, but can also be used to
+change other formatting options.  The buffer is automatically refreshed
+after the switches are changed to let the new format take effect.
+The default value for the switches comes from the variable
+@code{dired-listing-switches}; a prefix argument to @code{dired} can be
+use to determine the switches used for a specific buffer.
+@xref{Entering Dired}.  Each Dired buffer has its own value for the
+switches, stored in the variable @code{dired-actual-switches}.@refill
+@vindex dired-actual-switches
+@vindex dired-sort-by-name-regexp
+@vindex dired-sort-by-date-regexp
+The Dired modeline displays @samp{by name} or @samp{by date} to indicate
+the sort mode.  It uses the regexps in the variables
+@code{dired-sort-by-date-regexp} and @code{dired-sort-by-name-regexp} to
+decide what should be displayed.  If neither of the regexps matches, the
+listing switches are displayed literally.  You can use this to always
+display the literal switches instead of @samp{by name} or @samp{by
+date}: set them to a regexp that never matches any listing switches, for
+example @samp{^$}.@refill
+@vindex dired-ls-sorting-switches
+Most @samp{ls} programs can only sort by name (without @samp{-t}) or by
+date (with @samp{-t}), nothing else.  GNU @samp{ls} additionally sorts
+on size with @samp{-S}, on extension with @samp{-X}, and unsorted (in
+directory order) with @samp{-U}.  So anything that does not contain
+these is sort "by name".  However, this is configurable in the variable
+@code{dired-ls-sorting-switches}, which defaults to @code{"SXU"}.  It
+contains a string of @samp{ls} switches (single letters) except @samp{t} that
+influence sorting.  It is consulted at load time, so if you redefine it,
+you must do it before Dired is loaded.@refill
+@table @kbd
+@item s
+@kindex s
+@findex dired-sort-toggle-or-edit
+(@code{dired-sort-toggle-or-edit}) Toggle between sort by name/date and
+refresh the dired buffer.  With a prefix argument you can edit the
+current listing switches instead.
+@end table
+@cindex Refreshing a Dired listing
+After some time the listing may become out of date because of actions by
+other programs than Dired.  You can refresh the complete Dired buffer
+from disk or only refresh the lines of certain files or a single file.
+@table @kbd
+@item l
+@kindex l
+@findex dired-do-redisplay
+(@code{dired-do-redisplay}) Redisplay all marked (or, with a prefix
+argument, the next @var{N}) files.  As always, if no files are marked,
+the current file is used.
+If on a headerline, redisplay that subdirectory.  In that case,
+a prefix arg lets you edit the @samp{ls} switches used for the new listing.
+@kindex g
+@findex revert-buffer
+@item g
+(@code{revert-buffer}) The @kbd{g} command in Dired ultimately runs
+@code{dired-revert} to reinitialize the buffer from the actual disk
+directory (or directories).  All marks and flags in the Dired buffer are
+restored, except of course for files that have vanished.  Hidden
+subdirectories are hidden again.  @xref{Hiding Directories in Dired}.
+@refill
+@item k
+@kindex k
+@findex dired-kill-line-or-subdir
+(@code{dired-kill-line-or-subdir}) Kill this line (but not this file).
+Optional prefix argument is a repeat factor.
+If file is displayed as expanded subdirectory, kill that as well.
+If on a subdirectory line, kill that subdirectory.  Reinsert it with
+@kbd{i} (@code{dired-maybe-insert-subdir}), @xref{Subdirectories in
+Dired}.
+Killing a file line means that the line is removed from the Dired
+buffer.  The file is not touched, and the line will reappear when the
+buffer is refreshed (using @kbd{g}, @code{revert-buffer}).  A killed
+subdirectory will not reappear after reverting the buffer, since @kbd{g}
+only list those subdirectories that were listed before.
+@item M-k
+@kindex M-k
+@findex dired-do-kill
+(@code{dired-do-kill}) Kill all marked lines (not files).  With a prefix
+argument, kill all lines not marked or flagged.
+(For file marking, @xref{Marking Files in Dired}.)
+@item C-x u
+@kindex C-x u
+@item C-_
+@kindex C-_
+@findex dired-undo
+(@code{dired-undo}) Undo in a Dired buffer.  This doesn't recover lost
+files, it is just normal undo with a temporarily writable buffer.  You
+can use it to recover marks, killed lines or subdirs.  In the latter
+case, you have to do @kbd{M-x dired-build-subdir-alist} to parse the
+buffer again for the new subdirectory list.@refill
+@end table
+@node Marking Files in Dired, Mark-using Commands, Listing Files in Dired, Dired
+@section Marking Files in Dired
+@noindent
+This section describes commands to mark and unmark single files, and
+commands to mark several files at once if they match certain criteria.
+There also is a command to move to the next marked file.
+As always, hidden subdirs are not affected.  @xref{Hiding Directories in
+Dired}.
+@table @kbd
+@item m
+@kindex m
+@findex dired-mark-subdir-or-file
+(@code{dired-mark-subdir-or-file}) If on a file line, mark the current
+file.  A numeric argument tells how many next or previous files to mark.
+If on a subdirectory header line, mark all its files except `.' and `..'.
+@item u
+@kindex u
+@findex dired-unmark-subdir-or-file
+(@code{dired-unmark-subdir-or-file}) Like @kbd{m}, only unmarking
+instead of marking.
+@item DEL
+@kindex DEL
+@findex dired-backup-unflag
+(@code{dired-backup-unflag}) Move up lines and remove flags there.
+Optional prefix argument says how many lines to unflag; default is one
+line.
+@item M-DEL
+@kindex M-DEL
+@findex dired-unflag-all-files
+(@code{dired-unflag-all-files}) Remove a specific or all flags from
+every file.  With an argument, queries for each marked file.  Type your
+help character, usually
+@kbd{C-h}, at that time for help.
+@item *
+@kindex *
+@findex dired-mark-executables
+(@code{dired-mark-executables}) Mark all executable files.  With prefix
+argument, unflag all those files.
+@item @@
+@kindex @@
+@findex dired-mark-symlinks
+(@code{dired-mark-symlinks}) Mark all symbolic links.  With prefix
+argument, unflag all those files.
+@item /
+@kindex /
+@findex dired-mark-directories
+(@code{dired-mark-directories}) Mark all directory files except `.' and
+`..'.  With prefix argument, unflag all those files.
+@item %m
+@kindex %m
+@findex dired-mark-files-regexp
+(@code{dired-mark-files-regexp}) Mark all files matching @var{regexp}
+for use in later commands.  A prefix argument means to unmark them
+instead.  @file{.} and @file{..} are never marked.
+The match is against the non-directory part of the filename.  Use
+@samp{^} and @samp{$} to anchor matches.  Exclude subdirs by hiding
+them.
+This is an Emacs regexp, not a shell wildcard.	E.g., use @samp{\.o$}
+for object files - just @samp{.o} will mark more than you might think.
+By default, the match is case sensitive (just like filenames), since
+@code{case-fold-search} is set to @code{nil} in Dired buffers.
+@item M-@}
+@kindex M-@}
+@findex dired-next-marked-file
+(@code{dired-next-marked-file}) Move to the next marked file, wrapping
+around the end of the buffer.
+@item M-@{
+@kindex M-@{
+@findex dired-prev-marked-file
+(@code{dired-prev-marked-file}) Move to the previous marked file,
+wrapping around the beginning of the buffer.
+@end table
+@node Mark-using Commands, Commands That Do Not Use Marks, Marking Files in Dired, Dired
+@section Mark-using Commands
+@cindex Mark-using commands
+Most Dired commands operate on the ``marked'' files and default to the
+current file.  They are the ``mark-using'' commands.  Deleting is the
+only mark-using command that does not default to the current file.
+@cindex Numeric argument to Dired's mark-using commands
+@cindex Prefix argument to Dired's mark-using commands
+@cindex Repeat count for Dired's mark-using commands
+@cindex Mark-using commands, use of prefix argument as repeat count
+Mark-using Dired commands treat a numeric argument as a repeat count,
+meaning to act on the files of the next few lines instead of on the
+marked files.  That is, when you give a prefix argument the marks are
+not consulted at all.  A negative argument means to operate on the files
+of the preceding lines.  Either set of files is called @dfn{marked
+files} below, whether they really come from marks or from a prefix
+argument.  The prompt of a mark-using command always makes clear which
+set of files is operated upon: it mentions either the marker character
+@samp{*} or the @samp{next @var{N}} files, where a negative @var{N}
+really means the previous @var{-N} files.@refill
+@cindex Prefix argument via digit keys
+Thus you can use a prefix argument of @code{1} to apply a command to just the
+current file, e.g, if you don't want to disturb the other files you
+marked.  As digits are prefix arguments in Dired, simply type @kbd{1}
+followed by the command.
+Many mark-using commands treat a prefix of @var{N=0} specially, since it
+would otherwise be a no-op.
+@cindex Why something went wrong in Dired
+@cindex Error logging in Dired
+@kindex W
+All mark-using commands display a list of files for which they failed.
+Type @kbd{W} to see why a (mark-using or other) command failed.  Error
+messages from shell commands (@samp{stderr}) cannot be redirected
+separately and goes together with the usual output (@samp{stdout}).
+@menu
+* Copy and Move Into a Directory::
+* Renaming and More With Regexps::
+* Other File Creating Commands::
+* Deleting Files With Dired::
+* Dired Shell Commands::
+* Compressing and Uncompressing::
+* Changing File Attributes::
+* Loading and Byte-compiling Emacs Lisp Files::
+* Printing the Marked Files::
+@end menu
+@node Copy and Move Into a Directory, Renaming and More With Regexps, Mark-using Commands, Mark-using Commands
+@subsection Copy, Move etc. Into a Directory
+@cindex Target commands in Dired
+@cindex Dired target commands
+@noindent
+This section explains commands that create a new file for each marked
+file, for example by copying (@kbd{c}) or moving (@kbd{r}) files.  They
+prompt in the minibuffer for a @var{target} argument, usually the target
+directory in which the new files are created.  But if there is but one
+marked file, the target may also be a plain file.  (Otherwise you could
+not simply rename or copy a single file within the same directory.)
+Even with one marked file the target may still be an (existing)
+directory.
+@cindex Target default in Dired
+@cindex Default target in Dired
+@vindex dired-dwim-target
+The target prompt displays a @dfn{default target} that will be used if
+you just type @kbd{RET}.  Normally the default target is the current
+Dired directory, so if you want to copy into some specific subdirectory,
+move point into that subdirectory before typing @kbd{c}.  But if there
+is a Dired buffer in the next window, and @code{dired-dwim-target} is
+true, its current Dired directory is used.  This makes it easy to copy
+from one Dired buffer into another if both are displayed.  On the other
+hand you have to use @kbd{C-x 1} to make other Dired buffers vanish if
+you do not want to have them as default targets.  To make Dired never
+look at the next window, set the variable @code{dired-dwim-target} to
+nil (@samp{dwim} means Do What I Mean).  @xref{Dired User Options}, on
+how to set cutomization variables.
+@cindex Overwriting of files in Dired
+As a general rule, Dired will not let you remove or overwrite a file
+without explicit confirmation.  Dired asks you for each existing target
+file whether or not to overwrite just this file (answer @kbd{y} or
+@kbd{n}) or all remaining files (answer @kbd{!}).  You can also type
+your help character, usually @kbd{C-h}, at that time for help.
+@table @kbd
+@findex dired-do-copy
+@kindex c
+@vindex dired-copy-preserve-time
+@item c
+(@code{dired-do-copy}) Copy the marked (or next @var{N}) files into a
+directory, or copy a single file.
+Thus, a zero prefix argument (@var{N-0}) copies nothing.  But it toggles
+the variable @code{dired-copy-preserve-time}.@*
+@xref{Dired User Options}, on how to set customization variables.
+@findex dired-do-move
+@kindex r
+@item r
+(@code{dired-do-move}) Move the marked files into a directory.  If
+there is just one marked file, rename that file.  As the marked files
+default to the current file, this can also be used to simply rename the
+current file.
+Dired silently changes the visited file name of buffers associated with
+moved files so that they refer to the new location of the file.
+When a directory is renamed, its headerlines in Dired buffers are
+updated, and any buffers visiting affected files have their visited file
+name changed to refer to the new location.  Their buffer name is changed
+if no buffer with such a name already exists.  Affected files are all
+those which contain the directory somewhere in their absolute path name.
+A zero prefix arguments does not move any files, but toggles the
+variable @code{dired-dwim-target}.
+@findex dired-do-hardlink
+@kindex H
+@item H
+(@code{dired-do-hardlink}) Make hard links from the target directory
+to each marked file.
+@findex dired-do-symlink
+@kindex Y
+@item Y
+(@code{dired-do-symlink}) Make symbolic links from the target
+directory to each marked file.
+@end table
+@vindex dired-keep-marker-copy
+@vindex dired-keep-marker-hardlink
+@vindex dired-keep-marker-symlink
+Linking is very similar to copying in that new files are created while
+the old files stay.  If you want each newly copied or linked file to be
+marked with the same marker that its original has, set the variables
+@code{dired-keep-marker-copy}, @code{dired-keep-marker-hardlink} or
+@code{dired-keep-marker-symlink} to @code{t}.  Set them to @code{nil} to
+not give these newly created files marks.  The default is to mark them
+with @samp{C}, @samp{H} and @samp{Y}, respectively.
+@vindex dired-keep-marker-move
+Moving differs from copying and linking in that the old file is removed
+as part of the creation of the new file.  Thus it makes sense to set the
+variable @code{dired-keep-marker-move} to @code{t} (the default) so that
+moved files ``take their markers with them''.
+@node Renaming and More With Regexps, Other File Creating Commands, Copy and Move Into a Directory, Mark-using Commands
+@subsection Renaming (and More) With Regexps
+@cindex Regexp commands in Dired
+@cindex Dired regexp commands
+A second class of Commands uses regular expressions to construct a new
+filename from each marked file. @xref{Regexps,Syntax of Regular
+Expressions,Regular Expressions,emacs,The GNU Emacs Manual}.  The commands
+to make new names by regexp conversion are the same as those to make
+them in another directory, except that they share a prefix char, @kbd{%}.
+@table @kbd
+@item %r
+@kindex %r
+@findex dired-rename-regexp
+(@code{dired-rename-regexp}) Rename files with regexps
+@item %c
+@kindex %c
+@findex dired-do-copy-regexp
+(@code{dired-do-copy-regexp})
+Copy files with regexps.
+@item %H
+@kindex %H
+@findex dired-do-hardlink-regexp
+(@code{dired-do-hardlink-regexp})
+Make hard links with regexps.
+@item %Y
+@kindex %Y
+@findex dired-do-symlink-regexp
+(@code{dired-do-symlink-regexp})
+Make symbolic links with regexps.
+@end table
+These commands prompt in the minibuffer for a @var{regexp} and a
+@var{newname}.  For each marked file matching @var{regexp}, a new
+filename is constructed from @var{newname}.  The match can be anywhere
+in the file name, it need not span the whole filename.  Use @samp{^} and
+@samp{$} to anchor matches that should span the whole filename.  Only
+the first match in the filename is replaced with @var{newtext}.  (It
+would be easy to change this to replace all matches, but probably harder
+to use.)
+@samp{\&} in @var{newname} stands for the entire text being replaced.
+@samp{\@var{d}} in @var{newname}, where @var{d} is a digit, stands for
+whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
+As each match is found, the user must type a character saying whether or
+not to apply the command to just this file (@kbd{y} or @kbd{n}) or to
+all remaining files(@kbd{!}).  For help type your help character,
+usually @kbd{C-h}, at that time.@refill
+For example, if you want to rename all @file{.lsp} files to @file{.el}
+files, type first @kbd{%m} with @samp{\.lsp$} as regexp to mark all
+@file{.lsp} files.  Then type @kbd{%r} with @samp{\.lsp$} and @samp{.el}
+as @var{regexp} and @var{newtext} arguments.  Dired will prompt you for
+each file to be renamed.
+Or to append @file{.old} to all marked files, use @kbd{%r} @samp{$}
+@kbd{RET} @samp{.old} @kbd{RET}, replacing the empty string at the end
+of each file name with @samp{.old}.
+You can use the regexp @samp{\(.+\)\.\(.+\)$} to make the
+basename as @samp{\1} and the extension as @samp{\2} available in
+@var{newtext}.
+With a zero prefix arg, renaming by regexp affects the complete
+pathname.  Usually only the non-directory part of file names is used and
+changed, and renaming only takes place within the current directory.
+The zero prefix argument can be used to change the directory part as
+well.
+Often you will want to apply the command to all files matching the same
+@var{regexp} that you use in the command.  Simply use the @kbd{%m}
+command with @var{regexp} as argument, which will then also be the
+default for the next regexp using command.@refill For example, to remove
+a @file{V17I12-} prefix from several filenames, use @kbd{%m}
+@samp{^V17I12-} @kbd{RET} @kbd{%r} @kbd{RET} @kbd{RET}, in effect
+replacing the prefix with the empy string.
+@node Other File Creating Commands, Deleting Files With Dired, Renaming and More With Regexps, Mark-using Commands
+@subsection Other File Creating Commands
+@cindex Case-changing Dired commands
+@cindex Dired case-changing commands
+Commands to change the case of file names:
+@table @kbd
+@findex dired-upcase
+@kindex %u
+@item %u
+(@code{dired-upcase}) Rename each marked file to upper case.
+@findex dired-downcase
+@kindex %l
+@item %l
+(@code{dired-downcase}) Rename each marked file to lower case.
+@end table
+@node Deleting Files With Dired, Dired Shell Commands, Other File Creating Commands, Mark-using Commands
+@subsection Deleting Files With Dired
+@noindent
+Deleting is a special mark-using command.  It uses a special marker,
+@samp{D}, and does not default to the current file if no files are
+marked to prevent accidental deletions.@refill
+@xref{Dired Customization}, variable @code{dired-del-marker} to make
+deleting behave exactly like any mark-using command.@refill
+@table @kbd
+@findex dired-flag-file-deleted
+@kindex d
+@item d
+(@code{dired-flag-file-deleted}) Flag this file for deletion.  If on a
+subdirectory headerline, mark all its files except @file{.} and @file{..}.
+@findex dired-unmark-subdir-or-file
+@kindex u
+@item u
+(@code{dired-unmark-subdir-or-file}) Remove deletion-flag on this line.
+@findex dired-backup-unflag
+@kindex @key{DEL}
+@item @key{DEL}
+(@code{dired-backup-unflag}) Remove deletion-flag on previous line,
+moving point to that line.
+@findex dired-flag-regexp-files
+@kindex %d
+@item %d
+(@code{dired-flag-regexp-files}) Flag all files containing the specified
+@var{regexp} for deletion.
+The match is against the non-directory part of the filename.  Use
+@samp{^} and @samp{$} to anchor matches.  Exclude subdirs by hiding
+them.
+The special directories @file{.} and @file{..} are never flagged.
+@findex dired-do-deletions
+@kindex x
+@item x
+(@code{dired-do-deletions}) Delete the files that are flagged for
+deletion (with @samp{D}).
+@findex dired-do-delete
+@kindex X
+@item X
+(@code{dired-do-delete}) Delete the @samp{*}-marked (as opposed to the
+@samp{D}-flagged) files.
+@findex dired-flag-auto-save-files
+@kindex #
+@item #
+(@code{dired-flag-auto-save-files}) Flag all auto-save files (files
+whose names start and end with @samp{#}) for deletion (@pxref{Auto
+Save,Auto-Saving: Protection Against Disasters,Auto Save,emacs,The GNU Emacs
+Manual}).
+@findex dired-flag-backup-files
+@kindex ~
+@item ~
+(@code{dired-flag-backup-files}) Flag all backup files (files whose
+names end with @samp{~}) for deletion (@pxref{Backup,Backup
+Files,Backup,emacs,The GNU Emacs Manual}).
+@findex dired-clean-directory
+@kindex .
+@item .@: @r{(Period)}
+(@code{dired-clean-directory}) Flag excess numeric backup files for
+deletion.  The oldest and newest few backup files of any one file are
+exempt; the middle ones are flagged.
+@end table
+You can flag a file for deletion by moving to the line describing the
+file and typing @kbd{d} or @kbd{C-d}.  The deletion flag is visible as a
+@samp{D} at the beginning of the line.  Point is moved to the beginning
+of the next line, so that repeated @kbd{d} commands flag successive
+files.
+The files are flagged for deletion rather than deleted immediately to
+avoid the danger of deleting a file accidentally.  Until you direct
+Dired to delete the flagged files, you can remove deletion flags using
+the commands @kbd{u} and @key{DEL}.  @kbd{u} works just like @kbd{d},
+but removes flags rather than making flags.  @key{DEL} moves upward,
+removing flags; it is like @kbd{u} with numeric argument automatically
+negated.
+To delete the flagged files, type @kbd{x}.  This command first displays
+a list of all the file names flagged for deletion, and requests
+confirmation with @kbd{yes}.  Once you confirm, all the flagged files
+are deleted, and their lines are deleted from the text of the Dired
+buffer.  The shortened Dired buffer remains selected.  If you answer
+@kbd{no} or quit with @kbd{C-g}, you return immediately to Dired, with
+the deletion flags still present and no files actually deleted.
+Deletions proceed from the end of the buffer, so if subdirs are in a
+natural order in the buffer, it usually works to flag @samp{dir1},
+@samp{dir1/dir2} and @samp{dir1/dir2/*} (by typing @kbd{d} on the
+directory headerlines) and delete everything, including @samp{dir1/dir2}
+and @samp{dir1}.  Using shell commands (e.g.  @samp{rm -rf}) to remove
+complete directories may be quicker than having Dired remove each file
+separately. (@xref{Dired Shell Commands}.)  However, like all actions
+external to Dired, this does not update the display.@refill
+@c and does not offer to kill buffers of deleted files.
+The @kbd{#}, @kbd{~} and @kbd{.} commands flag many files for deletion,
+based on their names.  These commands are useful precisely because they
+do not actually delete any files; you can remove the deletion flags from
+any flagged files that you really wish to keep.@refill
+@kbd{#} flags for deletion all files that appear to have been made by
+auto-saving (that is, files whose names begin and end with @samp{#}).
+@kbd{~} flags for deletion all files that appear to have been made as
+backups for files that were edited (that is, files whose names end with
+@samp{~}).
+@vindex dired-kept-versions
+@kbd{.} (Period) flags just some of the backup files for deletion: only
+numeric backups that are not among the oldest few nor the newest few
+backups of any one file.  Normally @code{dired-kept-versions} (not
+@code{kept-new-versions}; that applies only when saving) specifies the
+number of newest versions of each file to keep, and
+@code{kept-old-versions} specifies the number of oldest versions to
+keep.  Period with a positive numeric argument, as in @kbd{C-u 3 .},
+specifies the number of newest versions to keep, overriding
+@code{dired-kept-versions}.  A negative numeric argument overrides
+@code{kept-old-versions}, using minus the value of the argument to
+specify the number of oldest versions of each file to keep.@refill
+@node Dired Shell Commands, Compressing and Uncompressing, Deleting Files With Dired, Mark-using Commands
+@subsection Shell Commands on Marked files
+@cindex Shell commands (in Dired)
+@noindent
+You can run arbitrary shell commands on the marked files. If there is
+output, it goes to a separate buffer.
+@table @kbd
+@findex dired-do-shell-command
+@kindex !
+@item !
+(@code{dired-do-shell-command}) Run a shell command on the marked
+files.
+@end table
+A command string is prompted for in the minibuffer.  The list of marked
+files is appended to the command string unless asterisks @samp{*}
+indicate the place(s) where the list should go.  Thus,@refill
+@example
+command -flags
+@end example
+is equivalent to
+@example
+command -flags *
+@end example
+The filenames are inserted in the order they appear in the buffer.  The
+file listed topmost in the buffer will be the leftmost in the list.
+Currently, there is no way to insert a real @samp{*} into the command.
+As with all mark-using commands, if no files are marked or a specific
+numeric prefix arg is given, the current or the next @var{N} files are
+used.  The prompt mentions the file(s) or the marker, as appropriate.
+However, for shell commands, a zero argument is special. It means to run
+command on each marked file separately:
+@example
+cmd * |foo
+@end example
+results in
+@example
+cmd F1 |foo; @dots{}; cmd F@var{n} |foo
+@end example
+Usually
+@example
+cmd F1 @dots{} F@var{n} |foo
+@end example
+would be executed.@refill
+No automatic redisplay is attempted because Dired cannot know what files
+should be redisplayed for a general shell command.  For example, a
+@samp{tar cvf} will not change the marked files at all, but rather
+create a new file, while a @samp{ci -u -m'@dots{}' *} will probably change
+the permission bits of all marked files.
+Type @kbd{l} to redisplay just the marked files, or @kbd{l} on a
+directory headerline to redisplay just that directory, or @kbd{g} to
+redisplay all directories.@refill
+The shell command has the top level directory as working directory, so
+output files usually are created there instead of in a subdirectory,
+which may sometimes be surprising if all files come from the same
+subdirectory.  Just remember that an Emacs buffer can have but one
+working directory, and this is the top level directory in Dired
+buffers.
+Examples for shell commands:
+@itemize @bullet
+@item
+Type @kbd{!} and
+@example
+tar cvf foo.tar
+@end example
+@noindent
+to tar all marked files into a @file{foo.tar} file.  Dired does not know
+that a new file has been created and you have to type @kbd{g} to refresh
+the listing.  If you have several subdirectories in your Dired buffer,
+the names given to @samp{tar} will be relative to the top level
+directory, and the output file @file{foo.tar} will also be created
+there.@refill
+You can use
+@example
+tar cvf - * | compress -c > foo.tar.Z
+@end example
+@noindent
+as an alternative to immediately compress the tar file.
+@item
+Type @kbd{0 !} and
+@example
+uudecode
+@end example
+@noindent
+to uudecode each of the marked files.  Note the use of the zero prefix
+argument to apply the shell command to each file separately (uudecode
+doesn't accept a list of input files).  Type @kbd{g} afterwards to see
+the created files.
+@item
+Type @kbd{0 !} and
+@example
+uuencode * * >*.uu
+@end example
+@noindent
+to uuencode each of the marked files, writing into a corresponding
+@file{.uu} file.  Note the use of the zero prefix argument to apply the
+shell command to each file separately.  Type @kbd{g} afterwards to see
+the created @file{.uu} files.
+@item
+Type @kbd{1 !} and
+@example
+mail joe@@somewhere <*
+@end example
+@noindent
+to mail the current file (note the prefix argument @samp{1}) to user
+@samp{joe@@somewhere}.@refill
+@item
+@cindex running the current file
+@cindex executing the current file
+@cindex current file, how to run it
+Here is a Dired shell command to execute the current file, assuming no
+other files are marked (else just give the prefix @kbd{1} to @kbd{!}):
+@example
+./*
+@end example
+which will be expanded to @samp{./@var{cmd}}, thus @var{cmd} will be
+executed..  (Just @samp{./} would be expanded to @samp{./ @var{cmd}},
+with an intervening @kbd{SPC}.)  This will work even if you don't have
+@file{.} in your @code{$PATH}.  If @file{.} is in your path (not a good
+idea, as you will find out if you dired a directory containing a file
+named @file{ls}), a single @kbd{SPC} as command would also work.
+@c <<NEED MORE AND BETTER EXAMPLES HERE>>
+@end itemize
+@node  Compressing and Uncompressing, Changing File Attributes, Dired Shell Commands, Mark-using Commands
+@subsection Compressing and Uncompressing
+@noindent
+You can compress or uncompress the marked files.  Dired refuses to
+compress files ending in @file{.Z} (which are already compressed) or
+symbolic links (the link would be overwritten by a plain, compressed
+file) and to uncompress files not ending in @file{.Z}.
+@table @kbd
+@findex dired-do-compress
+@kindex C
+@item C
+(@code{dired-do-compress}) Compress the marked files.
+@findex dired-do-uncompress
+@kindex U
+@item U
+(@code{dired-do-uncompress}) Uncompress the marked files.
+@end table
+@node Changing File Attributes, Loading and Byte-compiling Emacs Lisp Files, Compressing and Uncompressing, Mark-using Commands
+@subsection Changing File Attributes
+@noindent
+You can change the file attributes (mode, group, owner) of marked files.
+@table @kbd
+@findex dired-do-chmod
+@kindex M
+@item M
+(@code{dired-do-chmod}) Change the mode (also called ``permission
+bits'') of the marked files.  This calls the @samp{chmod} program, thus
+symbolic modes like @samp{g+w} are allowed.
+Multiple switches like @samp{-fR g+w} are not understood, though.  Use
+@kbd{!} (@code{dired-do-shell-command}) for that.
+@findex dired-do-chgrp
+@kindex G
+@item G
+(@code{dired-do-chgrp}) Change the group of the marked files.
+@vindex dired-chown-program
+@findex dired-do-chown
+@kindex O
+@item O
+(@code{dired-do-chown}) Change the owner of the marked files.  This
+usually works for the superuser only.  It uses the program in the
+variable @code{dired-chown-program} to do the change.@refill
+@end table
+@node Loading and Byte-compiling Emacs Lisp Files, Printing the Marked Files, Changing File Attributes, Mark-using Commands
+@subsection Loading and Byte-compiling Emacs Lisp Files
+@noindent
+You can load and byte-compile GNU Emacs Lisp files.  Errors are caught and
+reported after all files have been processed.
+@table @kbd
+@findex dired-do-load
+@kindex L
+@item L
+(@code{dired-do-load}) Load the marked elisp files.
+@findex dired-do-byte-compile
+@kindex B
+@item B
+(@code{dired-do-byte-compile}) Byte compile the marked elisp files.
+@end table
+@node  Printing the Marked Files,  , Loading and Byte-compiling Emacs Lisp Files, Mark-using Commands
+@subsection Printing the Marked Files
+@table @kbd
+@findex dired-do-print
+@kindex P
+@vindex lpr-command
+@vindex lpr-switches
+@item P
+(@code{dired-do-print}) Print the marked (or next @var{N}) files.
+Uses the shell command coming from variables @code{lpr-command} and
+@code{lpr-switches} as default.
+Since internally this is just a special case of
+@code{dired-do-shell-command}, you can use @samp{*} and pipes like for
+shell command, e.g.,
+@example
+(setq lpr-command: "lwf")
+(setq lpr-switches: '("-l -m * | lpr -Palw"))
+@end example
+to print with the shell command @samp{lwf -l -m * | lpr -Palw}, where
+@samp{*} will be substituted by the marked files.  The @code{lpr-buffer}
+and @code{lpr-region} don't know about @samp{*} or @samp{|}, though, only
+Dired does.
+@end table
+@node Commands That Do Not Use Marks, Subdirectories in Dired, Mark-using Commands, Dired
+@section Commands That Do Not Use Marks
+@noindent
+These are commands that visit files.
+@xref{Visiting,Visiting Files,Visiting,emacs,The GNU Emacs Manual}.
+@table @kbd
+@findex dired-advertised-find-file
+@kindex f
+@item f
+(@code{dired-advertised-find-file}) Visits the file described on the
+current line.  It is just like typing @kbd{C-x C-f} and supplying that
+file name.  If the file on this line is a subdirectory, @kbd{f} actually
+causes Dired to be invoked on that subdirectory.
+@findex dired-find-file-other-window
+@kindex o
+@item o
+(@code{dired-find-file-other-window}) Like @kbd{f}, but uses another
+window to display the file's buffer.  The Dired buffer remains visible
+in the first window.  This is like using @kbd{C-x 4 C-f} to visit the
+file.  @xref{Windows,Multiple Windows,Windows,emacs,The GNU Emacs Manual}.
+@findex dired-view-file
+@kindex v
+@item v
+(@code{dired-view-file}) Views the file described on this line using
+@kbd{M-x view-file}.  Viewing a file is like visiting it, but is slanted
+toward moving around in the file conveniently and does not allow
+changing the file.  @xref{Misc File Ops,View File,Miscellaneous File
+Operations,emacs,The GNU Emacs Manual}.  @refill Viewing a file that is a
+directory goes to its headerline if it is in this buffer.  Otherwise, it
+is displayed in another buffer.
+@c Forgot that this only works for my version of C-x C-r...
+@c
+@c You might think that a @code{dired-view-file-other-window} command is
+@c missing, but it is easy to use @kbd{o} followed by @kbd{C-x C-r}
+@c @kbd{RET}, which will first visit the file in the other window, then
+@c @samp{find-file-read-only} it (@kbd{RET} defaulting to the current
+@c buffer's file).
+@end table
+@cindex Diffing files in Dired
+@noindent
+Commands to diff a file:
+@table @kbd
+@findex dired-diff
+@kindex D
+@item D
+(@code{dired-diff}) Compare file at point with another file (default:
+file at mark), by running the system command @samp{diff}.  The other
+file is the first file given to @samp{diff}.
+@findex dired-backup-diff
+@kindex M-~
+@item M-~
+(@code{dired-backup-diff}) Diff this file with its backup file.  Uses
+the latest backup, if there are several numerical backups.  If this file
+is a backup, diff it with its original.  The backup file is the first
+file given to @samp{diff}.
+@end table
+@noindent
+Other commands:
+@table @kbd
+@findex dired-create-directory
+@kindex +
+@cindex Creating a directory in Dired
+@cindex Directory, how to create one in Dired
+@item +
+(@code{dired-create-directory}) Create a directory.
+@end table
+@table @kbd
+@findex dired-why
+@kindex W
+@cindex Why something went wrong in Dired
+@cindex Error logging in Dired
+@item W
+(@code{dired-why}) Pop up a buffer with error log output from Dired.
+All mark-using commands log errors there.  (Standard error from shell
+commands cannot be logged separately, it goes into the usual shell
+command output buffer.)  A group of errors from a single command ends
+with a formfeed, so that you can use @kbd{C-x [} (@code{backward-page})
+to find the beginning of new error logs that are reported by a command.
+@end table
+@node   Subdirectories in Dired, Hiding Directories in Dired, Commands That Do Not Use Marks, Dired
+@section Subdirectories in Dired
+@noindent
+Thise section explains how to @dfn{insert} (or @dfn{expand})
+subdirectories in the same Dired buffer and move around in them.
+@cindex Inserting subdirectories in same Dired buffer
+@cindex Expanding subdirectories in Dired
+You can display subdirectories in your Dired buffer by using @samp{-R}
+in your Dired listing switches.  But you do not usually want to have a
+complete recursive listing in all your Dired buffers.  So there is a
+command to insert a single directory:
+@table @kbd
+@findex dired-maybe-insert-subdir
+@kindex i
+@item i
+@cindex Inserted subdirectory
+@cindex Expanded subdirectory
+@cindex In-situ subdirectory
+@cindex Headerline
+(@code{dired-maybe-insert-subdir}) Insert this subdirectory into the
+same Dired buffer.  If it is already present, just move to it (type
+@kbd{l}, @code{dired-do-redisplay} to refresh it).  Else inserts it as
+@samp{ls -lR} would have done.  With a prefix arg, you may edit the ls
+switches used for this listing.  You can add @samp{R} to the switches to
+expand the whole tree starting at this subdirectory.  This function
+takes some pains to conform to @samp{ls -lR} output.  For example, it adds the
+headerline for the inserted subdirectory.@refill
+The mark is dropped before moving, so @kbd{C-x C-x} takes you back to
+the old position in the buffer.
+@end table
+Dired changes the buffer-local value of the variable
+@code{page-delimiter} to @code{"\n\n"}, so that subdirectories become
+pages.  Thus, the page moving commands @kbd{C-x [} and @kbd{C-x ]}
+(@code{backward-page} and @code{forward-page}) can be used to move to
+the beginning (i.e., the headerlines) of subdirectories.
+In addition, the following commands move around directory-wise, usually
+putting you on a file line instead of on a headerline.  For a mnemonic,
+note that they all look like rotated versions of each other, and that
+they move in the direction they point to.
+@table @kbd
+@findex dired-prev-dirline
+@kindex <
+@item <
+(@code{dired-prev-dirline}) Goto previous directory file line.
+@findex dired-next-dirline
+@kindex >
+@item >
+(@code{dired-next-dirline}) Goto next directory file line.
+@findex dired-up-directory
+@kindex ^
+@item ^
+(@code{dired-up-directory}) Dired parent directory.  Tries first to find
+its file line, then its header line in this buffer, then its Dired
+buffer, finally creating a new Dired buffer if necessary.
+@findex dired-view-file
+@kindex v
+@item v
+(@code{dired-view-file}) When the current file is not a directory, view
+it.  When file is a directory, tries to go to its subdirectory.
+@comment actually, it is not always inverse
+This command is inverse to the @kbd{^} command and it is very convenient
+to use these two commands together.
+@end table
+The following commands move up and down in the directory tree:
+@table @kbd
+@findex dired-tree-up
+@kindex M-C-u
+@item M-C-u
+(@code{dired-tree-up}) Go up to the parent directory's headerline.
+@findex dired-tree-down
+@kindex M-C-d
+@item M-C-d
+(@code{dired-tree-down}) Go down in the tree, to the first
+subdirectory's headerline.
+@end table
+The following commands move forwards and backwards to subdirectory headerlines:
+@table @kbd
+@findex dired-next-subdir
+@kindex M-C-n
+@item M-C-n
+(@code{dired-next-subdir}) Go to next subdirectory headerline,
+regardless of level.
+@findex dired-prev-subdir
+@kindex M-C-p
+@item M-C-p
+(@code{dired-prev-subdir}) Go to previous subdirectory headerline,
+regardless of level.
+@end table
+@node Hiding Directories in Dired, Acknowledgement, Subdirectories in Dired, Dired
+@section Hiding Directories in Dired
+@cindex Hiding in Dired
+@noindent
+@dfn{Hiding} a subdirectory means to make it invisible, except for its
+headerline.  Files inside a hidden subdirectory are never considered by
+Dired.  For example, mark-using commands will not ``see'' files in a
+hidden directory.  Thus you can use hiding to temporarily exclude
+subdirectories from operations without having to remove the markers.
+The hiding commands toggle, that is they unhide what was hidden and vice
+versa.
+@table @kbd
+@findex dired-hide-subdir
+@kindex $
+@item $
+(@code{dired-hide-subdir}) Hide or unhide the current subdirectory and
+move to next directory.  Optional prefix argument is a repeat factor.
+@findex dired-hide-all
+@kindex =
+@item =
+(@code{dired-hide-all}) Hide all subdirectories, leaving only their
+header lines.  If there is already something hidden, make everything
+visible again.  Use this command to get an overview in very deep
+directory trees or to move quickly to subdirs far away.
+@end table
+@node Acknowledgement, Dired Customization, Hiding Directories in Dired, Dired
+@section Acknowledgement
+@noindent
+I would like to thank
+@itemize @bullet
+@item
+Richard Stallman for providing a pre-release version of @file{dired.el}
+from Emacs 19, critical comments and many helpful suggestions
+@item
+Andy Norman for the collaboration that made Tree Dired and ange-ftp such
+a successful combination
+@item
+Jamie Zawinski for insisting on and writing nested Dired format, and for
+lots of other things
+@item
+Michael Ernst for the ``omitting'' code and helpful discussion about
+Dired design
+@item
+Hans Chalupsky for providing FTP service and writing
+@file{dired-trns.el}
+@item
+Roland McGrath for @file{find-dired.el} and bug fixes for the diffing
+commands
+@item
+Kevin Gallagher for sending me existing VMS Dired fixes
+@item
+Hal R. Brand for VMS support and porting his old dired fixes to Tree
+Dired
+@item
+Hugh Secker-Walker for writing @file{dired-cd.el}
+@item
+Tom Wurgler for ideas such as the @dfn{dired-jump-back} command
+@item
+Cengiz Alaettinoglu, who found more bugs in Tree Dired than anybody else
+(except me)
+@end itemize
+@noindent
+and all other beta testers and people who reported bugs or just said
+``thanks''.
+@node Dired Customization,  , Acknowledgement, Dired
+@section Dired Customization
+@noindent
+You can customize Dired by setting some variables in your @file{~/.emacs}
+file.  Other variables are intended to be configured when Dired is
+installed.  Finally, there are so-called `hook' variables.
+@menu
+* Dired User Options::
+* Dired Configuration::
+* Dired Hooks::
+@end menu
+@node Dired User Options, Dired Configuration, Dired Customization, Dired Customization
+@subsection Customization of Dired
+@noindent
+The following variables are for personal customization in your
+@file{~/.emacs} file.  For example, include a line similar to the
+following
+@example
+(setq dired-listing-switches "-Alt")  ; sort on time, ignore . and ..
+@end example
+to set your favorite Dired listing switches.
+@c Should actually use @defopt here, but this is in Texinfo2 only.
+@table @code
+@vindex dired-listing-switches
+@item dired-listing-switches
+Default: @code{"-al"}
+Switches passed to @samp{ls} for Dired. @i{Must} contain the @samp{l} option.
+@vindex dired-trivial-filenames
+@item dired-trivial-filenames
+Default: @code{"^\\.\\.?$\\|^#"}
+Regexp of files to skip when moving point to the first file of a new
+directory listing.  Nil means move to the subdirectory line, t means move to
+first file.
+@vindex dired-marker-char
+@item dired-marker-char
+Default: @code{?*} (@samp{?*} is the Lisp notation for the character
+@samp{*}.)
+In Dired, character used to mark files for later commands.
+This is a variable so that one can write things like
+@example
+(let ((dired-marker-char ?X))
+;; great code using X markers ...
+)
+@end example
+@vindex dired-del-marker
+@item dired-del-marker
+Default: @code{?D}
+Character used to flag files for deletion.
+Usually, marking for commands and flagging for deletion are separate
+features.  (Internally they use the same marking mechanism.)  You type
+@kbd{d} to flag with @samp{D} and @kbd{x} to delete the @samp{D}-flagged
+files.@refill
+This explains how to make deletion behave just like a special case of
+the general file marking feature, so that you type @kbd{m} to mark with
+@samp{*} (as usual) and @kbd{d} to delete the @samp{*} (or next @var{N})
+files: In your @file{~/.emacs}, include
+@example
+(setq dired-del-marker dired-marker-char) ; use * also for deletions
+(setq dired-load-hook
+(function
+(lambda ()
+;; other customizations here
+;; let "d" do the actual deletion:
+(define-key dired-mode-map "d" 'dired-do-delete))))
+@end example
+If you do not like that @kbd{d} defaults to the current file if there
+are no marks, replace the @code{define-key} statement in
+@code{dired-load-hook} above with this one:
+@example
+(define-key dired-mode-map "d" 'dired-do-deletions)
+@end example
+@vindex dired-shrink-to-fit
+@item dired-shrink-to-fit
+Default: @code{(if (fboundp 'baud-rate) (> (baud-rate) search-slow-speed) t)}
+Whether Dired shrinks the display buffer to fit the marked files.
+@vindex dired-no-confirm
+@item dired-no-confirm
+Default: @code{nil}
+If non-nil, list of commands Dired should not confirm.  Confirmation for
+commands that require an argument to be entered (like the shell command
+for @kbd{!}) means a list of marked files is displayed in a pop-up
+buffer.  Confirmation for commands that do not require an argument (like
+compressing with @kbd{C}) means you have to confirm by typing @kbd{y} or
+@kbd{SPC}.
+Except @code{nil}, it can be a sublist of
+@example
+'(byte-compile chgrp chmod chown compress copy delete hardlink load
+move print shell symlink uncompress)
+@end example
+to suppress confirmation for just those commands.
+@c @vindex dired-deletion-confirmer
+@c But you can
+@c set the variable @code{dired-deletion-confirmer} to another function
+@c than @code{yes-or-no-p}, its default value.  Using @code{y-or-no-p} will
+@c confirm with only a single key stroke, @key{y} or @key{n}, and using
+@c @code{identity} will effectively switch off confirmation.
+@vindex dired-keep-marker-move
+@item dired-keep-marker-move
+Default: @code{t}
+If nil, moved files are not marked.
+If t, moved marked files are marked with the same marker they had before
+(maybe none if you used the prefix argument to specify the next @var{N}
+files).
+If a character, moved files (marked or not) are marked with that
+character.
+This also applies to the following, similar variables for copied, and
+hard or symbolically linked files:
+@vindex dired-keep-marker-copy
+@item dired-keep-marker-copy
+Default: @code{?C}
+@vindex dired-keep-marker-hardlink
+@item dired-keep-marker-hardlink
+Default: @code{?H}
+@vindex dired-keep-marker-symlink
+@item dired-keep-marker-symlink
+Default: @code{?Y}
+@vindex dired-dwim-target
+@item dired-dwim-target
+Default: @code{nil}
+If non-nil, Dired tries to guess a default target directory: If there is
+a Dired buffer displayed in the next window, use its current subdirectory,
+instead of the current subdirectory of this Dired buffer.
+The target is used in the prompt for file copy, move etc.,
+@xref{Copy and Move Into a Directory}.
+@item dired-copy-preserve-time
+@vindex dired-copy-preserve-time
+Default: @code{nil}
+If non-nil, Dired preserves the last-modified time in a file copy.
+(This works on only some systems.)  Use @kbd{c} (@code{dired-do-copy})
+with a zero prefix argument to toggle its value.  The prompt of copy
+commands will display @samp{Copy [-p]} instead of just @samp{Copy} if
+preservation of file times is turned on.
+@item dired-backup-if-overwrite
+@vindex dired-backup-if-overwrite
+Default: @code{nil}
+Non-nil if Dired should ask about making backups before overwriting files.
+Special value @code{'always} suppresses confirmation.
+@end table
+@node Dired Configuration, Dired Hooks, Dired User Options, Dired Customization
+@subsection Dired Configuration
+The following variables should have already been installed correctly by
+your system manager.  If not, you can still set them in your
+@file{~/.emacs} file.@refill
+@table @code
+@vindex dired-chown-program
+@item dired-chown-program
+Pathname of chown command, default @code{"chown"} (or
+@code{"/etc/chown"} on System V derived systems.)
+@vindex dired-ls-program
+@item dired-ls-program
+Absolute or relative name of the @samp{ls} program used by Dired,
+default @code{"ls"}.
+@vindex dired-ls-F-marks-symlinks
+@item dired-ls-F-marks-symlinks
+Set this to @code{t} if dired-ls-program with @samp{-lF} marks the
+symbolic link itself with a trailing @samp{@@} (usually the case under
+Ultrix).
+Example: If
+@example
+ln -s foo bar; ls -F bar
+@end example
+gives
+@example
+bar -> foo
+@end example
+set it to @code{nil}, if it gives
+@example
+bar@@ -> foo
+@end example
+set it to @code{t}.
+Dired checks if there is really a @@ appended.  Thus, if you have a
+marking @samp{ls} program on one host and a non-marking one on another
+host, and do not care about symbolic links which really end in a @@, you
+can always set this variable to @code{t}.
+@end table
+@node Dired Hooks,  , Dired Configuration, Dired Customization
+@subsection Dired Hooks
+@noindent
+Hook variables can contain functions that are run at certain times in
+Dired.
+@table @code
+@vindex dired-load-hook
+@item dired-load-hook
+Run after loading Dired.  You can customize key bindings or load
+extensions with this.  For example:
+@example
+(setq dired-load-hook
+(function
+(lambda ()
+;; Load extras:
+(load "dired-x")
+;; How to define your own key bindings:
+(define-key dired-mode-map " " 'scroll-up)
+(define-key dired-mode-map "b" 'scroll-down))))
+@end example
+@vindex dired-mode-hook
+@item dired-mode-hook
+Run at the very end of @code{dired-mode}, after most buffer local
+variables have been initialized (e.g., @code{default-directory} and
+@code{dired-directory}), but before the directory listing has been read
+in.
+Do buffer local things here, for example:
+@example
+(setq dired-mode-hook
+(function
+(lambda ()
+(dired-extra-startup)	 ;; dired-extra support
+;; How to set (local) variables in each new Dired buffer:
+(setq case-fold-search t)
+(setq truncate-lines t))))
+@end example
+Since the listing has not yet been inserted you could still change
+@code{dired-actual-switches}.  For example, if you use
+@file{ange-ftp.el}, you might want to replace the @samp{-A} with the
+@samp{-a} switch, depending on whether @code{default-directory}
+corresponds to a System V hosts that does not understand all BSD
+@samp{ls} switches.  The @code{dired.README} file gives an example.  If
+you set @code{dired-actual-switches} remember that you may also have to
+set @code{dired-sort-mode} to the appropriate string so that the
+modeline looks right.
+Do not set @code{dired-mode-hook} inside your @code{dired-load-hook},
+simply set it somewhere in your @file{~/.emacs} (before Dired is loaded,
+if you explicitly load Dired).  This is so that extensions packages
+loaded via the load hook can add things to the @code{dired-mode-hook} at
+the front or at the end, as they see fit.
+In case you set @code{truncate-lines} to @code{t} as in the above
+example, here is a function to toggle the value of
+@code{truncate-lines}, in Dired and other buffers:
+@example
+(defun set-truncate-lines ()
+"Toggle value of truncate-lines and refresh window display."
+(interactive)
+(setq truncate-lines (not truncate-lines))
+;; now refresh window display (an idiom from simple.el):
+(save-excursion
+(set-window-start (selected-window)
+(window-start (selected-window)))))
+@end example
+You could bind it to @kbd{C-x 4 $}:
+@example
+(define-key ctl-x-4-map "$" 'set-truncate-lines)
+@end example
+It is sometimes useful to toggle @code{truncate-lines} in Dired buffers
+to make long filenames completely visible and get the listing properly
+aligned again.
+@vindex dired-before-readin-hook
+@item dired-before-readin-hook
+This hook is run before a dired buffer is newly read in (created or reverted).
+@vindex dired-after-readin-hook
+@item dired-after-readin-hook
+After each listing of a file or directory, this hook is run with the
+buffer narrowed to the listing.
+The @code{dired-subdir-alist} has already been updated so that the usual
+Dired functions like @code{dired-get-filename} work.  It is possible to
+modify the buffer with this hook.  The package @file{dired-x.el} does
+this to implement omitting certain uninteresting files from a Dired
+buffer.  Under X11, highlighting of certain files is also possible (see
+package @file{dired-x11.el}).
+@end table
+@node Tree Dired Extra, Dired Internals, Dired, Top
+@chapter Tree Dired Extra features
+Numerous ``extra'' features are available, such as omitting certain
+files from listings, minibuffer history, RCS related commands, and more.
+@menu
+* Tree Dired Extra Features::
+* Dired Minibuffer History::
+* Inserting All Marked Subdirectories::
+* Dynamic Dired Markers::
+* Omitting Files in Dired::
+* Advanced Dired Mark Commands::
+* Virtual Dired::
+* Multiple Dired Directories::
+* Dired Local Variables::
+* Making Relative Symbolic Links in Dired::
+* Letting Dired Guess What Shell Command to Apply::
+* dired-trns.el::		Filename Transformers for Dired Shell Commands
+* dired-cd.el::			Changing the Working Directory for Dired Shell Commands
+* dired-nstd.el::		Nested Dired format
+* find-dired.el::		Feeding Find Output to Dired
+@end menu
+@node Tree Dired Extra Features, Dired Minibuffer History, Tree Dired Extra, Tree Dired Extra
+@section Tree Dired Extra Features
+The rest of this manual describes the extra features provided by the
+file @file{dired-x.el} and some other files.
+To take advantage of these features, you must load the file and set some
+variables and hooks.  See the accompanying @file{dired-x.README}
+file for details and a template of code to insert in your @file{.emacs}.
+Miscellanous features not fitting anywhere else:
+Variables:
+@table @code
+@item dired-find-subdir
+@vindex dired-find-subdir
+Default: @code{nil}
+If non-nil, Dired does not make a new buffer for a directory if it
+can be found (perhaps as subdirectory) in some existing Dired buffer.
+If there are several Dired buffers for a directory, the most recently
+used is chosen.
+Dired avoids switching to the current buffer, so that if you have a
+normal and a wildcard buffer for the same directory, @kbd{C-x d RET}
+will toggle between those two.
+@end table
+@table @kbd
+@findex dired-goto-file
+@kindex M-g
+@item M-g
+(@code{dired-goto-file}) Goto file line of a file (or directory).
+@findex dired-goto-subdir
+@kindex M-G
+@item M-G
+(@code{dired-goto-subdir}) Goto headerline of an inserted directory.
+This commands reads its argument with completion over the names of the
+inserted subdirectories.
+@end table
+@table @kbd
+@findex dired-do-background-shell-command
+@kindex &
+@cindex Input to Dired shell commands
+@cindex Interactive Dired shell commands
+@cindex Background Dired shell commands
+@item &
+(@code{dired-do-background-shell-command}) Run a shell command on the
+marked files, in the background.  This requires @file{background.el}
+from Olin Shiver's comint package to work.  Note that you can type input
+to the command in its buffer.
+@item w
+@kindex w
+@findex dired-copy-filename-as-kill
+(@code{dired-copy-filename-as-kill}) The @kbd{w} command puts the names
+of the marked (or next @var{N}) files into the kill ring, as if you had
+killed them with @kbd{C-w}.  With a zero prefix argument @var{N}=0, use the
+complete pathname of each file.  With a raw (just @kbd{C-u}) prefix argument,
+use the relative pathname of each marked file.  As a special case, if no
+prefix argument is given and point is on a directory headerline, it
+gives you the name of that directory, without looking for marked files.
+@vindex dired-marked-files
+The list of names is also stored onto the variable @code{dired-marked-files}
+for use, e.g., in an @kbd{ESC ESC} (@code{eval-expression}) command.
+As this command also displays what was pushed onto the kill ring you can
+use it to display the list of currently marked files in the
+echo area (unless you happen to be on a subdirectory headerline).
+You can then feed the file name to other Emacs commands with @kbd{C-y}.
+For example, say you want to rename a long filename to a slightly
+different name.  First type @kbd{w} to push the old name onto the kill
+ring.  Then type @kbd{r} to rename it and use @kbd{C-y} inside @kbd{r}'s
+minibuffer prompt to insert the old name at a convenient place.
+@item T
+@kindex T
+@findex dired-do-toggle
+(@code{dired-do-toggle}) Toggle marks.  That is, currently marked
+files become unmarked and vice versa.  Files marked with other flags
+(such as `D') are not affected.  The special directories `.' and `..'
+are never toggled.
+@end table
+@node Dired Minibuffer History, Inserting All Marked Subdirectories, Tree Dired Extra Features, Tree Dired Extra
+@section Minibuffer History for Dired Shell Commands
+@cindex History of Minibuffer input
+@cindex Minibuffer History
+@cindex Gmhist
+@kindex !
+@kindex &
+@kindex M-p
+@kindex M-n
+If @file{dired-x.el} determines at load-time that the Gmhist package is
+available, the Dired shell commands @kbd{!} and @kbd{&} maintain a
+history of commands.  Use @kbd{M-p} and @kbd{M-n} to scroll through them
+while you are prompted in the minibuffer for a shell command.
+@xref{Gmhist Keys in the Minibuffer,Gmhist Keys in the Minibuffer,Gmhist
+Keys in the Minibuffer,gmhist,The Gmhist Manual}, for more info.
+Gmhist also handles defaults:
+@table @code
+@vindex dired-dangerous-shell-command
+@item dired-dangerous-shell-command
+Default: @code{"rm"}
+Regexp for dangerous shell commands that should never be the default.
+It is deliberately chosen to match @samp{rm} anywhere in the command,
+e.g. in @samp{rmdir}.
+@end table
+@node Inserting All Marked Subdirectories, Dynamic Dired Markers, Dired Minibuffer History, Tree Dired Extra
+@section Insert all marked subdirectories
+@table @kbd
+@kindex I
+@findex dired-do-insert-subdir
+@item I
+(@code{dired-do-insert-subdir}) Insert all marked subdirectories that
+are not already inserted.  Non-directories are silently ignored.
+Thus type @kbd{/I} to insert one more level of subdirectories.  You can
+repeat this until no new directories are inserted to fully expand the
+directory tree in this buffer.  As a faster alternative, use the prefix
+argument for @kbd{C-x d} (@code{dired}) to add @samp{R} to the switches.
+@end table
+@node Dynamic Dired Markers, Omitting Files in Dired, Inserting All Marked Subdirectories, Tree Dired Extra
+@section Dynamic Marker Characters
+@cindex Dynamic marker characters
+@cindex Marker characters in Dired, changing them
+@cindex Changing marker character in Dired
+@cindex Stack of marker characters in Dired
+You can change the marker character from its usual value @code{*} to
+something else.  Use this to mark a different set of files while keeping
+the information on the already marked files.  You can nest several
+marker characters.  The current stack of marker characters is displayed
+in the Dired mode line, and all prompts of mark-using commands mention
+to which marker they apply.
+@table @kbd
+@item (
+@kindex (
+@findex dired-set-marker-char
+(@code{dired-set-marker-char}) Set the marker character to something
+else.  Use @kbd{)} to restore the previous value.
+@item )
+@kindex )
+@findex dired-restore-marker-char
+(@code{dired-restore-marker-char}) Restore the marker character to its
+previous value.  Uses @code{dired-default-marker} if the marker stack is
+empty.
+@end table
+@kindex A
+@kindex Z
+@kindex m
+@kindex (
+Instead of using @kbd{m} inside a @kbd{(}@dots{}@kbd{)}, you can mark
+files ``in passing'' with, say @samp{Z} without changing the
+current marker character.  You will probably later use @kbd{(} to
+temporarily make @samp{Z} to the marker and do something on the
+@samp{Z}-files, and then return using @code{)}.
+@table @code
+@item dired-mark-keys
+Default: @code{'("Z")}
+List of keys (strings) that insert themselves as file markers.
+@end table
+@node  Omitting Files in Dired, Advanced Dired Mark Commands, Dynamic Dired Markers, Tree Dired Extra
+@section Omitting Files in Dired
+@cindex Omitting Files in Dired
+@dfn{Omitting} a file means removing it from the directory listing.
+Omitting is useful for keeping Dired buffers free of uninteresting files
+(for instance, auto-save, auxiliary, backup, and revision control files)
+so that the user can concentrate on the interesting files.  Like hidden
+files, omitted files are never seen by Dired.
+@xref{Dired Hiding,Hiding in Dired,Hiding in Dired,dired,Tree Dired Manual}.
+Omitting differs from hiding in several respects:
+@itemize @bullet
+@item
+Omitting works on individual files, not on directories; an entire
+directory cannot be omitted (though each of its files could be).
+@item
+Omitting is wholesale; if omitting is turned on for a dired buffer, then
+all ``uninteresting'' files listed in that buffer are omitted.  The user
+does not omit (or unomit) files one at a time.
+@item
+Omitting can be automatic; uninteresting file lines in the buffer can
+be removed before the user ever sees them.
+@item
+Marked files are never omitted.
+@end itemize
+@table @kbd
+@item M-o
+@kindex M-o
+@findex dired-omit-toggle
+(@code{dired-omit-toggle})
+Toggle between displaying and omitting ``uninteresting'' files.
+With a prefix argument, don't toggle and just mark the files, but don't
+actually omit them.
+@end table
+In order to make omitting work, you must have @code{dired-omit-expunge}
+on your @code{dired-after-readin-hook}, and you must call
+@code{dired-omit-startup} (or @code{dired-extra-startup}, which calls
+@code{dired-omit-startup}) in your @code{dired-mode-hook}.  Simply
+loading @file{dired-x.el} inside @code{dired-load-hook} takes care of
+all this.
+The following variables can be used to customize omitting.
+@table @code
+@vindex dired-omit-files-p
+@item dired-omit-files-p
+Default: @code{nil}
+@cindex How to make omitting the default in Dired
+If non-nil, ``uninteresting'' files are not listed.  Uninteresting files
+are those whose filenames match regexp @code{dired-omit-files}, plus those
+ending with extensions in @code{dired-omit-extensions}.  @kbd{M-o}
+(@code{dired-omit-toggle}) toggles its value, which is buffer-local.  Do
+@example
+(setq dired-omit-files-p t)
+@end example
+inside your @code{dired-mode-hook} to have omitting initially turned on
+in every Dired buffer.  Since @file{dired-x.el} prepends the form
+@samp{(dired-extra-startup)} to what you put yourself in your
+@code{dired-mode-hook}, the @code{setq} will take place after
+@code{dired-omit-files-p} has already been made local to the current
+Dired buffer, so modelines of non-dired buffers are not affected.  For
+this to work you shouldn't set @code{dired-mode-hook} inside
+@code{dired-load-hook}, but directly in your @file{~/.emacs} (before
+Dired is loaded, if you explicitly load Dired).
+You can then use @kbd{M-o} to unomit in that buffer.
+@vindex dired-omit-files
+@item dired-omit-files
+Default: @code{"^#\\|\\.$"}
+Filenames matching this buffer-local regexp will not be displayed.
+This only has effect when @code{dired-omit-files-p} is t.
+The default value omits the special directories @file{.} and @file{..}
+and autosave files (plus other files ending in ``.'').
+@vindex dired-omit-extensions
+@item dired-omit-extensions
+Default: The elements of @code{completion-ignored-extensions},
+@code{latex-unclean-extensions}, @code{bibtex-unclean-extensions} and
+@code{texinfo-unclean-extensions}.
+If non-nil, a list of extensions (strings) to omit from Dired listings.
+Its format is the same as that of @code{completion-ignored-extensions}.
+@vindex dired-omit-localp
+@item dired-omit-localp
+Default:  @code{'no-dir}
+The @var{localp} argument @code{dired-omit-expunge} passes to
+@code{dired-get-filename}.  If it is @code{'no-dir}, omitting is much
+faster, but you can only match against the non-directory part of the
+filename.  Set it to @code{nil} if you need to match the whole pathname
+or @code{t} to match the pathname relative to the buffer's top-level
+directory.
+@item dired-omit-marker-char
+@vindex dired-omit-marker-char
+Default: @kbd{C-o}
+Temporary marker used by by Dired to implement omitting.
+Should never be used as marker by the user or other packages.
+@cindex Omitting additional files
+There is one exception to this rule: by doing
+@example
+(setq dired-mark-keys "\C-o")
+;; i.e., the value of dired-omit-marker-char
+;; (which is not defined yet)
+@end example
+anywhere in your @file{~/.emacs}, you will bind the @kbd{C-o} key to
+insert a @key{C-o} marker, thus causing these files to be omitted in
+addition to the usually omitted files.  Unfortunately the files you
+omitted manually this way will show up again after reverting the buffer,
+unlike the others.
+@end table
+@cindex RCS files, how to omit them in Dired
+@cindex Omitting RCS files in Dired
+To avoid seeing RCS files and the RCS directory, do
+@example
+(setq dired-omit-files "\\.$\\|#\\|^RCS$\\|,v$")
+@end example
+This assumes @code{dired-omit-localp} has its default value of
+@code{'no-dir} to make the @code{^}-anchored matches work.  As a slower
+alternative, with @code{dired-omit-localp} set to @code{nil}, you can
+use @code{/} instead of @code{^} in the regexp.
+@cindex Tib files, how to omit them in Dired
+@cindex Omitting tib files in Dired
+If you use tib, the bibliography program for use with @TeX{} and
+La@TeX{}, you might want to omit the @file{INDEX} and the @file{-t.tex}
+files:
+@example
+(setq dired-omit-files "\\.$\\|#\\|^INDEX$\\|-t\\.tex$")
+@end example
+@node Advanced Dired Mark Commands, Virtual Dired, Omitting Files in Dired, Tree Dired Extra
+@section Advanced Mark Commands
+@table @kbd
+@item M-(
+@kindex M-(
+@findex dired-mark-sexp
+@cindex Lisp expression, marking files with in Dired
+@cindex Mark file by lisp expression
+(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns non-nil.
+With a prefix argument, unflag those files instead.
+The @var{predicate} is a lisp expression that can refer to the following
+symbols:
+@table @code
+@item inode
+[@i{integer}] the inode of the file (only for @samp{ls -i} output)
+@item s
+[@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or,
+with @samp{-k}, in KBytes)
+@item mode
+[@i{string}]  file permission bits, e.g., @samp{"-rw-r--r--"}
+@item nlink
+[@i{integer}] number of links to file
+@item uid
+[@i{string}]  owner
+@item gid
+[@i{string}]  group  (If the gid is not displayed by @samp{ls}, this
+will still be set (to the same as uid))
+@item size
+[@i{integer}] file size in bytes
+@item time
+[@i{string}]  the time that @samp{ls} displays, e.g., @samp{"Feb 12 14:17"}
+@item name
+[@i{string}]  the name of the file
+@item sym
+[@i{string}]  if file is a symbolic link, the linked-to name, else @samp{""}
+@end table
+@noindent
+For example, use
+@example
+(equal 0 size)
+@end example
+to mark all zero length files.
+To find out all not yet compiled Emacs lisp files in a directory, dired
+all @file{.el} files in the lisp directory using the wildcard
+@samp{*.el}.  Then use @kbd{M-(} with
+@example
+(not (file-exists-p (concat name "c")))
+@end example
+to mark all @file{.el} files without a corresponding @file{.elc} file.
+@item M-M
+@kindex M-M
+@cindex Marker character, how to replace it
+@cindex Replacing one marker character with another
+(@code{dired-do-unmark}) Unmark marked files by replacing the marker
+with another character.  The new character defaults to a space,
+effectively unmarking them.
+@item ,
+@kindex ,
+@cindex RCS controlled files, how to mark them
+@cindex Marking RCS controlled files
+(@code{dired-mark-rcs-files}) Mark all files that are under RCS control.
+With prefix argument, unflag all those files.  Mentions RCS files for
+which a working file was not found in this buffer.  Type @kbd{W}
+(@code{dired-why}) to see them again.
+@item C-m C-c
+@kindex C-m C-c
+@cindex Compilation files, how to mark them
+@cindex Marking compilation files
+@cindex List of files, how to mark them
+@cindex Marking a list of files from a buffer
+(@kbd{C-m C-c} is the suggested binding for
+@code{dired-mark-files-compilation-buffer}, it is not bound by default.)
+Mark the files mentioned in the @samp{*compilation*} buffer.  With an
+argument, you may specify the other buffer and your own regexp instead of
+@code{compilation-error-regexp}.  Use @samp{^.+$} (the default with a
+prefix argument) to match complete lines.  In conjunction with narrowing the
+other buffer you can mark an arbitrary list of files, one per line, with
+this command.  If your regexp contains a subexpression, i.e.
+@samp{\(@var{...}\)}, that subexpression is taken for the file name,
+else the whole match is used.  Thus you can easily strip pre- and
+suffixes from filenames by using @samp{@var{prefix}\(.+\)@var{postfix}}
+as regexp.
+This is especially useful for a list of files obtained from @kbd{M-x
+grep} or output from a similar shell command.
+@item C-m C-d
+@kindex C-m C-d
+@cindex Corresponding files, how to mark them
+@cindex List of files, how to mark them
+(@kbd{C-m C-d} is the suggested binding for
+@code{dired-mark-files-from-other-dired-buffer}, it is not bound by default.)
+Mark those files in this Dired buffer that have the same name as the
+marked files in the Dired buffer in the other window.
+In short, mark the corresponding files from the other Dired buffer.
+@end table
+@table @kbd
+@item F
+@kindex F
+@cindex Visiting several files at once
+@cindex Simultaneous visiting of several files
+@findex dired-do-find-file
+(@code{dired-do-find-file}) Visit all marked files at once, and
+display them simultaneously.  If you want to keep the dired buffer
+displayed, type @kbd{C-x 2} first.  If you want just the marked files
+displayed and nothing else, type @kbd{C-x 1} first.
+The current window is split across all files.  Remaining lines go to the
+last window.
+The number of files that can be displayed this way is restricted by the
+height of the current window and the variable @code{window-min-height}.
+@end table
+@table @code
+@item dired-mark-extension
+@findex dired-mark-extension
+Mark all files with a certain extension for use in later commands.
+A @samp{.} is not automatically prepended to the string entered.
+When called from lisp, @var{extension} may also be a list of extensions
+and an optional argument @var{marker-char} specifies the marker used.
+@item dired-flag-extension
+@findex dired-flag-extension
+Flag all files with a certain extension for deletion.
+A @samp{.} is @emph{not} automatically prepended to the string entered.
+@item dired-clean-patch
+@findex dired-clean-patch
+Flag dispensable files created by the @samp{patch} program for deletion.
+See variable @code{patch-unclean-extensions}.
+@item dired-clean-tex
+@findex dired-clean-tex
+Flag dispensable files created by @TeX{}, La@TeX{} and @samp{texinfo}
+for deletion.  See variables @code{tex-unclean-extensions},
+@code{texinfo-unclean-extensions}, @code{latex-unclean-extensions} and
+@code{bibtex-unclean-extensions}.
+@end table
+Variables used by the above cleanup commands (and in the default value
+for variable @code{dired-omit-extensions}):
+@table @code
+@item patch-unclean-extensions
+@vindex patch-unclean-extensions
+Default:  @code{'(".rej" ".orig")}
+List of extensions of dispensable files created by the @samp{patch} program.
+@item tex-unclean-extensions
+@vindex tex-unclean-extensions
+Default:  @code{'(".toc" ".log" ".aux")}
+List of extensions of dispensable files created by @TeX{}.
+@item texinfo-unclean-extensions
+@vindex texinfo-unclean-extensions
+Default: @code{'(".cp" ".cps" ".fn" ".fns" ".ky" ".kys" ".pg" ".pgs"
+".tp" ".tps" ".vr" ".vrs")}
+List of extensions of dispensable files created by texinfo.
+@item latex-unclean-extensions
+@vindex latex-unclean-extensions
+Default: @code{'(".idx" ".lof" ".lot" ".glo")}
+List of extensions of dispensable files created by LaTeX.
+@item bibtex-unclean-extensions
+@vindex bibtex-unclean-extensions
+Default:  @code{'(".blg" ".bbl")}
+List of extensions of dispensable files created by BibTeX.
+@end table
+@node Virtual Dired, Multiple Dired Directories, Advanced Dired Mark Commands, Tree Dired Extra
+@section Virtual Dired
+@cindex Virtual Dired
+@cindex Perusing ls listings
+@cindex ls listings, how to peruse them in Dired
+Using @dfn{Virtual Dired} means putting a buffer with Dired-like
+contents in Dired mode.  The files described by the buffer contents need
+not actually exist.  This is useful if you want to peruse an @samp{ls -lR}
+output file, for example one you got from an FTP server.  You can use
+all motion commands usually available in Tree Dired.  You can also use
+it to save a Dired buffer in a file and resume it in a later session.
+@findex dired-virtual
+@kindex g
+@findex dired-virtual-revert
+Type @kbd{M-x dired-virtual} to put the current buffer into virtual
+Dired mode.  You will be prompted for the top level directory of this
+buffer, with a default value guessed from the buffer contents.  To
+convert the virtual to a real Dired buffer again, type @kbd{g} (which
+calls @code{dired-virtual-revert}) in the virtual Dired buffer and
+answer @samp{y}.  You don't have to do this, though: you can relist
+single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory
+headerline, leaving the buffer in virtual Dired mode all the time.
+@findex dired-virtual-mode
+@vindex auto-mode-alist
+The function @samp{dired-virtual-mode} is specially designed to turn on
+virtual Dired mode from the @code{auto-mode-alist}.  To automatically
+edit all @file{*.dired} files in virtual Dired mode, put this into your
+@file{~/.emacs}:
+@example
+(setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode)
+auto-mode-alist))
+@end example
+The regexp is a bit more complicated than usual to exclude ".dired"
+local variable files.
+@node Multiple Dired Directories, Dired Local Variables, Virtual Dired, Tree Dired Extra
+@section Multiple Dired Directories and Non-Dired Commands
+@cindex Multiple Dired directories
+@cindex Working directory
+An Emacs buffer can have but one working directory, stored in the
+buffer-local variable @code{default-directory}.  A Dired buffer may have
+several subdirectories inserted, but still has but one working
+directory: that of the top level Dired directory in that buffer.  For
+some commands it is appropriate that they use the current Dired
+directory instead of @code{default-directory}, e.g., @code{find-file} and
+@code{compile}.
+A general mechanism is provided for special handling of the working
+directory in special major modes:
+@table @code
+@item default-directory-alist
+@vindex default-directory-alist
+Default: @code{((dired-mode . (dired-current-directory)))}
+Alist of major modes and their opinion on @code{default-directory}, as a
+lisp expression to evaluate.  A resulting value of @code{nil} is ignored
+in favor of @code{default-directory}.
+@item default-directory
+@findex default-directory
+Function with usage like variable @code{default-directory}, but knows about the
+special cases in variable @code{default-directory-alist}.
+@end table
+The following dired-x commands take special care about the current
+Dired directory:
+@table @code
+@item find-this-file
+@findex find-this-file
+@findex find-file
+@kindex C-x C-f
+Bind this to @kbd{C-x C-f} as a replacement for @code{find-file} that
+will prompt for the filename within the current Dired subdirectory, not
+the top level directory.
+@item find-this-file-other-window
+@findex find-this-file-other-window
+@findex find-file-other-window
+@kindex C-x 4 C-f
+Bind this to @kbd{C-x 4 C-f} as a replacement for
+@code{find-file-other-window}.
+@item dired-smart-shell-command
+@findex dired-smart-shell-command
+@findex shell-command
+@kindex M-!
+Like function @code{shell-command}, but in the current Tree Dired directory.
+Bound to @kbd{M-!} in Dired buffers.
+@item dired-smart-background-shell-command
+@findex dired-smart-background-shell-command
+@findex background
+@kindex M-&
+Like function @code{background}, but in the current Tree Dired directory.
+Bound to @kbd{M-&} in Dired buffers.
+@item dired-jump-back
+@findex dired-jump-back
+@kindex C-x j
+(Suggested binding @kbd{C-x j}) Jump back to dired: If in a file, dired
+the current directory and move to file's line.  If in Dired already, pop
+up a level and goto old directory's line.  In case the proper Dired file
+line cannot be found, refresh the Dired buffer and try again.
+@item dired-jump-back-other-window
+@findex dired-jump-back-other-window
+@kindex C-x 4 j
+(Suggested binding @kbd{C-x 4 j}) Like @code{dired-jump-back}, but to
+other window.
+@item dired-vm
+@kindex V
+@findex dired-vm
+@vindex vm-folder-directory
+(@kbd{V}) Run VM on this file (assumed to be a UNIX mail folder).
+Further `v' commands from within VM in that folder will default to the
+folder's directory, not the usual @code{vm-folder-directory}.
+@vindex dired-vm-read-only-folders
+If you give this command a prefix argument, it will visit the folder
+read-only.  This only works in VM 5, not VM 4.
+If the variable @code{dired-vm-read-only-folders} is t, @code{dired-vm}
+will visit all folders read-only.  If it is neither @code{nil} nor
+@code{t}, e.g., the symbol @code{'if-file-read-only}, only files not
+writable by you are visited read-only.  This is the recommended value if
+you run VM 5.
+@item dired-rmail
+@findex dired-rmail
+Run Rmail on this file (assumed to be mail folder in Rmail/BABYL format).
+@end table
+@c subsection Narrow and Widen in a Dired Buffer
+@node Dired Local Variables, Making Relative Symbolic Links in Dired, Multiple Dired Directories, Tree Dired Extra
+@section Local Variables for Dired Directories
+@cindex Local Variables for Dired Directories
+@vindex dired-local-variables-file
+When Dired visits a directory, it looks for a file whose name is the
+value of variable @code{dired-local-variables-file} (default:
+@file{.dired}).  If such a file is found, Dired will temporarily insert
+it into the Dired buffer and run @code{hack-local-variables}.
+@xref{File Variables,Local Variables in Files,Local Variables in
+Files,emacs,The GNU Emacs Manual}.  You can set
+@code{dired-local-variables-file} to @code{nil} to suppress this.
+For example, put
+@example
+Local Variables:
+dired-actual-switches: "-lat"
+dired-sort-mode: " by date"
+End:
+@end example
+into a @file{.dired} file of a directory to sort by date only in that
+directory.  Note that since @code{dired-hack-local-variables} is run
+inside @code{dired-mode-hook} the modeline has already been set, so you
+have to update that for yourself by setting @code{dired-sort-mode} in
+addition to changing the switches.
+@node Making Relative Symbolic Links in Dired, Letting Dired Guess What Shell Command to Apply, Dired Local Variables, Tree Dired Extra
+@section Making Relative Symbolic Links in Dired
+In GNU Emacs version 18, the built-in function @code{make-symbolic-link}
+always calls @code{expand-file-name} on its arguments, so relative
+symlinks (e.g.  @samp{foo -> ../bar/foo}) are impossible to create.
+Dired Extra uses @code{call-process} and @samp{ln -s} for a workaround.
+@table @code
+@item dired-make-symbolic-link
+@findex dired-make-symbolic-link
+Arguments @var{name1} @var{name2} and optional
+@var{ok-if-already-exists}.  Create file @var{name2}, a symbolic link
+pointing to @var{name1} (which may be any string whatsoever and is
+passed untouched to @samp{ln -s}).  @var{ok-if-already-exists} means that
+@var{name2} will be overwritten if it already exists.  If it is an
+integer, user will be asked about this.  On error, signals a file-error.
+@item dired-make-relative-symlink
+@findex dired-make-relative-symlink
+Three arguments: @var{file1} @var{file2} and optional
+@var{ok-if-already-exists}.  Make a symbolic link @var{file2} (pointing
+to @var{file1}).  The link is relative (if possible), for example
+@example
+(dired-make-relative-symlink "/vol/tex/bin/foo"
+"/vol/local/bin/foo")
+@end example
+@noindent
+results in a link
+@example
+/vol/local/bin/foo -> ../../tex/bin/foo
+@end example
+@item dired-do-relsymlink
+@findex dired-do-relsymlink
+(binding @kbd{S}) Symbolically link all marked (or next @var{N}) files
+into a directory, or make a symbolic link to the current file.  This
+creates relative symbolic links like
+@example
+foo -> ../bar/foo
+@end example
+@noindent
+not absolute ones like
+@example
+foo -> /ugly/path/that/may/change/any/day/bar/foo
+@end example
+@item dired-do-relsymlink-regexp
+@findex dired-do-relsymlink-regexp
+(@kbd{%S}) Symbolically link all marked files containing @var{regexp} to
+@var{newname}, using relative (not absolute) names.  See functions
+@code{dired-rename-regexp} and @code{dired-do-relsymlink} for more info.
+@end table
+@node Letting Dired Guess What Shell Command to Apply, dired-trns.el, Making Relative Symbolic Links in Dired, Tree Dired Extra
+@section Letting Dired Guess What Shell Command to Apply
+Based upon the name of a filename, Dired tries to guess what shell
+command you might want to apply to it.  For example, if you have point
+on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess
+you want to @samp{tar xvf} it and suggest that as the default shell
+command.
+If you are using the @file{gmhist} package (@xref{Dired Minibuffer
+History}), the default will be mentioned in brackets and you can type
+@kbd{M-p} to get the default into the minibuffer so that you can edit
+it, e.g., changing @samp{tar xvf} to @samp{tar tvf}.  If there are
+several commands for a given file, e.g., @samp{xtex} and @samp{dvips}
+for a @file{.dvi} file, you can type @kbd{M-p} several times to see each
+of the matching commands.
+Dired only tries to guess a command for a single file, never for a list
+of marked files.
+@table @code
+@item dired-auto-shell-command-alist-default
+@vindex dired-auto-shell-command-alist-default
+Predefined rules for shell commands.  Set this to nil to turn guessing off.
+The elements of @code{dired-auto-shell-command-alist} (defined by the
+user) will override these rules.@refill
+@item dired-auto-shell-command-alist
+@vindex dired-auto-shell-command-alist
+If non-nil, an alist of file regexps and their suggested commands
+overriding the predefined rules in
+@code{dired-auto-shell-command-alist-default}.@refill
+Each element of the alist looks like
+@example
+(@var{regexp} @var{command}@dots{})
+@end example
+where each @var{command} can either be a string or a lisp expression
+that evaluates to a string.  If several @var{COMMAND}s are given, all
+will temporarily be pushed on the history.
+These rules take precedence over the predefined rules in the variable
+@code{dired-auto-shell-command-alist-default} (to which they are
+prepended when @file{dired-x} is loaded).
+You can set this variable in your @file{~/.emacs}.  For example,
+to add rules for @samp{.foo} and @samp{.bar} file extensions, write
+@example
+(setq dired-auto-shell-command-alist
+(list
+(list "\\.foo$" "@var{foo-command}");; fixed rule
+;; possibly more rules...
+(list "\\.bar$";; rule with condition test
+'(if @var{condition}
+"@var{bar-command-1}"
+"@var{bar-command-2}"))))
+@end example
+@noindent
+This will override any predefined rules for the same extensions.
+@item dired-guess-have-gnutar
+@vindex dired-guess-have-gnutar
+Default: @code{nil}
+If non-nil, name of the GNU tar executable (e.g., @samp{"tar"} or
+@samp{"gnutar"}).  GNU tar's @samp{z} switch is used for compressed tar
+files.  If you don't have GNU tar, set this to nil: a pipe using
+@samp{zcat} is then used.
+@end table
+@node dired-trns.el, dired-cd.el, Letting Dired Guess What Shell Command to Apply, Tree Dired Extra
+@section Filename Transformers for Dired Shell Commands
+@cindex Transformer
+@cindex Basename of a file, how to use in Dired shell commands
+@cindex Extension of a file, how to use in Dired shell commands
+File name @dfn{transformers} are functions that take a filename (a string)
+as an argument and transform it into some other string (e.g., a filename
+without an extension).  This package makes transformers available in
+Dired shell commands.
+For example, running the Dired shell command (type @kbd{!} or @kbd{M-x}
+@code{dired-do-shell-command})@refill
+@example
+echo * [b] [db]
+@end example
+would list the full name, the basename, and the absolute basename of
+each marked file.
+Each transformer is associated with a dispatch character. The associations
+are stored in a keymap for fast and easy lookup. The dispatch character
+is used to activate the associated transformer function at a particular
+position in a shell command issued in Dired.  The dispatch character
+must be enclosed in brackets to distinguish it from normal letters.
+To take advantage of this package, simply load it after loading Dired,
+e.g., in your @code{dired-load-hook}.  You can then use transformers like
+"[b]" for the basename in your Dired shell commands (see below).
+You can define your own transformers using the macro @code{dired-trans-define}.
+@table @code
+@item dired-trans-define
+@findex dired-trans-define
+Macro that assigns the transformer function @code{(lambda (file)
+@var{body})} to @var{char} (a character or string).  @var{body} must
+return a string: the transformed file.
+@end table
+Several transformers are predefined:
+@table @samp
+@item *
+returns the unmodified filename (equivalent to @samp{[dbe]}).
+@item n
+returns the Name component of a filename without directory information
+@item d
+returns the Directory component of a filename
+@item b
+returns the Basename of a filename, i.e., the name of the file without
+directory and extension (see variable @code{dired-trans-re-ext})
+A basename with directory component can be obtained by @samp{[db]}.
+@item e
+returns the Extension of a filename (i.e., whatever
+@code{dired-trans-re-ext} splits off)
+@item v
+returns a file without directory and without @file{,v} suffixes if any.
+@item z
+returns a file without directory and without @file{.Z} suffixes if any.
+@end table
+@noindent
+The following variables can be used to customize @file{dired-trns.el}:
+@table @code
+@item dired-trans-re-ext
+@vindex dired-trans-re-ext
+Default: @code{"\\.[^.]*\\(\\.Z\\)?$"}
+The part of a filename matching this regexp will be viewed as extension.
+@item dired-trans-starters
+@vindex dired-trans-starters
+Default: @code{"[#[]"}
+User definable set of characters to be used to indicate the start of a
+transformer sequence.
+@item dired-trans-enders
+@vindex dired-trans-enders
+Default: @code{"[]# ]"}
+User definable set of characters to be used to indicate the end of a
+transformer sequence.
+@end table
+@node dired-cd.el, dired-nstd.el, dired-trns.el, Tree Dired Extra
+@section Changing the Working Directory for Dired Shell Commands
+The package @file{dired-cd.el} permits the working directory of the
+Dired shell commands @kbd{!} (@code{dired-do-shell-command}) and @kbd{&}
+(@code{dired-do-background-shell-command}) to be the files' subdirectory
+under certain circumstances.  Loading this extension does not change the
+behavior of Dired until the variables @code{dired-cd-same-subdir} and/or
+@code{dired-cd-on-each} are non-nil.
+@vindex dired-cd-same-subdir
+If @code{dired-cd-same-subdir} is non-nil and if all the selected files
+(marked, non-zero numeric argument, etc.) are in the same subdirectory,
+then @code{dired-do-shell-command} and
+@code{dired-do-background-shell-command} cause the shell to perform a
+@samp{cd} into that directory before the commands are executed.  Also,
+the selected filenames are provided to the command without any directory
+components.
+@vindex dired-cd-on-each
+If @code{dired-cd-on-each} is non-nil and if the @samp{on-each} option
+is specified (numeric argument of zero), then @kbd{!}
+(@code{dired-do-shell-command}) and @kbd{&}
+(@code{dired-mark-background-shell-command}) use a subshell to perform a
+@samp{cd} into the subdirectory of each file before the commands on that
+file are executed.  Also, each filename is provided to the command
+without any directory components.  Note that this behavior occurs
+regardless of whether the files are all in the same directory or not.
+After the above @samp{cd} wrapping has occured, the existing
+@code{dired-shell-stuff-it} is used to do the actual file-name quoting
+and substitution into the command.  Thus, custom versions of this
+procedure should work, e.g., the @samp{dired-trans} package will transform
+commands correctly.  However, since filenames lack any directory
+components, features that use the directory components will fail, e.g.
+the @samp{[d]} transform specifier will be empty.
+To use this package, load it in your @code{dired-load-hook}.  Do
+@example
+(setq dired-cd-same-subdir t)
+@end example
+@noindent
+and perhaps
+@example
+(setq dired-cd-on-each t)
+@end example
+@noindent
+in your @file{~/.emacs}.  By default, @code{dired-cd} doesn't change the
+behavior of Dired when it is loaded.
+@vindex dired-cd-same-subdir
+If @code{dired-cd-same-subdir} is non-nil, then the shell commands
+@samp{cd} to the appropriate directory if all the selected files are in
+that directory; however, on-each behavior (with zero prefix argument) is
+not changed.
+@vindex dired-cd-on-each
+If @code{dired-cd-on-each} is non-nil, then each instance of the command
+for an on-each shell command runs in the file's directory regardless of
+whether the files are all in the same directory.
+@node dired-nstd.el, find-dired.el, dired-cd.el, Tree Dired Extra
+@section Nested Dired format
+[NO DOCUMENTATION YET]
+This is still buggy, @xref{Dired Known Problems}.
+@node find-dired.el,  , dired-nstd.el, Tree Dired Extra
+@section Feeding Find Output to Dired
+@cindex Find and Dired
+The @code{find-dired} command runs the @samp{find} command in a buffer
+and starts Dired on the inserted file lines, even while @samp{find} is
+still running.  For example, with @samp{-type d} as argument, you will
+get a Dired buffer that contains all subdirectories of a given
+directory, but none of the other files.
+Note that @samp{find} just gives you file lines, not inserted
+subdirectories with associated headerlines as repeated use of the
+@kbd{i} (@code{dired-maybe-insert-subdir}) command would.  Also, the
+names contain slashes if they are in a subdirectory, which never occurs
+in a normal Dired buffer.  Dired understands these names anyway and you
+can for example type @kbd{f} on such lines as usual.  However, while
+@samp{find} is still running you shouldn't type @kbd{i} to insert
+subdirectories, since new @samp{find} output is always appended at the
+end.  Use @kbd{f} or @kbd{o} instead to dired the specific subdirectory
+in a new Dired buffer.  After @samp{find} has finished (as indicated by
+a message and the modeline) all Dired commands work as usual.
+@table @code
+@item find-dired
+@findex find-dired
+Run @samp{find} on a directory @var{dir}, with find arguments
+@var{args}, and go into dired-mode on a buffer of the output.  The
+command run (after changing into @var{dir}) is
+@example
+find . \( @var{args} \) -ls
+@end example
+@item find-name-dired
+@findex find-name-dired
+Search @var{dir} recursively for files matching the globbing pattern
+@var{pattern}, and run Dired on those files.  @var{pattern} is a shell
+wildcard (not an Emacs regexp) and need not be quoted.  The command
+run (after changing into @var{dir}) is
+@example
+find . -name '@var{pattern}' -ls
+@end example
+@item find-grep-dired
+@findex find-grep-dired
+Find files in directory @var{dir} containing a regexp @var{arg} and
+start Dired on output.  The command run (after changing into @var{dir})
+is
+@example
+find . -exec grep -s @var{arg} @{@} \; -ls
+@end example
+@end table
+@node Dired Internals, Dired Known Problems, Tree Dired Extra, Top
+@appendix Dired Internals
+This is a short introduction about how Dired's Tree and Mark features
+work.  You are encouraged to read the code (@file{dired.el}) for more
+information.
+@menu
+* Tree Dired Internals::
+* Dired Mark Internals::
+@end menu
+@node Tree Dired Internals, Dired Mark Internals, Dired Internals, Dired Internals
+@section Tree Dired Internals
+@cindex Internals of Tree Dired
+@cindex Tree Dired Internals
+@vindex dired-subdir-alist
+@vindex default-directory
+In Tree Dired, instead of just one directory, all or part of the
+directory @emph{tree} starting at the top level directory (the working
+directory or @code{default-directory} of the buffer) may be in a
+Dired buffer.  Each file line belongs to exactly one of those
+subdirectories.  After the @code{ls} program has inserted its output,
+Dired parses the buffer once to find out where the subdirectory
+boundaries are and saves them in the variable @code{dired-subdir-alist}.
+The beginning of the headerline inserted by @code{ls} serves as boundary
+between subdirectories.
+@kindex i
+@findex dired-maybe-insert-subdir
+Subsequent @kbd{i} (@code{dired-maybe-insert-subdir}) commands update this
+alist and insert the appropriate headerline.  Each retrieval of the
+filename on the current line first extracts the basename (assuming a
+more or less standard @code{ls} output format), and then function
+@code{dired-current-directory} looks up the current Dired directory in
+@code{dired-subdir-alist}.  The lookup is keyed on buffer position, as
+each buffer position is between exactly two subdirectory boundaries.  (The end
+of the buffer serves as an implicit subdirectory boundary.)
+@table @code
+@item dired-subdir-alist
+@vindex dired-subdir-alist
+Association list of subdirectories and their buffer positions:
+@example
+((@var{lastdir} . @var{lastmarker}) @dots{} (@var{default-directory} . @var{firstmarker})).
+@end example
+The markers point right before the beginning of the line, so that they
+separate subdirectories adjacent in the buffer.  The directories must be
+in the form returned by @code{file-name-as-directory}.
+@item dired-subdir-regexp
+@vindex dired-subdir-regexp
+Value: "^. \\([^ \n\r]+\\)\\(:\\)[\n\r]"
+Regexp matching a maybe hidden subdirectory line in @samp{ls -lR}
+output.  Subexpression 1 is subdirectory proper, no trailing colon.  The
+match starts at the beginning of the line and ends after the end of the
+line (@samp{\n} or @samp{\r}).  Subexpression 2 must end right before
+the @samp{\n} or @code{\r}.  This is so that Dired can easily check
+whether a subdirectory is hidden or not: hidden lines end with @samp{\r}
+(@kbd{C-m}) instead of a newline.
+This regexp used to be @code{"^. \\(/[^\n\r]*\\)\\(:\\)[\n\r]"},
+allowing spaces, but disallowing relative filenames (which occur when
+browsing ls -lR listing in virtual Dired mode, so I changed it).
+Note that @code{"^. \\([^\n\r]+\\)\\(:\\)[\n\r]"} (desirable since it
+allows both spaces and relative names) will not always work: if you have
+a file that ends in a colon, its whole line (including permission bits,
+date etc.) would be mistaken for a subdirectory headerline when parsing
+@samp{ls -lR} output.
+@code{dired-subdir-regexp} is only relevant for parsing @samp{ls -lR}
+output.  If Dired inserts subdirectories itself (using
+@code{dired-insert-subdir}), they will always be absolute and there is
+no restriction on the format of filenames, e.g., they can contain
+spaces.
+@end table
+@node Dired Mark Internals,  , Tree Dired Internals, Dired Internals
+@section Dired Mark Internals
+This is a short overview about how marking files and retrieving marked
+files in Dired works.
+@cindex Internal of Dired file marking
+@cindex Dired file marking internals
+@cindex File marking internals in Dired
+@cindex Marking files in Dired, internals of
+@code{ls} output is indented two spaces two make room for an optional
+marker character in front of each file line.  Marking simply replaces the
+first space with the marker character, usually @code{*} or, for
+deletions, @code{D}.  Indenting just by one would leave the markers
+adjacent to the permission bits.
+@table @code
+@item dired-mark-if
+@findex dired-mark-if
+The macro @code{dired-mark-if} is used internally to mark files matching
+certain criteria. It takes two arguments, the @var{predicate}, a lisp
+expression evaluating non-nil on file lines to be marked, and @var{msg},
+a message to be displayed while scanning the buffer.  @var{msg} may be
+nil to suppress the message.
+@findex dired-mark-map
+@item dired-mark-map
+To operate on the marked files, all internal Dired functions ultimately
+call the macro @code{dired-mark-map}.  It takes two arguments,
+@var{body} and @var{arg}, plus an optional argument @var{show-progress}:
+Perform @var{body} with point somewhere on each marked line (inside a
+@code{save-excursion}) and return a list of @var{body}'s results.  If no
+marked file could be found, execute @var{body} on the current line.
+If @var{arg} is an integer, use the next @var{arg} (or previous
+-@var{arg}, if @var{arg}<0) files instead of the marked files.  In that
+case point is dragged along.  This is so that commands on the next ARG
+(instead of the marked) files can be chained easily.  Note that for
+positive ARG point is left on the first file not operated upon, for
+negative on the last file operated upon
+If @var{arg} is otherwise non-nil, use current file instead.
+If optional third argument @var{show-progress} evaluates to non-nil, we
+redisplay the Dired buffer after each file is processed.  No guarantee
+is made about the position on the marked line.  @var{body} must ensure
+this itself if it depends on this.  Search starts at the beginning of
+the buffer, thus the @code{car} of the list corresponds to the line nearest to
+the buffer's bottom.  This is also true for (positive and negative)
+integer values of @var{arg}.  The @var{body} should not be too long as
+it is expanded four times.@refill
+@c This warning should no longer apply. sk  6-Sep-1991 16:28
+@c Warning: @var{body} must not add new lines before point - this may cause
+@c an endless loop.
+@end table
+@noindent
+A common case is to retrieve the names of all marked files:
+@table @code
+@findex dired-mark-get-files
+@item dired-mark-get-files
+Return the marked files as list of strings.  The list is in the same
+order as the buffer, that is, the car is the first marked file.  Values
+returned are normally absolute pathnames.  Optional argument @var{localp}
+equal to @code{no-dir} means return the filename proper only, with no
+directory information; any other non-nil value means make them relative
+to default-directory.  Optional second argument @var{arg} forces use of
+other files.  If @var{arg} is an integer, use the next @var{arg} files.
+If @var{arg} is otherwise non-nil, use the current file.
+@end table
+@node Dired Known Problems, Dired Variable Index, Dired Internals, Top
+@appendix Known Problems with Dired
+There are some problems with Dired that are either not Dired's fault,
+hard to fix or not worth fixing.
+@itemize @bullet
+@item
+Renaming directories usually works fine (all affected Dired and file
+buffers are updated), but moving a directory between different
+filesystems (those on different hard disks or different partitions) does
+not work: it creates a plain target file containing the contents of the
+original directory (inodes and filenames) or fails completely.
+Unfortunately Emacs' builtin function @code{rename-file} does not give
+you a clear error message like @samp{cross-device link attempted}, but
+rather a spurious @code{(file-error "Removing old name" "not owner")},
+at least in Emacs 18.55.
+On some systems renaming a directory always fails (even within
+the same filesystem) with the spurious @samp{not owner} error.
+@c This was reported for HP-UX.
+@c
+@c On one system (IBM Rs6000 running AIX 3.1.3) date lossage was reported,
+@c but this was not reproducible.
+@item
+If @file{foo} is a symlink to a non-existing file, @code{(file-exists-p
+"foo")} returns nil.  Thus, Dired will overwite such (strange) kinds of
+symlinks without noticing.
+Dired could test both @code{file-symlink-p} and @code{file-exists-p},
+but this would slow down all file operations to catch a very rare case.
+@item
+Copying a directory does not work - it results in a zero-length
+target file.
+This comes from Emacs' @code{copy-file} function, not from Dired.
+If you really want to copy a directory (recursively), use `!' and
+your favorite shell command to do it (e.g. cp -R or cp -r).
+@item
+Initial spaces in a filename are not recognized.  If I could be sure
+that all @samp{ls} programs insert exactly one space between the time and
+the filename, I could easily fix this.  But @samp{ls} programs tend to vary
+in their amount of white space, and even with one @samp{ls} program there
+is a difference between year and clocktime formats
+@example
+drwxr-xr-x 2 ab027    thp           512 Aug 13 1990  thp/
+drwxr-xr-x 4 ab027    thp           512 Feb  3 21:59 ./
+@end example
+If your @samp{ls} supports the @samp{-b} switch and quotes spaces with
+that switch, simply add @samp{b} to your @code{dired-listing-switches}.
+@xref{Listing Files in Dired}.
+Spaces anywhere but at the beginning do work.
+@item
+In general, only commands that may have targets outside of the
+current directory tree update other buffers (copy, move and link
+commands).
+Especially, deletions, (un)compress, chmod/chgrp/chown update only
+the current buffer.
+@item
+Some compress programs make output even if all goes well.  Dired
+takes output as a sign of trouble and assumes that the subprocess
+failed.
+Redefine function @code{dired-check-process-checker} suitably to
+look closer at the generated output.  In Emacs 19, the exit status
+of compress will be checked.
+@item
+Aliases like @samp{rm -i} for @samp{rm} or @samp{ls -F} for @samp{ls}
+can cause problems in Dired's (and Emacs') shell command.  (Aliases for
+@samp{ls} only matter if you dired wildcards, because only then the shell is
+used to run @samp{ls}.)  Csh expands aliases only for interactive shells, which
+is probably what you want.  In Bash, you can achieve this by testing
+@code{PS1} in your @file{~/.bashrc}:
+@example
+# `.bashrc' file
+# this test fails when invoked by rsh
+if [ "$@{PS1-no@}" != "no" ]       # is this an interactive shell?
+then
+	  . ~/.bash_alias          # if so, source aliases
+fi
+@end example
+@item
+Directory names starting with @file{-} (a minus) may lose when they are
+to be created or removed.  If you care about this, and your rmdir
+and mkdir understand about @file{--} meaning end of options, change
+@file{emacs-19.el} accordingly.
+In Emacs 19 the @code{make-directory} and @code{remove-directory}
+operations will be builtin, not implemented with @samp{rmdir} and
+@samp{mkdir} subprocesses.
+@item
+@file{dired-nstd.el}: This is still buggy.  For example, after you've
+compressed the last file it may not correctly return that file's
+absolute pathname (@code{dired-current-directory} erronously returns nil
+because of markers collapsed during redisplay), ultimately leading to
+lisp errors.
+@c Not longer a problem as of dired-version 5.242, sk 28-Jan-1992 11:17.
+@c @item
+@c Symbolic links to directories are sometimes strange.  On System V
+@c derived systems (e.g., DG/UX, AIX/370), after
+@c @example
+@c mkdir dir; ln -s dir link
+@c @end example
+@c both @file{link} and @file{link/} are considered symbolic links by the
+@c @samp{stat(2)} system call, while on BSD derived systems (e.g., Sun OS,
+@c Mach, HP/UX, Ultrix) @file{link/} is considered a directory.  In
+@c general, the BSD behaviour is preferable, at least for Dired.  On the
+@c other systems it is cumbersome to get Dired to dereference those links.
+@item
+The regexp-using @kbd{%}-commands get into an endless loop if you
+specify a regular expression that matches the empty string.
+@item
+Function @code{find-alternate-file} in Emacs 18.57 has a bug that causes
+@kbd{C-x C-v RET} (which usually re-visits the current buffer) to fail
+on Dired buffers.  This is fixed in the version in @file{emacs-19.el},
+automatically loaded by Dired.
+@item
+It is not possible to resort the Dired buffer without reverting it. That
+would be hard to implement (and slow to run) given that ls date format
+would have to be parsed for @samp{ls -t} sorting order.
+@end itemize
+@node     Dired Variable Index, Dired Function Index, Dired Known Problems, Top
+@unnumbered Dired Variable Index
+@printindex vr
+@node     Dired Function Index, Dired Key Index, Dired Variable Index, Top
+@unnumbered Dired Function Index
+@printindex fn
+@node     Dired Key Index, Dired Concept Index, Dired Function Index, Top
+@unnumbered Dired Key Index
+@printindex ky
+@node     Dired Concept Index,  , Dired Key Index, Top
+@unnumbered Dired Concept Index
+@printindex cp
+@c @summarycontents
+@contents
+@bye

Mercurial > hg > xemacs-beta

comparison man/dired.texi @ 0:376386a54a3c r19-14