Merge from origin/emacs-26

5de608f (origin/emacs-26) Update the documentation of 'perform-replace'
06245b6 * etc/NEWS: Another fix for the last change (noted by Juri Li...
8f6293c Fix use of @key in Texinfo manuals
f4c9894 Improve documentation of actual arglist
ce0e253 ; * etc/NEWS: Improve last change as proposed by Phil Sainty
b89ff0e Don't assume term-current-row cache is valid (Bug#31193)
326a296 ; * etc/NEWS: Mention 'display-buffer-in-major-side-window' c...
3bdc9a1 Fix flyspell-auto-correct-previous-word broken by recent change
a539eb5 * test/src/lread-tests.el (lread-test-bug-31186): New test.
3fa472b Fix undefined behaviour while looking for lexical-binding fil...
4341aac Minor wording improvement in "Bookmarks"

Conflicts:
	test/src/lread-tests.el

doc/emacs/frames.texi

@@ -485,7 +485,7 @@ Delete all frames on the current terminal, except the selected one.
 Toggle the maximization state of the current frame.  When a frame is
 maximized, it fills the screen.
 
-@item @key{F11>}
+@item @key{F11}
 @kindex F11
 @findex toggle-frame-fullscreen
 Toggle full-screen mode for the current frame.  (The difference

doc/emacs/kmacro.texi

@@ -157,7 +157,7 @@ definition, type @kbd{C-x )} (@code{kmacro-end-macro}).  To execute
 the most recent macro, type @kbd{C-x e}
 (@code{kmacro-end-and-call-macro}).  If you enter @kbd{C-x e} while
 defining a macro, the macro is terminated and executed immediately.
-Immediately after typing @kbd{C-x e}, you can type @key{e} repeatedly
+Immediately after typing @kbd{C-x e}, you can type @kbd{e} repeatedly
 to immediately repeat the macro one or more times.  You can also give
 @kbd{C-x e} a repeat argument, just like @key{F4} (when it is used to
 execute a macro).

doc/emacs/msdos.texi

@@ -597,7 +597,7 @@ search string against previously sought strings during incremental
 search.  @code{(w32-register-hot-key [s-])} with
 @code{w32-lwindow-modifier} bound to @code{super} disables all the
 Windows' own Windows key based shortcuts.@footnote{There is one known
-exception: The combination @kbd{@key{Windows}-@key{L}} that locks the
+exception: The combination @kbd{@key{Windows}-L} that locks the
 workstation is handled by the system on a lower level.  For this
 reason, @code{w32-register-hot-key} cannot override this key
 combination - it always locks the computer.}
@@ -607,9 +607,9 @@ combination - it always locks the computer.}
 call.  Thus, you can set @code{w32-lwindow-modifier} as @code{super},
 then call @code{(w32-register-hot-key [s-r])}, and finally set
 @code{w32-rwindow-modifier} as @code{super} as well.  The result is
-that the left Windows key together with @key{R} invokes whichever
+that the left Windows key together with @kbd{R} invokes whichever
 function you have bound for the combination in Emacs, and the right
-Windows key and @key{R} opens the Windows @code{Run} dialog.
+Windows key and @kbd{R} opens the Windows @code{Run} dialog.
 
   The hotkey registrations always also include all the shift and
 control modifier combinations for the given hotkey; that is,

doc/emacs/regs.texi

@@ -314,18 +314,18 @@ Save all the current bookmark values in the default bookmark file.
 @findex bookmark-set
 @kindex C-x r b
 @findex bookmark-jump
