diff options
| -rw-r--r-- | doc/emacs/search.texi | 117 | ||||
| -rw-r--r-- | doc/lispref/commands.texi | 3 | ||||
| -rw-r--r-- | doc/lispref/functions.texi | 7 | ||||
| -rw-r--r-- | doc/lispref/processes.texi | 14 | ||||
| -rw-r--r-- | lisp/emacs-lisp/pcase.el | 18 | ||||
| -rw-r--r-- | lisp/emacs-lisp/rx.el | 2 | ||||
| -rw-r--r-- | lisp/mail/rmailsum.el | 2 | ||||
| -rw-r--r-- | lisp/simple.el | 2 | ||||
| -rw-r--r-- | src/callproc.c | 21 |
9 files changed, 119 insertions, 67 deletions
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index c9f3ccc5481..801e8bb33eb 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -114,24 +114,30 @@ Isearch}, for more about dealing with unsuccessful search. @cindex exit incremental search @cindex incremental search, exiting +@findex isearch-exit +@kindex RET @r{(Incremental search)} 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; 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}. +@key{RET} (@code{isearch-exit}). 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; 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}.) +@findex isearch-abort +@findex isearch-cancel +@kindex C-g C-g @r{(Incremental Search)} +@kindex ESC ESC ESC @r{(Incremental Search)} 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}). @@ -154,13 +160,18 @@ matches that begin after it. @node Repeat Isearch @subsection Repeating Incremental Search +@kindex C-s @r{(Incremental Search)} +@kindex C-r @r{(Incremental Search)} +@findex isearch-repeat-forward +@findex isearch-repeat-backward Suppose you search forward for @samp{FOO} and find a match, but not the one you expected to find: the @samp{FOO} you were aiming for -occurs later in the buffer. In this event, type another @kbd{C-s} to -move to the next occurrence of the search string. You can repeat this -any number of times. If you overshoot, you can cancel some @kbd{C-s} -characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward -incremental search repeats the backward search. +occurs later in the buffer. In this event, type another @kbd{C-s} +(@code{isearch-repeat-forward}) to move to the next occurrence of the +search string. You can repeat this any number of times. If you +overshoot, you can cancel some @kbd{C-s} commands with @key{DEL}. +Similarly, each @kbd{C-r} (@code{isearch-repeat-backward}) in a +backward incremental search repeats the backward search. @cindex lazy search highlighting If you pause for a little while during incremental search, Emacs @@ -200,12 +211,15 @@ going past the original starting point of the search, it changes to you have already seen. @cindex search ring +@findex isearch-ring-advance +@findex isearch-ring-retreat @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 +commands @kbd{M-p} (@code{isearch-ring-retreat}) and @kbd{M-n} +(@code{isearch-ring-advance}) 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. 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 @@ -214,14 +228,16 @@ saved in the search ring is specified by the variable @cindex incremental search, edit search string @cindex interactively edit search string +@findex isearch-edit-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} 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. +replacing it with items from the search ring, type @kbd{M-e} +(@code{isearch-edit-string}) 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 @@ -364,17 +380,22 @@ following methods: @itemize @bullet @item -Type @kbd{C-q}, followed by a non-graphic character or a sequence of -octal digits. This adds a character to the search string, similar to -inserting into a buffer using @kbd{C-q} (@pxref{Inserting Text}). For -example, @kbd{C-q C-s} during incremental search adds the -@samp{control-S} character to the search string. +@findex isearch-quote-char +@kindex C-q @r{(Incremental Search)} +Type @kbd{C-q} (@code{isearch-quote-char}), followed by a non-graphic +character or a sequence of octal digits. This adds a character to the +search string, similar to inserting into a buffer using @kbd{C-q} +(@pxref{Inserting Text}). For 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 -in hex. This adds the specified character into the search string, -similar to the usual @code{insert-char} command (@pxref{Inserting -Text}). +@findex isearch-char-by-name +@kindex C-x 8 RET @r{(Incremental Search)} +Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), 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)} @@ -407,12 +428,20 @@ current buffer afterwards. @code{isearch-occur}, which runs @code{occur} with the current search string. @xref{Other Repeating Search, occur}. +@findex isearch-query-replace +@findex isearch-query-replace-regexp @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 -current search string used as the string to replace. A negative -prefix argument means to replace backward. @xref{Query Replace}. - +@kindex C-M-% @r{(Incremental search)} + Typing @kbd{M-%} (@code{isearch-query-replace}) in incremental +search invokes @code{query-replace} or @code{query-replace-regexp} +(depending on search mode) with the current search string used as the +string to replace. A negative prefix argument means to replace +backward. @xref{Query Replace}. Typing @kbd{C-M-%} +(@code{isearch-query-replace-regexp}) invokes +@code{query-replace-regexp} with the current search string used as the +regexp to replace. + +@findex isearch-complete @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 @@ -618,15 +647,17 @@ Search backward for @var{words}, using a nonincremental word search. Search the Web for the text in region. @end table -@kindex M-s w @findex isearch-forward-word +@findex isearch-toggle-word +@kindex M-s w To begin a forward incremental word search, type @kbd{M-s w}. If incremental search is not already active, this runs the command @code{isearch-forward-word}. If incremental search is already active -(whether a forward or backward search), @kbd{M-s w} switches to a word -search while keeping the direction of the search and the current -search string unchanged. You can toggle word search back off by -typing @kbd{M-s w} again. +(whether a forward or backward search), @kbd{M-s w} runs the command +@code{isearch-toggle-word}, which switches to a word search while +keeping the direction of the search and the current search string +unchanged. You can toggle word search back off by typing @kbd{M-s w} +again. @findex word-search-forward @findex word-search-backward diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 49c839a8971..427379bc79c 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -136,6 +136,9 @@ start with a capital, e.g., @code{"use (system-name) instead."}); @code{t}; any other symbol, which should be an alternative function to use in Lisp code. +Generic functions (@pxref{Generic Functions}) cannot be turned into +commands by adding the @code{interactive} form to them. + @menu * Using Interactive:: General rules for @code{interactive}. * Interactive Codes:: The standard letter-codes for reading arguments diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 3be52d8e624..69e9919f708 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1350,6 +1350,13 @@ to invoke the other auxiliary or primary methods. This allows you to add more methods, distinguished by @var{string}, for the same specializers and qualifiers. @end table + +Functions defined using @code{cl-defmethod} cannot be made +interactive, i.e.@: commands (@pxref{Defining Commands}), by adding +the @code{interactive} form to them. If you need a polymorphic +command, we recommend defining a normal command that calls a +polymorphic function defined via @code{cl-defgeneric} and +@code{cl-defmethod}. @end defmac @cindex dispatch of methods for generic function diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 2afc6a33828..d88c7fbe622 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -609,13 +609,13 @@ Shell mode, because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@: between the process and its children, and because interactive programs treat ptys as terminal devices, whereas pipes don't support these features. However, for subprocesses used by Lisp programs for -internal purposes (i.e., with no user interaction), where significant -amounts of data need to be exchanged between the subprocess and the -Lisp program, it is often better to use a pipe, because pipes are -more efficient, and because they are immune to stray character -injections that ptys introduce for large (around 500 byte) messages. -Also, the total number of ptys is limited on many systems, and it is -good not to waste them unnecessarily. +internal purposes (i.e., no user interaction with the subprocess is +required), where significant amounts of data need to be exchanged +between the subprocess and the Lisp program, it is often better to use +a pipe, because pipes are more efficient, and because they are immune +to stray character injections that ptys introduce for large (around +500 byte) messages. Also, the total number of ptys is limited on many +systems, and it is good not to waste them unnecessarily. @defun make-process &rest args This function is the basic low-level primitive for starting diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el index 57c2d6c3cb5..2746738d41a 100644 --- a/lisp/emacs-lisp/pcase.el +++ b/lisp/emacs-lisp/pcase.el @@ -266,7 +266,8 @@ variable name being but a special case of it)." (defmacro pcase-let* (bindings &rest body) "Like `let*' but where you can use `pcase' patterns for bindings. BODY should be an expression, and BINDINGS should be a list of bindings -of the form (PAT EXP)." +of the form (PATTERN EXP). +See `pcase-let' for discussion of how PATTERN is matched." (declare (indent 1) (debug ((&rest (pcase-PAT &optional form)) body))) (let ((cached (gethash bindings pcase--memoize))) @@ -281,10 +282,11 @@ of the form (PAT EXP)." (defmacro pcase-let (bindings &rest body) "Like `let' but where you can use `pcase' patterns for bindings. BODY should be a list of expressions, and BINDINGS should be a list of bindings -of the form (PAT EXP). -The macro is expanded and optimized under the assumption that those -patterns *will* match, so a mismatch may go undetected or may cause -any kind of error." +of the form (PATTERN EXP). +The PATTERNs are only used to extract data, so the code does not test +whether the data does match the corresponding patterns: a mismatch +may signal an error or may go undetected, binding variables to arbitrary +values, such as nil." (declare (indent 1) (debug pcase-let*)) (if (null (cdr bindings)) `(pcase-let* ,bindings ,@body) @@ -302,7 +304,11 @@ any kind of error." ;;;###autoload (defmacro pcase-dolist (spec &rest body) - "Like `dolist' but where the binding can be a `pcase' pattern. + "Superset of `dolist' where the VAR binding can be a `pcase' PATTERN. +More specifically, this is just a shorthand for the following combination +of `dolist' and `pcase-let': + + (dolist (x LIST) (pcase-let ((PATTERN x)) BODY...)) \n(fn (PATTERN LIST) BODY...)" (declare (indent 1) (debug ((pcase-PAT form) body))) (if (pcase--trivial-upat-p (car spec)) diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el index bb759011513..1230df4f15d 100644 --- a/lisp/emacs-lisp/rx.el +++ b/lisp/emacs-lisp/rx.el @@ -1060,7 +1060,7 @@ CHAR `chinese-two-byte' (\\cC) `greek-two-byte' (\\cG) `japanese-hiragana-two-byte' (\\cH) - `indian-tow-byte' (\\cI) + `indian-two-byte' (\\cI) `japanese-katakana-two-byte' (\\cK) `korean-hangul-two-byte' (\\cN) `cyrillic-two-byte' (\\cY) diff --git a/lisp/mail/rmailsum.el b/lisp/mail/rmailsum.el index 10345b63ae2..f8adf774002 100644 --- a/lisp/mail/rmailsum.el +++ b/lisp/mail/rmailsum.el @@ -1694,7 +1694,7 @@ Deleted messages are skipped and don't count. When called from Lisp code, N may be omitted and defaults to 1. This command always outputs the complete message header, -even the header display is currently pruned." +even if the header display is currently pruned." (interactive (progn (require 'rmailout) (list (rmail-output-read-file-name) diff --git a/lisp/simple.el b/lisp/simple.el index 6a7d210e483..245675504a3 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -4266,7 +4266,7 @@ unless a hook has been set. Use `filter-buffer-substring' instead of `buffer-substring', `buffer-substring-no-properties', or `delete-and-extract-region' when you want to allow filtering to take place. For example, major or minor -modes can use `filter-buffer-substring-function' to extract characters +modes can use `filter-buffer-substring-function' to exclude text properties that are special to a buffer, and should not be copied into other buffers." (funcall filter-buffer-substring-function beg end delete)) diff --git a/src/callproc.c b/src/callproc.c index e6a81802936..a2cfd2e94da 100644 --- a/src/callproc.c +++ b/src/callproc.c @@ -221,15 +221,20 @@ DEFUN ("call-process", Fcall_process, Scall_process, 1, MANY, 0, doc: /* Call PROGRAM synchronously in separate process. The remaining arguments are optional. The program's input comes from file INFILE (nil means `/dev/null'). -Insert output in DESTINATION before point; t means current buffer; nil for DESTINATION - means discard it; 0 means discard and don't wait; and `(:file FILE)', where - FILE is a file name string, means that it should be written to that file - (if the file already exists it is overwritten). + +Third argument DESTINATION specifies how to handle program's output. +If DESTINATION is a buffer, or t that stands for the current buffer, + it means insert output in that buffer before point. +If DESTINATION is nil, it means discard output; 0 means discard + and don't wait for the program to terminate. +If DESTINATION is `(:file FILE)', where FILE is a file name string, + it means that output should be written to that file (if the file + already exists it is overwritten). DESTINATION can also have the form (REAL-BUFFER STDERR-FILE); in that case, -REAL-BUFFER says what to do with standard output, as above, -while STDERR-FILE says what to do with standard error in the child. -STDERR-FILE may be nil (discard standard error output), -t (mix it with ordinary output), or a file name string. + REAL-BUFFER says what to do with standard output, as above, + while STDERR-FILE says what to do with standard error in the child. + STDERR-FILE may be nil (discard standard error output), + t (mix it with ordinary output), or a file name string. Fourth arg DISPLAY non-nil means redisplay buffer as output is inserted. Remaining arguments are strings passed as command arguments to PROGRAM. |