X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/8a36c07fc81f0ed28f03a5f014e7b490485036aa..491384001301d37b038f3ee074b13f658d094966:/doc/misc/dired-x.texi diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 9ae569c151..cd1ad79eab 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -7,10 +7,11 @@ @c [Dodd's address no longer valid.] @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 +@settitle Dired Extra User's Manual + +@include emacsver.texi + @iftex @finalout @end iftex @@ -18,7 +19,8 @@ @comment %**end of header (This is for running Texinfo on a region.) @copying -Copyright @copyright{} 1994-1995, 1999, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1994-1995, 1999, 2001-2012 +Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -34,7 +36,7 @@ developing GNU and promoting software freedom.'' @end quotation @end copying -@dircategory Emacs +@dircategory Emacs misc features @direntry * Dired-X: (dired-x). Dired Extra Features. @end direntry @@ -47,8 +49,7 @@ developing GNU and promoting software freedom.'' @titlepage @sp 6 -@c dired-x.el REVISION NUMBER -@center @titlefont{Dired Extra Version 2} +@center @titlefont{Dired Extra} @sp 2 @center @titlefont{For The GNU Emacs} @sp 1 @@ -70,10 +71,9 @@ developing GNU and promoting software freedom.'' @node Top @top Dired Extra -@comment node-name, next, previous, up @noindent -This documents the ``extra'' features for Dired Mode for GNU Emacs that are +This documents the ``extra'' features for GNU Emacs's Dired Mode that are provided by the file @file{dired-x.el}. @itemize @bullet @@ -81,20 +81,8 @@ provided by the file @file{dired-x.el}. @item Based on @file{dired.texi} by Sebastian Kremer -@c dired-x.el REVISION NUMBER @item -For @file{dired-x.el} revision 2 - -@c @item -@c Revision of this manual: 2.53 (2001/02/25 14:05:46) - -@c @item -@c Bugs to Lawrence R. Dodd . @emph{Please} type -@c @kbd{M-x dired-x-submit-report} to submit a bug report (@pxref{Bugs}). - -@c @item -@c You can obtain a copy of this package via anonymous ftp in -@c @t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz} +For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. @end itemize @@ -123,20 +111,12 @@ For @file{dired-x.el} revision 2 @end ifnottex -@node Introduction, Installation, Top, Top -@comment node-name, next, previous, up +@node Introduction @chapter Introduction -This documents the @emph{extra} features for Dired Mode for GNU Emacs. It -is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el}. - -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. Finally, a few other -features have been added and a few more functions have been bound to keys. +This documents some @emph{extra} features for GNU Emacs's Dired Mode +that are provided by @file{dired-x.el} (derived from Sebastian Kremer's +original @file{dired-x.el}). @ifnottex @menu @@ -145,84 +125,55 @@ features have been added and a few more functions have been bound to keys. @end menu @end ifnottex -@node Features, Technical Details, , Introduction -@comment node-name, next, previous, up +@node Features @section Features @cindex Features -Some features provided by Dired Extra +Some features provided by Dired Extra: @enumerate @item -Omitting uninteresting files from Dired listing. -@itemize @bullet -@xref{Omitting Files in Dired}. -@end itemize +Omitting uninteresting files from Dired listing +(@pxref{Omitting Files in Dired}). @item -Local variables for Dired directories. -@itemize @bullet -@xref{Local Variables}. -@end itemize +Guessing shell commands in Dired buffers +(@pxref{Shell Command Guessing}). @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 +Running Dired command in non-Dired buffers +(@pxref{Virtual Dired}). @item Finding a file mentioned in a buffer -@itemize @bullet -@xref{Find File At Point}. -@end itemize +(@pxref{Find File At Point}). @item -Commands using file marking. -@itemize @bullet -@xref{Advanced Mark Commands}. -@end itemize +Commands using file marking +(@pxref{Advanced Mark Commands}). @end enumerate @noindent @file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to -@code{dired-jump} (@pxref{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 (@pxref{Find File At -Point}). +@code{dired-jump} (@pxref{Miscellaneous Commands}). Optionally, it +also binds @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 (@pxref{Find File At Point}). -@node Technical Details, , Features, Introduction -@comment node-name, next, previous, up +@node Technical Details @section Technical Details -@cindex Redefined functions +@cindex Modified 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} -@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 - -@node Installation, Omitting Files in Dired, Introduction, Top -@comment node-name, next, previous, up +When @file{dired-x.el} is loaded, some standard Dired functions from +@file{dired.el} and @file{dired-aux.el} offer additional features. +@code{dired-add-entry} obeys Dired Omit mode (@pxref{Omitting Files in +Dired}), if it is active. @code{dired-find-buffer-nocreate} and +@code{dired-initial-position} respect the value of +@code{dired-find-subdir} (@pxref{Miscellaneous Commands}). +@code{dired-clean-up-after-deletion} respects the value of +@code{dired-clean-up-buffers-too}. @code{dired-read-shell-command} uses +@code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to +offer a smarter default command. + +@node Installation @chapter Installation @noindent @@ -231,8 +182,8 @@ This manual describes the Dired features provided by the file 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 +In your @file{~/.emacs} file, or in the system-wide initialization file +@file{default.el} in the @file{site-lisp} directory, put @example (add-hook 'dired-load-hook @@ -260,70 +211,36 @@ when you first type @kbd{C-x d}). @end menu @end ifnottex -@node Optional Installation Dired Jump, Optional Installation File At Point, , Installation -@comment node-name, next, previous, up +@node Optional Installation Dired Jump @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} (@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and -@code{dired-x} have been properly loaded the user should set-up an autoload +@code{dired-x} have been properly loaded you 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 'dired-jump "dired-x" + "Jump to Dired buffer corresponding to current buffer." t) -(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 +(autoload 'dired-jump-other-window "dired-x" + "Like \\[dired-jump] (dired-jump) but in other window." t) -@example (define-key global-map "\C-x\C-j" 'dired-jump) +(define-key global-map "\C-x4\C-j" 'dired-jump-other-window) @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, , Optional Installation Dired Jump, Installation -@comment node-name, next, previous, up +@node Optional Installation File At Point @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} (@pxref{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 - (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 +@code{dired-x-hands-off-my-keys}. To do this, either set it +@emph{before} @file{dired-x.el} is loaded, or use @kbd{M-x customize-variable}, +or call @code{dired-x-bind-find-file} after changing the value. @example (add-hook 'dired-load-hook @@ -334,8 +251,7 @@ loaded )) @end example -@node Omitting Files in Dired, Local Variables, Installation, Top -@comment node-name, next, previous, up +@node Omitting Files in Dired @chapter Omitting Files in Dired @cindex Omitting Files in Dired @@ -391,9 +307,7 @@ inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate @end menu @end ifnottex -@node Omitting Variables, Omitting Examples, , Omitting Files in Dired -@comment node-name, next, previous, up - +@node Omitting Variables @section Omitting Variables @cindex Customizing file omitting @@ -422,28 +336,17 @@ inside your @code{dired-mode-hook} to have omitting initially turned on in @emph{every} Dired buffer (@pxref{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 +To enable omitting automatically only in certain directories you can add +a directory local setting +(@pxref{Directory Variables,,,emacs,The Gnu Emacs manual}) for Dired mode @example -Local Variables: -dired-omit-mode: t -End: +((dired-mode . ((dired-omit-mode . t)))) @end example @noindent -into a file @file{.dired} (the default value of -@code{dired-local-variables-file}) in that directory (@pxref{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 (@pxref{Local Variables}). -@end table +to a @file{.dir-locals.el} file in that directory. You can use the +command @code{add-dir-local-variable} to do this. @vindex dired-omit-files @item dired-omit-files @@ -500,8 +403,7 @@ 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 +@node Omitting Examples @section Examples of Omitting Various File Types @itemize @bullet @@ -527,7 +429,7 @@ in the @code{dired-load-hook} (@pxref{Installation}). This assumes @cindex Tib files, how to omit them in Dired @cindex Omitting tib files in Dired If you use @code{tib}, the bibliography program for use with @TeX{} and -La@TeX{}, and you +@LaTeX{}, and you want to omit the @file{INDEX} and the @file{*-t.tex} files, then put @example @@ -550,12 +452,13 @@ then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). +in the @code{dired-load-hook} (@pxref{Installation}). (Of course, a +better way to achieve this particular goal is simply to omit @samp{-a} from +@code{dired-listing-switches}.) @end itemize -@node Omitting Technical, , Omitting Examples, Omitting Files in Dired -@comment node-name, next, previous, up +@node Omitting Technical @section Some Technical Details of Omitting Loading @file{dired-x.el} will install Dired Omit by putting @@ -563,18 +466,22 @@ Loading @file{dired-x.el} will install Dired Omit by putting 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 Files in Dired, Top -@comment node-name, next, previous, up +@node Local Variables @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}. +This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs +directory local variables mechanism (@pxref{Directory +Variables,,,emacs,The Gnu Emacs manual}) replaces it. For an example of +the new mechanisms, @pxref{Omitting Variables}. + +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 @@ -600,7 +507,7 @@ omitted automatically @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 +local variables are read. This variable exists so that it may override the default value of @code{enable-local-variables}. @noindent @@ -624,16 +531,13 @@ into the Dired buffer and run @code{hack-local-variables}. @item dired-enable-local-variables Default: @code{t} -Controls the 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. +Controls the use of local-variables lists in Dired. This variable +temporarily overrides the value of @code{enable-local-variables} when +the Dired Local Variables are hacked. It takes the same values as that +variable. A value of @code{nil} means to ignore any Dired Local Variables. @end table -@node Shell Command Guessing, Virtual Dired, Local Variables, Top -@comment node-name, next, previous, up +@node Shell Command Guessing @chapter Shell Command Guessing @cindex Guessing shell commands for files. @@ -739,8 +643,7 @@ smaller than the @file{.gz} file. 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 +@node Virtual Dired @chapter Virtual Dired @cindex Virtual Dired @@ -781,8 +684,7 @@ virtual Dired mode from the @code{auto-mode-alist}. To edit all The regexp is a bit more complicated than usual to exclude @file{.dired} local-variable files. -@node Advanced Mark Commands, Multiple Dired Directories, Virtual Dired, Top -@comment node-name, next, previous, up +@node Advanced Mark Commands @chapter Advanced Mark Commands @table @kbd @@ -828,9 +730,7 @@ Flag all files with a certain extension for deletion. A @samp{.} is @end menu @end ifnottex -@node Advanced Cleaning Functions, Advanced Cleaning Variables, , Advanced Mark Commands -@comment node-name, next, previous, up - +@node Advanced Cleaning Functions @section Advanced Cleaning Functions @table @code @@ -841,7 +741,7 @@ 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 +Flag dispensable files created by @TeX{}, @LaTeX{}, and @samp{texinfo} for deletion. See the following variables (@pxref{Advanced Cleaning Variables}): @itemize @bullet @@ -857,13 +757,11 @@ deletion. See the following variables (@pxref{Advanced Cleaning Variables}): @item dired-very-clean-tex @findex dired-very-clean-tex -Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, +Flag dispensable files created by @TeX{}, @LaTeX{}, @samp{texinfo}, and @file{*.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 - +@node Advanced Cleaning Variables @section Advanced Cleaning Variables @noindent Variables used by the above cleaning commands (and in the default value for @@ -893,7 +791,7 @@ List of extensions of dispensable files created by @samp{texinfo}. @vindex dired-latex-unclean-extensions Default: @code{(".idx" ".lof" ".lot" ".glo")} -List of extensions of dispensable files created by La@TeX{}. +List of extensions of dispensable files created by @LaTeX{}. @item dired-bibtex-unclean-extensions @vindex dired-bibtex-unclean-extensions @@ -902,9 +800,7 @@ Default: @code{(".blg" ".bbl")} List of extensions of dispensable files created by Bib@TeX{}. @end table -@node Special Marking Function, , Advanced Cleaning Variables, Advanced Mark Commands -@comment node-name, next, previous, up - +@node Special Marking Function @section Special Marking Function @table @kbd @@ -960,8 +856,7 @@ to mark all @file{.el} files without a corresponding @file{.elc} file. @end table -@node Multiple Dired Directories, Find File At Point, Advanced Mark Commands, Top -@comment node-name, next, previous, up +@node Multiple Dired Directories @chapter Multiple Dired Directories and Non-Dired Commands @cindex Multiple Dired directories @@ -974,29 +869,15 @@ 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 notion of @code{default-directory}, as a -Lisp expression to evaluate. A resulting value of @code{nil} is ignored -in favor of @code{default-directory}. - -@item dired-default-directory -@findex dired-default-directory -Use this function like you would use the variable -@code{default-directory}, except that @code{dired-default-directory} -also consults the variable @code{default-directory-alist}. -@end table - -@node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top -@comment node-name, next, previous, up +@findex dired-smart-shell-command +@findex shell-command +@kindex M-! +The command @code{dired-smart-shell-command}, bound to @kbd{M-!} in +Dired buffers, is like @code{shell-command}, but it runs with +@code{default-directory} bound to the current Dired directory. -@section Find File At Point +@node Find File At Point +@chapter Find File At Point @cindex Visiting a file mentioned in a buffer @cindex Finding a file at point @@ -1071,8 +952,7 @@ that uses the value of @code{dired-x-hands-off-my-keys} to determine if @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 +@node Miscellaneous Commands @chapter Miscellaneous Commands Miscellaneous features not fitting anywhere else: @@ -1103,12 +983,6 @@ inserted subdirectories. @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 @@ -1141,13 +1015,12 @@ 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. +read-only. If the variable @code{dired-vm-read-only-folders} is @code{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. +@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. @vindex dired-bind-vm If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound @@ -1209,51 +1082,31 @@ Bound to @kbd{%Y}. Relative symlink all marked files containing info. @end table -@node Bugs, GNU Free Documentation License, Miscellaneous Commands, Top -@comment node-name, next, previous, up +@node Bugs @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 -@c +If you encounter a bug in this package, or wish to suggest an +enhancement, then please use @kbd{M-x report-emacs-bug} to report it. -@node GNU Free Documentation License, Concept Index, Bugs, Top +@node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi -@node Concept Index, Command Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up +@node Concept Index @unnumbered Concept Index @printindex cp -@node Command Index, Key Index, Concept Index, Top -@comment node-name, next, previous, up +@node Command Index @unnumbered Function Index @printindex fn -@node Key Index, Variable Index, Command Index, Top -@comment node-name, next, previous, up +@node Key Index @unnumbered Key Index @printindex ky -@node Variable Index, , Key Index, Top -@comment node-name, next, previous, up +@node Variable Index @unnumbered Variable Index @printindex vr