Merge from origin/emacs-26

eb903d8 * lisp/emacs-lisp/pcase.el: Improve docstrings.
86abbb3 * lisp/emacs-lisp/rx.el (rx): Fix typo in doc string.  (Bug#3...
ced58d3 Improve doc string of 'call-process'
38f88a7 Document that generic functions cannot be commands
5aeddfa * lisp/mail/rmailsum.el (rmail-summary-output): Add lost word...
10e0fd8 Add index entries for more isearch commands/bindings (Bug#32990)
de28184 * lisp/simple.el (filter-buffer-substring): Clarify doc (Bug#...
d192c16 Fix recent change in lispref/processes.texi.

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

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

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

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

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))

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)

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)

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))
 

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.