-  The prototypical use for bookmarks is to record one current position
-in each of several files.  So the command @kbd{C-x r m}, which sets a
-bookmark, uses the visited file name as the default for the bookmark
-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.
+  To record the current position in the visited file, use the command
+@kbd{C-x r m}, which sets a bookmark using the visited file name as
+the default for the bookmark 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.
+like @w{@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
 @findex list-bookmarks

doc/emacs/search.texi

@@ -1673,7 +1673,7 @@ 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
+multi-buffer replacements (like the Dired @kbd{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.

doc/lispintro/emacs-lisp-intro.texi

@@ -914,17 +914,17 @@ the command in parentheses, like this: @kbd{M-C-\}
 @kbd{M-C-\}.  (You can, if you wish, change the keys that are typed to
 invoke the command; this is called @dfn{rebinding}.  @xref{Keymaps, ,
 Keymaps}.)  The abbreviation @kbd{M-C-\} means that you type your
-@key{META} key, @key{CTRL} key and @key{\} key all at the same time.
+@key{META} key, @key{CTRL} key and @kbd{\} key all at the same time.
 (On many modern keyboards the @key{META} key is labeled
 @key{ALT}.)
 Sometimes a combination like this is called a keychord, since it is
 similar to the way you play a chord on a piano.  If your keyboard does
 not have a @key{META} key, the @key{ESC} key prefix is used in place
 of it.  In this case, @kbd{M-C-\} means that you press and release your
-@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
+@key{ESC} key and then type the @key{CTRL} key and the @kbd{\} key at
 the same time.  But usually @kbd{M-C-\} means press the @key{CTRL} key
 along with the key that is labeled @key{ALT} and, at the same time,
-press the @key{\} key.
+press the @kbd{\} key.
 
 In addition to typing a lone keychord, you can prefix what you type
 with @kbd{C-u}, which is called the @dfn{universal argument}.  The
@@ -17109,8 +17109,8 @@ This also shows how to set a key globally, for all modes.
 The command is @code{global-set-key}.  It is followed by the
 keybinding.  In a @file{.emacs} file, the keybinding is written as
 shown: @code{\C-c} stands for Control-C, which means to press the
-control key and the @key{c} key at the same time.  The @code{w} means
-to press the @key{w} key.  The keybinding is surrounded by double
+control key and the @kbd{c} key at the same time.  The @code{w} means
+to press the @kbd{w} key.  The keybinding is surrounded by double
 quotation marks.  In documentation, you would write this as
 @w{@kbd{C-c w}}.  (If you were binding a @key{META} key, such as
 @kbd{M-c}, rather than a @key{CTRL} key, you would write

doc/lispref/functions.texi

@@ -498,6 +498,14 @@ derived from the actual arguments of the function.
 arguments written in a macro definition often do not correspond to the
 way users think of the parts of the macro call.
 
+  Do not use this feature if you want to deprecate the calling
+convention and favor the one you advertise by the above specification.
+Instead, use the @code{advertised-calling-convention} declaration
+(@pxref{Declare Form}) or @code{set-advertised-calling-convention}
+(@pxref{Obsolete Functions}), because these two will cause the byte
+compiler emit a warning message when it compiles Lisp programs which
+use the deprecated calling convention.
+
 @node Function Names
 @section Naming a Function
 @cindex function definition

doc/lispref/searching.texi

@@ -1751,13 +1751,14 @@ of matching @var{regexp} against a substring of @var{string}.
   If you want to write a command along the lines of @code{query-replace},
 you can use @code{perform-replace} to do the work.
 
-@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
+@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end backward region-noncontiguous-p
 This function is the guts of @code{query-replace} and related
 commands.  It searches for occurrences of @var{from-string} in the
 text between positions @var{start} and @var{end} and replaces some or
 all of them.  If @var{start} is @code{nil} (or omitted), point is used
 instead, and the end of the buffer's accessible portion is used for
-@var{end}.
+@var{end}.  (If the optional argument @var{backward} is
+non-@code{nil}, the search starts at @var{end} and goes backward.)
 
 If @var{query-flag} is @code{nil}, it replaces all
 occurrences; otherwise, it asks the user what to do about each one.
@@ -1789,6 +1790,11 @@ user responses for queries.  The argument @var{map}, if
 non-@code{nil}, specifies a keymap to use instead of
 @code{query-replace-map}.
 
+Non-@code{nil} @var{region-noncontiguous-p} means that the region
+between @var{start} and @var{end} is composed of noncontiguous pieces.
+The most common example of this is a rectangular region, where the
+pieces are separated by newline characters.
+
 This function uses one of two functions to search for the next
 occurrence of @var{from-string}.  These functions are specified by the
 values of two variables: @code{replace-re-search-function} and

doc/lispref/tips.texi

@@ -316,7 +316,7 @@ any context prevents recognition of escape sequences as function keys in
 that context.
 
 @item
-Similarly, don't bind a key sequence ending in @key{C-g}, since that
+Similarly, don't bind a key sequence ending in @kbd{C-g}, since that
 is commonly used to cancel a key sequence.
 
 @item

doc/misc/ada-mode.texi

@@ -1356,7 +1356,7 @@ specified by the variable @code{ada-case-exception-file}
 specifies the casing of one word or word fragment. Comments may be
 included, separated from the word by a space.
 
-If the word starts with an asterisk (@key{*}), it defines the casing
+If the word starts with an asterisk (@samp{*}), it defines the casing
 as a word fragment (or ``substring''); part of a word between two
 underscores or word boundary.
 

doc/misc/calc.texi

@@ -12422,7 +12422,7 @@ Calculations are normally performed numerically wherever possible.
 For example, the @code{calc-sqrt} command, or @code{sqrt} function in an
 algebraic expression, produces a numeric answer if the argument is a
 number or a symbolic expression if the argument is an expression:
-@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}.
+@kbd{2 Q} pushes 1.4142 but @kbd{' x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}.
 
 @kindex m s
 @pindex calc-symbolic-mode
@@ -16338,7 +16338,7 @@ computes an Nth root:  @kbd{125 @key{RET} 3 I ^} computes the number 5.
 @tindex \
 The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack
 to produce an integer result.  It is equivalent to dividing with
-@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit
+@kbd{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit
 more convenient and efficient.  Also, since it is an all-integer
 operation when the arguments are integers, it avoids problems that
 @kbd{/ F} would have with floating-point roundoff.
@@ -30289,7 +30289,7 @@ is the same as @key{CONJ}.
 @item INV *
 is the same as @key{y^x}.
 @item INV /
-is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}).
+is the same as @kbd{INV y^x} (the @expr{x}th root of @expr{y}).
 @item HYP/INV 1
 are the same as @key{SIN} / @kbd{INV SIN}.
 @item HYP/INV 2
@@ -30366,9 +30366,9 @@ number.  (@xref{Random Numbers}.)  @key{RAGN} is the ``random
 again'' command; it computes another random number using the
 same limit as last time.
 
-@key{INV GCD} computes the LCM (least common multiple) function.
+@kbd{INV GCD} computes the LCM (least common multiple) function.
 
-@key{INV FACT} is the gamma function.
+@kbd{INV FACT} is the gamma function.
 @texline @math{\Gamma(x) = (x-1)!}.
 @infoline @expr{gamma(x) = (x-1)!}.
 
@@ -30396,14 +30396,14 @@ finds the previous prime.
 @noindent
 The keys in this menu perform operations on binary integers.
 Note that both logical and arithmetic right-shifts are provided.
-@key{INV LSH} rotates one bit to the left.
+@kbd{INV LSH} rotates one bit to the left.
 
-The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}.
-The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}.
+The ``difference'' function (normally on @kbd{b d}) is on @kbd{INV AND}.
+The ``clip'' function (normally on @w{@kbd{b c}}) is on @kbd{INV NOT}.
 
 The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the
 current radix for display and entry of numbers:  Decimal, hexadecimal,
-octal, or binary.  The six letter keys @key{A} through @key{F} are used
+octal, or binary.  The six letter keys @kbd{A} through @kbd{F} are used
 for entering hexadecimal numbers.
 
 The @key{WSIZ} key displays the current word size for binary operations
@@ -30461,13 +30461,13 @@ equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}).
 @key{PROD} computes the product of the elements of a vector, and
 @key{MAX} computes the maximum of all the elements of a vector.
 
