Mercurial > emacs
diff man/dired-x.texi @ 25829:ac7e9e5e2ccb
#
| author | Dave Love <fx@gnu.org> |
|---|---|
| date | Wed, 29 Sep 1999 15:17:24 +0000 |
| parents | |
| children | 1c8b8c87db6f |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/dired-x.texi Wed Sep 29 15:17:24 1999 +0000 @@ -0,0 +1,1375 @@ +\input texinfo @comment -*-texinfo-*- + +@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs19 +@c +@c Author: Sebastian Kremer <sk@thp.uni-koeln.de> +@c Lawrence R. Dodd <dodd@roebling.poly.edu> +@c Maintainer: Lawrence R. Dodd <dodd@roebling.poly.edu> +@c Version: 2.52 +@c Date: 1994/08/09 16:51:31 +@c Keywords: dired extensions +@c dired-x.el REVISION NUMBER: 2 + +@c State: Released +@c Ident: dired-x.texi,v 2.52 1994/08/09 16:51:31 dodd Released + +@comment %**start of header (This is for running Texinfo on a region.) +@c FOR GNU EMACS USE ../info/dired-x BELOW +@setfilename ../info/dired-x +@c dired-x.el REVISION NUMBER +@settitle Dired Extra Version 2 User's Manual + +@dircategory Editors +@direntry +* Dired-X: (dired-x). Dired Extra Features. +@end direntry + +@iftex +@finalout +@end iftex +@c @setchapternewpage odd % For book style double sided manual. +@comment %**end of header (This is for running Texinfo on a region.) +@c @smallbook +@tex +\overfullrule=0pt +%\global\baselineskip 30pt % For printing in double spaces +@end tex + +@ifinfo +@node Copyright, Top, (dir), (dir) +@comment node-name, next, previous, up +This documents the ``extra'' features for Dired Mode for GNU Emacs 19 found in +the file @file{dired-x.el}. + +Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc. + +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. + +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, 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 this permission notice may be stated +in a translation approved by the Free Software Foundation. + +The file used to create this is called @file{dired-x.texi}, but the +original work that was altered to make that file was called +@file{dired.texi} written by Sebastian Kremer. + +@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 +@end ifinfo + +@c +@titlepage +@sp 6 +@c dired-x.el REVISION NUMBER +@center @titlefont{Dired Extra Version 2} +@sp 2 +@center @titlefont{For The GNU Emacs 19} +@sp 1 +@center @titlefont{Directory Editor} +@sp 4 +@center Manual Revision: 2.52 +@center 1994/08/09 16:51:31 +@sp 5 +@center Lawrence R@. Dodd +@center @t{dodd@@roebling.poly.edu} +@sp 5 +@center (Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>) +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1993, 1994 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. + +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, 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 this permission notice may be stated +in a translation approved by the Free Software Foundation. + +The file used to create this is called @file{dired-x.texi}, but the +original work that was altered to make that file was called +@file{dired.texi} written by Sebastian Kremer. + +@end titlepage + +@page + +@ifinfo + +@node Top, Introduction, Copyright, (dir) +@comment node-name, next, previous, up + +@noindent +This documents the ``extra'' features for Dired Mode for GNU Emacs 19 that are +provided by the file @file{dired-x.el}. + +@itemize @bullet + +@item +Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de> + +@c dired-x.el REVISION NUMBER +@item +For @file{dired-x.el} revision 2 + +@item +Revision of this manual: 2.52 (1994/08/09 16:51:31) + +@item +Bugs to Lawrence R. Dodd <dodd@@roebling.poly.edu>. @emph{Please} type +@kbd{M-x dired-x-submit-report} to submit a bug report (@xref{Bugs}). + +@item +You can obtain a copy of this package via anonymous ftp in +@t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz} + +@end itemize + +@menu +* Introduction:: +* Installation:: +* Omitting Files in Dired:: +* Local Variables:: +* Shell Command Guessing:: +* Virtual Dired:: +* Advanced Mark Commands:: +* Multiple Dired Directories:: +* Find File At Point:: +* Miscellaneous Commands:: +* Bugs:: + +* Concept Index:: +* Command Index:: +* Key Index:: +* Variable Index:: + +@end menu + +@end ifinfo + +@node Introduction, Features, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +This documents the @emph{extra} features for Dired Mode for GNU Emacs 19. It +is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el} and is +GNU Emacs v19 compatible. + +In adopting this @file{dired-x.el} to GNU Emacs v19 some material that has +been incorporated into @file{dired.el} and @file{dired-aux.el} of the GNU Emacs +19 distribution has been removed and some material was modified for agreement +with the functions in @file{dired.el} and @file{dired-aux.el}. For example, +the code using @code{gmhist} history functions was replaced with code using +the mini-buffer history now built into GNU Emacs 19. Finally, a few other +features have been added and a few more functions have been bound to keys. + +Please note that @file{dired-x.el} and this texinfo file @file{dired-x.texi} +are bundled with GNU Emacs versions 19.23 and later. + +@ifinfo +@menu +* Features:: +* Technical Details:: +@end menu +@end ifinfo + +@node Features, Technical Details, Introduction, Introduction +@comment node-name, next, previous, up +@section Features +@cindex Features + +Some features provided by Dired Extra + +@enumerate +@item +Omitting of uninteresting files from dired listing. +@itemize @bullet +@xref{Omitting Files in Dired} +@end itemize +@item +Local variables for dired directories. +@itemize @bullet +@xref{Local Variables} +@end itemize +@item +Guessing shell commands in dired buffers. +@itemize @bullet +@xref{Shell Command Guessing} +@end itemize +@item +Running dired command in non-dired buffers. +@itemize @bullet +@xref{Virtual Dired} +@end itemize +@item +Finding a file mentioned in a buffer +@itemize @bullet +@xref{Find File At Point} +@end itemize +@item +Commands using file marking. +@itemize @bullet +@xref{Advanced Mark Commands} +@end itemize +@end enumerate + +@noindent +@file{dired-x.el} binds some functions to keys in Dired Mode (@xref{Key +Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to +@code{dired-jump} (@xref{Miscellaneous Commands}). It may also bind @kbd{C-x +C-f} and @kbd{C-x 4 C-f} to @code{dired-x-find-file} and +@code{dired-x-find-file-other-window}, respectively (@xref{Find File At +Point}). + +@node Technical Details, Installation, Features, Introduction +@comment node-name, next, previous, up +@section Technical Details +@cindex Redefined functions +@cindex @file{dired-aux.el} + +When loaded this code @emph{redefines} the following functions of GNU Emacs +from @file{dired.el} + +@itemize @bullet +@item +@code{dired-clean-up-after-deletion} +@item +@code{dired-find-buffer-nocreate} +@item +@code{dired-initial-position} +@item +@code{dired-up-directory} +@end itemize + +@noindent +and the following functions from @file{dired-aux.el} + +@itemize @bullet +@item +@code{dired-add-entry} +@item +@code{dired-read-shell-command} +@end itemize + +One drawback is that @file{dired-x.el} will load @file{dired-aux.el} as soon +as dired is loaded. Thus, the advantage of separating out non-essential dired +stuff into @file{dired-aux.el} and only loading when necessary will be lost +when @file{dired-x.el} is used. + +@node Installation, Optional Installation Dired Jump, Technical Details, Top +@comment node-name, next, previous, up +@chapter Installation + +@noindent +This manual describes the dired features provided by the file +@file{dired-x.el}. To take advantage of these features, you must load the +file and (optionally) set some variables. + +@noindent +In your @file{.emacs} file in your home directory, or in the system-wide +initialization file @file{default.el} in the @file{site-lisp} directory, put + +@example +(add-hook 'dired-load-hook + (function (lambda () + (load "dired-x") + ;; Set dired-x global variables here. For example: + ;; (setq dired-guess-shell-gnutar "gtar") + ;; (setq dired-x-hands-off-my-keys nil) + ))) +(add-hook 'dired-mode-hook + (function (lambda () + ;; Set dired-x buffer-local variables here. For example: + ;; (setq dired-omit-files-p t) + ))) +@end example + +@noindent +This will load @file{dired-x.el} when dired is first invoked (for example, +when you first do @kbd{C-x d}). + +@ifinfo +@menu +* Optional Installation Dired Jump:: +* Optional Installation File At Point:: +* Special Notes:: +@end menu +@end ifinfo + +@node Optional Installation Dired Jump, Optional Installation File At Point, Installation, Installation +@comment node-name, next, previous, up +@section Optional Installation Dired Jump + +@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window} + +In order to have @code{dired-jump} and @code{dired-jump-other-window} +(@xref{Miscellaneous Commands}) work @emph{before} @code{dired} and +@code{dired-x} have been properly loaded the user should set-up an autoload +for these functions. In your @file{.emacs} file put + +@example +;;; Autoload `dired-jump' and `dired-jump-other-window'. +;;; We autoload from FILE dired.el. This will then load dired-x.el +;;; and hence define `dired-jump' and `dired-jump-other-window'. +(define-key global-map "\C-x\C-j" 'dired-jump) +(define-key global-map "\C-x4\C-j" 'dired-jump-other-window) + +(autoload (quote dired-jump) "dired" "\ +Jump to dired buffer corresponding to current buffer. +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." t nil) + +(autoload (quote dired-jump-other-window) "dired" "\ +Like \\[dired-jump] (dired-jump) but in other window." t nil) +@end example + +Note that in recent releases of GNU Emacs 19 (i.e., 19.25 or later) the file +@file{../lisp/loaddefs.el} of the Emacs distribution already contains the +proper auto-loading for @code{dired-jump} so you need only put + +@example +(define-key global-map "\C-x\C-j" 'dired-jump) +@end example + +@noindent in your @file{.emacs} file in order to have @kbd{C-x C-j} work +before @code{dired} is loaded. + +@node Optional Installation File At Point, Special Notes, Optional Installation Dired Jump, Installation +@comment node-name, next, previous, up +@section Optional Installation File At Point + +@cindex Binding @code{dired-x-find-file} +If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over +@code{find-file} (@xref{Find File At Point}), then you will need to set +@code{dired-x-hands-off-my-keys} and make a call to the function +@code{dired-x-bind-find-file} in the @code{dired-load-hook}: + +@example +(add-hook 'dired-load-hook + (function (lambda () + (load "dired-x") + ;; Bind dired-x-find-file. + (setq dired-x-hands-off-my-keys nil) + ;; Make sure our binding preference is invoked. + (dired-x-bind-find-file) + ))) +@end example + +Alternatively, you can set the variable @emph{before} @file{dired-x.el} is +loaded + +@example +(add-hook 'dired-load-hook + (function (lambda () + ;; Bind dired-x-find-file. + (setq dired-x-hands-off-my-keys nil) + (load "dired-x") + ))) +@end example + +@node Special Notes, Omitting Files in Dired, Optional Installation File At Point, Installation +@comment node-name, next, previous, up +@section Special Notes + +If @file{dired-x.el} was @emph{not} bundled with the version of GNU Emacs +installed at your site (i.e., not in the default @file{../lisp} directory) +then you must put the file @file{dired-x.el} in a directory known to GNU +Emacs. Examine the variable @code{load-path} for a list of these directories. +If you wish to add a new directory on this list of directories use something +like this in your @file{.emacs} file + +@example +;;; LOAD PATH +(setq load-path (append + load-path ; default at top + (list + "/the/directory/where/you/put/dired-x"))) +@end example + +@noindent If you wish to put the new directory at the head of the list (where +it will be found first) then you should use instead + +@example +;;; LOAD PATH +(setq load-path (append + (list + "/the/directory/where/you/put/dired-x") + load-path)) ; default at bottom +@end example + +You must also byte compile the file (for example, hitting @kbd{B} in +@code{dired-mode}). When byte-compiling @file{dired-x.el} you may get +messages about functions @code{vm-visit-folder}, @code{Man-notify-when-ready}, +and @code{reporter-submit-bug-report} not being defined. These are warnings +and should be ignored. + +@noindent CAUTION: If you are using a version of GNU Emacs earlier than 19.20 +than you may have to edit @file{dired.el}. The copy of @file{dired.el} in GNU +Emacs versions earlier than 19.20 incorrectly had the call to @code{run-hooks} +@emph{before} the call to @code{provide}. In such a case, it is possible that +byte-compiling and/or loading dired can cause an infinite loop. To prevent +this, make sure the line of code + +@example + (run-hooks 'dired-load-hook) +@end example + +@noindent is the @emph{last} executable line in the file @file{dired.el}. +That is, make sure it comes @emph{after} the line + +@example + (provide 'dired) +@end example + +@node Omitting Files in Dired, Omitting Variables, Special Notes, Top +@comment node-name, next, previous, up +@chapter 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. 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 + +@noindent +In order to make Dired Omit work you first need to load @file{dired-x.el} +inside @code{dired-load-hook} (@xref{Installation}) and then set +@code{dired-omit-files-p} in some way (@xref{Omitting Variables}). + +@ifinfo +@menu +* Omitting Variables:: +* Omitting Examples:: +* Omitting Technical:: +@end menu +@end ifinfo + +@node Omitting Variables, Omitting Examples, Omitting Files in Dired, Omitting Files in Dired +@comment node-name, next, previous, up + +@section Omitting Variables + +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-@code{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. Put + +@example +(setq dired-omit-files-p t) +@end example + +inside your @code{dired-mode-hook} to have omitting initially turned on in +@emph{every} Dired buffer (@xref{Installation}). You can then use @kbd{M-o} to +unomit in that buffer. + +To enable omitting automatically only in certain directories one can use Dired +Local Variables and put + +@example +Local Variables: +dired-omit-files-p: t +End: +@end example + +@noindent +into a file @file{.dired} (the default value of +@code{dired-local-variables-file}) in that directory (@xref{Local Variables}). + +@table @code +@findex dired-omit-here-always +@item dired-omit-here-always + +This is an interactive function that creates a local variables file exactly +like the example above (if it does not already exist) in the file +@code{dired-local-variables-file} in the current directory and then refreshes +the directory listing (@xref{Local Variables}). +@end table + +@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 ``.'') (@xref{Omitting Examples}). + +@vindex dired-omit-extensions +@item dired-omit-extensions + +Default: The elements of @code{completion-ignored-extensions} (as defined in +the file @file{loaddefs.el} of the GNU Emacs distribution), +@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions} +and @code{dired-texinfo-unclean-extensions}. + +If non-@code{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 +@cindex Omitting additional files +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. 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 +@kbd{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 + +@node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired +@comment node-name, next, previous, up +@section Examples of Omitting Various File Types + +@itemize @bullet + +@item +@cindex RCS files, how to omit them in Dired +@cindex Omitting RCS files in Dired +If you wish to avoid seeing RCS files and the RCS directory, then put + +@example +(setq dired-omit-files + (concat dired-omit-files "\\|^RCS$\\|,v$")) +@end example +@noindent +in the @code{dired-load-hook} (@xref{Installation}). 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. + +@item +@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, then put + +@example +(setq dired-omit-files + (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$")) +@end example + +@noindent +in the @code{dired-load-hook} (@xref{Installation}). + +@item +@cindex Dot files, how to omit them in Dired +@cindex Omitting dot files in Dired +If you do not wish to see @samp{dot} files (files starting with a @samp{.}), +then put + +@example +(setq dired-omit-files + (concat dired-omit-files "\\|^\\..+$")) +@end example + +@noindent +in the @code{dired-load-hook} (@xref{Installation}). + +@end itemize + +@node Omitting Technical, Local Variables, Omitting Examples, Omitting Files in Dired +@comment node-name, next, previous, up +@section Some Technical Details of Omitting + +Loading @file{dired-x.el} will install Dired Omit by putting +@code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will +call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} +in your @code{dired-mode-hook}. + +@node Local Variables, Shell Command Guessing, Omitting Technical, Top +@comment node-name, next, previous, up +@chapter Local Variables for Dired Directories + +@cindex Local Variables for Dired Directories +@vindex dired-local-variables-file +@vindex dired-enable-local-variables +@noindent +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}. + +@noindent +For example, if the user puts + +@example +Local Variables: +dired-actual-switches: "-lat" +dired-omit-files-p: t +End: +@end example + +@noindent +into a file called @file{.dired} in a directory then when that directory is +viewed it will be + +@enumerate +@item +sorted by date +@item +omitted automatically +@end enumerate + +@noindent +You can set @code{dired-local-variables-file} to @code{nil} to suppress this. +The value of @code{dired-enable-local-variables} controls if and how these +local variables are read. This variable exists so that if may override the +default value of @code{enable-local-variables}. + +@noindent +Please see the GNU Emacs Manual to learn more about local variables. +@xref{File Variables,Local Variables in Files,Local Variables in +Files,emacs,The GNU Emacs Manual}. + +@noindent +The following variables affect Dired Local Variables + +@table @code +@vindex dired-local-variables-file +@item dired-local-variables-file +Default: @code{".dired"} + +If non-@code{nil}, filename for local variables for Dired. If Dired finds a +file with that name in the current directory, it will temporarily insert it +into the dired buffer and run `hack-local-variables'. + +@vindex dired-enable-local-variables +@item dired-enable-local-variables +Default: @code{t} + +Controls use of local-variables lists in dired. The value can be @code{t}, +@code{nil}, or something else. A value of @code{t} means local-variables +lists are obeyed in the @code{dired-local-variables-file}; @code{nil} means +they are ignored; anything else means query. This variable temporarily +overrides the value of @code{enable-local-variables} when the Dired Local +Variables are hacked. +@end table + +@node Shell Command Guessing, Virtual Dired, Local Variables, Top +@comment node-name, next, previous, up +@chapter Shell Command Guessing +@cindex Guessing shell commands for files. + +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. + +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-guess-shell-alist-default +@vindex dired-guess-shell-alist-default +Predefined rules for shell commands. Set this to @code{nil} to turn guessing off. +The elements of @code{dired-guess-shell-alist-user} (defined by the +user) will override these rules.@refill + +@item dired-guess-shell-alist-user +@vindex dired-guess-shell-alist-user +If non-@code{nil}, a user-defined alist of file regexps and their suggested +commands. These rules take precedence over the predefined rules in the +variable @code{dired-guess-shell-alist-default} (to which they are prepended) +when @code{dired-do-shell-command} is run). +@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. + +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-guess-shell-alist-user + (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-shell-gnutar +@vindex dired-guess-shell-gnutar +@cindex Passing GNU tar its `z' switch. +Default: @code{nil} + +If non-@code{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 @code{nil}: a pipe using @samp{zcat} is +then used. + +@item dired-guess-shell-gzip-quiet +@vindex dired-guess-shell-gzip-quiet +@cindex GNU zip. +Default: @code{t} + +A non-@code{nil} value means that @code{-q} is passed to gzip overriding a +verbose GNU zip's @samp{GZIP} environment variable. + +@item dired-guess-shell-znew-switches nil +@vindex dired-guess-shell-znew-switches nil +@cindex GNU zip. +Default: @code{nil} + +A string of switches passed to GNU zip's @file{znew}. An example is +@samp{"-K"} which will make @file{znew} keep a .Z file when it is smaller than +the .gz file. + +@item dired-shell-command-history nil +@vindex dired-shell-command-history nil + +History list for commands that read dired-shell commands. +@end table + +@node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top +@comment node-name, next, previous, up +@chapter 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 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 edit all +@file{*.dired} files automatically 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 Advanced Mark Commands, Advanced Cleaning Functions, Virtual Dired, Top +@comment node-name, next, previous, up +@chapter Advanced Mark Commands + +@table @kbd +@item F +@kindex F +@cindex Visiting several files at once +@cindex Simultaneous visiting of several files +@findex dired-do-find-marked-files +(@code{dired-do-find-marked-files}) Find all marked files at once displaying +simultaneously. If optional NOSELECT is non-@code{nil} then just find the +files but do not select. 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 marked, as evenly as possible. +Remaining lines go to the bottom-most 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. +@end table + +@ifinfo +@menu +* Advanced Cleaning Functions:: +* Advanced Cleaning Variables:: +* Special Marking Function:: +@end menu +@end ifinfo + +@node Advanced Cleaning Functions, Advanced Cleaning Variables, Advanced Mark Commands, Advanced Mark Commands +@comment node-name, next, previous, up + +@section Advanced Cleaning Functions + +@table @code +@item dired-clean-patch +@findex dired-clean-patch +Flag dispensable files created by the @samp{patch} program for deletion. See +variable @code{dired-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 the following variables (@xref{Advanced Cleaning Variables}) + +@itemize @bullet +@item +@code{dired-tex-unclean-extensions} +@item +@code{dired-texinfo-unclean-extensions} +@item +@code{dired-latex-unclean-extensions} +@item +@code{dired-bibtex-unclean-extensions} +@end itemize + +@item dired-very-clean-tex +@findex dired-very-clean-tex +Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, and ".dvi" +files for deletion. +@end table + +@node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands +@comment node-name, next, previous, up + +@section Advanced Cleaning Variables + +@noindent Variables used by the above cleaning commands (and in the default value for +variable @code{dired-omit-extensions}, @xref{Omitting Variables}) + +@table @code +@item dired-patch-unclean-extensions +@vindex dired-patch-unclean-extensions +Default: @code{'(".rej" ".orig")} + +List of extensions of dispensable files created by the @samp{patch} program. + +@item dired-tex-unclean-extensions +@vindex dired-tex-unclean-extensions +Default: @code{'(".toc" ".log" ".aux")} + +List of extensions of dispensable files created by @TeX{}. + +@item dired-texinfo-unclean-extensions +@vindex dired-texinfo-unclean-extensions +Default: @code{'(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"} +@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")} + +List of extensions of dispensable files created by @samp{texinfo}. + +@item dired-latex-unclean-extensions +@vindex dired-latex-unclean-extensions +Default: @code{'(".idx" ".lof" ".lot" ".glo")} + +List of extensions of dispensable files created by La@TeX{}. + +@item dired-bibtex-unclean-extensions +@vindex dired-bibtex-unclean-extensions +Default: @code{'(".blg" ".bbl")} + +List of extensions of dispensable files created by Bib@TeX{}. +@end table + +@node Special Marking Function, Multiple Dired Directories, Advanced Cleaning Variables, Advanced Mark Commands +@comment node-name, next, previous, up + +@section Special Marking Function + +@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-@code{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. + +@end table + +@node Multiple Dired Directories, Find File At Point, Special Marking Function, Top +@comment node-name, next, previous, up +@chapter 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 + +@node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top +@comment node-name, next, previous, up + +@section Find File At Point +@cindex Visiting a file mentioned in a buffer +@cindex Finding a file at point + +@file{dired-x} provides a method of visiting or editing a file mentioned in +the buffer you are viewing (e.g., a mail buffer, a news article, a README +file, etc.) or to test if that file exists. You can then modify this in the +minibuffer after snatching the filename. + +When installed @file{dired-x} will substitute @code{dired-x-find-file} for +@code{find-file} (normally bound to @kbd{C-x C-f}) and +@code{dired-x-find-file-other-window} for @code{find-file-other-window} +(normally bound to @kbd{C-x 4 C-f}). + +In order to use this feature, you will need to set +@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} +(@xref{Optional Installation File At Point}). + +@table @code +@item dired-x-find-file +@findex dired-x-find-file +@kindex C-x C-f + +@code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound +to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which +case it will use the filename at point as a guess for the file to visit. + +For example, if the buffer you were reading contained the words + +@example +Available via anonymous ftp in + + /roebling.poly.edu:/pub/lisp/crypt++.el.gz +@end example + +then you could move your cursor to the line containing the ftp address and +type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The +minibuffer would read + +@example +Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz +@end example + +with the point after the last @code{/}. If you hit return emacs will visit +the file at that address. This also works with files on your own computer. + +@item dired-x-find-file-other-window +@findex dired-x-find-file-other-window +@kindex C-x 4 C-f + +@code{dired-x-find-file-other-window} behaves exactly like +@code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a +prefix argument is used. See @code{dired-x-find-file} for more information. + +@item dired-x-hands-off-my-keys +@vindex dired-x-hands-off-my-keys +If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind +@code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it +should not bind @code{dired-x-find-file-other-window} over +@code{find-file-other-window}. If you change this variable after +@file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The +default value of this variable is @kbd{t}; by default, the binding is not +done. See @xref{Optional Installation File At Point}. + +@item dired-x-bind-find-file +@findex dired-x-bind-find-file +A function, which can be called interactively or in your @file{~/.emacs} file, +that uses the value of @code{dired-x-hands-off-my-keys} to determine if +@code{dired-x-find-file} should be bound over @code{find-file} and +@code{dired-x-find-file-other-window} bound over +@code{find-file-other-window}. See @xref{Optional Installation File At Point}. +@end table + +@node Miscellaneous Commands, Bugs, Find File At Point, Top +@comment node-name, next, previous, up +@chapter Miscellaneous Commands + +Miscellaneous features not fitting anywhere else: + +@table @code +@item dired-find-subdir +@vindex dired-find-subdir +Default: @code{nil} + +If non-@code{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 +@item w +@cindex Adding to the kill ring in dired. +@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 the @kbd{M-:} (@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 +@cindex Toggling marks. +@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 + +@table @code +@item dired-smart-shell-command +@findex dired-smart-shell-command +@findex shell-command +@kindex M-! +Like function @code{shell-command}, but in the current Dired directory. +Bound to @kbd{M-!} in Dired buffers. + +@item dired-jump +@findex dired-jump +@kindex C-x C-j +@cindex Jumping to dired listing containing file. +Bound to @kbd{C-x C-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-other-window +@findex dired-jump-other-window +@kindex C-x 4 C-j +Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window. + +These functions can be autoloaded so they work even though @file{dired-x.el} +has not been loaded yet (@xref{Optional Installation Dired Jump}). + +@vindex dired-bind-jump +If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be +bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to +@kbd{C-x 4 C-j}. + +@item dired-vm +@cindex Reading mail. +@kindex V +@findex dired-vm +Bound to @kbd{V} if @code{dired-bind-vm} is t. Run VM on this file (assumed +to be a UNIX mail folder). + +@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. + +@vindex dired-bind-vm +If the variable @code{dired-bind-vm} is t, @code{dired-vm} will be bound to +@kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. + +@item dired-rmail +@cindex Reading mail. +@findex dired-rmail +Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this +file (assumed to be mail folder in Rmail/BABYL format). + +@item dired-info +@kindex I +@cindex Running info. +@findex dired-info +Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info +format). + +@vindex dired-bind-info +If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will +not be bound to I. + +@item dired-man +@cindex Running man. +@kindex N +@findex dired-man +Bound to @kbd{N}. Run man on this file (assumed to be a file in nroff +format). + +@vindex dired-bind-man +If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not +be bound to N. + +@item dired-do-relative-symlink +@cindex Relative symbolic links. +@kindex Y +@findex dired-do-relative-symlink +Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a +directory, or make a relative symbolic link to the current file. This creates +relative symbolic links like + + foo -> ../bar/foo + +not absolute ones like + + foo -> /ugly/path/that/may/change/any/day/bar/foo + +@item dired-do-relative-symlink-regexp +@kindex %Y +@findex dired-do-relative-symlink-regexp +Bound to @kbd{%Y}. Relative symlink all marked files containing REGEXP to +NEWNAME. See functions `dired-do-rename-regexp' and `dired-do-relsymlink' for +more info. +@end table + +@node Bugs, Concept Index, Miscellaneous Commands, Top +@comment node-name, next, previous, up +@chapter Bugs +@cindex Bugs +@findex dired-x-submit-report + +@noindent +If you encounter a bug in this package, wish to suggest an +enhancement, or want to make a smart remark, then type + +@example +@kbd{M-x dired-x-submit-report} +@end example + +@noindent +to set up an outgoing mail buffer, with the proper address to the +@file{dired-x.el} maintainer automatically inserted in the @samp{To:@:} field. +This command also inserts information that the Dired X maintainer can use to +recreate your exact setup, making it easier to verify your bug or social +maladjustment. + +Lawrence R. Dodd <dodd@@roebling.poly.edu> + +@node Concept Index, Command Index, Bugs, Top +@comment node-name, next, previous, up +@unnumbered Concept Index +@printindex cp + +@node Command Index, Key Index, Concept Index, Top +@comment node-name, next, previous, up +@unnumbered Function Index +@printindex fn + +@node Key Index, Variable Index, Command Index, Top +@comment node-name, next, previous, up +@unnumbered Key Index +@printindex ky + +@node Variable Index, , Key Index, Top +@comment node-name, next, previous, up +@unnumbered Variable Index +@printindex vr + +@c @summarycontents +@contents + +@bye +@c dired-x.texi ends here.