Merge from origin/emacs-27

70fe552c61 ; xref-references-in-directory: Autoload as well
181f571651 Fix up requires
43f66c3368 Extract xref-matches-in-files from project--find-regexp-in...
65af18d86e Rename xref-collect-references and xref-collect-matches
98788bf976 ; Improve the docstring some more
c190e91a1e Improve docstrings
012c12a05e Fix when expose draws partially visible first glyph (bug#3...
d915b8c3f1 Don't require semantic/fw
50a0126402 Do some renames for clarity
74261ff301 Rearrange NEWS, add missing documentation
6c9571379e Fix interactive spec in netrc-parse
32222fb34c Fix documentation of define-obsolete-* functions

# Conflicts:
#	etc/NEWS

13 files changed, 126 insertions, 28 deletions

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index d1863510d45..8a4fa7e183d 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -720,6 +720,11 @@ should create non-existent directories in @var{new}.
 Dired automatically changes the visited file name of buffers associated
 with renamed files so that they refer to the new names.
 
+@vindex dired-vc-rename
+If the value of the variable @code{dired-vc-rename} is non-@code{nil},
+files are renamed using the commands of the underlying VCS, via
+@code{vc-rename-file} (@pxref{VC Delete/Rename}).
+
 @findex dired-do-hardlink
 @kindex H @r{(Dired)}
 @cindex hard links (in Dired)
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index cb37ef448e8..313abde6cf6 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -797,6 +797,8 @@ would be selected if you click a mouse or press @key{RET}.
 @kindex C-x C--
 @kindex C-x C-=
 @kindex C-x C-0
+@kindex C-wheel-down
+@kindex C-wheel-up
   To increase the height of the default face in the current buffer,
 type @kbd{C-x C-+} or @kbd{C-x C-=}.  To decrease it, type @kbd{C-x
 C--}.  To restore the default (global) face height, type @kbd{C-x
@@ -804,6 +806,11 @@ C-0}.  These keys are all bound to the same command,
 @code{text-scale-adjust}, which looks at the last key typed to
 determine which action to take.
 
+  Similarly, scrolling the mouse wheel with the @kbd{Ctrl} modifier
+pressed, when the mouse pointer is above buffer text, will increase or
+decrease the height of the default face, depending on the direction of
+the scrolling.
+
   The final key of these commands may be repeated without the leading
 @kbd{C-x}.  For instance, @kbd{C-x C-= C-= C-=} increases the face
 height by three steps.  Each step scales the text height by a factor
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 8ea923fccb8..560d612ed43 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -222,6 +222,9 @@ be tilted.  This feature is off by default; the variable
 the direction of horizontal scrolling, customize the variable
 @code{mouse-wheel-flip-direction} to a non-@code{nil} value.
 
+When the mouse pointer is over an image, scrolling the mouse wheel
+with the @key{Ctrl} modifier scales the image under the mouse pointer.
+
 
 @node Word and Line Mouse
 @section Mouse Commands for Words and Lines
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index fa92f568dac..6985486d09e 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -968,6 +968,9 @@ Display the changes that will be sent by the next ``push'' operation
 @item C-x v h
 Display the history of changes made in the region of file visited by
 the current buffer (@code{vc-region-history}).
+
+@item M-x vc-log-search @key{RET}
+Search the change history for a specified pattern.
 @end table
 
 @kindex C-x v l
@@ -1103,6 +1106,13 @@ defined by Diff mode (@pxref{Diff Mode}).
 
 This command is currently available only with Git and Mercurial (hg).
 
+@findex vc-log-search
+The command @code{vc-log-search} allows searching for a pattern in the
+log of changes.  It prompts for a pattern (a regular expression), and
+displays all entries in the change history whose log messages match
+the pattern.  When invoked with a prefix argument, the command will
+also prompt for a specific VCS shell command to run for this purpose.
+
 @node VC Undo
 @subsection Undoing Version Control Actions
 
@@ -2001,6 +2011,11 @@ Perform interactive query-replace on references that match
 @var{pattern} (@code{xref-query-replace-in-results}), replacing
 the match with @var{replacement}.  @xref{Identifier Search}.
 
+@item g
+@findex xref-revert-buffer
+Refresh the contents of the @file{*xref*} buffer
+(@code{xref-revert-buffer}.
+
 @findex xref-quit
 @item q
 Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 1c0f8534275..b9eb0a5852d 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -258,7 +258,11 @@ option has the value @code{allow-unsigned}, and a usable OpenPGP
 configuration is found, signed packages will be checked, but you can
 still install a package that is not signed.  If you use some archives
 that do not sign their packages, you can add them to the list
-@code{package-unsigned-archives}.
+@code{package-unsigned-archives}.  (If the value is
+@code{allow-unsigned} and no usable OpenPGP is found, this option is
+treated as if its value was @code{nil}.)  If the value is @code{t}, at
+least one signature must be valid; if the value is @code{all}, all of
+them must be valid.
 
   For more information on cryptographic keys and signing,
 @pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}.
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index c0aaf6eda92..aa21312039a 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -168,10 +168,14 @@ matches that begin after it.
 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}
 (@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.
+search string, or @kbd{C-r} (@code{isearch-repeat-backward}) to move
+to the previous occurrence.  You can repeat these commands any number
+of times.  Alternatively, you can supply a numeric prefix argument of
+@var{n} to @kbd{C-s} and @kbd{C-r} to find the @var{n}th next or
+previous occurrence.  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
@@ -251,14 +255,18 @@ that conveniently.
   @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.)
