diff options
Diffstat (limited to 'doc/emacs')
| -rw-r--r-- | doc/emacs/abbrevs.texi | 4 | ||||
| -rw-r--r-- | doc/emacs/ack.texi | 4 | ||||
| -rw-r--r-- | doc/emacs/buffers.texi | 5 | ||||
| -rw-r--r-- | doc/emacs/custom.texi | 8 | ||||
| -rw-r--r-- | doc/emacs/emacs.texi | 19 | ||||
| -rw-r--r-- | doc/emacs/files.texi | 11 | ||||
| -rw-r--r-- | doc/emacs/frames.texi | 9 | ||||
| -rw-r--r-- | doc/emacs/glossary.texi | 11 | ||||
| -rw-r--r-- | doc/emacs/help.texi | 17 | ||||
| -rw-r--r-- | doc/emacs/killing.texi | 23 | ||||
| -rw-r--r-- | doc/emacs/m-x.texi | 18 | ||||
| -rw-r--r-- | doc/emacs/maintaining.texi | 102 | ||||
| -rw-r--r-- | doc/emacs/mini.texi | 34 | ||||
| -rw-r--r-- | doc/emacs/misc.texi | 26 | ||||
| -rw-r--r-- | doc/emacs/package.texi | 33 | ||||
| -rw-r--r-- | doc/emacs/programs.texi | 77 | ||||
| -rw-r--r-- | doc/emacs/regs.texi | 10 | ||||
| -rw-r--r-- | doc/emacs/rmail.texi | 30 | ||||
| -rw-r--r-- | doc/emacs/search.texi | 779 | ||||
| -rw-r--r-- | doc/emacs/trouble.texi | 2 |
20 files changed, 912 insertions, 310 deletions
diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index 23d7e28f4e3..695ffa8d1cd 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -407,7 +407,7 @@ you are expanding. 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}). +case while searching for expansions (@pxref{Lax Search}). @vindex dabbrev-case-replace Normally, dynamic abbrev expansion preserves the case pattern @@ -421,7 +421,7 @@ 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 is @code{case-replace} (the default), then the variable @code{case-replace} controls whether to copy the expansion verbatim -(@pxref{Replacement and Case}). +(@pxref{Replacement and Lax Matches}). 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/ack.texi b/doc/emacs/ack.texi index 1c88e97a659..4d53456d0f0 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -64,6 +64,10 @@ point vertically fixed by scrolling the window when moving up and down in the buffer. @item +Aurélien Aptel added dynamic module support to Emacs. Philipp +Stephani and others also worked on the dynamic module code. + +@item Joe Arceneaux wrote the original text property implementation, and implemented support for X11. diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 5a4d1abfc39..ae64fefbb70 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -703,5 +703,6 @@ C-b}. To customize this buffer list, use the @code{bs} Custom group MSB global minor mode (``MSB'' stands for ``mouse select buffer'') provides a different and customizable mouse buffer menu which you may prefer. It replaces the bindings of @code{mouse-buffer-menu}, -normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You -can customize the menu in the @code{msb} Custom group. +normally on @kbd{C-Down-Mouse-1} and @kbd{C-@key{F10}}, and the menu +bar buffer menu. You can customize the menu in the @code{msb} Custom +group. diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 8441c889bbf..fc405e3a147 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -403,6 +403,8 @@ customizations in your initialization file. This is because saving customizations from such a session would wipe out all the other customizations you might have on your initialization file. +@cindex unsaved customizations, reminder to save +@findex custom-prompt-customize-unsaved-options Please note that any customizations you have not chosen to save for future sessions will be lost when you terminate Emacs. If you'd like to be prompted about unsaved customizations at termination time, add @@ -1131,6 +1133,12 @@ won't confuse other programs that the file is intended for. The example above is for the C programming language, where comments start with @samp{/*} and end with @samp{*/}. +If some unrelated text might look to Emacs as a local variables list, +you can countermand that by inserting a form-feed character (a page +delimiter, @pxref{Pages}) after that text. Emacs only looks for +file-local variables in the last page of a file, after the last page +delimiter. + @findex add-file-local-variable @findex delete-file-local-variable @findex copy-dir-locals-to-file-locals diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 27bb77d5cac..0030467cdce 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -188,6 +188,7 @@ Advanced Features * Sending Mail:: Sending mail in Emacs. * Rmail:: Reading mail in Emacs. * Gnus:: A flexible mail and news reader. +* Host Security:: Security issues on a single computer. * Network Security:: Managing the network security. * Document View:: Viewing PDF, PS and DVI files. * EWW:: A web browser in Emacs. @@ -392,18 +393,20 @@ Searching and Replacement * Regexps:: Syntax of regular expressions. * Regexp Backslash:: Regular expression constructs starting with `\'. * Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. +* Lax Search:: Search ignores some distinctions between + similar characters, like letter-case. * Replace:: Search, and replace some or all matches. * Other Repeating Search:: Operating on all matches for some regexp. +* Search Customizations:: Various search customizations. Incremental Search * Basic Isearch:: Basic incremental search commands. * Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. * Isearch Yank:: Commands that grab text into the search string or else edit the search string. +* Error in Isearch:: When your string is not found. +* Special Isearch:: Special input in incremental search. * Not Exiting Isearch:: Prefix argument and scrolling commands. * Isearch Minibuffer:: Incremental search of the minibuffer history. @@ -411,7 +414,8 @@ Replacement Commands * Unconditional Replace:: Replacing all matches for a string. * Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. +* Replacement and Lax Matches:: + Lax searching for text to replace. * Query Replace:: How to use querying. Commands for Fixing Typos @@ -534,6 +538,7 @@ Frames and Graphical Displays * Multiple Displays:: How one Emacs instance can talk to several displays. * Frame Parameters:: Changing the colors and other modes of frames. * Scroll Bars:: How to enable and disable scroll bars; how to use them. +* Window Dividers:: Window separators that can be dragged with the mouse. * Drag and Drop:: Using drag and drop to open files and insert text. * Menu Bars:: Enabling and disabling the menu bar. * Tool Bars:: Enabling and disabling the tool bar. @@ -589,6 +594,7 @@ Commands for Human Languages * Sentences:: Moving over and killing sentences. * Paragraphs:: Moving over paragraphs. * Pages:: Moving over pages. +* Quotation Marks:: Inserting quotation marks. * Filling:: Filling or justifying text. * Case:: Changing the case of text. * Text Mode:: The major modes for editing text files. @@ -1164,6 +1170,11 @@ Reporting Bugs * Checklist:: Steps to follow for a good bug report. * Sending Patches:: How to send a patch for GNU Emacs. +Contributing to Emacs Development + +* Coding Standards:: Gnu Emacs coding standards. +* Copyright Assignment:: Assigning copyright to the FSF. + Command Line Arguments for Emacs Invocation * Action Arguments:: Arguments to visit files, load libraries, diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 5752d02fe85..4f7596e058c 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1295,11 +1295,12 @@ would make to the file if you save the buffer. @findex compare-windows The command @kbd{M-x compare-windows} compares the text in the -current window with that in the next window. (For more information -about windows in Emacs, @ref{Windows}.) Comparison starts at point in -each window, after pushing each initial point value on the mark ring -in its respective buffer. Then it moves point forward in each window, -one character at a time, until it reaches characters that don't match. +current window with that in the window that was the selected window +before you selected the current one. (For more information about +windows in Emacs, @ref{Windows}.) Comparison starts at point in each +window, after pushing each initial point value on the mark ring in its +respective buffer. Then it moves point forward in each window, one +character at a time, until it reaches characters that don't match. Then the command exits. If point in the two windows is followed by non-matching text when diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 95b721fa739..acfdfe25cb2 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -1265,10 +1265,11 @@ Some text terminals support mouse clicks in the terminal window. In a terminal emulator which is compatible with @command{xterm}, you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple uses of the mouse---basically, only non-modified single clicks are -supported. The normal @command{xterm} mouse functionality for such -clicks is still available by holding down the @kbd{SHIFT} key when you -press the mouse button. Xterm Mouse mode is a global minor mode -(@pxref{Minor Modes}). Repeating the command turns the mode off +supported. Newer versions of @command{xterm} also support +mouse-tracking. The normal @command{xterm} mouse functionality for +such clicks is still available by holding down the @kbd{SHIFT} key +when you press the mouse button. Xterm Mouse mode is a global minor +mode (@pxref{Minor Modes}). Repeating the command turns the mode off again. @findex gpm-mouse-mode diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index e66cd79e740..cc81101d67a 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -175,11 +175,22 @@ corresponding Control character. @xref{User Input,C-M-}. Case conversion means changing text from upper case to lower case or vice versa. @xref{Case}. +@item Case Folding +Case folding means ignoring the differences between case variants of +the same letter: upper-case, lower-case, and title-case. Emacs +performs case folding by default in text search. @xref{Lax Search}. + @item Character Characters form the contents of an Emacs buffer. Also, key sequences (q.v.@:) are usually made up of characters (though they may include other input events as well). @xref{User Input}. +@item Character Folding +Character folding means ignoring differences between similarly looking +characters, such as between @code{a}, and @code{@:a} and @code{@'a}. +Emacs performs character folding by default in text search. @xref{Lax +Search}. + @item Character Set Emacs supports a number of character sets, each of which represents a particular alphabet or script. @xref{International}. diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index a9c63b91785..25e783f6ed7 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -126,6 +126,10 @@ Display documentation of the current major mode and minor modes (@code{describe-mode}). @item C-h n Display news of recent Emacs changes (@code{view-emacs-news}). +@item C-h o @var{symbol} +Display documentation of the Lisp symbol named @var{symbol} +(@code{describe-symbol}). This will show the documentation of all +kinds of symbols: functions, variables, and faces. @item C-h p Find packages by topic keyword (@code{finder-by-keyword}). This lists packages using a package menu buffer. @xref{Packages}. @@ -272,6 +276,14 @@ source files installed (@pxref{Hyperlinking}). (@code{Info-goto-emacs-command-node}). This knows about various manuals, not just the Emacs manual, and finds the right one. +@kindex C-h o +@findex describe-symbol + @kbd{C-h o} (@code{describe-symbol}) is like @kbd{C-h f} and +@kbd{C-h v}, but it describes any symbol, be it a function, a +variable, or a face. If the symbol has more than one definition, like +it has both definition as a function and as a variable, this command +will show the documentation of all of them, one after the other. + @node Apropos @section Apropos @cindex apropos @@ -524,8 +536,9 @@ command works depend on the major mode. @findex view-lossage If something surprising happens, and you are not sure what you typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays your last -300 input keystrokes. If you see commands that you don't know, you can -use @kbd{C-h c} to find out what they do. +300 input keystrokes and the commands they invoked. If you see +commands that you are not familiar with, you can use @kbd{C-h k} or +@kbd{C-h f} to find out what they do. @kindex C-h e @findex view-echo-area-messages diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index d453647b0c5..9761ac7d11c 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -504,9 +504,9 @@ does not alter the clipboard. However, if you change @code{yank-pop-change-selection} to @code{t}, then @kbd{M-y} saves the new yank to the clipboard. -@vindex x-select-enable-clipboard +@vindex select-enable-clipboard To prevent kill and yank commands from accessing the clipboard, -change the variable @code{x-select-enable-clipboard} to @code{nil}. +change the variable @code{select-enable-clipboard} to @code{nil}. @cindex clipboard manager @vindex x-select-enable-clipboard-manager @@ -519,14 +519,14 @@ when exiting Emacs; if you wish to prevent Emacs from transferring data to the clipboard manager, change the variable @code{x-select-enable-clipboard-manager} to @code{nil}. -@vindex x-select-enable-primary +@vindex select-enable-primary @findex clipboard-kill-region @findex clipboard-kill-ring-save @findex clipboard-yank Prior to Emacs 24, the kill and yank commands used the primary selection (@pxref{Primary Selection}), not the clipboard. If you -prefer this behavior, change @code{x-select-enable-clipboard} to -@code{nil}, @code{x-select-enable-primary} to @code{t}, and +prefer this behavior, change @code{select-enable-clipboard} to +@code{nil}, @code{select-enable-primary} to @code{t}, and @code{mouse-drag-copy-region} to @code{t}. In this case, you can use the following commands to act explicitly on the clipboard: @code{clipboard-kill-region} kills the region and saves it to the @@ -853,6 +853,19 @@ so in a rectangular fashion, and killing and yanking operate on the rectangle. @xref{Killing}. The mode persists only as long as the region is active. +Unlike the standard region, the region-rectangle can have its corners +extended past the end of buffer, or inside stretches of white space +that point normally cannot enter, like the TAB. + +@findex rectangle-exchange-point-and-mark +@findex exchange-point-and-mark@r{, in rectangle-mark-mode} +@kindex C-x C-x@r{, in rectangle-mark-mode} +When the region is in rectangle-mark-mode, @kbd{C-x C-x} runs the +command @code{rectangle-exchange-point-and-mark}, which cycles between +the four corners of the region-rectangle. This comes in handy if you +want to modify the dimensions of the region-rectangle before invoking +an operation on the marked text. + @node CUA Bindings @section CUA Bindings @findex cua-mode diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index c9ae559f984..795d6fe373b 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -43,6 +43,13 @@ Note that @code{forward-char} is the same command that you invoke with the key @kbd{C-f}. The existence of a key binding does not stop you from running the command by name. +@cindex obsolete command + When @kbd{M-x} completes on commands, it ignores the commands that +are declared @dfn{obsolete}; for these, you will have to type their +full name. Obsolete commands are those for which newer, better +alternatives exist, and which are slated for removal in some future +Emacs release. + To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead of entering the command name. This takes you back to command level. @@ -57,7 +64,16 @@ mentions this in the echo area after running the command. For example, if you type @kbd{M-x forward-word}, the message says that you can run the same command by typing @kbd{M-f}. You can turn off these messages by setting the variable @code{suggest-key-bindings} to -@code{nil}. +@code{nil}. The value of @code{suggest-key-bindings} can also be a +number, in which case Emacs will show the binding for that many +seconds before removing it from display. The default behavior is to +display the binding for 2 seconds. + + Commands that don't have key bindings, can still be invoked after +typing less than their full name at the @samp{M-x} prompt. Emacs +mentions such shorthands in the echo area if they are significantly +shorter than the full command name. The setting of +@code{suggest-key-bindings} affects these hints as well. In this manual, when we speak of running a command by name, we often omit the @key{RET} that terminates the name. Thus we might say diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index a571ea7ed67..801d147845b 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -47,6 +47,17 @@ variable @code{vc-handled-backends} to @code{nil} (@pxref{Customizing VC}). @end ifnottex +@findex vc-refresh-state +@findex vc-state-refresh + To update the VC state information for the file visited in the +current buffer, use the command @code{vc-refresh-state}. This command +is useful when you perform version control commands outside Emacs +(e.g., from the shell prompt), or if you put the buffer's file under a +different version control system, or remove it from version control +entirely. A companion command @code{vc-state-refresh} does the same, +but does not consider switching the version control system or removal +from VC. + @menu * Introduction to VC:: How version control works in general. * VC Mode Line:: How the mode line shows version control status. @@ -821,15 +832,19 @@ corresponding to @var{revision}, saves it to window. @findex vc-annotate +@vindex vc-annotate-background-mode @kindex C-x v g Many version control systems allow you to view files @dfn{annotated} with per-line revision information, by typing @kbd{C-x v g} (@code{vc-annotate}). This creates a new ``annotate'' buffer -displaying the file's text, with each line colored to show -how old it is. Red text is new, blue is old, and intermediate colors -indicate intermediate ages. By default, the color is scaled over the -full range of ages, such that the oldest changes are blue, and the -newest changes are red. +displaying the file's text, with each line colored to show how old it +is. Red text is new, blue is old, and intermediate colors indicate +intermediate ages. By default, the color is scaled over the full +range of ages, such that the oldest changes are blue, and the newest +changes are red. If the variable @code{vc-annotate-background-mode} +is non-@code{nil}, the colors expressing the age of each line are +applied to the background color, leaving the foreground at its default +color. When you give a prefix argument to this command, Emacs reads two arguments using the minibuffer: the revision to display and annotate @@ -1009,6 +1024,22 @@ increase the number of revisions shown in an existing entries} or @samp{Show unlimited entries} buttons at the end of the buffer. However, RCS, SCCS, and CVS do not support this feature. +@findex vc-region-history +A useful variant of examining changes is provided by the command +@kbd{vc-region-history}, which shows a @file{*VC-history*} buffer with +the history of changes to the region of the current file between point +and the mark (@pxref{Mark}). The history of changes includes the +commit log messages and also the changes themselves in the Diff +format. + +Invoke this command after marking the region of the current file in +whose changes you are interested. In the @file{*VC-history*} buffer +it pops up, you can use all of the commands available in the +@file{*vc-change-log*} buffer described above, and also the commands +defined by Diff mode (@pxref{Diff Mode}). + +This command is currently available only with Git. + @node VC Undo @subsection Undoing Version Control Actions @@ -1353,19 +1384,43 @@ commit will be committed to that specific branch. @subsubsection Pulling/Pushing Changes into/from a Branch @table @kbd +@item C-x v P +On a decentralized version control system, update another location +with changes from the current branch (a.k.a. ``push'' changes). This +concept does not exist for centralized version control systems + @item C-x v + On a decentralized version control system, update the current branch by ``pulling in'' changes from another location. On a centralized version control system, update the current VC fileset. - -@item C-x v P -On a decentralized version control system, ``push'' changes from the -current branch to another location. This concept does not exist -for centralized version control systems. @end table +@kindex C-x v P +@findex vc-push +On a decentralized version control system, the command @kbd{C-x v P} +(@code{vc-push}) updates another location with changes from the +current branch. With a prefix argument, it prompts for the exact +version control command to run, which lets you specify where to push +changes; the default is @command{bzr push} with Bazaar, @command{git +push} with Git, and @command{hg push} with Mercurial. The default +commands always push to a default location determined by the version +control system from your branch configuration. + +Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing}) +to view a log buffer of the changes to be sent. @xref{VC Change Log}. + +@cindex bound branch (Bazaar VCS) +This command is currently supported only by Bazaar, Git, and Mercurial. +The concept of ``pushing'' does not exist for centralized version +control systems, where this operation is a part of committing a +changeset, so invoking this command on a centralized VCS signals an +error. This command also signals an error when attempted in a Bazaar +@dfn{bound branch}, where committing a changeset automatically pushes +the changes to the remote repository to which the local branch is +bound. + @kindex C-x v + @findex vc-pull On a decentralized version control system, the command @kbd{C-x v +} @@ -1377,12 +1432,12 @@ Otherwise, it pulls from a default location determined by the version control system. Amongst decentralized version control systems, @kbd{C-x v +} is -currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it -calls @command{bzr pull} for ordinary branches (to pull from a master -branch into a mirroring branch), and @command{bzr update} for a bound -branch (to pull from a central repository). On Git, it calls +currently supported only by Bazaar, Git, and Mercurial. With Bazaar, +it calls @command{bzr pull} for ordinary branches (to pull from a +master branch into a mirroring branch), and @command{bzr update} for a +bound branch (to pull from a central repository). With Git, it calls @command{git pull} to fetch changes from a remote repository and merge -it into the current branch. On Mercurial, it calls @command{hg pull +it into the current branch. With Mercurial, it calls @command{hg pull -u} to fetch changesets from the default remote repository and update the working directory. @@ -1393,21 +1448,6 @@ Log}. On a centralized version control system like CVS, @kbd{C-x v +} updates the current VC fileset from the repository. -@kindex C-x v P -@findex vc-push - On a decentralized version control system, the command @kbd{C-x v P} -(@code{vc-push}) sends changes from your current branch to another location. -With a prefix argument, the command prompts for the exact -version control command to use, which lets you specify where to push -changes. Otherwise, it pushes to a default location determined -by the version control system. - - Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing}) -to view a log buffer of the changes to be sent. @xref{VC Change Log}. - -This command is currently supported only by Bazaar, Git, and Mercurial. -It signals an error for centralized version control systems. - @node Merging @subsubsection Merging Branches @cindex merging changes @@ -2285,7 +2325,7 @@ input. @xref{Query Replace}, for more information on query replace. You can control the case-sensitivity of tags search commands by customizing the value of the variable @code{tags-case-fold-search}. The default is to use the same setting as the value of -@code{case-fold-search} (@pxref{Search Case}). +@code{case-fold-search} (@pxref{Lax Search}). It is possible to get through all the files in the tags table with a single invocation of @kbd{M-x tags-query-replace}. But often it is diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index 2493fdadf37..869e06424ad 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -588,13 +588,17 @@ argument into the minibuffer: @table @kbd @item M-p -@itemx @key{UP} Move to the previous item in the minibuffer history, an earlier argument (@code{previous-history-element}). @item M-n -@itemx @key{DOWN} Move to the next item in the minibuffer history (@code{next-history-element}). +@item @key{UP} +@itemx @key{DOWN} +Like @kbd{M-p} and @kbd{M-n}, but move to the previous or next line of +a multi-line item before going to the previous history item +(@code{previous-line-or-history-element} and +@code{next-line-or-history-element}) . @item M-r @var{regexp} @key{RET} Move to an earlier item in the minibuffer history that matches @var{regexp} (@code{previous-matching-history-element}). @@ -609,13 +613,13 @@ Move to a later item in the minibuffer history that matches @kindex DOWN @r{(minibuffer history)} @findex next-history-element @findex previous-history-element - While in the minibuffer, @kbd{M-p} or @key{UP} -(@code{previous-history-element}) moves through the minibuffer history -list, one item at a time. Each @kbd{M-p} fetches an earlier item from -the history list into the minibuffer, replacing its existing contents. -Typing @kbd{M-n} or @key{DOWN} (@code{next-history-element}) moves -through the minibuffer history list in the opposite direction, -fetching later entries into the minibuffer. + While in the minibuffer, @kbd{M-p} (@code{previous-history-element}) +moves through the minibuffer history list, one item at a time. Each +@kbd{M-p} fetches an earlier item from the history list into the +minibuffer, replacing its existing contents. Typing @kbd{M-n} +(@code{next-history-element}) moves through the minibuffer history +list in the opposite direction, fetching later entries into the +minibuffer. If you type @kbd{M-n} in the minibuffer when there are no later entries in the minibuffer history (e.g., if you haven't previously @@ -623,6 +627,14 @@ typed @kbd{M-p}), Emacs tries fetching from a list of default arguments: values that you are likely to enter. You can think of this as moving through the ``future history''. +@findex previous-line-or-history-element +@findex next-line-or-history-element + The arrow keys @kbd{@key{UP}} and @kbd{@key{DOWN}} work like +@kbd{M-p} and @kbd{M-n}, but if the current history item is longer +than a single line, they allow you to move to the previous or next +line of the current history item before going to the previous or next +history item. + If you edit the text inserted by the @kbd{M-p} or @kbd{M-n} minibuffer history commands, this does not change its entry in the history list. However, the edited argument does go at the end of the @@ -642,8 +654,8 @@ expressions. A numeric prefix argument @var{n} means to fetch the @var{n}th matching entry. These commands are unusual, in that they use the minibuffer to read the regular expression argument, even though they are invoked from the minibuffer. An upper-case letter in -the regular expression makes the search case-sensitive (@pxref{Search -Case}). +the regular expression makes the search case-sensitive (@pxref{Lax +Search}). You can also search through the history using an incremental search. @xref{Isearch Minibuffer}. diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 7fad8268d06..41dce521c0a 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -6,7 +6,8 @@ @chapter Miscellaneous Commands This chapter contains several brief topics that do not fit anywhere -else: reading Usenet news, viewing PDFs and other such documents, web +else: reading Usenet news, host and network security, +viewing PDFs and other such documents, web browsing, running shell commands and shell subprocesses, using a single shared Emacs for utilities that expect to run an editor as a subprocess, printing, sorting text, editing binary files, saving an @@ -249,6 +250,25 @@ Search forward for articles containing a match for @var{regexp}. Exit the summary buffer and return to the group buffer. @end table +@node Host Security +@section Host Security +@cindex security + +Emacs runs inside an operating system such as GNU/Linux, and relies on +the operating system to check security constraints such as accesses to +files. The default settings for Emacs are designed for typical use; +they may require some tailoring in environments where security is more +of a concern, or less of a concern, than usual. For example, +file-local variables can be risky, and you can set the variable +@code{enable-local-variables} to @code{:safe} or (even more +conservatively) to @code{nil}; conversely, if your files can all be +trusted and the default checking for these variables is irritating, +you can set @code{enable-local-variables} to @code{:all}. @xref{Safe +File Variables}. + +@xref{Security Considerations,,, elisp, The Emacs Lisp Reference +Manual}, for more information about security considerations when using +Emacs as part of a larger application. @node Network Security @section Network Security @@ -741,6 +761,10 @@ advancing point, and any terminal input for the subshell comes from text in the buffer. To give input to the subshell, go to the end of the buffer and type the input, terminated by @key{RET}. + By default, when the subshell is invoked interactively, the +@file{*shell*} buffer is displayed in a new window. This behavior can +be customized via @code{display-buffer-alist} (@pxref{Window Choice}). + While the subshell is waiting or running a command, you can switch windows or buffers and perform other editing in Emacs. Emacs inserts the output from the subshell into the Shell buffer whenever it has diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 1a6a735d3ae..5f80b0afe3f 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -59,7 +59,12 @@ The package's version number (e.g., @samp{11.86}). The package's status---normally one of @samp{available} (can be downloaded from the package archive), @samp{installed}, @c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}), -or @samp{built-in} (included in Emacs by default). +or @samp{built-in} (included in Emacs by default). The status +@samp{external} means the package is not built-in and not from the +directory specified by @code{package-user-dir} (@pxref{Package +Files}). External packages are treated much like built-in: they +cannot be deleted through the package menu, and are not considered for +upgrading. The status can also be @samp{new}. This is equivalent to @samp{available}, except that it means the package became newly @@ -106,7 +111,13 @@ line; typing @kbd{x} (see below) will delete the package. @xref{Package Files}, for information about what package deletion entails. +@item ~ +Mark all obsolete packages for deletion +(@code{package-menu-mark-obsolete-for-deletion}). This marks for +deletion all the packages whose status is @samp{obsolete}. + @item u +@itemx @key{DEL} Remove any installation or deletion mark previously added to the current line by an @kbd{i} or @kbd{d} command. @@ -117,6 +128,7 @@ on the new available versions, and a deletion mark on the old installed versions. @item x +@vindex package-menu-async Download and install all packages marked with @kbd{i}, and their dependencies; also, delete all packages marked with @kbd{d} (@code{package-menu-execute}). This also removes the marks. @@ -131,6 +143,14 @@ Filter the package list (@code{package-menu-filter}). This prompts for a keyword (e.g., @samp{games}), then shows only the packages that relate to that keyword. To restore the full package list, type @kbd{q}. + +@item H +Permanently hide packages that match a regexp +(@code{package-menu-hide-package}). + +@item ( +Toggle visibility of old versions of packages and also of versions +from lower-priority archives (@code{package-menu-toggle-hiding}). @end table @noindent @@ -205,6 +225,17 @@ offer different versions of the same package, you may find the option pairs to this list, to ensure that the specified package is only ever downloaded from the specified archive. +@vindex package-archive-priorities +@vindex package-menu-hide-low-priority + Another option that is useful when you have several package archives +enabled is @code{package-archive-priorities}. It specifies the +priority of each archive (higher numbers specify higher priority +archives). By default, archives have the priority of zero, unless +specified otherwise by this option's value. Packages from +lower-priority archives will not be shown in the menu, if the same +package is available from a higher-priority archive. (This is +controlled by the value of @code{package-menu-hide-low-priority}.) + Once a package is downloaded and installed, it is @dfn{loaded} into the current Emacs session. Loading a package is not quite the same as loading a Lisp library (@pxref{Lisp Libraries}); its effect varies diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 1f2c8b1e1c2..8423b70203c 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -833,9 +833,36 @@ displayed. The default is 102400. @findex show-paren-mode Show Paren mode, a global minor mode, provides a more powerful kind of automatic matching. Whenever point is before an opening delimiter -or after a closing delimiter, both that delimiter and its opposite -delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x -show-paren-mode}. +or after a closing delimiter, the delimiter, its matching delimiter, +and optionally the text between them are highlighted. To toggle Show +Paren mode, type @kbd{M-x show-paren-mode}. To customize it, type +@kbd{M-x customize-group @key{RET} paren-showing}. The customizable +options which control the operation of this mode include: + +@itemize @bullet +@item +@code{show-paren-highlight-open-paren} controls whether to highlight +an open paren when point stands just before it, and hence its position +is marked by the cursor anyway. The default is non-@code{nil} (yes). + +@item +@code{show-paren-style} controls whether just the two parens, or also +the space between them get highlighted. The valid options here are +@code{parenthesis} (show the matching paren), @code{expression} +(highlight the entire expression enclosed by the parens), and +@code{mixed} (highlight the matching paren if it is visible, the +expression otherwise). + +@item +@code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes +highlighting also when point is on the inside of a parenthesis. + +@item +@code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes +highlighting also when point is in whitespace at the beginning or end +of a line, and there is a paren at, respectively, the first or last, +or the last, non-whitespace position on the line. +@end itemize @cindex Electric Pair mode @cindex inserting matching parentheses @@ -917,6 +944,8 @@ will indent the comment to the appropriate position. @item @kbd{M-;} Insert or realign comment on current line; if the region is active, comment or uncomment the region instead (@code{comment-dwim}). +@item @kbd{C-x C-;} +Comment or uncomment the current line (@code{comment-line}). @item @kbd{C-u M-;} Kill comment on current line (@code{comment-kill}). @item @kbd{C-x ;} @@ -971,6 +1000,18 @@ are not moved. Even when an existing comment is properly aligned, @kbd{M-;} is still useful for moving directly to the start of the comment text. +@findex comment-line +@kindex C-x C-; + @kbd{C-x C-;} (@code{comment-line}) comments or uncomments complete +lines. When a region is active (@pxref{Mark}), @kbd{C-x C-;} either +comments or uncomments the lines in the region. If the region is not +active, this command comments or uncomments the line point is on. +With a positive prefix argument @var{n}, it operates on @var{n} lines +starting with the current one; with a negative @var{n}, it affects +@var{n} preceding lines. After invoking this command with a negative +argument, successive invocations with a positive argument will operate +on preceding lines as if the argument were negated. + @findex comment-kill @kindex C-u M-; @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any @@ -1220,13 +1261,16 @@ variables that you want to use. @xref{Name Help}. @cindex Eldoc mode @findex eldoc-mode +@findex global-eldoc-mode Eldoc is a buffer-local minor mode that helps with looking up Lisp documentation. When it is enabled, the echo area displays some useful information whenever there is a Lisp function or variable at point; for a function, it shows the argument list, and for a variable it shows the first line of the variable's documentation string. To -toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used -with the Emacs Lisp and Lisp Interaction major modes. +toggle Eldoc mode, type @kbd{M-x eldoc-mode}. There's also a Global +Eldoc mode, which is turned on by default, and affects buffers, such +as @samp{*scratch*}, whose major mode is Emacs Lisp or Lisp +Interaction (@w{@kbd{M-x global-eldoc-mode}} to turn it off globally). @node Hideshow @section Hideshow minor mode @@ -1484,14 +1528,21 @@ with the Foldout package (@pxref{Foldout}). @findex prettify-symbols-mode Prettify Symbols mode is a buffer-local minor mode that replaces -certain strings with more attractive versions for display -purposes. For example, in Emacs Lisp mode, it replaces the string -@samp{lambda} with the Greek lambda character @samp{λ}. You may wish -to use this -in non-programming modes as well. You can customize the mode by -adding more entries to @code{prettify-symbols-alist}. There is also a -global version, @code{global-prettify-symbols-mode}, which enables the -mode in all buffers that support it. +certain strings with more attractive versions for display purposes. +For example, in Emacs Lisp mode, it replaces the string @samp{lambda} +with the Greek lambda character @samp{λ}. You may wish to use this in +non-programming modes as well. You can customize the mode by adding +more entries to @code{prettify-symbols-alist}. More elaborate +customization is available via customizing +@code{prettify-symbols-compose-predicate} if its default value +@code{prettify-symbols-default-compose-p} is not appropriate. There +is also a global version, @code{global-prettify-symbols-mode}, which +enables the mode in all buffers that support it. + + The symbol at point can be shown in its original form. This is +controlled by the variable @code{prettify-symbols-unprettify-at-point}: +if non-@code{nil}, the original form of symbol at point will be +restored for as long as point is at it. @node C Modes diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index d8841caa311..13c03f78a52 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -293,9 +293,11 @@ various files. Set the bookmark for the visited file, at point. @item C-x r m @var{bookmark} @key{RET} -@findex bookmark-set Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). +@item C-x r M @var{bookmark} @key{RET} +Like @kbd{C-x r m}, but don't overwrite an existing bookmark. + @item C-x r b @var{bookmark} @key{RET} @findex bookmark-jump Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). @@ -320,6 +322,12 @@ name. If you name each bookmark after the file it points to, then you can conveniently revisit any of those files with @kbd{C-x r b}, and move to the position of the bookmark at the same time. +@kindex C-x r M +@findex bookmark-set-no-overwrite + The command @kbd{C-x r M} (@code{bookmark-set-no-overwrite}) works +like @kbd{C-x r m}, but it signals an error if the specified bookmark +already exists, instead of overwriting it. + @kindex C-x r l To display a list of all your bookmarks in a separate buffer, type @kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index 6e2a60b6378..b37f42cc56f 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -282,9 +282,9 @@ current message and select another. @kbd{d} messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward}) moves to the previous nondeleted message. If there is no nondeleted message to move to in the specified direction, the message that was just -deleted remains current. @kbd{d} with a prefix argument is equivalent -to @kbd{C-d}. Note that the Rmail summary versions of these commands -behave slightly differently (@pxref{Rmail Summary Edit}). +deleted remains current. A numeric prefix argument serves as a repeat +count, to allow deletion of several messages in a single command. A +negative argument reverses the meaning of @kbd{d} and @kbd{C-d}. @c mention other hooks, e.g., show message hook? @vindex rmail-delete-message-hook @@ -305,7 +305,8 @@ type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still effect of a @kbd{d} command in most cases. It undeletes the current message if the current message is deleted. Otherwise it moves backward to previous messages until a deleted message is found, and undeletes -that message. +that message. A numeric prefix argument serves as a repeat count, to +allow deletion of several messages in a single command. You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves back to and undeletes the message that the @kbd{d} deleted. But @@ -974,13 +975,11 @@ different lines. It doesn't matter what Emacs command you use to move point; whichever line point is on at the end of the command, that message is selected in the Rmail buffer. - Almost all Rmail commands work in the summary buffer as well as in the -Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current -message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the -summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u} -serves as a repeat count. A negative argument reverses the meaning of -@kbd{d} and @kbd{C-d}. Also, if there are no more undeleted messages in -the relevant direction, the delete commands go to the first or last + Almost all Rmail commands work in the summary buffer as well as in +the Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the +current message, @kbd{u} undeletes, and @kbd{x} expunges. (However, +in the summary buffer, if there are no more undeleted messages in the +relevant direction, the delete commands go to the first or last message, rather than staying on the current message.) @kbd{o} and @kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply to it; etc. You can scroll the current message while remaining in the @@ -1224,6 +1223,15 @@ tagline (except for buttons for other actions, if there are any). Type the undecoded @acronym{MIME} data. With a prefix argument, this command toggles the display of only an entity at point. +@vindex rmail-mime-prefer-html + If the message has an @acronym{HTML} @acronym{MIME} part, Rmail +displays it in preference to the plain-text part, if Emacs can render +@acronym{HTML}@footnote{ +This capability requires that Emacs be built with @file{libxml2} +support or that you have the Lynx browser installed.}. To prevent +that, and have the plain-text part displayed instead, customize the +variable @code{rmail-mime-prefer-html} to a @code{nil} value. + To prevent Rmail from handling MIME decoded messages, change the variable @code{rmail-enable-mime} to @code{nil}. When this is the case, the @kbd{v} (@code{rmail-mime}) command instead creates a diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index ae275d1ca67..1cc7753f113 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -26,9 +26,11 @@ thing, but search for patterns instead of fixed strings. * Regexps:: Syntax of regular expressions. * Regexp Backslash:: Regular expression constructs starting with `\'. * Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. +* Lax Search:: Search ignores some distinctions among + similar characters, like letter-case. * Replace:: Search, and replace some or all matches. * Other Repeating Search:: Operating on all matches for some regexp. +* Search Customizations:: Various search customizations. @end menu @node Incremental Search @@ -54,10 +56,10 @@ Incremental search backward (@code{isearch-backward}). @menu * Basic Isearch:: Basic incremental search commands. * Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. * Isearch Yank:: Commands that grab text into the search string or else edit the search string. +* Error in Isearch:: When your string is not found. +* Special Isearch:: Special input in incremental search. * Not Exiting Isearch:: Prefix argument and scrolling commands. * Isearch Minibuffer:: Incremental search of the minibuffer history. @end menu @@ -89,31 +91,46 @@ cursor moves to just after the first @samp{FOO}. @cindex isearch face At each step, Emacs highlights the @dfn{current match}---the buffer text that matches the search string---using the @code{isearch} face -(@pxref{Faces}). The current search string is also displayed in the -echo area. +(@pxref{Faces}). @xref{Search Customizations}, for various options +that customize this highlighting. The current search string is also +displayed in the echo area. If you make a mistake typing the search string, type @key{DEL}. Each @key{DEL} cancels the last character of the search string. +@xref{Error in Isearch}, for more about dealing with unsuccessful +search. +@cindex exit incremental search +@cindex incremental search, exiting When you are satisfied with the place you have reached, type @key{RET}. This stops searching, leaving the cursor where the search brought it. Also, any command not specially meaningful in searches stops the searching and is then executed. Thus, typing @kbd{C-a} -exits the search and then moves to the beginning of the line. -@key{RET} is necessary only if the next command you want to type is a -printing character, @key{DEL}, @key{RET}, or another character that is -special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, -@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others -described below). +exits the search and then moves to the beginning of the line; typing +one of the arrow keys exits the search and performs the respective +movement command; etc. @key{RET} is necessary only if the next +command you want to type is a printing character, @key{DEL}, +@key{RET}, or another character that is special within searches +(@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, @kbd{C-y}, @kbd{M-y}, +@kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others described below). +You can fine-tune the commands that exit the search; see @ref{Not +Exiting Isearch}. As a special exception, entering @key{RET} when the search string is empty launches nonincremental search (@pxref{Nonincremental Search}). +(This can be customized; see @ref{Search Customizations}.) + + To abandon the search and return to the place where you started, +type @kbd{@key{ESC} @key{ESC} @key{ESC}} (@code{isearch-cancel}) or +@kbd{C-g C-g} (@code{isearch-abort}). When you exit the incremental search, it adds the original value of point to the mark ring, without activating the mark; you can thus use -@kbd{C-u C-@key{SPC}} to return to where you were before beginning the -search. @xref{Mark Ring}. It only does this if the mark was not -already active. +@kbd{C-u C-@key{SPC}} or @kbd{C-x C-x} to return to where you were +before beginning the search. @xref{Mark Ring}. (Emacs only does this +if the mark was not already active; if the mark was active when you +started the search, both @kbd{C-u C-@key{SPC}} and @kbd{C-x C-x} will +go to the mark.) @kindex C-r @findex isearch-backward @@ -134,7 +151,6 @@ characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward incremental search repeats the backward search. @cindex lazy search highlighting -@vindex isearch-lazy-highlight If you pause for a little while during incremental search, Emacs highlights all the other possible matches for the search string that are present on the screen. This helps you anticipate where you can @@ -142,21 +158,26 @@ get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search. The other matches are highlighted differently from the current match, using the customizable face @code{lazy-highlight} (@pxref{Faces}). If you don't like this feature, you can disable it by setting -@code{isearch-lazy-highlight} to @code{nil}. +@code{isearch-lazy-highlight} to @code{nil}. For other customizations +related to highlighting matches, see @ref{Search Customizations}. After exiting a search, you can search for the same string again by typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that invokes incremental search, and the second @kbd{C-s} means to search -again. Similarly, @kbd{C-r C-r} searches backward for the last -search string. In determining the last search string, it doesn't -matter whether the string was searched for with @kbd{C-s} or -@kbd{C-r}. +again for the last search string. Similarly, @kbd{C-r C-r} searches +backward for the last search string. In determining the last search +string, it doesn't matter whether that string was searched for with +@kbd{C-s} or @kbd{C-r}. If you are searching forward but you realize you were looking for something before the starting point, type @kbd{C-r} to switch to a backward search, leaving the search string unchanged. Similarly, @kbd{C-s} in a backward search switches to a forward search. +@cindex search, wrapping around +@cindex search, overwrapped +@cindex wrapped search +@cindex overwrapped search If a search is failing and you ask to repeat it by typing another @kbd{C-s}, it starts again from the beginning of the buffer. Repeating a failing reverse search with @kbd{C-r} starts again from @@ -169,19 +190,86 @@ you have already seen. @cindex search ring @kindex M-n @r{(Incremental search)} @kindex M-p @r{(Incremental search)} +@vindex search-ring-max To reuse earlier search strings, use the @dfn{search ring}. The commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search string to reuse. These commands leave the selected search ring -element in the minibuffer, where you can edit it. - +element in the minibuffer, where you can edit it. Type +@kbd{C-s}/@kbd{C-r} or @key{RET} to accept the string and start +searching for it. The number of most recently used search strings +saved in the search ring is specified by the variable +@code{search-ring-max}, 16 by default. + +@cindex incremental search, edit search string +@cindex interactively edit search string @kindex M-e @r{(Incremental search)} +@kindex Mouse-1 @r{in the minibuffer (Incremental Search)} To edit the current search string in the minibuffer without -replacing it with items from the search ring, type @kbd{M-e}. Type @key{RET}, -@kbd{C-s} or @kbd{C-r} to finish editing the string and search for it. +replacing it with items from the search ring, type @kbd{M-e} or click +@kbd{Mouse-1} in the minibuffer. Type @key{RET}, @kbd{C-s} or +@kbd{C-r} to finish editing the string and search for it. Type +@kbd{C-f} or @kbd{@key{RIGHT}} to add to the search string characters +following point from the buffer from which you started the search. + +@node Isearch Yank +@subsection Isearch Yanking + + In many cases, you will want to use text at or near point as your +search string. The commands described in this subsection let you do +that conveniently. + +@kindex C-w @r{(Incremental search)} +@findex isearch-yank-word-or-char + @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next +character or word at point to the search string. This is an easy way +to search for another occurrence of the text at point. (The decision +of whether to copy a character or a word is heuristic.) + +@kindex M-s C-e @r{(Incremental search)} +@findex isearch-yank-line + Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest +of the current line to the search string. If point is already at the +end of a line, it appends the next line. With a prefix argument +@var{n}, it appends the next @var{n} lines. + +@kindex C-y @r{(Incremental search)} +@kindex M-y @r{(Incremental search)} +@kindex Mouse-2 @r{in the minibuffer (Incremental search)} +@findex isearch-yank-kill +@findex isearch-yank-pop +@findex isearch-yank-x-selection + Within incremental search, @kbd{C-y} (@code{isearch-yank-kill}) +appends the current kill to the search string. @kbd{M-y} +(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that +appended text with an earlier kill, similar to the usual @kbd{M-y} +(@code{yank-pop}) command (@pxref{Yanking}). Clicking @kbd{Mouse-2} +in the echo area appends the current X selection (@pxref{Primary +Selection}) to the search string (@code{isearch-yank-x-selection}). + +@kindex C-M-w @r{(Incremental search)} +@kindex C-M-y @r{(Incremental search)} +@findex isearch-del-char +@findex isearch-yank-char + @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character +from the search string, and @kbd{C-M-y} (@code{isearch-yank-char}) +appends the character after point to the search string. An +alternative method to add the character after point is to enter the +minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f} +or @kbd{@key{RIGHT}} at the end of the search string in the +minibuffer. Each @kbd{C-f} or @kbd{@key{RIGHT}} you type adds another +character following point to the search string. + + Normally, when the search is case-insensitive, text yanked into the +search string is converted to lower case, so that the search remains +case-insensitive (@pxref{Lax Search, case folding}). However, if the +value of the variable @code{search-upper-case} (@pxref{Lax Search, +search-upper-case}) is other than @code{not-yanks}, that disables this +down-casing. @node Error in Isearch @subsection Errors in Incremental Search +@cindex isearch-fail face If your string is not found at all, the echo area says @samp{Failing I-Search}, and the cursor moves past the place where Emacs found as much of your string as it could. Thus, if you search for @samp{FOOT}, @@ -192,12 +280,13 @@ string that failed to match is highlighted using the face At this point, there are several things you can do. If your string was mistyped, you can use @key{DEL} to erase some of it and correct -it. If you like the place you have found, you can type @key{RET} to -remain there. Or you can type @kbd{C-g}, which removes from the -search string the characters that could not be found (the @samp{T} in -@samp{FOOT}), leaving those that were found (the @samp{FOO} in -@samp{FOOT}). A second @kbd{C-g} at that point cancels the search -entirely, returning point to where it was when the search started. +it, or you can type @kbd{M-e} and edit it. If you like the place you +have found, you can type @key{RET} to remain there. Or you can type +@kbd{C-g}, which removes from the search string the characters that +could not be found (the @samp{T} in @samp{FOOT}), leaving those that +were found (the @samp{FOO} in @samp{FOOT}). A second @kbd{C-g} at +that point cancels the search entirely, returning point to where it +was when the search started. @cindex quitting (in search) @kindex C-g @r{(Incremental search)} @@ -216,34 +305,21 @@ search. @node Special Isearch @subsection Special Input for Incremental Search - Some of the characters you type during incremental search have -special effects. + In addition to characters described in the previous subsections, +some of the other characters you type during incremental search have +special effects. They are described here. -@cindex lax space matching -@kindex M-s SPC @r{(Incremental search)} -@kindex SPC @r{(Incremental search)} -@findex isearch-toggle-lax-whitespace -@vindex search-whitespace-regexp - By default, incremental search performs @dfn{lax space matching}: -each space, or sequence of spaces, matches any sequence of one or more -spaces in the text. Hence, @samp{foo bar} matches @samp{foo bar}, -@samp{foo@w{ }bar}, @samp{foo@w{ }bar}, and so on (but not -@samp{foobar}). More precisely, Emacs matches each sequence of space -characters in the search string to a regular expression specified by -the variable @code{search-whitespace-regexp}. For example, to make -spaces match sequences of newlines as well as spaces, set it to -@samp{"[[:space:]\n]+"}. - - To toggle lax space matching, type @kbd{M-s @key{SPC}} -(@code{isearch-toggle-lax-whitespace}). To disable this feature -entirely, change @code{search-whitespace-regexp} to @code{nil}; then -each space in the search string matches exactly one space. - - If the search string you entered contains only lower-case letters, -the search is case-insensitive; as long as an upper-case letter exists -in the search string, the search becomes case-sensitive. If you -delete the upper-case character from the search string, it ceases to -have this effect. @xref{Search Case}. + To toggle lax space matching (@pxref{Lax Search, lax space +matching}), type @kbd{M-s @key{SPC}}. + + To toggle case sensitivity of the search, type @kbd{M-c} or +@kbd{M-s c}. @xref{Lax Search, case folding}. If the search string +includes upper-case letters, the search is case-sensitive by default. + + To toggle whether or not the search will consider similar and +equivalent characters as a match, type @kbd{M-s '}. @xref{Lax Search, +character folding}. If the search string includes accented +characters, that disables character folding during that search. @cindex invisible text, searching for @kindex M-s i @r{(Incremental search)} @@ -251,7 +327,17 @@ have this effect. @xref{Search Case}. To toggle whether or not invisible text is searched, type @kbd{M-s i} (@code{isearch-toggle-invisible}). @xref{Outline Search}. - To search for a newline character, type @kbd{C-j}. +@kindex M-r @r{(Incremental Search)} +@kindex M-s r @r{(Incremental Search)} +@findex isearch-toggle-regexp + To toggle between non-regexp and regexp incremental search, type +@kbd{M-r} or @kbd{M-s r} (@code{isearch-toggle-regexp}). +@xref{Regexp Search}. + + To toggle symbol mode, type @kbd{M-s _}. @xref{Symbol Search}. + + To search for a newline character, type @kbd{C-j} as part of the +search string. To search for non-@acronym{ASCII} characters, use one of the following methods: @@ -265,17 +351,21 @@ example, @kbd{C-q C-s} during incremental search adds the @samp{control-S} character to the search string. @item -Type @kbd{C-x 8 @key{RET}}, followed by a Unicode name or code-point. -This adds the specified character into the search string, similar to -the usual @code{insert-char} command (@pxref{Inserting Text}). +Type @kbd{C-x 8 @key{RET}}, followed by a Unicode name or code-point +in hex. This adds the specified character into the search string, +similar to the usual @code{insert-char} command (@pxref{Inserting +Text}). @item +@kindex C-^ @r{(Incremental Search)} +@findex isearch-toggle-input-method +@findex isearch-toggle-specified-input-method Use an input method (@pxref{Input Methods}). If an input method is -enabled in the current buffer when you start the search, you can use -it in the search string also. While typing the search string, you can -toggle the input method with @kbd{C-\} -(@code{isearch-toggle-input-method}). You can also turn on a -non-default input method with @kbd{C-^} +enabled in the current buffer when you start the search, the same +method will be active in the minibuffer when you type the search +string. While typing the search string, you can toggle the input +method with @kbd{C-\} (@code{isearch-toggle-input-method}). You can +also turn on a non-default input method with @kbd{C-^} (@code{isearch-toggle-specified-input-method}), which prompts for the name of the input method. When an input method is active during incremental search, the search prompt includes the input method @@ -286,13 +376,17 @@ I-search [@var{im}]: @end example @noindent -@findex isearch-toggle-input-method -@findex isearch-toggle-specified-input-method where @var{im} is the mnemonic of the active input method. Any input method you enable during incremental search remains enabled in the current buffer afterwards. @end itemize +@kindex M-s o @r{(Incremental Search)} +@findex isearch-occur + Typing @kbd{M-s o} in incremental search invokes +@code{isearch-occur}, which runs @code{occur} with the current search +string. @xref{Other Repeating Search, occur}. + @kindex M-% @r{(Incremental search)} Typing @kbd{M-%} in incremental search invokes @code{query-replace} or @code{query-replace-regexp} (depending on search mode) with the @@ -302,83 +396,72 @@ prefix argument means to replace backward. @xref{Query Replace}. @kindex M-TAB @r{(Incremental search)} Typing @kbd{M-@key{TAB}} in incremental search invokes @code{isearch-complete}, which attempts to complete the search string -using the search ring as a list of completion alternatives. -@xref{Completion}. In many operating systems, the @kbd{M-@key{TAB}} -key sequence is captured by the window manager; you then need to -rebind @code{isearch-complete} to another key sequence if you want to -use it (@pxref{Rebinding}). - +using the search ring (the previous search strings you used) as a list +of completion alternatives. @xref{Completion}. In many operating +systems, the @kbd{M-@key{TAB}} key sequence is captured by the window +manager; you then need to rebind @code{isearch-complete} to another +key sequence if you want to use it (@pxref{Rebinding}). + +@kindex M-s h r @r{(Incremental Search)} +@findex isearch-highlight-regexp + You can exit the search while leaving the matches for the last +search string highlighted on display. To this end, type @kbd{M-s h r} +(@code{isearch-highlight-regexp}), which will run +@code{highlight-regexp} (@pxref{Highlight Interactively}) passing +it the regexp derived from the last search string and prompting you +for the face to use for highlighting. To remove the highlighting, +type @kbd{M-s h u} (@code{unhighlight-regexp}). + +@cindex incremental search, help on special keys +@kindex C-h C-h @r{(Incremental Search)} +@findex isearch-help-map @vindex isearch-mode-map - When incremental search is active, you can type @kbd{C-h C-h} to -access interactive help options, including a list of special key -bindings. These key bindings are part of the keymap -@code{isearch-mode-map} (@pxref{Keymaps}). - -@node Isearch Yank -@subsection Isearch Yanking - -@kindex C-y @r{(Incremental search)} -@kindex M-y @r{(Incremental search)} -@findex isearch-yank-kill -@findex isearch-yank-pop - Within incremental search, @kbd{C-y} (@code{isearch-yank-kill}) -appends the current kill to the search string. @kbd{M-y} -(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that -appended text with an earlier kill, similar to the usual @kbd{M-y} -(@code{yank-pop}) command (@pxref{Yanking}). @kbd{Mouse-2} appends -the current X selection (@pxref{Primary Selection}). - -@kindex C-w @r{(Incremental search)} -@findex isearch-yank-word-or-char - @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next -character or word at point to the search string. This is an easy way -to search for another occurrence of the text at point. (The decision -of whether to copy a character or a word is heuristic.) - -@kindex M-s C-e @r{(Incremental search)} -@findex isearch-yank-line - Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest -of the current line to the search string. If point is already at the -end of a line, it appends the next line. With a prefix argument -@var{n}, it appends the next @var{n} lines. - - If the search is currently case-insensitive, both @kbd{C-w} and -@kbd{M-s C-e} convert the text they copy to lower case, so that the -search remains case-insensitive. - -@kindex C-M-w @r{(Incremental search)} -@kindex C-M-y @r{(Incremental search)} -@findex isearch-del-char -@findex isearch-yank-char - @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character -from the search string, and @kbd{C-M-y} (@code{isearch-yank-char}) -appends the character after point to the search string. An -alternative method to add the character after point is to enter the -minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f} -at the end of the search string in the minibuffer. + When incremental search is active, you can type @kbd{C-h C-h} +(@code{isearch-help-map}) to access interactive help options, +including a list of special key bindings. These key bindings are part +of the keymap @code{isearch-mode-map} (@pxref{Keymaps}). @node Not Exiting Isearch @subsection Not Exiting Incremental Search -This subsection describes two categories of commands which you can -type without exiting the current incremental search, even though they -are not themselves part of incremental search. +This subsection describes how to control whether typing a command not +specifically meaningful is searches exits the search before executing +the command. It also describes two categories of commands which you +can type without exiting the current incremental search, even though +they are not themselves part of incremental search. + +@vindex search-exit-option + Normally, typing a command that is not bound by the incremental +search exits the search before executing the command. Thus, the +command operates on the buffer from which you invoked the search. +However, if you customize the variable @code{search-exit-option} to +@code{nil}, the characters which you type that are not interpreted by +the incremental search are simply appended to the search string. This +is so you could include in the search string control characters, such +as @kbd{C-a}, that would normally exit the search and invoke the +command bound to them on the buffer. @table @asis @item Prefix Arguments +@cindex prefix argument commands, during incremental search @vindex isearch-allow-prefix - In incremental search, when you enter a prefix argument -(@pxref{Arguments}), by default it will apply either to the next -action in the search or to the command that exits the search. + In incremental search, when you type a command that specifies a +prefix argument (@pxref{Arguments}), by default it will apply either +to the next action in the search or to the command that exits the +search. In other words, entering a prefix argument will not by itself +terminate the search. In previous versions of Emacs, entering a prefix argument always terminated the search. You can revert to this behavior by setting the variable @code{isearch-allow-prefix} to @code{nil}. When @code{isearch-allow-scroll} is non-@code{nil} (see below), -prefix arguments always have the default behavior described above. +prefix arguments always have the default behavior described above, +i.e., they don't terminate the search, even if +@code{isearch-allow-prefix} is @code{nil}. @item Scrolling Commands +@cindex scrolling commands, during incremental search @vindex isearch-allow-scroll Normally, scrolling commands exit incremental search. If you change the variable @code{isearch-allow-scroll} to a non-@code{nil} value, @@ -390,12 +473,14 @@ prefix arguments to these commands in the usual way. This feature won't let you scroll the current match out of visibility, however. The @code{isearch-allow-scroll} feature also affects some other -commands, such as @kbd{C-x 2} (@code{split-window-below}) and @kbd{C-x -^} (@code{enlarge-window}), which don't exactly scroll but do affect -where the text appears on the screen. It applies to any command whose -name has a non-@code{nil} @code{isearch-scroll} property. So you can -control which commands are affected by changing these properties. - +commands, such as @kbd{C-x 2} (@code{split-window-below}) and +@kbd{C-x ^} (@code{enlarge-window}), which don't exactly scroll but do +affect where the text appears on the screen. It applies to any +command whose name has a non-@code{nil} @code{isearch-scroll} +property. So you can control which commands are affected by changing +these properties. + +@cindex prevent commands from exiting incremental search For example, to make @kbd{C-h l} usable within an incremental search in all future Emacs sessions, use @kbd{C-h c} to find what command it runs (@pxref{Key Help}), which is @code{view-lossage}. Then you can @@ -409,7 +494,8 @@ put the following line in your init file (@pxref{Init File}): This feature can be applied to any command that doesn't permanently change point, the buffer contents, the match data, the current buffer, or the selected window and frame. The command must not itself attempt -an incremental search. +an incremental search. This feature is disabled if +@code{isearch-allow-scroll} is @code{nil} (which it is by default). @end table @node Isearch Minibuffer @@ -455,14 +541,22 @@ This enters the minibuffer to read the search string; terminate the string with @key{RET}, and then the search takes place. If the string is not found, the search command signals an error. -@findex search-forward -@findex search-backward When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental search as usual. That command is specially programmed to invoke the -command for nonincremental search, @code{search-forward}, if the -string you specify is empty. (Such an empty argument would otherwise -be useless.) @kbd{C-r @key{RET}} does likewise, invoking the command -@code{search-backward}. +command for nonincremental search, if the string you specify is empty. +(Such an empty argument would otherwise be useless.) @kbd{C-r +@key{RET}} does likewise, invoking the nonincremental +backward-searching command. + + Nonincremental search can also be invoked form the menu bar's +@samp{Edit->Search} menu. + +@findex search-forward +@findex search-backward + You can also use two simpler commands, @kbd{M-x search-forward} and +@kbd{M-x search-backward}. These commands look for the literal +strings you specify, and don't support any of the lax-search features +(@pxref{Lax Search}) except case folding. @node Word Search @section Word Search @@ -475,11 +569,13 @@ search matches any sequence of those two words separated by one or more spaces, newlines, or other punctuation characters. This is particularly useful for searching text documents, because you don't have to worry whether the words you are looking for are separated by -newlines or spaces. +newlines or spaces. Note that major modes for programming languages +or other specialized modes can modify the definition of a word to suit +their syntactic needs. @table @kbd @item M-s w -If incremental search is active, toggle word search mode + If incremental search is active, toggle word search mode (@code{isearch-toggle-word}); otherwise, begin an incremental forward word search (@code{isearch-forward-word}). @item M-s w @key{RET} @var{words} @key{RET} @@ -514,6 +610,18 @@ so that the matching can proceed incrementally as you type. This additional laxity does not apply to the lazy highlight (@pxref{Incremental Search}), which always matches whole words. + The word search commands don't perform character folding, and +toggling lax whitespace matching (@pxref{Lax Search, lax space +matching}) has no effect on them. + +@kindex M-s M-w +@findex eww-search-word +@vindex eww-search-prefix + Search the Web for the text in region. This command performs an +Internet search for the words in region using the search engine whose +@acronym{URL} is specified by the variable @code{eww-search-prefix}. +@xref{Basics, EWW, , eww, The Emacs Web Wowser Manual}. + @node Symbol Search @section Symbol Search @cindex symbol search @@ -529,6 +637,7 @@ searching source code. @table @kbd @item M-s _ +@findex isearch-toggle-symbol If incremental search is active, toggle symbol search mode (@code{isearch-toggle-symbol}); otherwise, begin an incremental forward symbol search (@code{isearch-forward-symbol}). @@ -561,6 +670,10 @@ search. In nonincremental symbol searches, the beginning and end of the search string are required to match the beginning and end of a symbol, respectively. + The symbol search commands don't perform character folding, and +toggling lax whitespace matching (@pxref{Lax Search, lax space +matching}) has no effect on them. + @node Regexp Search @section Regular Expression Search @cindex regexp search @@ -595,22 +708,31 @@ for. To search backward for a regexp, use @kbd{C-M-r} (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, or @kbd{M-r} within a backward incremental search. +@vindex regexp-search-ring-max All of the special key sequences in an ordinary incremental search -do similar things in an incremental regexp search. For instance, -typing @kbd{C-s} immediately after starting the search retrieves the -last incremental search regexp used and searches forward for it. -Incremental regexp and non-regexp searches have independent defaults. -They also have separate search rings, which you can access with -@kbd{M-p} and @kbd{M-n}. +(@pxref{Special Isearch}) do similar things in an incremental regexp +search. For instance, typing @kbd{C-s} immediately after starting the +search retrieves the last incremental search regexp used and searches +forward for it. Incremental regexp and non-regexp searches have +independent defaults. They also have separate search rings, which you +can access with @kbd{M-p} and @kbd{M-n}. The maximum number of search +regexps saved in the search ring is determined by the value of +@code{regexp-search-ring-max}, 16 by default. Unlike ordinary incremental search, incremental regexp search -do not use lax space matching by default. To toggle this feature +does not use lax space matching by default. To toggle this feature use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}). Then any @key{SPC} typed in incremental regexp search will match any sequence of one or more whitespace characters. The variable @code{search-whitespace-regexp} specifies the regexp for the lax space matching. @xref{Special Isearch}. + Also unlike ordinary incremental search, incremental regexp search +cannot use character folding (@pxref{Lax Search}). (If you toggle +character folding during incremental regexp search with @kbd{M-s '}, +the search becomes a non-regexp search and the search pattern you +typed is interpreted as a literal string.) + In some cases, adding characters to the regexp in an incremental regexp search can make the cursor move back and start again. For example, if you have searched for @samp{foo} and you add @samp{\|bar}, @@ -629,7 +751,10 @@ starting position. These search methods are not mirror images. Nonincremental search for a regexp is done with the commands @code{re-search-forward} and @code{re-search-backward}. You can invoke these with @kbd{M-x}, or by way of incremental regexp search -with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. +with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. When you invoke +these commands with @kbd{M-x}, they search for the exact regexp you +specify, and thus don't support any lax-search features (@pxref{Lax +Search}) except case folding. If you use the incremental regexp search commands with a prefix argument, they perform ordinary string search, like @@ -1030,21 +1155,67 @@ This contains two parts in succession: a character set matching period, @samp{?}, or @samp{!}, and a character set matching close-brackets, quotes, or parentheses, repeated zero or more times. -@node Search Case -@section Searching and Case +@node Lax Search +@section Lax Matching During Searching - Searches in Emacs normally ignore the case of the text they are -searching through, if you specify the text in lower case. Thus, if -you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} -also match. Regexps, and in particular character sets, behave -likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or -@samp{B}. +@cindex lax search +@cindex character equivalence in search + Normally, you'd want search commands to disregard certain minor +differences between the search string you type and the text being +searched. For example, sequences of whitespace characters of +different length are usually perceived as equivalent; letter-case +differences usually don't matter; etc. This is known as +@dfn{character equivalence}. - An upper-case letter anywhere in the incremental search string makes -the search case-sensitive. Thus, searching for @samp{Foo} does not find -@samp{foo} or @samp{FOO}. This applies to regular expression search as -well as to string search. The effect ceases if you delete the -upper-case letter from the search string. + This section describes the Emacs lax search features, and how to +tailor them to your needs. + +@cindex lax space matching in search +@kindex M-s SPC @r{(Incremental search)} +@kindex SPC @r{(Incremental search)} +@findex isearch-toggle-lax-whitespace +@vindex search-whitespace-regexp + By default, search commands perform @dfn{lax space matching}: +each space, or sequence of spaces, matches any sequence of one or more +whitespace characters in the text. (Incremental regexp search has a +separate default; see @ref{Regexp Search}.) Hence, @samp{foo bar} +matches @samp{foo bar}, @samp{foo@w{ }bar}, @samp{foo@w{ }bar}, and +so on (but not @samp{foobar}). More precisely, Emacs matches each +sequence of space characters in the search string to a regular +expression specified by the variable @code{search-whitespace-regexp}. +For example, to make spaces match sequences of newlines as well as +spaces, set it to @samp{"[[:space:]\n]+"}. The default value of this +variable depends on the buffer's major mode; most major modes classify +spaces, tabs, and formfeed characters as whitespace. + + If you want whitespace characters to match exactly, you can turn lax +space matching off by typing @kbd{M-s @key{SPC}} +(@code{isearch-toggle-lax-whitespace}) within an incremental search. +Another @kbd{M-s @key{SPC}} turns lax space matching back on. To +disable lax whitespace matching for all searches, change +@code{search-whitespace-regexp} to @code{nil}; then each space in the +search string matches exactly one space. + +@cindex case folding in search +@cindex case-sensitivity and search + Searches in Emacs by default ignore the case of the text they are +searching through, if you specify the search string in lower case. +Thus, if you specify searching for @samp{foo}, then @samp{Foo} and +@samp{foo} also match. Regexps, and in particular character sets, +behave likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} +or @samp{B}. This feature is known as @dfn{case folding}, and it is +supported in both incremental and non-incremental search modes. + +@vindex search-upper-case + An upper-case letter anywhere in the search string makes the search +case-sensitive. Thus, searching for @samp{Foo} does not find +@samp{foo} or @samp{FOO}. This applies to regular expression search +as well as to literal string search. The effect ceases if you delete +the upper-case letter from the search string. The variable +@code{search-upper-case} controls this: if it is non-@code{nil} (the +default), an upper-case character in the search string make the search +case-sensitive; setting it to @code{nil} disables this effect of +upper-case characters. @vindex case-fold-search If you set the variable @code{case-fold-search} to @code{nil}, then @@ -1055,12 +1226,14 @@ This variable applies to nonincremental searches also, including those performed by the replace commands (@pxref{Replace}) and the minibuffer history matching commands (@pxref{Minibuffer History}). -@c isearch-toggle-case-fold - Typing @kbd{M-c} within an incremental search toggles the case -sensitivity of that search. The effect does not extend beyond the -current incremental search to the next one, but it does override the -effect of adding or removing an upper-case letter in the current -search. +@kindex M-c @r{(Incremental search)} +@kindex M-s c @r{(Incremental search)} +@findex isearch-toggle-case-fold + Typing @kbd{M-c} or @kbd{M-s c} (@code{isearch-toggle-case-fold}) +within an incremental search toggles the case sensitivity of that +search. The effect does not extend beyond the current incremental +search, but it does override the effect of adding or removing an +upper-case letter in the current search. Several related variables control case-sensitivity of searching and matching for specific commands or activities. For instance, @@ -1068,6 +1241,45 @@ matching for specific commands or activities. For instance, @code{find-tag}. To find these variables, do @kbd{M-x apropos-variable @key{RET} case-fold-search @key{RET}}. +@cindex character folding in search +@cindex equivalent character sequences + Case folding disregards case distinctions among characters, making +upper-case characters match lower-case variants, and vice versa. A +generalization of case folding is @dfn{character folding}, which +disregards wider classes of distinctions among similar characters. +For instance, under character folding the letter @code{a} matches all +of its accented cousins like @code{@"a} and @code{@'a}, i.e., the +match disregards the diacritics that distinguish these +variants. In addition, @code{a} matches other characters that +resemble it, or have it as part of their graphical representation, +such as @sc{u+249c parenthesized latin small letter a} and @sc{u+2100 +account of} (which looks like a small @code{a} over @code{c}). +Similarly, the @acronym{ASCII} double-quote character @code{"} matches +all the other variants of double quotes defined by the Unicode +standard. Finally, character folding can make a sequence of one or +more characters match another sequence of a different length: for +example, the sequence of two characters @code{ff} matches @sc{u+fb00 +latin small ligature ff}. Character sequences that are not identical, +but match under character folding are known as @dfn{equivalent +character sequences}. + +@kindex M-s ' @r{(Incremental Search)} +@findex isearch-toggle-character-fold + Generally, search commands in Emacs by default perform character +folding, thus matching equivalent character sequences. You can +disable this behavior by customizing the variable +@code{search-default-regexp-mode} to @code{nil}. @xref{Search +Customizations}. Within an incremental search, typing @kbd{M-s '} +(@code{isearch-toggle-character-fold}) toggles character folding, but +only for that search. (Replace commands have a different default, +controlled by a separate option; see @ref{Replacement and Lax +Matches}.) + + Like with case folding, typing an explicit variant of a character, +such as @code{@"a}, as part of the search string disables character +folding for that search. If you delete such a character from the +search string, this effect ceases. + @node Replace @section Replacement Commands @cindex replacement @@ -1078,7 +1290,8 @@ apropos-variable @key{RET} case-fold-search @key{RET}}. Emacs provides several commands for performing search-and-replace operations. In addition to the simple @kbd{M-x replace-string} command, there is @kbd{M-%} (@code{query-replace}), which presents -each occurrence of the pattern and asks you whether to replace it. +each occurrence of the search pattern and asks you whether to replace +it. The replace commands normally operate on the text from point to the end of the buffer. When the region is active, they operate on it @@ -1087,17 +1300,11 @@ instead (@pxref{Mark}). The basic replace commands replace one is possible to perform several replacements in parallel, using the command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). -@vindex replace-lax-whitespace - Unlike incremental search, the replacement commands do not use lax -space matching (@pxref{Special Isearch}) by default. To enable lax -space matching for replacement, change the variable -@code{replace-lax-whitespace} to @code{t}. (This only affects how -Emacs finds the text to replace, not the replacement text.) - @menu * Unconditional Replace:: Replacing all matches for a string. * Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. +* Replacement and Lax Matches:: + Lax searching for text to replace. * Query Replace:: How to use querying. @end menu @@ -1128,8 +1335,8 @@ activating the mark; use @kbd{C-u C-@key{SPC}} to move back there. A prefix argument restricts replacement to matches that are surrounded by word boundaries. - @xref{Replacement and Case}, for details about case-sensitivity in -replace commands. + @xref{Replacement and Lax Matches}, for details about +case-sensitivity in replace commands. @node Regexp Replace @subsection Regexp Replacement @@ -1137,7 +1344,7 @@ replace commands. The @kbd{M-x replace-string} command replaces exact matches for a single string. The similar command @kbd{M-x replace-regexp} replaces -any match for a specified pattern. +any match for a specified regular expression pattern (@pxref{Regexps}). @table @kbd @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} @@ -1218,9 +1425,28 @@ M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} \,(format "%-72sABC%05d" \& \#) @key{RET} @end example -@node Replacement and Case -@subsection Replace Commands and Case +@node Replacement and Lax Matches +@subsection Replace Commands and Lax Matches + + This subsection describes the behavior of replace commands with +respect to lax matches (@pxref{Lax Search}) and how to customize it. +In general, replace commands mostly default to stricter matching than +their search counterparts. +@cindex lax space matching in replace commands +@vindex replace-lax-whitespace + Unlike incremental search, the replacement commands do not use lax +space matching (@pxref{Lax Search, lax space matching}) by default. +To enable lax space matching for replacement, change the variable +@code{replace-lax-whitespace} to non-@code{nil}. (This only affects +how Emacs finds the text to replace, not the replacement text.) + +@vindex replace-regexp-lax-whitespace + A companion variable @code{replace-regexp-lax-whitespace} controls +whether @code{query-replace-regexp} uses lax whitespace matching when +searching for patterns. + +@cindex case folding in replace commands If the first argument of a replace command is all lower case, the command ignores case while searching for occurrences to replace---provided @code{case-fold-search} is non-@code{nil}. If @@ -1250,6 +1476,15 @@ exactly as given, with no case conversion. Likewise, if either @code{case-replace} or @code{case-fold-search} is set to @code{nil}, replacement is done without case conversion. +@cindex character folding in replace commands + The replacement commands by default do not use character folding +(@pxref{Lax Search, character folding}) when looking for the text to +replace. To enable character folding for matching in +@code{query-replace} and @code{replace-string}, set the variable +@code{replace-character-fold} to a non-@code{nil} value. (This +setting does not affect the replacement text, only how Emacs finds the +text to replace. It also doesn't affect @code{replace-regexp}.) + @node Query Replace @subsection Query Replace @cindex query replace @@ -1270,9 +1505,9 @@ occurrence and asks you whether to replace it. Aside from querying, @code{query-replace} works just like @code{replace-string} (@pxref{Unconditional Replace}). In particular, it preserves case provided @code{case-replace} is non-@code{nil}, as it normally is -(@pxref{Replacement and Case}). A numeric argument means to consider -only occurrences that are bounded by word-delimiter characters. A -negative prefix argument replaces backward. +(@pxref{Replacement and Lax Matches}). A numeric argument means to +consider only occurrences that are bounded by word-delimiter +characters. A negative prefix argument replaces backward. @kindex C-M-% @findex query-replace-regexp @@ -1280,18 +1515,38 @@ negative prefix argument replaces backward. It works like @code{replace-regexp} except that it queries like @code{query-replace}. +@vindex query-replace-from-to-separator + You can reuse earlier replacements with these commands. When +@code{query-replace} or @code{query-replace-regexp} prompts for the +search string, use @kbd{M-p} and @kbd{M-n} to show previous +replacements in the form @samp{@var{from} -> @var{to}}, where +@var{from} is the search pattern, @var{to} is its replacement, and the +separator between them is determined by the value of the variable +@code{query-replace-from-to-separator}. Type @key{RET} to select the +desired replacement. + @cindex faces for highlighting query replace @cindex query-replace face -@cindex lazy-highlight face +@cindex lazy-highlight face, in replace +@vindex query-replace-highlight +@vindex query-replace-lazy-highlight +@vindex query-replace-show-replacement These commands highlight the current match using the face -@code{query-replace}. They highlight other matches using -@code{lazy-highlight} just like incremental search (@pxref{Incremental -Search}). By default, @code{query-replace-regexp} will show the -substituted replacement string for the current match in the -minibuffer. If you want to keep special sequences @samp{\&} and -@samp{\@var{n}} unexpanded, customize +@code{query-replace}. You can disable this highlight by setting the +variable @code{query-replace-highlight} to @code{nil}. They highlight +other matches using @code{lazy-highlight} just like incremental search +(@pxref{Incremental Search}); this can be disabled by setting +@code{query-replace-lazy-highlight} to @code{nil}. By default, +@code{query-replace-regexp} will show the substituted replacement +string for the current match in the minibuffer. If you want to keep +special sequences @samp{\&} and @samp{\@var{n}} unexpanded, customize @code{query-replace-show-replacement} variable. +@vindex query-replace-skip-read-only + The variable @code{query-replace-skip-read-only}, if set +non-@code{nil}, will cause replacement commands to ignore matches in +read-only text. The default is not to ignore them. + The characters you can type when you are shown a match for the string or regexp are: @@ -1311,9 +1566,13 @@ or regexp are: @c WideCommands @table @kbd @item @key{SPC} +@itemx y to replace the occurrence with @var{newstring}. @item @key{DEL} +@itemx @key{Delete} +@itemx @key{BACKSPACE} +@itemx n to skip to the next occurrence without replacing this one. @item , @r{(Comma)} @@ -1329,6 +1588,7 @@ must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart (@pxref{Repetition}). @item @key{RET} +@itemx q to exit without doing any more replacements. @item .@: @r{(Period)} @@ -1338,19 +1598,6 @@ occurrences. @item ! to replace all remaining occurrences without asking again. -@item Y @r{(Upper-case)} -to replace all remaining occurrences in all remaining buffers in -multi-buffer replacements (like the Dired @key{Q} command that performs -query replace on selected files). It answers this question and all -subsequent questions in the series with ``yes'', without further -user interaction. - -@item N @r{(Upper-case)} -to skip to the next buffer in multi-buffer replacements without -replacing remaining occurrences in the current buffer. It answers -this question ``no'', gives up on the questions for the current buffer, -and continues to the next buffer in the sequence. - @item ^ to go back to the position of the previous occurrence (or what used to be an occurrence), in case you changed it by mistake or want to @@ -1378,19 +1625,30 @@ replacement string for any further occurrences. to redisplay the screen. Then you must type another character to specify what to do with this occurrence. +@item Y @r{(Upper-case)} +to replace all remaining occurrences in all remaining buffers in +multi-buffer replacements (like the Dired @key{Q} command that performs +query replace on selected files). It answers this question and all +subsequent questions in the series with ``yes'', without further +user interaction. + +@item N @r{(Upper-case)} +to skip to the next buffer in multi-buffer replacements without +replacing remaining occurrences in the current buffer. It answers +this question ``no'', gives up on the questions for the current buffer, +and continues to the next buffer in the sequence. + @item C-h +@itemx ? +@itemx @key{F1} to display a message summarizing these options. Then you must type another character to specify what to do with this occurrence. @end table - Some other characters are aliases for the ones listed above: @kbd{y}, -@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and -@key{RET}. - Aside from this, any other character exits the @code{query-replace}, and is then reread as part of a key sequence. Thus, if you type @kbd{C-k}, it exits the @code{query-replace} and then kills to end of -line. +line. In particular, @kbd{C-g} simply exits the @code{query-replace}. To restart a @code{query-replace} once it is exited, use @kbd{C-x @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it @@ -1454,12 +1712,17 @@ a multi-file incremental search is activated automatically. @cindex Occur mode @cindex mode, Occur +@cindex match (face name) +@vindex list-matching-lines-default-context-lines @item M-x occur Prompt for a regexp, and display a list showing each line in the -buffer that contains a match for it. To limit the search to part of -the buffer, narrow to that part (@pxref{Narrowing}). A numeric +buffer that contains a match for it. The text that matched is +highlighted using the @code{match} face. To limit the search to part +of the buffer, narrow to that part (@pxref{Narrowing}). A numeric argument @var{n} specifies that @var{n} lines of context are to be -displayed before and after each matching line. +displayed before and after each matching line. The default number of +context lines is specified by the variable +@code{list-matching-lines-default-context-lines}. @kindex RET @r{(Occur mode)} @kindex o @r{(Occur mode)} @@ -1526,3 +1789,89 @@ it never deletes lines that are only partially contained in the region If a match is split across lines, this command keeps all those lines. @end table + +@node Search Customizations +@section Tailoring Search to Your Needs +@cindex search customizations + + This section describes miscellaneous search-related customizations +not described elsewhere. + +@cindex default search mode +@cindex search mode, default + The default search mode for the incremental search is specified by +the variable @code{search-default-regexp-mode}. It can be @code{nil}, +@code{t}, or a function. If it is @code{nil}, the default mode is to +do literal searches without character folding, but with case folding +and lax-whitespace matches as determined by @code{case-fold-search} +and @code{search-whitespace-regexp}, respectively (@pxref{Lax +Search}). If the value is @code{t}, incremental search defaults to +regexp searches. The default value specifies a function that causes +the default search mode to perform character folding in addition to +case folding and lax-whitespace matching. + +@vindex search-highlight + The current match of an on-going incremental search is highlighted +using the @code{isearch} face. This highlighting can be disabled by +setting the variable @code{search-highlight} to @code{nil}. + +@cindex lazy highlighting customizations +@vindex isearch-lazy-highlight +@cindex lazy-highlight face + The other matches for the search string that are visible on display +are highlighted using the @code{lazy-highlight} face. Setting the +variable @code{isearch-lazy-highlight} to @code{nil} disables this +highlighting. Here are some other variables that customize the lazy +highlighting: + +@table @code +@item lazy-highlight-initial-delay +Time in seconds to wait before highlighting visible matches. + +@item lazy-highlight-interval +Time in seconds between highlighting successive matches. + +@item lazy-highlight-max-at-a-time +The maximum number of matches to highlight before checking for input. +A large number can take some time to highlight, so if you want to +continue searching and type @kbd{C-s} or @kbd{C-r} during that time, +Emacs will not respond until it finishes highlighting all those +matches. Thus, smaller values make Emacs more responsive. +@end table + +@vindex search-nonincremental-instead + Normally, entering @key{RET} within incremental search when the +search string is empty launches a nonincremental search. (Actually, +it lets you edit the search string, and the next @key{RET} does the +search.) However, if you customize the variable +@code{search-nonincremental-instead} to @code{nil}, typing @key{RET} +will always exit the incremental search, even if the search string is +empty. + +@vindex isearch-hide-immediately + By default, incremental search and query-replace commands match +invisible text, but hide any such matches as soon as the current match +moves off the invisible text. If you customize the variable +@code{isearch-hide-immediately} to @code{nil}, any invisible text +where matches were found stays on display until the search or the +replace command exits. + +@cindex search display on slow terminals +@vindex search-slow-speed +@vindex search-slow-window-lines + Searching incrementally on slow terminals, such as displays +connected to remote machines over slow connection, could be annoying +due to the need to redraw large portions of the display as the search +proceeds. Emacs provides a special display mode for slow terminals, +whereby search pops up a separate small window and displays the text +surrounding the match in that window. Small windows display faster, +so the annoying effect of slow speed is alleviated. The variable +@code{search-slow-speed} determines the baud rate threshold below +which Emacs will use this display mode. The variable +@code{search-slow-window-lines} controls the number of lines in the +window Emacs pops up for displaying the search results; the default is +1 line. Normally, this window will pop up at the bottom of the window +that displays the buffer where you start searching, bit if the value +of @code{search-slow-window-lines} is negative, that means to put the +window at the top and give it the number of lines that is the absolute +value of that value. diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 087681b5618..4286cfeb737 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -1065,7 +1065,7 @@ send it to the developers. Sending it to recommended, because that list is coupled to a tracking system that makes it easier to locate patches. If your patch is not complete and you think it needs more discussion, you might want to send it to -@email{emacs-devel@@gnu@@gnu.org} instead. If you revise your patch, +@email{emacs-devel@@gnu.org} instead. If you revise your patch, send it as a followup to the initial topic. We prefer to get the patches as plain text, either inline (be careful |