-@key{INV SUM} computes the alternating sum of the first element
+@kbd{INV SUM} computes the alternating sum of the first element
 minus the second, plus the third, minus the fourth, and so on.
-@key{INV MAX} computes the minimum of the vector elements.
+@kbd{INV MAX} computes the minimum of the vector elements.
 
-@key{HYP SUM} computes the mean of the vector elements.
-@key{HYP PROD} computes the sample standard deviation.
-@key{HYP MAX} computes the median.
+@kbd{HYP SUM} computes the mean of the vector elements.
+@kbd{HYP PROD} computes the sample standard deviation.
+@kbd{HYP MAX} computes the median.
 
 @key{MAP*} multiplies two vectors elementwise.  It is equivalent
 to the @kbd{V M *} command.  @key{MAP^} computes powers elementwise.

doc/misc/ediff.texi

@@ -1557,7 +1557,7 @@ selective browsing.  To change the default Ediff function, add a function to
 @strong{Useful hint}: To specify a regexp that matches everything, don't
 simply type @key{RET} in response to a prompt.  Typing @key{RET} tells Ediff
 to accept the default value, which may not be what you want.  Instead, you
-should enter something like @key{^} or @key{$}.  These match every
+should enter something like @kbd{^} or @kbd{$}.  These match every
 line.
 
 You can use the status command, @kbd{i}, to find out whether

