Commit c40a7de7 authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 3d992aa0
......@@ -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
......
2011-12-26 Chong Yidong <cyd@gnu.org>
* 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 <cyd@gnu.org>
* maintaining.texi (Tags): Mention Semantic.
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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}).
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment