Merge from origin/emacs-26

226aca3 (origin/emacs-26) Fix documentation of 'flyspell-auto-correct...
a8c8434 * doc/emacs/misc.texi (Saving Emacs Sessions): Fix markup.
275e735 More changes in the Emacs manuals
d962be5 More fixes in the Emacs manual
6dc2846 * src/data.c (Faref): Fix a typo in the doc string.  (Bug#30510)
36e729f Minor edit in tramp.texi
6537f99 ; Fix oversight from last commit
eb94588 ; * doc/emacs/maintaining.texi: Fix two typos.
258135f More improvements in the Emacs manual
f138bca Improve documentation of 'electric-pair-mode'
f74ab96 ; Spelling and grammar fixes.
42f9dc4 ; * lisp/textmodes/flyspell.el (flyspell-auto-correct-word): ...

7 files changed, 76 insertions, 43 deletions

diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi
index 9349d2d5baa..00b9e560ac0 100644
--- a/doc/emacs/abbrevs.texi
+++ b/doc/emacs/abbrevs.texi
@@ -72,18 +72,24 @@ use in later sessions.
 @item C-x a g
 Define an abbrev, using one or more words before point as its expansion
 (@code{add-global-abbrev}).
+
 @item C-x a l
 Similar, but define an abbrev specific to the current major mode
 (@code{add-mode-abbrev}).
+
 @item C-x a i g
 Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
+
 @item C-x a i l
 Define a word in the buffer as a mode-specific abbrev
 (@code{inverse-add-mode-abbrev}).
+
 @item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
 Define @var{abbrev} as an abbrev expanding into @var{exp}.
+
 @item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
 Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}.
+
 @item M-x kill-all-abbrevs
 Discard all abbrev definitions, leaving a blank slate.
 @end table
@@ -160,10 +166,16 @@ to @samp{FIND OUTER OTTER}.
 @item M-'
 Separate a prefix from a following abbrev to be expanded
 (@code{abbrev-prefix-mark}).
+
 @item C-x a e
 @findex expand-abbrev
 Expand the abbrev before point (@code{expand-abbrev}).
 This is effective even when Abbrev mode is not enabled.
+
+@item M-x unexpand-abbrev
+@findex unexpand-abbrev
+Undo the expansion of the last expanded abbrev.
+
 @item M-x expand-region-abbrevs
 Expand some or all abbrevs found in the region.
 @end table
@@ -188,7 +200,6 @@ its expansion, you can accomplish this by inserting the following
 punctuation with @kbd{C-q}.  Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
 the buffer, not expanding it.
 
-@findex unexpand-abbrev
   If you expand an abbrev by mistake, you can undo the expansion by
 typing @kbd{C-/} (@code{undo}).  @xref{Undo}.  This undoes the
 insertion of the abbrev expansion and brings back the abbrev text.  If
@@ -219,6 +230,7 @@ Reference Manual}.
 @item M-x list-abbrevs
 Display a list of all abbrev definitions.  With a numeric argument, list
 only local abbrevs.
+
 @item M-x edit-abbrevs
 Edit a list of abbrevs; you can add, alter or remove definitions.
 @end table
@@ -278,10 +290,13 @@ sessions.
 @table @kbd
 @item M-x write-abbrev-file @key{RET} @var{file} @key{RET}
 Write a file @var{file} describing all defined abbrevs.
+
 @item M-x read-abbrev-file @key{RET} @var{file} @key{RET}
 Read the file @var{file} and define abbrevs as specified therein.
+
 @item M-x define-abbrevs
 Define abbrevs from definitions in current buffer.
+
 @item M-x insert-abbrevs
 Insert all abbrevs and their expansions into current buffer.
 @end table
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 4db3855dd9c..aa91f0555e1 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -778,12 +778,12 @@ lines).
 
   You can use a numeric argument before a self-inserting character to
 insert multiple copies of it.  This is straightforward when the
-character is not a digit; for example, @kbd{C-u 6 4 a} inserts 64
+character is not a digit; for example, @w{@kbd{C-u 6 4 a}} inserts 64
 copies of the character @samp{a}.  But this does not work for
-inserting digits; @kbd{C-u 6 4 1} specifies an argument of 641.  You
-can separate the argument from the digit to insert with another
-@kbd{C-u}; for example, @kbd{C-u 6 4 C-u 1} does insert 64 copies of
-the character @samp{1}.
+inserting digits; @w{@kbd{C-u 6 4 1}} specifies an argument of 641.
+You can separate the argument from the digit to insert with another
+@kbd{C-u}; for example, @w{@kbd{C-u 6 4 C-u 1}} does insert 64 copies
+of the character @samp{1}.
 
   Some commands care whether there is an argument, but ignore its
 value.  For example, the command @kbd{M-q} (@code{fill-paragraph})