+of whether to copy a character or a word is heuristic.)  With a prefix
+numeric argument of @var{n}, append the next @var{n} characters or
+words.
 
 @kindex C-M-w @r{(Incremental search)}
 @findex isearch-yank-symbol-or-char
   @kbd{C-M-w} (@code{isearch-yank-symbol-or-char}) appends the next
 character or symbol at point to the search string.  This is an easy way
 to search for another occurrence of the symbol at point.  (The decision
-of whether to copy a character or a symbol is heuristic.)
+of whether to copy a character or a symbol is heuristic.)  With a prefix
+numeric argument of @var{n}, append the next @var{n} characters or
+symbols.
 
 @kindex M-s C-e @r{(Incremental search)}
 @findex isearch-yank-line
@@ -270,10 +278,12 @@ end of a line, it appends the next line.  With a prefix argument
 @kindex C-M-z @r{(Incremental search)}
 @findex isearch-yank-until-char
   Similarly, @kbd{C-M-z} (@code{isearch-yank-until-char}) appends to
-the search string everything from point until the next occurence of
+the search string everything from point until the next occurrence of
 a specified character (not including that character).  This is especially
 useful for keyboard macros, for example in programming languages or
-markup languages in which that character marks a token boundary.
+markup languages in which that character marks a token boundary.  With
+a prefix numeric argument of @var{n}, the command appends everything
+from point to the @var{n}th occurrence of the specified character.
 
 @kindex C-y @r{(Incremental search)}
 @kindex M-y @r{(Incremental search)}
@@ -481,6 +491,16 @@ remove the highlighting, type @kbd{M-s h u} (@code{unhighlight-regexp}).
 including a list of special key bindings.  These key bindings are part
 of the keymap @code{isearch-mode-map} (@pxref{Keymaps}).
 
+@cindex incremental search, go to first or last occurrence
+@kindex M-s M->
+@kindex M-s M-<
+  When incremental search is active, typing @kbd{M-s M->} will go to
+the last occurrence of the search string, and @kbd{M-s M-<} will go to
+the first occurrence.  With a prefix numeric argument of @var{n},
+these commands will go to the @var{n}th occurrence of the search
+string counting from the beginning or end of the buffer,
+respectively.
+
 @node Not Exiting Isearch
 @subsection Not Exiting Incremental Search
 