doc/misc/efaq-w32.texi

@@ -398,7 +398,7 @@ of which varies according to Windows version and whether the computer is
 part of a domain.
 @end enumerate
 
-Within Emacs, @key{~} at the beginning of a file name is expanded to your
+Within Emacs, @kbd{~} at the beginning of a file name is expanded to your
 @env{HOME} directory, so you can always find your @file{.emacs} file
 by typing the command @kbd{C-x C-f ~/.emacs}.
 

doc/misc/efaq.texi

@@ -134,14 +134,14 @@ used in the FAQ.
 @itemize @bullet
 
 @item
-@kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
+@kbd{C-x}: press the @kbd{x} key while holding down the @key{Control} key
 
 @item
-@kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
+@kbd{M-x}: press the @kbd{x} key while holding down the @key{Meta} key
 (if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
 
 @item
-@kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
+@kbd{M-C-x}: press the @kbd{x} key while holding down both @key{Control}
 and @key{Meta}
 
 @item
@@ -181,10 +181,10 @@ Any real spaces in such a key sequence should be ignored; only @key{SPC}
 really means press the space key.
 
 The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
-that would be sent by pressing just @key{x} minus 96 (or 64 for
-upper-case @key{X}) and will be from 0 to 31.  On Unix and GNU/Linux
+that would be sent by pressing just @kbd{x} minus 96 (or 64 for
+upper-case @kbd{X}) and will be from 0 to 31.  On Unix and GNU/Linux
 terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
-@acronym{ASCII} code that would be sent by pressing just @key{x}.  Essentially,
+@acronym{ASCII} code that would be sent by pressing just @kbd{x}.  Essentially,
 @key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
 7@footnote{
 DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
@@ -211,7 +211,7 @@ what @kbd{M-x} and @key{RET} mean.)
 @code{execute-extended-command}.  This command allows you to run any
 Emacs command if you can remember the command's name.  If you can't
 remember the command's name, you can type @key{TAB} and @key{SPC} for
-completion, @key{?} for a list of possibilities, and @kbd{M-p} and
+completion, @kbd{?} for a list of possibilities, and @kbd{M-p} and
 @kbd{M-n} (or up-arrow and down-arrow) to see previous commands entered.
 An Emacs @dfn{command} is an @dfn{interactive} Emacs function.
 
@@ -235,7 +235,7 @@ read this manual node inside Emacs (assuming nothing is broken) by
 typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
 
 This invokes Info, the GNU hypertext documentation browser.  If you don't
-already know how to use Info, type @key{?} from within Info.
+already know how to use Info, type @kbd{?} from within Info.
 
 If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
 @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
@@ -576,7 +576,7 @@ There are several methods for finding out how to do things in Emacs.
 @item
 The complete text of the Emacs manual is available via the Info
 hypertext reader.  Type @kbd{C-h r} to display the manual in Info mode.
-Typing @key{h} immediately after entering Info will provide a short
+Typing @kbd{h} immediately after entering Info will provide a short
 tutorial on how to use it.
 
 @cindex Lookup a subject in a manual
@@ -761,7 +761,7 @@ named @samp{Top} in that file.  For example, to view an Info file named
 @end example
 
 Alternatively, you can feed a file name to the @code{Info-goto-node}
-command (invoked by pressing @key{g} in Info mode) by typing the name
+command (invoked by pressing @kbd{g} in Info mode) by typing the name
 of the file in parentheses, like this:
 
 @example
@@ -946,7 +946,7 @@ status of its latest version.
 @cindex Original version of Emacs
 
 Emacs originally was an acronym for Editor MACroS@.  RMS says he ``picked
-the name Emacs because @key{E} was not in use as an abbreviation on ITS at
+the name Emacs because @kbd{E} was not in use as an abbreviation on ITS at
 the time.''  The first Emacs was a set of macros written in 1976 at MIT
 by RMS for the editor TECO (Text Editor and COrrector, originally Tape
 Editor and COrrector) under ITS (the Incompatible Timesharing System) on
@@ -2240,7 +2240,7 @@ and braces at the same time by modifying the syntax table.)
 
 @cindex Show matching paren as in @code{vi}
 @item