@@ -822,7 +822,7 @@ invoking the command.
 @cindex repeating a command
 
   Many simple commands, such as those invoked with a single key or
-with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by
+with @w{@kbd{M-x @var{command-name} @key{RET}}}, can be repeated by
 invoking them with a numeric argument that serves as a repeat count
 (@pxref{Arguments}).  However, if the command you want to repeat
 prompts for input, or uses a numeric argument in another way, that
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index b985d12cde4..07ddd1f23b9 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -109,7 +109,7 @@ group, which contains several other groups (@samp{Editing},
 listed here, only one line of documentation each.
 
   The @dfn{state} of the group indicates whether setting in that group
-has been edited, set or saved.  @xref{Changing a Variable}.
+has been edited, set, or saved.  @xref{Changing a Variable}.
 
 @cindex editable fields (customization buffer)
 @cindex buttons (customization buffer)
@@ -168,7 +168,7 @@ search field, except that it reads the search term(s) using the
 minibuffer.  @xref{Specific Customization}.
 
   @kbd{M-x customize-browse} is another way to browse the available
-settings.  This command creates a special customization buffer which
+settings.  This command creates a special customization buffer, which
 shows only the names of groups and settings, in a structured layout.
 You can show the contents of a group, in the same buffer, by invoking
 the @samp{[+]} button next to the group name.  When the group contents
@@ -580,7 +580,7 @@ directory specified by the variable @code{custom-theme-directory}
 (which defaults to @file{~/.emacs.d/}), and a directory named
 @file{etc/themes} in your Emacs installation (see the variable
 @code{data-directory}).  The latter contains several Custom themes
-which are distributed with Emacs, which customize Emacs's faces to fit
+distributed with Emacs that customize Emacs's faces to fit
 various color schemes.  (Note, however, that Custom themes need not be
 restricted to this purpose; they can be used to customize variables
 too.)
@@ -663,7 +663,7 @@ to insert some common Emacs faces into the theme (a convenience, since
 Custom themes are often used to customize faces).  If you answer no,
 the theme will initially contain no settings.
 
-  Near the top of the @file{*Custom Theme*} buffer are editable fields
+  Near the top of the @file{*Custom Theme*} buffer, there are editable fields
 where you can enter the theme's name and description.  The name can be
 anything except @samp{user}.  The description is the one that will be
 shown when you invoke @kbd{M-x describe-theme} for the theme.  Its
@@ -1427,7 +1427,7 @@ of lower-case letters and hyphens.
 
   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of
 @dfn{input events} that have a meaning as a unit.  Input events
-include characters, function keys and mouse buttons---all the inputs
+include characters, function keys, and mouse buttons---all the inputs
 that you can send to the computer.  A key sequence gets its meaning
 from its @dfn{binding}, which says what command it runs.
 
@@ -1460,7 +1460,7 @@ can even mix mouse events with keyboard events, such as
 @kbd{S-down-mouse-1}.
 
   On text terminals, typing a function key actually sends the computer
-a sequence of characters; the precise details of the sequence depends
+a sequence of characters; the precise details of the sequence depend
 on the function key and on the terminal type.  (Often the sequence
 starts with @kbd{@key{ESC} [}.)  If Emacs understands your terminal
 type properly, it automatically handles such sequences as single input
@@ -1484,7 +1484,7 @@ the same, but it provides a command name for the prefix key that can be
 used as a description of what the prefix key is for.  Thus, the binding
 of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function
 definition is the keymap for @kbd{C-x} commands.  The definitions of
-@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
+@kbd{C-c}, @kbd{C-x}, @kbd{C-h}, and @key{ESC} as prefix keys appear in
 the global map, so these prefix keys are always available.
 
   Aside from ordinary prefix keys, there is a fictitious ``prefix key''
@@ -1669,6 +1669,8 @@ command is less work to invoke when you really want to.
 @node Init Rebinding
 @subsection Rebinding Keys in Your Init File
 @cindex rebinding major mode keys
+@cindex key rebinding, permanent
+@cindex rebinding keys, permanently
 @c This node is referenced in the tutorial.  When renaming or deleting
 @c it, the tutorial needs to be adjusted.  (TUTORIAL.de)
 
@@ -1795,7 +1797,7 @@ could make @kbd{M-a} and @kbd{M-A} run different commands.
 
   Although only the @key{Control} and @key{META} modifier keys are
 commonly used, Emacs supports three other modifier keys.  These are
-called @key{Super}, @key{Hyper} and @key{Alt}.  Few terminals provide
+called @key{Super}, @key{Hyper}, and @key{Alt}.  Few terminals provide
 ways to use these modifiers; the key labeled @key{Alt} on most
 keyboards usually issues the @key{META} modifier, not @key{Alt}.  The
 standard key bindings in Emacs do not include any characters with
@@ -1856,7 +1858,7 @@ key.
   @xref{Init Rebinding}, for examples of binding function keys.
 
 @cindex keypad
-  Many keyboards have a numeric keypad on the right hand side.
+  Many keyboards have a numeric keypad on the right-hand side.
 The numeric keys in the keypad double up as cursor motion keys,
 toggled by a key labeled @samp{Num Lock}.  By default, Emacs
 translates these keys to the corresponding keys on the main keyboard.
@@ -1882,7 +1884,7 @@ prefix arguments.
 @node Named ASCII Chars
 @subsection Named @acronym{ASCII} Control Characters
 
-  @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
+  @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC}, and @key{DEL}
 started out as names for certain @acronym{ASCII} control characters,
 used so often that they have special keys of their own.  For instance,
 @key{TAB} was another name for @kbd{C-i}.  Later, users found it
@@ -1999,7 +2001,7 @@ units of 1/8 of a character cell on text-mode terminals; the default is
 
   The symbols for mouse events also indicate the status of the modifier
 keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
-@samp{s-}, @samp{A-} and @samp{S-}.  These always precede @samp{double-}
+@samp{s-}, @samp{A-}, and @samp{S-}.  These always precede @samp{double-}
 or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
 
   A frame includes areas that don't show text from the buffer, such as
@@ -2099,8 +2101,6 @@ as a function from Lisp programs.
 @cindex .emacs file
 @cindex ~/.emacs file
 @cindex Emacs initialization file
-@cindex key rebinding, permanent
-@cindex rebinding keys, permanently
 @cindex startup (init file)
 
   When Emacs is started, it normally tries to load a Lisp program from
@@ -2311,7 +2311,7 @@ name.
 
 @need 1500
 @item
-Set up defaults for the Latin-1 character set
+Set up defaults for the Latin-1 character set,
 which supports most of the languages of Western Europe.
 
 @example
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 541bf9708ba..23e08a58e88 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1611,7 +1611,7 @@ To change this, customize @code{change-log-directory-files}.
 
 @vindex add-log-keep-changes-together
   When the variable @code{add-log-keep-changes-together} is
-non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
+non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file,
 rather than starting a new item.
 
 You can combine multiple changes of the same nature.  If you don't
@@ -1827,7 +1827,7 @@ If the specified identifier has only one definition, the command jumps
 to it.  If the identifier has more than one possible definition (e.g.,
 in an object-oriented language, or if there's a function and a
 variable by the same name), the command shows the candidate
-definitions in a @file{*xref*} buffer, together with the files in
+definitions in the @file{*xref*} buffer, together with the files in
 which these definitions are found.  Selecting one of these candidates
 by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
 showing the corresponding definition.
@@ -1883,28 +1883,34 @@ the special XREF mode:
 @item @key{RET}
 @itemx mouse-2
 Display the reference on the current line.
+
 @item n
 @itemx .
 @findex xref-next-line
 Move to the next reference and display it in the other window
 (@code{xref-next-line}).
+
 @item p
 @itemx ,
 @findex xref-prev-line
 Move to the previous reference and display it in the other window
 (@code{xref-prev-line}).
+
 @item C-o
 @findex xref-show-location-at-point
 Display the reference on the current line in the other window
 (@code{xref-show-location-at-point}).
+
 @item @key{TAB}
 @findex xref-quit-and-goto-xref
 Display the reference on the current line and bury the @file{*xref*}
 buffer (@code{xref-quit-and-goto-xref}).
+
 @item r @var{pattern} @key{RET} @var{replacement} @key{RET}
 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}.