@@ -530,7 +550,9 @@ commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}).
 This applies only to calling these commands via their bound key
 sequences---typing @kbd{M-x} will still exit the search.  You can give
 prefix arguments to these commands in the usual way.  This feature
-won't let you scroll the current match out of visibility, however.
+normally won't let you scroll the current match out of visibility; but
+if you customize @code{isearch-allow-scroll} to the special value
+@code{unlimited}, that restriction is lifted.
 
   The @code{isearch-allow-scroll} feature also affects some other
 commands, such as @kbd{C-x 2} (@code{split-window-below}) and
@@ -739,15 +761,18 @@ Search backward for @var{symbol}, nonincrementally.
 @findex isearch-forward-symbol-at-point
   To begin a forward incremental symbol search, type @kbd{M-s _} (or
 @kbd{M-s .} if the symbol to search is near point).  If incremental
-search is not already active, this runs the command
-@code{isearch-forward-symbol}.  If incremental search is already
-active, @kbd{M-s _} switches to a symbol search, preserving the
-direction of the search and the current search string; you can disable
-symbol search by typing @kbd{M-s _} again.  In incremental symbol
-search, while you are typing the search string, only the beginning
-of the search string is required to match the beginning of a symbol,
-and @samp{Pending} appears in the search prompt until you use a search
-repeating key like @kbd{C-s}.
+search is not already active, @kbd{M-s _} runs the command
+@code{isearch-forward-symbol} and @kbd{M-s .} runs the command
+@code{isearch-forward-symbol-at-point}.  With a numeric prefix
+argument of @var{n}, @kbd{M-s .} will search for the @var{n}the next
+occurrence of the symbol at point; negative values of @var{n} search
+backwards.  If incremental search is already active, @kbd{M-s _}
+switches to a symbol search, preserving the direction of the search
+and the current search string; you can disable symbol search by typing
+@kbd{M-s _} again.  In incremental symbol search, while you are typing
+the search string, only the beginning of the search string is required
+to match the beginning of a symbol, and @samp{Pending} appears in the
+search prompt until you use a search repeating key like @kbd{C-s}.
 
   To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}}
 for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward
@@ -1955,17 +1980,32 @@ highlighting:
 
 @table @code
 @item lazy-highlight-initial-delay
+@vindex lazy-highlight-initial-delay
 Time in seconds to wait before highlighting visible matches.
 
 @item lazy-highlight-interval
+@vindex lazy-highlight-interval
 Time in seconds between highlighting successive matches.
 
 @item lazy-highlight-max-at-a-time
+@vindex 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.
+
+@item isearch-lazy-count
+@vindex isearch-lazy-count
+Show the current match number and the total number of matches in the
+search prompt.
+
+@item lazy-count-prefix-format
+@itemx lazy-count-suffix-format
+@vindex lazy-count-prefix-format
+@vindex lazy-count-suffix-format
+These two variables determine the format of showing the current and
+the total number of matches for @code{isearch-lazy-count}.
 @end table
 
 @vindex search-nonincremental-instead
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 53e9a4bb584..2c5a8463992 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -542,6 +542,16 @@ Reference Manual}), and cannot exceed the size of the containing frame.
 @node Window Convenience
 @section Convenience Features for Window Handling
 
+@findex global-tab-line-mode
+@cindex tab line
+  The command @code{global-tab-line-mode} toggles the display of a
+@dfn{tab line} on the top screen line of each window.  The tab line
+shows special buttons (``tabs'') for each buffer that was displayed in
+a window, and allows switching to any of these buffers by clicking the
+corresponding button.  You can add a tab by clicking on the @kbd{+}
+icon and delete a tab by clicking on the @kbd{x} icon of a tab.  The
+mouse wheel on the tab line scrolls the tabs horizontally.
+
 @findex winner-mode
 @vindex winner-dont-bind-my-keys
 @vindex winner-ring-size
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 64c06c23867..b19feaf977f 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -427,6 +427,13 @@ the build-time context.  This also has the side-effect that the
 @xref{Building Emacs}.
 @end table
 
