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

ChangeLog.2

@@ -26364,7 +26364,7 @@
 	(verilog-calc-1): Detect 'pure virtual method' declarations which
 	exist in abstract classes.  Reported by Enzo Chi and Kaushal Modi.
 	(verilog-backward-ws&directives): When moving back to the start of
-	a line and the preceeding line ended with an escaped-newline, then
+	a line and the preceding line ended with an escaped-newline, then
 	jump up one line.  This properly consumes a multi-line
 	pre-processor directive.  Reported by Kaushal Modi.
 	(verilog-dpi-import-export-re, verilog-extended-complete-re)

ChangeLog.3

@@ -9905,7 +9905,7 @@
 
 	* lisp/man.el (Man-see-also-regexp): Add support for SEE ALSO
 	section detection in several langages: French, German, Spanish,
-	Portugese, Italian, Polish, Turkish, Japanese, Chinese.  (Bug#28142)
+	Portuguese, Italian, Polish, Turkish, Japanese, Chinese.  (Bug#28142)
 
 2017-08-26  Paul Eggert  <eggert@cs.ucla.edu>
 

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

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
+inserting digits; @w{@kbd{C-u 6 4 1}} specifies an argument of 641.
-can separate the argument from the digit to insert with another
+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
+@kbd{C-u}; for example, @w{@kbd{C-u 6 4 C-u 1}} does insert 64 copies
-the character @samp{1}.
+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

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

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
+  In these regular expressions, @samp{\} quotes the next character,
-all the GCC character escape sequences are supported (@samp{\a} for
+and all the C character escape sequences are supported: @samp{\a} for
-bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
+bell, @samp{\b} for back space, @samp{\e} for escape, @samp{\f} for
-escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
+formfeed, @samp{\n} for newline, @samp{\r} for carriage return,
-carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
+@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.
 

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

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,
+insert matching delimiters: parentheses, braces, brackets, etc.
-the matching closing delimiter is automatically inserted as well,
+Whenever you insert an opening delimiter, the matching closing
-leaving point between the two.  Conversely, when you insert a closing
+delimiter is automatically inserted as well, leaving point between the
-delimiter over an existing one, no inserting takes places and that
+two.  Conversely, when you insert a closing delimiter over an existing
-position is simply skipped over.  These variables control additional
+one, no insertion takes places, and that position is simply skipped
-features of Electric Pair mode:
+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

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
+Since true Common Lisp supports up to four different kinds of floating-point
-precisions, it has families of constants like
+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
+kind of floating-point number, so this package just uses single constants.
-from the constants' names.
 
 @defvar cl-most-positive-float
 This constant equals the largest value a Lisp float can hold.

lisp/ChangeLog.6

@@ -3506,7 +3506,7 @@
 	(sgml-beginning-of-tag, sgml-value): New functions.
 
 	(html-*): All these functions and variables are new.
-	Mostly they parametrize everything preceding.
+	Mostly they parameterize everything preceding.
 
 	* autoinsert.el (auto-insert-alist): For html-mode, use `sgml-tag'.
 

lisp/elec-pair.el

@@ -580,8 +580,11 @@ the mode if ARG is omitted or nil.
 
 Electric Pair mode is a global minor mode.  When enabled, typing
 an open parenthesis automatically inserts the corresponding
-closing parenthesis.  (Likewise for brackets, etc.). To toggle
+closing parenthesis, and vice versa.  (Likewise for brackets, etc.).
-the mode in a single buffer, use `electric-pair-local-mode'."
+If the region is active, the parentheses (brackets, etc.) are
+inserted around the region instead.
+
+To toggle the mode in a single buffer, use `electric-pair-local-mode'."
   :global t :group 'electricity
   (if electric-pair-mode
       (progn

lisp/emacs-lisp/byte-opt.el

@@ -1402,7 +1402,7 @@
 	     (setq offset (- offset #x80)))
             ((eq bytedecomp-op 'byte-switch)
              (cl-assert (hash-table-p last-constant) nil
-                        "byte-switch used without preceeding hash table")
+                        "byte-switch used without preceding hash table")
              ;; We cannot use the original hash table referenced in the op,
              ;; so we create a copy of it, and replace the addresses with
              ;; TAGs.

lisp/progmodes/cc-engine.el

@@ -2585,7 +2585,7 @@ comment at the start of cc-engine.el for more info."
   ;; or the car of the list is the "position element" of ELT, the position
   ;; where ELT is valid.
   ;;
-  ;; POINT is left at the postition for which the returned state is valid.  It
+  ;; POINT is left at the position for which the returned state is valid.  It
   ;; will be either the position element of ELT, or one character before
   ;; that.  (The latter happens in Emacs <= 25 and XEmacs, when ELT indicates
   ;; its position element directly follows a potential first character of a
@@ -2656,7 +2656,7 @@ comment at the start of cc-engine.el for more info."
 	      ((nth 3 state)		; A string
 	       (list (point) (nth 3 state) (nth 8 state)))
 	      ((and (nth 4 state)		 ; A comment
-		    (not (eq (nth 7 state) 'syntax-table))) ; but not a psuedo comment.
+		    (not (eq (nth 7 state) 'syntax-table))) ; but not a pseudo comment.
 	       (list (point)
 		     (if (eq (nth 7 state) 1) 'c++ 'c)
 		     (nth 8 state)))

lisp/textmodes/flyspell.el

@@ -1103,7 +1103,10 @@ If the optional argument FOLLOWING, or, when called interactively
 `ispell-following-word', is non-nil, checks the following (rather
 than preceding) word when the cursor is not over a word.  If
 optional argument KNOWN-MISSPELLING is non nil considers word a
-misspelling and skips redundant spell-checking step."
+misspelling and skips redundant spell-checking step.
+
+See `flyspell-get-word' for details of how this finds the word to
+spell-check."
   (interactive (list ispell-following-word))
   (ispell-set-spellchecker-params)    ; Initialize variables and dicts alists
   (save-excursion
@@ -1302,7 +1305,13 @@ misspelling and skips redundant spell-checking step."
 Optional argument FOLLOWING non-nil means to get the following
 \(rather than preceding) word when the cursor is not over a word.
 Optional second argument EXTRA-OTHERCHARS is a regexp of characters
-that may be included as part of a word (see `ispell-dictionary-alist')."
+that may be included as part of a word (see `ispell-dictionary-alist').
+
+This finds the word to spell-check by searching for CASECHARS defined
+in `ispell-dictionary-alist' for the current dictionary.  Thus, the
+word could be far away of point if point is inside whitespace or
+punctuation characters, or in text that belongs to a different
+language."
   (let* ((flyspell-casechars (flyspell-get-casechars))
 	 (flyspell-not-casechars (flyspell-get-not-casechars))
 	 (ispell-otherchars (ispell-get-otherchars))
@@ -1919,8 +1928,10 @@ before point that's highlighted as misspelled."
   "Correct the current word.
 This command proposes various successive corrections for the
 current word.  If invoked repeatedly on the same position, it
-cycles through the possible corrections of the word at or near
+cycles through the possible corrections of the current word.
-that position."
+
+See `flyspell-get-word' for details of how this finds the word to
+spell-check."
   (interactive)
   ;; If we are not in the construct where flyspell should be active,
   ;; invoke the original binding of M-TAB, if that was recorded.
@@ -2000,7 +2011,7 @@ that position."
                             (let ((new-word replace))
                               (if (not (equal new-word (car poss)))
                                   (progn
-                                    ;; the save the current replacements
+                                    ;; then save the current replacements
                                     (setq flyspell-auto-correct-region
                                           (cons start (length new-word)))
                                     (let ((l replacements))

src/data.c

@@ -2271,8 +2271,8 @@ function chain of symbols.  */)
 /* Extract and set vector and string elements.  */
 
 DEFUN ("aref", Faref, Saref, 2, 2, 0,
-       doc: /* Return the element of ARG at index IDX.
+       doc: /* Return the element of ARRAY at index IDX.
-ARG may be a vector, a string, a char-table, a bool-vector, a record,
+ARRAY may be a vector, a string, a char-table, a bool-vector, a record,
 or a byte-code object.  IDX starts at 0.  */)
   (register Lisp_Object array, Lisp_Object idx)
 {