+
 @findex xref-quit
 @item q
 Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
@@ -1926,14 +1932,18 @@ them.
 @table @kbd
 @item M-?
 Find all the references for the identifier at point.
+
 @item M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
 Interactively replace @var{regexp} with @var{replacement} in the names
 of all the identifiers shown in the @file{*xref*} buffer.
+
 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
 Search for @var{regexp} through the files in the selected tags
 table.
+
 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
 Perform a @code{query-replace-regexp} on each file in the selected tags table.
+
 @item M-x tags-loop-continue
 Restart one of the last 2 commands above, from the current location of point.
 @end table
@@ -1943,7 +1953,7 @@ Restart one of the last 2 commands above, from the current location of point.
   @kbd{M-?} finds all the references for the identifier at point.  If
 there's no identifier at point, or when invoked with a prefix
 argument, the command prompts for the identifier, with completion.  It
-then presents a @file{*xref*} buffer with all the references to the
+then presents the @file{*xref*} buffer with all the references to the
 identifier, showing the file name and the line where the identifier is
 referenced.  The XREF mode commands are available in this buffer, see
 @ref{Xref Commands}.
@@ -1967,7 +1977,7 @@ available (@pxref{Tags Tables}).
 
 @findex tags-loop-continue
   Having found one match with @code{tags-search}, you probably want to