+@item :local @var{value}
+@kindex local@r{, @code{defcustom} keyword}
+If the @var{value} is @code{t}, mark @var{option} as automatically
+buffer-local; if the value is @code{permanent}, also set @var{option}s
+@code{permanent-local} property to @code{t}.  @xref {Creating
+Buffer-Local}.
+
 @item :risky @var{value}
 @kindex risky@r{, @code{defcustom} keyword}
 Set the variable's @code{risky-local-variable} property to
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 6157f9a535b..4307aab9268 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2090,7 +2090,7 @@ alias for a function or macro can also be marked as obsolete; this
 makes the alias itself obsolete, not the function or macro which it
 resolves to.
 
-@defun make-obsolete obsolete-name current-name &optional when
+@defun make-obsolete obsolete-name current-name when
 This function marks @var{obsolete-name} as obsolete.
 @var{obsolete-name} should be a symbol naming a function or macro, or
 an alias for a function or macro.
@@ -2104,11 +2104,11 @@ should begin in lower case, and end with a period.  It can also be
 @code{nil}, in which case the warning message provides no additional
 details.
 
-If provided, @var{when} should be a string indicating when the function
+The argument @var{when} should be a string indicating when the function
 was first made obsolete---for example, a date or a release number.
 @end defun
 
-@defmac define-obsolete-function-alias obsolete-name current-name &optional when doc
+@defmac define-obsolete-function-alias obsolete-name current-name when &optional doc
 This convenience macro marks the function @var{obsolete-name} obsolete
 and also defines it as an alias for the function @var{current-name}.
 It is equivalent to the following:
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 4542db97306..26d26bed8ae 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -110,6 +110,10 @@ Function to call to quit the current buffer.
 @item change-major-mode-hook
 @xref{Creating Buffer-Local}.
 
+@item comint-password-function
+This abnormal hook permits a derived mode to supply a password for the
+underlying command interpreter without prompting the user.
+
 @item command-line-functions
 @xref{Command-Line Arguments}.
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 8ff329bdacb..813bf814394 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1171,6 +1171,8 @@ the second example.
 @end group
 @end example
 
+The @var{keymap} argument can also be a list of keymaps.
+
 Unlike @code{read-key-sequence}, this function does not modify the
 specified events in ways that discard information (@pxref{Key Sequence
 Input}).  In particular, it does not convert letters to lower case and
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 939ad5c85a1..3127354ee2e 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -316,11 +316,11 @@ and returns the result.  @var{x1} and @var{x2} must be floating point.
 @end defun
 
 @defun logb x
-This function returns the binary exponent of @var{x}.  More
-precisely, if @var{x} is finite and nonzero, the value is the
-logarithm base 2 of @math{|x|}, rounded down to an integer.
-If @var{x} is zero, infinite, or a NaN, the value is minus infinity,
-plus infinity, or a NaN respectively.
+This function returns the binary exponent of @var{x}.  More precisely,
+if @var{x} is finite and nonzero, the value is the logarithm base 2 of
+@math{|x|}, rounded down to an integer.  If @var{x} is zero or
+infinite, the value is infinity; if @var{x} is a NaN, the value is a
+NaN.
 
 @example
 (logb 10)
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index 600639f244f..08c3e519ebe 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -740,7 +740,8 @@ The default is @code{t}, meaning display in the echo area.
 @defvar print-quoted
 If this is non-@code{nil}, that means to print quoted forms using
 abbreviated reader syntax, e.g., @code{(quote foo)} prints as
-@code{'foo}, and @code{(function foo)} as @code{#'foo}.
+@code{'foo}, and @code{(function foo)} as @code{#'foo}.  The default
+is @code{t}.
 @end defvar
 
 @defvar print-escape-newlines