-Here is some Emacs Lisp that will make the @key{%} key show the matching
+Here is some Emacs Lisp that will make the @kbd{%} key show the matching
 parenthesis, like in @code{vi}.  In addition, if the cursor isn't over a
 parenthesis, it simply inserts a % like normal.
 
@@ -3993,8 +3993,8 @@ On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
 Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}.  In fact,
 Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
 (depending on the value of @code{meta-prefix-char}).  Note that you
-press @key{Meta} and @key{a} together, but with @key{ESC}, you press
-@key{ESC}, release it, and then press @key{a}.
+press @key{Meta} and @kbd{a} together, but with @key{ESC}, you press
+@key{ESC}, release it, and then press @kbd{a}.
 
 @node No Escape key
 @section What if I don't have an @key{Escape} key?
@@ -4487,9 +4487,9 @@ these systems, you should configure @code{movemail} to use @code{flock}.
 
 @c isaacson@@seas.upenn.edu
 Ron Isaacson says: When you hit
-@key{r} to reply in Rmail, by default it CCs all of the original
+@kbd{r} to reply in Rmail, by default it CCs all of the original
 recipients (everyone on the original @samp{To} and @samp{CC}
-lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
+lists). With a prefix argument (i.e., typing @kbd{C-u} before @kbd{r}),
 it replies only to the sender.  However, going through the whole
 @kbd{C-u} business every time you want to reply is a pain.  This is the
 best fix I've been able to come up with:

doc/misc/eshell.texi

@@ -1204,7 +1204,7 @@ perform this on-thy-fly rewriting.
 
 @item Write an alias for @command{less} that brings up a @code{view-mode} buffer
 
-Such that the user can press @key{SPC} and @key{DEL}, and then @key{q}
+Such that the user can press @key{SPC} and @key{DEL}, and then @kbd{q}
 to return to Eshell.  It would be equivalent to:
 @samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
 

doc/misc/gnus.texi

@@ -24577,7 +24577,7 @@ determined by either the @code{ham-process-destination} group
 parameter or a match in the @code{gnus-ham-process-destinations}
 variable, which is a list of regular expressions matched with group
 names (it's easiest to customize this variable with @kbd{M-x
-customize-variable @key{@key{RET}} gnus-ham-process-destinations}).  Each
+customize-variable @key{RET} gnus-ham-process-destinations}).  Each
 group name list is a standard Lisp list, if you prefer to customize
 the variable manually.  If the @code{ham-process-destination}
 parameter is not set, ham articles are left in place.  If the
@@ -24613,7 +24613,7 @@ When you leave a @emph{ham} or @emph{unclassified} group, all
 the @code{spam-process-destination} group parameter or a match in the
 @code{gnus-spam-process-destinations} variable, which is a list of
 regular expressions matched with group names (it's easiest to
-customize this variable with @kbd{M-x customize-variable @key{@key{RET}}
+customize this variable with @kbd{M-x customize-variable @key{RET}
 gnus-spam-process-destinations}).  Each group name list is a standard
 Lisp list, if you prefer to customize the variable manually.  If the
 @code{spam-process-destination} parameter is not set, the spam
@@ -28732,7 +28732,7 @@ commonly fetched via the protocol @acronym{NNTP}, whereas mail
 messages could be read from a file on the local disk.  The internal
 architecture of Gnus thus comprises a ``front end'' and a number of
 ``back ends''.  Internally, when you enter a group (by hitting
-@key{@key{RET}}, say), you thereby invoke a function in the front end in
+@key{RET}, say), you thereby invoke a function in the front end in
 Gnus.  The front end then ``talks'' to a back end and says things like
 ``Give me the list of articles in the foo group'' or ``Show me article
 number 4711''.