-find all the rest.  Type @kbd{M-x tags-loop-continue} to resume the
+find all the rest.  @kbd{M-x tags-loop-continue} resumes the
 @code{tags-search}, finding one more match.  This searches the rest of
 the current buffer, followed by the remaining files of the tags table.
 
@@ -2017,11 +2027,14 @@ Searching}.
 @itemx M-@key{TAB}
 Perform completion on the text around point, possibly using the
 selected tags table if one is loaded (@code{completion-at-point}).
+
 @item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
 Display a list of all known identifiers matching @var{regexp}.
+
 @item M-x list-tags @key{RET} @var{file} @key{RET}
 Display a list of the identifiers defined in the program file
 @var{file}.
+
 @item M-x next-file
 Visit files recorded in the selected tags table.
 @end table
@@ -2435,11 +2448,12 @@ matches at the beginning of a line.  If you want to allow indented
 tags, use a regexp that matches initial whitespace; start it with
 @samp{[ \t]*}.
 
-  In these regular expressions, @samp{\} quotes the next character, and
-all the GCC character escape sequences are supported (@samp{\a} for
-bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
-escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
-carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
+  In these regular expressions, @samp{\} quotes the next character,
+and all the C character escape sequences are supported: @samp{\a} for
+bell, @samp{\b} for back space, @samp{\e} for escape, @samp{\f} for
+formfeed, @samp{\n} for newline, @samp{\r} for carriage return,
+@samp{\t} for tab, and @samp{\v} for vertical tab.  In addition,
+@samp{\d} stands for the @code{DEL} character.
 
   Ideally, @var{tagregexp} should not match more characters than are
 needed to recognize what you want to tag.  If the syntax requires you
@@ -2607,13 +2621,13 @@ current list, it is used @emph{as well as} the others.
 @example
 @group
 (setq tags-table-list
-      '("~/emacs" "/usr/local/lib/emacs/src"))
+      '("~/.emacs.d" "/usr/local/lib/emacs/src"))
 @end group
 @end example
 
 @noindent
 This tells the tags commands to look at the @file{TAGS} files in your
-@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
+@file{~/.emacs.d} directory and in the @file{/usr/local/lib/emacs/src}
 directory.  The order depends on which file you are in and which tags
 table mentions that file.
 
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index cfc689e4641..9610ed4dd89 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2475,7 +2475,7 @@ seconds, if that is non-@code{nil} and non-zero.
   If you turn on @code{desktop-save-mode} in your init file, then when
 Emacs starts, it looks for a saved desktop in the current directory.
 (More precisely, it looks in the directories specified by
-@var{desktop-path}, and uses the first desktop it finds.)
+@code{desktop-path}, and uses the first desktop it finds.)
 Thus, you can have separate saved desktops in different directories,
 and the starting directory determines which one Emacs reloads.  You
 can save the current desktop and reload one saved in another directory
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 4a59f4307ed..042a197f9b7 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -843,12 +843,17 @@ or the last, non-whitespace position on the line.
 @cindex inserting matching parentheses
 @findex electric-pair-mode
   Electric Pair mode, a global minor mode, provides a way to easily
-insert matching delimiters.  Whenever you insert an opening delimiter,
-the matching closing delimiter is automatically inserted as well,
-leaving point between the two.  Conversely, when you insert a closing
-delimiter over an existing one, no inserting takes places and that
-position is simply skipped over.  These variables control additional
-features of Electric Pair mode:
+insert matching delimiters: parentheses, braces, brackets, etc.
+Whenever you insert an opening delimiter, the matching closing
+delimiter is automatically inserted as well, leaving point between the
+two.  Conversely, when you insert a closing delimiter over an existing
+one, no insertion takes places, and that position is simply skipped
+over.  If the region is active (@pxref{Mark}), insertion of a
+delimiter operates on the region: the characters in the region are
+enclosed in a pair of matching delimiters, leaving point after the
+delimiter you typed.
+
+These variables control additional features of Electric Pair mode:
 
 @itemize @bullet
 @item
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 709e9836c90..bf85b00e937 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -3124,12 +3124,11 @@ machines, but will fail if the machine's arithmetic is extremely
 unusual, e.g., decimal.
 @end defun
 
-Since true Common Lisp supports up to four different floating-point
-precisions, it has families of constants like
+Since true Common Lisp supports up to four different kinds of floating-point
+numbers, it has families of constants like
 @code{most-positive-single-float}, @code{most-positive-double-float},
 @code{most-positive-long-float}, and so on.  Emacs has only one
-floating-point precision, so this package omits the precision word
-from the constants' names.
+kind of floating-point number, so this package just uses single constants.
 
 @defvar cl-most-positive-float
 This constant equals the largest value a Lisp float can hold.