From: Chong Yidong Date: Mon, 26 Dec 2011 10:36:41 +0000 (+0800) Subject: Update Abbrevs and Dired chapters of Emacs manual. X-Git-Tag: emacs-pretest-24.0.93~111 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c40a7de7814a0b1d0c98e1d58513ec1e47230e1b;p=emacs.git Update Abbrevs and Dired chapters of Emacs manual. * dired.texi (Dired Enter, Misc Dired Features): Document dired-use-ls-dired changes. Mention quit-window. (Dired Navigation): Add index entries. (Dired Visiting): Fix View Mode xref. (Marks vs Flags): Prefer C-/ binding for undo. (Subdirectories in Dired): Add xrefs. (Misc Dired Features): Document some Emacs 24 changes. Add index entries. * abbrevs.texi (Abbrev Concepts): No need to mention abbrev-mode variable, since it is explained in Minor Modes node. (Defining Abbrevs): Copyedits. (Expanding Abbrevs): State default of abbrev-all-caps. Prefer the C-/ binding for undo. (Dabbrev Customization): Add xrefs for case-fold-search and case-replace. * dired-xtra.texi (Subdir Switches): Add xref. * maintaining.texi (VC Directory Commands): Mention quit-window. --- diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index 667a3e8effd..65f98c85496 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -124,7 +124,7 @@ TUTORIAL.zh ** Check the manual. -abbrevs.texi +abbrevs.texi cyd ack.texi anti.texi arevert-xtra.texi cyd @@ -136,7 +136,7 @@ cal-xtra.texi cmdargs.texi commands.texi cyd custom.texi -dired.texi +dired.texi cyd dired-xtra.texi display.texi cyd emacs.texi diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index dfa8006e03c..7857295de92 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,26 @@ +2011-12-26 Chong Yidong + + * dired.texi (Dired Enter, Misc Dired Features): Document + dired-use-ls-dired changes. Mention quit-window. + (Dired Navigation): Add index entries. + (Dired Visiting): Fix View Mode xref. + (Marks vs Flags): Prefer C-/ binding for undo. + (Subdirectories in Dired): Add xrefs. + (Misc Dired Features): Document some Emacs 24 changes. Add index + entries. + + * abbrevs.texi (Abbrev Concepts): No need to mention abbrev-mode + variable, since it is explained in Minor Modes node. + (Defining Abbrevs): Copyedits. + (Expanding Abbrevs): State default of abbrev-all-caps. Prefer the + C-/ binding for undo. + (Dabbrev Customization): Add xrefs for case-fold-search and + case-replace. + + * dired-xtra.texi (Subdir Switches): Add xref. + + * maintaining.texi (VC Directory Commands): Mention quit-window. + 2011-12-25 Chong Yidong * maintaining.texi (Tags): Mention Semantic. diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index 2eafadf4841..5868010806c 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -45,17 +45,14 @@ expanding to @samp{find outer otter}, then you can insert @samp{find outer otter.} into the buffer by typing @kbd{f o o .}. @findex abbrev-mode -@vindex abbrev-mode @cindex Abbrev mode @cindex mode, Abbrev - Abbrevs expand only when Abbrev mode (a minor mode) is enabled. -Disabling Abbrev mode does not cause abbrev definitions to be forgotten, -but they do not expand until Abbrev mode is enabled again. The command -@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it -turns Abbrev mode on if the argument is positive, off otherwise. -@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is -on when the variable is non-@code{nil}. The variable @code{abbrev-mode} -automatically becomes local to the current buffer when it is set. + Abbrevs expand only when Abbrev mode, a buffer-local minor mode, is +enabled. Disabling Abbrev mode does not cause abbrev definitions to +be forgotten, but they do not expand until Abbrev mode is enabled +again. The command @kbd{M-x abbrev-mode} toggles Abbrev mode; with a +numeric argument, it turns Abbrev mode on if the argument is positive, +off otherwise. @xref{Minor Modes}. Abbrevs can have @dfn{mode-specific} definitions, active only in one major mode. Abbrevs can also have @dfn{global} definitions that are active in @@ -108,22 +105,18 @@ region as the expansion of the abbrev being defined. @kindex C-x a l @findex add-mode-abbrev The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but -defines a mode-specific abbrev. Mode-specific abbrevs are active only in a -particular major mode. @kbd{C-x a l} defines an abbrev for the major mode -in effect at the time @kbd{C-x a l} is typed. The arguments work the same -as for @kbd{C-x a g}. +defines a mode-specific abbrev for the current major mode. The +arguments work the same as for @kbd{C-x a g}. @kindex C-x a i g @findex inverse-add-global-abbrev @kindex C-x a i l @findex inverse-add-mode-abbrev - If the abbrev text itself is already in the buffer, you can use the -commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and -@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an -abbrev by specify the expansion in the minibuffer. These commands are -called ``inverse'' because they invert the meaning of the two text -strings they use (one from the buffer and one read with the -minibuffer). + @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and @kbd{C-x a i +l} (@code{inverse-add-mode-abbrev}) perform the opposite task: if the +abbrev text is already in the buffer, you use these commands to define +an abbrev by specifying the expansion in the minibuffer. These +commands will expand the abbrev text used for the definition. @findex define-mode-abbrev @findex define-global-abbrev @@ -132,8 +125,8 @@ expansion in the buffer using the command @code{define-global-abbrev}. It reads two arguments---the abbrev, and its expansion. The command @code{define-mode-abbrev} does likewise for a mode-specific abbrev. - To change the definition of an abbrev, just define a new definition. -When the abbrev has a prior definition, the abbrev definition commands + To change the definition of an abbrev, just make a new definition. +When an abbrev has a prior definition, the abbrev definition commands ask for confirmation before replacing it. @findex kill-all-abbrevs @@ -155,11 +148,11 @@ The most common way to use an abbrev is to insert it and then insert a punctuation or whitespace character to expand it. @vindex abbrev-all-caps - Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find -outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into -@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the -variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies -@samp{FIND OUTER OTTER}). + Abbrev expansion preserves case: @samp{foo} expands to @samp{find +outer otter}, and @samp{Foo} to @samp{Find outer otter}. @samp{FOO} +expands to @samp{Find Outer Otter} by default, but if you change the +variable @code{abbrev-all-caps} to a non-@code{nil} value, it expands +to @samp{FIND OUTER OTTER}. These commands are used to control abbrev expansion: @@ -196,14 +189,14 @@ punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in the buffer, not expanding it. @findex unexpand-abbrev - If you expand an abbrev by mistake, you can undo the expansion and -bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}). -This also undoes the insertion of the non-word character that expanded -the abbrev. If the result you want is the terminating non-word -character plus the unexpanded abbrev, you must reinsert the terminating -character, quoting it with @kbd{C-q}. You can also use the command -@kbd{M-x unexpand-abbrev} to cancel the last expansion without -deleting the terminating character. + If you expand an abbrev by mistake, you can undo the expansion by +typing @kbd{C-/} (@code{undo}). @xref{Undo}. This undoes the +insertion of the abbrev expansion and brings back the abbrev text. If +the result you want is the terminating non-word character plus the +unexpanded abbrev, you must reinsert the terminating character, +quoting it with @kbd{C-q}. You can also use the command @kbd{M-x +unexpand-abbrev} to cancel the last expansion without deleting the +terminating character. @findex expand-region-abbrevs @kbd{M-x expand-region-abbrevs} searches through the region for defined @@ -409,12 +402,11 @@ you are expanding. @vindex dabbrev-case-fold-search This feature is controlled by the variable -@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in -this search; if it is @code{nil}, the word and the expansion must match -in case. If the value of @code{dabbrev-case-fold-search} is -@code{case-fold-search}, which is true by default, then the variable -@code{case-fold-search} controls whether to ignore case while searching -for expansions. +@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored +in this search; if it is @code{nil}, the word and the expansion must +match in case. If the value is @code{case-fold-search} (the default), +then the variable @code{case-fold-search} controls whether to ignore +case while searching for expansions (@pxref{Search Case}). @vindex dabbrev-case-replace Normally, dynamic abbrev expansion preserves the case pattern @@ -425,10 +417,10 @@ expansion to that case pattern. The variable @code{dabbrev-case-replace} controls whether to preserve the case pattern of the dynamic abbrev. If it is @code{t}, the dynamic abbrev's case pattern is preserved in most cases; if it is -@code{nil}, the expansion is always copied verbatim. If the value of -@code{dabbrev-case-replace} is @code{case-replace}, which is true by -default, then the variable @code{case-replace} controls whether to -copy the expansion verbatim. +@code{nil}, the expansion is always copied verbatim. If the value is +@code{case-replace} (the default), then the variable +@code{case-replace} controls whether to copy the expansion verbatim +(@pxref{Replacement and Case}). However, if the expansion contains a complex mixed case pattern, and the dynamic abbrev matches this pattern as far as it goes, then the diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi index efb05226ba8..52ccccce58c 100644 --- a/doc/emacs/dired-xtra.texi +++ b/doc/emacs/dired-xtra.texi @@ -7,24 +7,24 @@ @node Subdir Switches @section Subdirectory Switches in Dired -You can insert subdirectories with specified @code{ls} switches in -Dired buffers using @kbd{C-u i}. You can change the @code{ls} +You can insert subdirectories with specified @command{ls} switches in +Dired buffers using @kbd{C-u i}. You can change the @command{ls} switches of an already inserted subdirectory using @kbd{C-u l}. Dired preserves the switches if you revert the buffer. Deleting a subdirectory forgets about its switches. -Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) -to reinsert or delete subdirectories that were inserted with explicit -switches can bypass Dired's machinery for remembering (or forgetting) -switches. Deleting a subdirectory using @code{dired-undo} does not -forget its switches. When later reinserted using @kbd{i}, it will be -reinserted using its old switches. Using @code{dired-undo} to -reinsert a subdirectory that was deleted using the regular -Dired commands (not @code{dired-undo}) will originally insert it with -its old switches. Reverting the buffer, however, will relist it using -the buffer's default switches. If any of this yields problems, you -can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. +Using @code{dired-undo} (@pxref{Marks vs Flags}) to reinsert or delete +subdirectories that were inserted with explicit switches can bypass +Dired's machinery for remembering (or forgetting) switches. Deleting +a subdirectory using @code{dired-undo} does not forget its switches. +When later reinserted using @kbd{i}, it will be reinserted using its +old switches. Using @code{dired-undo} to reinsert a subdirectory that +was deleted using the regular Dired commands (not @code{dired-undo}) +will originally insert it with its old switches. Reverting the +buffer, however, will relist it using the buffer's default switches. +If any of this yields problems, you can easily correct the situation +using @kbd{C-u i} or @kbd{C-u l}. Dired does not remember the @code{R} switch. Inserting a subdirectory with switches that include the @code{R} switch is equivalent to diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index b6ed47fdb3f..5097565830e 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -73,32 +73,45 @@ completion commands can be used in the minibuffer; in particular, a directory name. The variable @code{dired-listing-switches} specifies the options to -give to @code{ls} for listing the directory; this string @emph{must} -contain @samp{-l}. If you use a prefix argument with the @code{dired} -command, you can specify the @code{ls} switches with the minibuffer -before you enter the directory specification. No matter how they are -specified, the @code{ls} switches can include short options (that is, -single characters) requiring no arguments, and long options (starting -with @samp{--}) whose arguments are specified with @samp{=}. +give to @command{ls} for listing the directory; this string +@emph{must} contain @samp{-l}. If you use a prefix argument with the +@code{dired} command, you can specify the @command{ls} switches with the +minibuffer before you enter the directory specification. No matter +how they are specified, the @command{ls} switches can include short +options (that is, single characters) requiring no arguments, and long +options (starting with @samp{--}) whose arguments are specified with +@samp{=}. @vindex dired-use-ls-dired - Note that Dired automatically adds the option @samp{--dired}, if -your @code{ls} program supports it, unless you explicitly set -the variable @code{dired-use-ls-dired} to @code{nil}. Without this -option, Dired will have trouble parsing some @samp{unusual} file-names. -See the documentation of @code{dired-use-ls-dired} for more details. - - On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls}; -see @ref{ls in Lisp}, for options and peculiarities of that emulation. + If your @command{ls} program supports the @samp{--dired} option, +Dired automatically passes it that option; this causes @command{ls} to +emit special escape sequences for certain unusual file names, without +which Dired will not be able to parse those names. The first time you +run Dired in an Emacs session, it checks whether @command{ls} supports +the @samp{--dired} option by calling it once with that option. If the +exit code is 0, Dired will subsequently use the @samp{--dired} option; +otherwise it will not. You can inhibit this check by customizing the +variable @code{dired-use-ls-dired}. The value @code{unspecified} (the +default) means to perform the check; any other non-@code{nil} value +means to use the @samp{--dired} option; and @code{nil} means not to +use the @samp{--dired} option. + + On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}. +@xref{ls in Lisp}, for options and peculiarities of this emulation. @findex dired-other-window @kindex C-x 4 d @findex dired-other-frame @kindex C-x 5 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}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a -separate frame to display the Dired buffer. + To display the Dired buffer in another window, use @kbd{C-x 4 d} +(@code{dired-other-window}) instead of @kbd{C-x d}. @kbd{C-x 5 d} +(@code{dired-other-frame}) displays the Dired buffer in a separate +frame. + +@kindex q @r{(Dired)} +@findex quit-window + Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and +deletes its window if the window was created just for that buffer. @node Dired Navigation @section Navigation in the Dired Buffer @@ -124,7 +137,11 @@ minibuffer, and moves point to the line in the Dired buffer describing that file. @cindex searching Dired buffers +@findex dired-isearch-filenames @vindex dired-isearch-filenames +@findex dired-isearch-filenames-regexp +@kindex M-s f C-s @r{(Dired)} +@kindex M-s f M-C-s @r{(Dired)} @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward incremental search in the Dired buffer, looking for matches only amongst the file names and ignoring the rest of the text in the @@ -331,18 +348,16 @@ another window, but do not select that window (@code{dired-display-file}). @item Mouse-1 @itemx Mouse-2 @findex dired-mouse-find-file-other-window -Visit the file named by the line you click on +Visit the file whose name you clicked on (@code{dired-mouse-find-file-other-window}). This uses another window to display the file, like the @kbd{o} command. @item v @kindex v @r{(Dired)} @findex dired-view-file -View the file described on the current line, using @kbd{M-x view-file} -(@code{dired-view-file}). Viewing a file with @code{view-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}. +View the file described on the current line, with View mode +(@code{dired-view-file}). View mode provides convenient commands to +navigate the buffer but forbids changing it; @xref{View Mode}. @item ^ @kindex ^ @r{(Dired)} @@ -520,9 +535,9 @@ the regular expression @var{regexp} @kbd{% m}, except that it searches the file contents instead of the file name. -@item C-x u +@item C-/ +@itemx C-x u @itemx C-_ -@itemx C-/ @kindex C-_ @r{(Dired)} @findex dired-undo Undo changes in the Dired buffer, such as adding or removing @@ -615,7 +630,7 @@ Like the other commands in this section, this command operates on the Rename the specified files (@code{dired-do-rename}). If you rename a single file, the argument @var{new} is the new name of the file. If you rename several files, the argument @var{new} is the directory into -which to move the files (this is like the shell command @code{mv}). +which to move the files (this is like the shell command @command{mv}). Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names. @@ -625,7 +640,7 @@ with renamed files so that they refer to the new names. @cindex hard links (in Dired) @item H @var{new} @key{RET} Make hard links to the specified files (@code{dired-do-hardlink}). -This is like the shell command @code{ln}. The argument @var{new} is +This is like the shell command @command{ln}. The argument @var{new} is the directory to make the links in, or (if making just one link) the name to give the link. @@ -642,9 +657,10 @@ link. @kindex M @r{(Dired)} @cindex changing file permissions (in Dired) @item M @var{modespec} @key{RET} -Change the mode (also called ``permission bits'') of the specified files -(@code{dired-do-chmod}). @var{modespec} can be in octal or symbolic -notation like arguments handled by the @code{chmod} program. +Change the mode (also called @dfn{permission bits}) of the specified +files (@code{dired-do-chmod}). @var{modespec} can be in octal or +symbolic notation, like arguments handled by the @command{chmod} +program. @findex dired-do-chgrp @kindex G @r{(Dired)} @@ -663,8 +679,8 @@ this.) @vindex dired-chown-program The variable @code{dired-chown-program} specifies the name of the -program to use to do the work (different systems put @code{chown} in -different places). +program to use to do the work (different systems put @command{chown} +in different places). @findex dired-do-touch @kindex T @r{(Dired)} @@ -952,17 +968,17 @@ The backup file is the first file given to @code{diff}. @cindex subdirectories in Dired @cindex expanding subdirectories in Dired - A Dired buffer displays just one directory in the normal case; -but you can optionally include its subdirectories as well. + A Dired buffer usually displays just one directory, but you can +optionally include its subdirectories as well. The simplest way to include multiple directories in one Dired buffer is -to specify the options @samp{-lR} for running @code{ls}. (If you give a +to specify the options @samp{-lR} for running @command{ls}. (If you give a numeric argument when you run Dired, then you can specify these options in the minibuffer.) That produces a recursive directory listing showing all subdirectories at all levels. More often, you will want to show only specific subdirectories. You -can do this with the @kbd{i} command: +can do this with @kbd{i} (@code{dired-maybe-insert-subdir}): @table @kbd @findex dired-maybe-insert-subdir @@ -973,25 +989,27 @@ can do this with the @kbd{i} command: Insert the contents of a subdirectory later in the buffer. @end table -Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line -that describes a file which is a directory. It inserts the contents of -that directory into the same Dired buffer, and moves there. Inserted -subdirectory contents follow the top-level directory of the Dired -buffer, just as they do in @samp{ls -lR} output. - -If the subdirectory's contents are already present in the buffer, the -@kbd{i} command just moves to it. - -In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u -C-@key{SPC}} takes you back to the old position in the buffer (the line -describing that subdirectory). You can also use @samp{^} to return -to the parent directory in the same Dired buffer. - -Use the @kbd{l} command (@code{dired-do-redisplay}) to update the -subdirectory's contents. Use @kbd{C-u k} on the subdirectory header -line to remove the subdirectory listing (@pxref{Dired Updating}). You -can also hide and show inserted subdirectories (@pxref{Hiding -Subdirectories}). +@noindent +If you use this command on a line that describes a file which is a +directory, it inserts the contents of that directory into the same +Dired buffer, and moves there. Inserted subdirectory contents follow +the top-level directory of the Dired buffer, just as they do in +@samp{ls -lR} output. + + If the subdirectory's contents are already present in the buffer, +the @kbd{i} command just moves to it. + + In either case, @kbd{i} sets the Emacs mark before moving, so +@kbd{C-u C-@key{SPC}} returns to your previous position in the Dired +buffer (@pxref{Setting Mark}). You can also use @samp{^} to return to +the parent directory in the same Dired buffer (@pxref{Dired +Visiting}). + + Use the @kbd{l} command (@code{dired-do-redisplay}) to update the +subdirectory's contents, and use @kbd{C-u k} on the subdirectory +header line to remove the subdirectory listing (@pxref{Dired +Updating}). You can also hide and show inserted subdirectories +(@pxref{Hiding Subdirectories}). @ifnottex @include dired-xtra.texi @@ -1209,10 +1227,10 @@ tell @command{find} what condition to test. To use this command, you need to know how to use @command{find}. @vindex find-ls-option - The format of listing produced by these commands is controlled by the -variable @code{find-ls-option}, whose default value specifies using -options @samp{-ld} for @code{ls}. If your listings are corrupted, you -may need to change the value of this variable. + The format of listing produced by these commands is controlled by +the variable @code{find-ls-option}, whose default value specifies +using options @samp{-ld} for @command{ls}. If your listings are +corrupted, you may need to change the value of this variable. @findex locate @findex locate-with-filter @@ -1338,10 +1356,14 @@ rotation is lossless, and uses an external utility called JpegTRAN. @kindex + @r{(Dired)} @findex dired-create-directory The command @kbd{+} (@code{dired-create-directory}) reads a -directory name, and creates the directory if it does not already -exist. +directory name, and creates that directory. It signals an error if +the directory already exists. @cindex searching multiple files via Dired +@kindex M-s a C-s @r{(Dired)} +@kindex M-s a M-C-s @r{(Dired)} +@findex dired-do-isearch +@findex dired-do-isearch-regexp The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a ``multi-file'' incremental search on the marked files. If a search fails at the end of a file, typing @kbd{C-s} advances to the next diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 88bd5949b47..6ce298c1795 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1183,6 +1183,12 @@ point is on a directory entry, mark all files in that directory tree (@code{vc-dir-mark-all-files}). With a prefix argument, mark all listed files and directories. +@kindex q @r{(VC Directory)} +@findex quit-window +@item q +Bury the VC Directory buffer, and delete its window if the window was +created just for that buffer. + @item u Unmark the file or directory on the current line. If the region is active, unmark all the files in the region (@code{vc-dir-unmark}). diff --git a/etc/NEWS b/etc/NEWS index 95d1854744b..f37f562ec82 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -665,7 +665,7 @@ The new function dbus-register-service registers a service known name on a D-Bus without simultaneously registering a property or a method. ** Dired-x - +--- *** dired-jump and dired-jump-other-window called with a prefix argument read a file name from the minibuffer instead of using buffer-file-name.