doc/misc/idlwave.texi

@@ -702,13 +702,13 @@ be located in the library.  E.g., if you have scanned the IDL-Astro
 library:
 
 @example
-    a=readf@key{M-@key{TAB}}
+    a=readf@kbd{M-@key{TAB}}
 @end example
 
 expands to ``readfits(''.  Then try
 
 @example
-    a=readfits(@key{C-c ?}
+    a=readfits(@kbd{C-c ?}
 @end example
 
 and you get:
@@ -2519,9 +2519,9 @@ between emacs and IDL sessions.  Here is a list of commonly used
 commands:
 
 @multitable @columnfractions .12 .88
-@item @key{UP}, @key{M-p}
+@item @key{UP}, @kbd{M-p}
 @tab Cycle backwards in input history
-@item @key{DOWN}, @key{M-n}
+@item @key{DOWN}, @kbd{M-n}
 @tab Cycle forwards in input history
 @item @kbd{M-r}
 @tab Previous input matching a regexp
@@ -3131,8 +3131,8 @@ variable, number, or function you see can be examined.
 If the variable @code{idlwave-shell-separate-examine-output} is
 non-@code{nil} (the default), all examine output will be sent to a
 special @file{*Examine*} buffer, rather than the shell.  The output of
-prior examine commands is saved in this buffer.  In this buffer @key{c}
-clears the contents, and @key{q} hides the buffer.
+prior examine commands is saved in this buffer.  In this buffer @kbd{c}
+clears the contents, and @kbd{q} hides the buffer.
 
 The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
 print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
@@ -4249,7 +4249,7 @@ This actually happens when running IDL in an XTerm as well.  There are
 a couple of workarounds: @code{define_key,/control,'^d'} (e.g., in
 your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character
 and give you a 512 character limit.  You won't be able to use
-@key{C-d} to quit the shell, however.  Another possibility is
+@kbd{C-d} to quit the shell, however.  Another possibility is
 @code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a
 memory-bounded limit), but disables the processing of background
 widget events (those with @code{/NO_BLOCK} passed to @code{XManager}).

doc/misc/info.texi

@@ -405,7 +405,7 @@ brief list of commands.  When you are finished looking at the list,
 make it go away by typing @key{SPC} repeatedly.
 
 @format
->> Type a @key{?} (or @key{H} in the stand-alone Info reader) now.
+>> Type @kbd{?} (or @kbd{H} in the stand-alone Info reader) now.
    Press @key{SPC} to see consecutive screenfuls of the list
    until finished.  Then type @key{SPC} several times.  If
    you are using Emacs, the help will then go away automatically.

doc/misc/org.texi

@@ -1468,8 +1468,8 @@ level).
 Move subtree down (swap with next subtree of same level).
 @orgcmd{M-h,org-mark-element}
 Mark the element at point.  Hitting repeatedly will mark subsequent elements
-of the one just marked.  E.g., hitting @key{M-h} on a paragraph will mark it,
-hitting @key{M-h} immediately again will mark the next one.
+of the one just marked.  E.g., hitting @kbd{M-h} on a paragraph will mark it,
+hitting @kbd{M-h} immediately again will mark the next one.
 @orgcmd{C-c @@,org-mark-subtree}
 Mark the subtree at point.  Hitting repeatedly will mark subsequent subtrees
 of the same level than the marked subtree.
@@ -1836,7 +1836,7 @@ this:
 @end example
 
 You can interactively insert drawers at point by calling
-@code{org-insert-drawer}, which is bound to @key{C-c C-x d}.  With an active
+@code{org-insert-drawer}, which is bound to @kbd{C-c C-x d}.  With an active
 region, this command will put the region inside the drawer.  With a prefix
 argument, this command calls @code{org-insert-property-drawer} and add
 a property drawer right below the current headline.  Completion over drawer
@@ -4410,7 +4410,7 @@ Then each time you turn an entry from a TODO (not-done) state into any of the
 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
 the headline.  If you turn the entry back into a TODO item through further
 state cycling, that line will be removed again.  If you turn the entry back
-to a non-TODO state (by pressing @key{C-c C-t @key{SPC}} for example), that line
+to a non-TODO state (by pressing @kbd{C-c C-t @key{SPC}} for example), that line
 will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
 non-@code{nil}.  If you want to record a note along with the timestamp,
 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
@@ -10606,7 +10606,7 @@ In-buffer settings may appear anywhere in the file, either directly or
 indirectly through a file included using @samp{#+SETUPFILE: filename or URL}
 syntax.  Option keyword sets tailored to a particular back-end can be
 inserted from the export dispatcher (@pxref{The export dispatcher}) using the
-@code{Insert template} command by pressing @key{#}.  To insert keywords
+@code{Insert template} command by pressing @kbd{#}.  To insert keywords
 individually, a good way to make sure the keyword is correct is to type
 @code{#+} and then to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept
 @kbd{M-@key{TAB}} to switch windows.  Use @kbd{C-M-i} or @kbd{@key{ESC}
@@ -15245,7 +15245,7 @@ Source code in the dialect of the specified language identifier.
 edit buffer containing the body of the @samp{src} code block, ready for any
 edits.  @kbd{C-c '} again to close the buffer and return to the Org buffer.
 
-@key{C-x C-s} saves the buffer and updates the contents of the Org buffer.
+@kbd{C-x C-s} saves the buffer and updates the contents of the Org buffer.
 
 Set @code{org-edit-src-auto-save-idle-delay} to save the base buffer after
 a certain idle delay time.

doc/misc/pcl-cvs.texi

@@ -470,7 +470,7 @@ commands that @samp{tag} or @samp{diff} a file (which can be changed
 with the variable @code{cvs-invert-ignore-marks}).
 
 In addition, you may use the special prefix @code{cvs-mode-toggle-marks}
-normally bound to @key{T} to toggle the use of marks for the following
+normally bound to @kbd{T} to toggle the use of marks for the following
 command.
 
 This scheme might seem a little complicated, but once one gets used to

doc/misc/reftex.texi

@@ -1710,8 +1710,8 @@ customizing @code{reftex-ref-macro-prompt} and relying only on the
 selection facilities provided in the last step.
 
 In the last step, i.e., the label selection, two key bindings are
-provided to set the reference macro.  Type @key{v} in order to cycle
-forward through the list of available macros or @key{V} to cycle
+provided to set the reference macro.  Type @kbd{v} in order to cycle
+forward through the list of available macros or @kbd{V} to cycle
 backward.  The mode line of the selection buffer shows the macro
 currently selected.
 

doc/misc/sc.texi

@@ -684,7 +684,7 @@ value of @code{sc-preferred-header-style}.
 Set the preferred reference header (i.e.,
 @code{sc-preferred-header-style}) to the currently displayed header.
 
-@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c})
+@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @kbd{@key{ESC} C-c})
 @kindex RET
 @kindex C-j
 @kindex q

doc/misc/tramp.texi

@@ -3873,7 +3873,7 @@ Then specify a method and user name where needed.  Examples:
 @end group
 @end example
 
-In BBDB buffer, access an entry by pressing the key @key{F}.
+In BBDB buffer, access an entry by pressing the key @kbd{F}.
 
 @end enumerate
 

doc/misc/vip.texi

@@ -1903,7 +1903,7 @@ by @kbd{o} or @kbd{O} command.
 @item vip-tags-file-name "TAGS"
 The name of the file used as the tags table.
 @item vip-help-in-insert-mode nil
-If @code{t} then @key{C-h} is bound to @code{help-command} in insert mode,
+If @code{t} then @kbd{C-h} is bound to @code{help-command} in insert mode,
 if @code{nil} then it sis bound to @code{delete-backward-char}.
 @end table
 @noindent

doc/misc/viper.texi

@@ -1743,7 +1743,7 @@ lines, etc.  @xref{Movement and Markers}, for more info.
 @item viper-ex-style-editing t
 Set this to @code{nil}, if you want
 @kbd{C-h} and @key{DEL} to not stop
-at the beginning of a line in Insert state, @key{X} and @key{x} to delete
+at the beginning of a line in Insert state, @kbd{X} and @kbd{x} to delete
 characters across lines in Vi command state, etc.
 @item viper-ESC-moves-cursor-back t
 It @code{t}, cursor moves back 1 character when switching from insert state to vi

etc/NEWS

@@ -490,6 +490,13 @@ vc-comment-search-forward, vc-comment-search-reverse, vc-comment-to-change-log,
 vc-diff-switches-list, vc-next-comment, vc-previous-comment, view-todo,
 x-lost-selection-hooks, x-sent-selection-hooks
 
+** The function 'display-buffer-in-major-side-window' no longer exists.
+It has been renamed as internal function 'window--make-major-side-window',
+however applications should instead call 'display-buffer-in-side-window'
+(passing the SIDE and SLOT parameters as elements of ALIST).  This approach
+is backwards-compatible with versions of Emacs in which the old function
+exists.  See the node "Displaying Buffers in Side Windows" in the ELisp
+manual for more details.
 
 * Lisp Changes in Emacs 27.1
 

lisp/term.el

@@ -3653,7 +3653,7 @@ all pending output has been dealt with."))
   (let ((start-column (term-horizontal-column)))
     (when (and check-for-scroll (or term-scroll-with-delete term-pager-count))
       (setq down (term-handle-scroll down)))
-    (unless (and (= term-current-row 0) (< down 0))
+    (unless (and (= (term-current-row) 0) (< down 0))
       (term-adjust-current-row-cache down)
       (when (or (/= (point) (point-max)) (< down 0))
 	(setq down (- down (term-vertical-motion down)))))
@@ -3663,7 +3663,7 @@ all pending output has been dealt with."))
 	   (setq term-current-column 0)
 	   (setq term-start-line-column 0))
 	  (t
-	   (when (= term-current-row 0)
+	   (when (= (term-current-row) 0)
 	     ;; Insert lines if at the beginning.
 	     (save-excursion (term-insert-char ?\n (- down)))
 	     (save-excursion

lisp/textmodes/flyspell.el

@@ -1950,8 +1950,9 @@ spell-check."
     (let ((pos     (point))
           (old-max (point-max)))
       ;; Flush a possibly stale cache from previous invocations of
-      ;; flyspell-auto-correct-word.
-      (if (not (eq last-command 'flyspell-auto-correct-word))
+      ;; flyspell-auto-correct-word/flyspell-auto-correct-previous-word.
+      (if (not (memq last-command '(flyspell-auto-correct-word
+                                    flyspell-auto-correct-previous-word)))
           (setq flyspell-auto-correct-region nil))
       ;; Use the correct dictionary.
       (flyspell-accept-buffer-local-defs)

src/lread.c

@@ -898,6 +898,7 @@ lisp_file_lexically_bound_p (Lisp_Object readcharfun)
 	    ch = READCHAR;
 
 	  i = 0;
+	  beg_end_state = NOMINAL;
 	  while (ch != ':' && ch != '\n' && ch != EOF && in_file_vars)
 	    {
 	      if (i < sizeof var - 1)
@@ -923,6 +924,7 @@ lisp_file_lexically_bound_p (Lisp_Object readcharfun)
 		ch = READCHAR;
 
 	      i = 0;
+	      beg_end_state = NOMINAL;
 	      while (ch != ';' && ch != '\n' && ch != EOF && in_file_vars)
 		{
 		  if (i < sizeof val - 1)

test/src/lread-tests.el

@@ -199,4 +199,12 @@ literals (Bug#20852)."
    (read "#xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
    :type 'overflow-error))
 
+(ert-deftest lread-test-bug-31186 ()
+  (with-temp-buffer
+    (insert ";; -*- -:*-")
+    (should-not
+     ;; This used to crash in lisp_file_lexically_bound_p before the
+     ;; bug was fixed.
+     (eval-buffer))))
+
 ;;; lread-tests.el ends here