Merge from origin/emacs-26

6f495ab (origin/emacs-26) Another round of manual fixups
59344c4 * doc/lispref/customize.texi (Custom Themes): Clarify .el pre...
6386efc * doc/emacs/entering.texi (Entering Emacs): Another wording fix.
e21f018 * doc/lispref/functions.texi (Inline Functions): Fix typo (Bu...
1c2fb04 * lisp/imenu.el (imenu-generic-expression): Rephrase doc (Bug...
b90e91c Fix last change of @key markup
f180075 * doc/emacs/entering.texi (Entering Emacs): Fix markup.

16 files changed, 76 insertions, 61 deletions

diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 55e0145d7d1..11be78de68b 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -286,11 +286,14 @@ arguments.
 @findex beginning-of-buffer
 Move to the top of the buffer (@code{beginning-of-buffer}).  With
 numeric argument @var{n}, move to @var{n}/10 of the way from the top.
+On graphical displays, @kbd{C-@key{HOME}} does the same.
 
 @item M->
 @kindex M->
+@kindex C-@key{END}
 @findex end-of-buffer
-Move to the end of the buffer (@code{end-of-buffer}).
+Move to the end of the buffer (@code{end-of-buffer}).  On graphical
+displays, @kbd{C-@key{END}} does the same.
 
 @item C-v
 @itemx @key{PageDown}
@@ -401,9 +404,12 @@ Delete the character after point (@code{delete-char}).
 
 @item C-k
 Kill to the end of the line (@code{kill-line}).
+
 @item M-d
 Kill forward to the end of the next word (@code{kill-word}).
+
 @item M-@key{DEL}
+@itemx M-@key{BACKSPACE}
 Kill back to the beginning of the previous word
 (@code{backward-kill-word}).
 @end table
@@ -448,12 +454,11 @@ commands.
 
 @table @kbd
 @item C-/
-Undo one entry of the undo records---usually, one command worth
-(@code{undo}).
-
-@item C-x u
+@itemx C-x u
 @itemx C-_
-The same.
+Undo one entry of the undo records---usually, one command worth
+(@code{undo}).  (The first key might be unavailable on text-mode
+displays.)
 @end table
 
   Emacs records a list of changes made in the buffer text, so you can
@@ -655,7 +660,7 @@ Toggle automatic display of the size of the buffer.
 @cindex cursor location
 @cindex point location
   @kbd{M-x what-line} displays the current line number in the echo
-area.  This command is usually redundant, because the current line
+area.  This command is usually redundant because the current line
 number is shown in the mode line (@pxref{Mode Line}).  However, if you
 narrow the buffer, the mode line shows the line number relative to
 the accessible portion (@pxref{Narrowing}).  By contrast,
@@ -800,7 +805,7 @@ fills text; with an argument, it justifies the text as well.
 commands, it is enough to specify the argument with a single
 @kbd{C-u}.
 
-  Some commands use the value of the argument as a repeat count, but
+  Some commands use the value of the argument as a repeat count but
 do something special when there is no argument.  For example, the
 command @kbd{C-k} (@code{kill-line}) with argument @var{n} kills
 @var{n} lines, including their terminating newlines.  But @kbd{C-k}
@@ -822,6 +827,9 @@ such arguments before the command, and to distinguish them from
 minibuffer arguments (@pxref{Minibuffer}), which are entered after
 invoking the command.
 
+  On graphical displays, @kbd{C-0}, @kbd{C-1}, etc.@ act the same as
+@kbd{M-0}, @kbd{M-1}, etc.
+
 @node Repeating
 @section Repeating a Command
 @cindex repeating a command
@@ -842,7 +850,7 @@ that were used before; it does not read new arguments each time.
 
   To repeat the command more than once, type additional @kbd{z}'s: each
 @kbd{z} repeats the command one more time.  Repetition ends when you
-type a character other than @kbd{z}, or press a mouse button.
+type a character other than @kbd{z} or press a mouse button.
 
   For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20
 characters.  You can repeat that command (including its argument) three
diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index f1fc24da6f2..3b645d5e65c 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -209,14 +209,13 @@ through errors in the opposite direction.
 act on the errors or matches listed in @file{*compilation*} and
 @file{*grep*} buffers; they also know how to iterate through error or
 match lists produced by other commands, such as @kbd{M-x occur}
-(@pxref{Other Repeating Search}).  If you are already in a buffer
-containing error messages or matches, those are the ones that are
-iterated through; otherwise, Emacs looks for a buffer containing error
-messages or matches amongst the windows of the selected frame, then
-for one that @code{next-error} or @code{previous-error} previously
-iterated through, and finally amongst all other buffers.  If the
-buffer chosen for iterating through is not currently displayed in a
-window, it will be displayed.
+(@pxref{Other Repeating Search}).  If the current buffer contains
+error messages or matches, these commands will iterate through them;
+otherwise, Emacs looks for a buffer containing error messages or
+matches amongst the windows of the selected frame, then for any buffer
+that @code{next-error} or @code{previous-error} previously visited,
+and finally all other buffers.  Any buffer these commands iterate
+through that is not currently displayed in a window will be displayed.
 
 @vindex compilation-skip-threshold
   By default, the @code{next-error} and @code{previous-error} commands
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 83051864cc8..7fbb0b91cc7 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -76,7 +76,7 @@ C-x d  ~/foo/*/*.el  @key{RET}
 
 The former lists all the files with extension @samp{.el} in directory
 @samp{foo}.  The latter lists the files with extension @samp{.el}
-in subdirectories 2 levels of depth below @samp{foo}.
+in all the subdirectories of @samp{foo}.
 
 The usual history and completion commands can be used in the minibuffer;
 in particular, @kbd{M-n} puts the name of the visited file (if any) in
@@ -241,7 +241,7 @@ Even if you have set @code{dired-recursive-deletes} to @code{nil},
 you might want sometimes to delete recursively directories
 without being asked for confirmation for all of them.  This is handy
 when you have marked many directories for deletion and you are very
-sure that all of them can safely being deleted.  For every nonempty
+sure that all of them can safely be deleted.  For every nonempty
 directory you are asked for confirmation; if you answer @code{all},
 then all the remaining directories will be deleted without more
 questions.
@@ -488,10 +488,11 @@ Remove all marks from all the files in this Dired buffer
 @kindex M-DEL @r{(Dired)}
 @findex dired-unmark-all-files
 Remove all marks that use the character @var{markchar}
-(@code{dired-unmark-all-files}).  The argument is a single
-character---do not use @key{RET} to terminate it.  See the description
-of the @kbd{* c} command below, which lets you replace one mark
-character with another.
+(@code{dired-unmark-all-files}).  If invoked with @kbd{M-@key{DEL}},
+the command prompts for @var{markchar}.  That @var{markchar} is a
+single character---do not use @key{RET} to terminate it.  See the
+description of the @kbd{* c} command below, which lets you replace one
+mark character with another.
 
 With a numeric argument, this command queries about each marked file,
 asking whether to remove its mark.  You can answer @kbd{y} meaning yes,
@@ -503,7 +504,7 @@ files without asking about them.
 @findex dired-next-marked-file
 @kindex * C-n @r{(Dired)}
 @kindex M-@} @r{(Dired)}
-Move down to the next marked file (@code{dired-next-marked-file})
+Move down to the next marked file (@code{dired-next-marked-file}).
 A file is ``marked'' if it has any kind of mark.
 
 @item * C-p
@@ -511,7 +512,7 @@ A file is ``marked'' if it has any kind of mark.
 @findex dired-prev-marked-file
 @kindex * C-p @r{(Dired)}
 @kindex M-@{ @r{(Dired)}
-Move up to the previous marked file (@code{dired-prev-marked-file})
+Move up to the previous marked file (@code{dired-prev-marked-file}).
 
 @item t
 @itemx * t
@@ -574,9 +575,9 @@ the regular expression @var{regexp}
 name.  Note that if a file is visited in an Emacs buffer,
 and @code{dired-always-read-filesystem} is @code{nil} (the default), this
 command will look in the buffer without revisiting the file, so the results
-might be inconsistent with the file on disk if its contents has changed
-since it was last visited.  If you don't want this, you may wish
-reverting the files you have visited in your buffers, or turning on
+might be inconsistent with the file on disk if its contents have changed
+since it was last visited.  If you don't want this, you may wish to
+revert the files you have visited in your buffers, or to turn on
 the @code{auto-revert} mode in those buffers, before invoking this
 command.  @xref{Reverting}.  If you prefer that this command always revisit
 the file, without having to revert the file or enable @code{auto-revert}
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index d0ab5486af1..e22d7f30afb 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -108,9 +108,9 @@ point unchanged, so that the text and point move up or down together.
   By default, these commands signal an error (by beeping or flashing
 the screen) if no more scrolling is possible, because the window has
 reached the beginning or end of the buffer.  If you change the
-variable @code{scroll-error-top-bottom} to @code{t}, the command moves
-point to the farthest possible position.  If point is already there,
-the command signals an error.
+variable @code{scroll-error-top-bottom} to @code{t}, these commands
+move point to the farthest possible position.  If point is already
+there, the commands signal an error.
 
 @vindex scroll-preserve-screen-position
 @cindex @code{scroll-command} property
@@ -270,7 +270,7 @@ parts of the window height from the bottom window edge.  Thus, larger
 view.  The default value, @code{nil}, is equivalent to 0.5.
 
   Likewise, @code{scroll-down-aggressively} is used when point goes
-above the bottom window edge (i.e., scrolling backward).  The value
+above the top window edge (i.e., scrolling backward).  The value
 specifies how far point should be from the top margin of the window
 after scrolling.  Thus, as with @code{scroll-up-aggressively}, a
 larger value is more aggressive.
@@ -330,8 +330,8 @@ scrolling away from that edge.
 scroll the window when point gets too close to the edge.  Zero, the
 default value, means to center point horizontally within the window.
 A positive integer value specifies the number of columns to scroll by.
-A floating-point number specifies the fraction of the window's width
-to scroll by.
+A floating-point number (whose value should be between 0 and 1)
+specifies the fraction of the window's width to scroll by.
 
   You can also perform explicit horizontal scrolling with the
 following commands:
@@ -1259,9 +1259,9 @@ Highlight empty lines.
 @item big-indent
 @vindex whitespace-big-indent-regexp
 Highlight too-deep indentation.  By default any sequence of at least 4
-consecutive @key{TAB} characters or 32 consecutive @key{SPC}
-characters is highlighted.  To change that, customize the regular
-expression @code{whitespace-big-indent-regexp}.
+consecutive TAB characters or 32 consecutive SPC characters is
+highlighted.  To change that, customize the regular expression
+@code{whitespace-big-indent-regexp}.
 
 @item space-mark
 Draw space and non-breaking characters with a special glyph.
@@ -1768,6 +1768,11 @@ variant, @code{global-display-line-numbers-mode}.  The user option
 @code{display-line-numbers-type} controls which sub-mode of
 line-number display, described above, will these modes activate.
 
+@noindent
+Note that line numbers are not displayed in the minibuffer and in the
+tooltips, even if you turn on @code{display-line-numbers-mode}
+globally.
+
 @vindex display-line-numbers-current-absolute
 When Emacs displays relative line numbers, you can control the number
 displayed before the current line, the line showing point.  By
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index b0539221b82..0051868fee6 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -723,7 +723,7 @@ C and Related Modes
 
 * Motion in C::         Commands to move by C statements, etc.
 * Electric C::          Colon and other chars can automatically reindent.
-* Hungry Delete::       A more powerful @key{DEL} command.
+* Hungry Delete::       A more powerful DEL command.
 * Other C Commands::    Filling comments, viewing expansion of macros,
                           and other neat features.
 
diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi
index 642c6ec1ab9..84b3e5d4cbf 100644
--- a/doc/emacs/entering.texi
+++ b/doc/emacs/entering.texi
@@ -18,11 +18,11 @@
 @cindex starting Emacs
 
   The usual way to invoke Emacs is with the shell command
-@command{emacs}.  From a terminal window running a Unix shell, you can
-run Emacs in the background with @command{emacs &}; this way, Emacs
-won't tie up the terminal window, so you can use it to run other shell
-commands.  (For comparable methods of starting Emacs on MS-Windows,
-see @ref{Windows Startup}.)
+@command{emacs}.  From a terminal window running a Unix shell on a GUI
+terminal, you can run Emacs in the background with @kbd{emacs &}; this
+way, Emacs won't tie up the terminal window, so you can use it to run
+other shell commands.  (For comparable methods of starting Emacs on
+MS-Windows, see @ref{Windows Startup}.)
 
 @cindex startup screen
   When Emacs starts up, the initial frame displays a special buffer
diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi
index 78203936c78..3416db53f4e 100644
--- a/doc/emacs/killing.texi
+++ b/doc/emacs/killing.texi
@@ -170,7 +170,7 @@ up to the end of the line; if point was originally at the beginning of
 the line, this leaves the line blank.
 
   Spaces and tabs at the end of the line are ignored when deciding
-which case applies.  As long as point is after the last visible
+which case applies.  As long as point is after the last non-whitespace
 character in the line, you can be sure that @kbd{C-k} will kill the
 newline.  To kill an entire non-blank line, go to the beginning and
 type @kbd{C-k} twice.
@@ -857,7 +857,7 @@ region is active.
 
 Unlike the standard region, the region-rectangle can have its corners
 extended past the end of buffer, or inside stretches of white space
-that point normally cannot enter, like the @key{TAB}.
+that point normally cannot enter, like the TAB.
 
 @findex rectangle-exchange-point-and-mark
 @findex exchange-point-and-mark@r{, in rectangle-mark-mode}
diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi
index c9cef750fb4..8528c9f6bd5 100644
--- a/doc/emacs/kmacro.texi
+++ b/doc/emacs/kmacro.texi
@@ -454,7 +454,7 @@ M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
 
 @noindent
 This inserts some Lisp code that, when executed later, will define the
-same macro with the same definition it has now.  (You need not
+same macro with the same definition it has now.  (You don't need to
 understand Lisp code to do this, because @code{insert-kbd-macro} writes
 the Lisp code for you.)  Then save the file.  You can load the file
 later with @code{load-file} (@pxref{Lisp Libraries}).  If the file you
diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 1438682d191..fcd229d817c 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -57,9 +57,9 @@ the minibuffer (since typing @key{RET} would no longer submit that
 default).  If you ever bring back the original minibuffer text, the
 prompt again shows the default.  Furthermore, if you change the
 variable @code{minibuffer-eldef-shorten-default} to a non-@code{nil}
-value, the default argument is displayed as @samp{[@var{default}]}
-instead of @samp{(default @var{default})}, saving some screen space.
-To enable this minor mode, type @kbd{M-x
+value, the default argument is displayed as @samp{[@var{default-arg}]}
+instead of @samp{(default @var{default-arg})}, saving some screen
+space.  To enable this minor mode, type @kbd{M-x
 minibuffer-electric-default-mode}.
 
   Since the minibuffer appears in the echo area, it can conflict with
@@ -224,7 +224,7 @@ set the variable @code{enable-recursive-minibuffers} to @code{t}.
   When not active, the minibuffer is in @code{minibuffer-inactive-mode},
 and clicking @kbd{mouse-1} there shows the @file{*Messages*} buffer.
 If you use a dedicated frame for minibuffers, Emacs also recognizes
-certain keys there, for example @kbd{n} to make a new frame.
+certain keys there, for example, @kbd{n} to make a new frame.
 
 @node Completion
 @section Completion
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 970647e1277..42891245451 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1587,7 +1587,7 @@ with Emacs.
 @menu
 * Motion in C::                 Commands to move by C statements, etc.
 * Electric C::                  Colon and other chars can automatically reindent.
-* Hungry Delete::               A more powerful @key{DEL} command.
+* Hungry Delete::               A more powerful DEL command.
 * Other C Commands::            Filling comments, viewing expansion of macros,
                                 and other neat features.
 @end menu
diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index 96500690de2..dd9e4d7cc7c 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -9,8 +9,8 @@
   Emacs @dfn{registers} are compartments where you can save text,
 rectangles, positions, and other things for later use.  Once you save
 text or a rectangle in a register, you can copy it into the buffer
-once, or many times; once you save a position in a register, you can
-jump back to that position once, or many times.
+once or many times; once you save a position in a register, you can
+jump back to that position once or many times.
 
   Each register has a name that consists of a single character, which
 we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 3c3ee659dcb..945b7cb941e 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -174,9 +174,9 @@ After the rightmost and bottommost window, it goes back to the one at
 the upper left corner.  A numeric argument means to move several steps
 in the cyclic order of windows.  A negative argument moves around the
 cycle in the opposite order.  When the minibuffer is active, the
-minibuffer is the last window in the cycle; you can switch from the
-minibuffer window to one of the other windows, and later switch back and
-finish supplying the minibuffer argument that is requested.
+minibuffer window is the last window in the cycle; you can switch from
+the minibuffer window to one of the other windows, and later switch
+back and finish supplying the minibuffer argument that is requested.
 @xref{Minibuffer Edit}.
 
 @kindex C-M-v
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 6c7ca260abc..7fea507fd03 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -1432,7 +1432,9 @@ where the list entries have the same meanings as in
 would be evaluated when loading the theme, but that is bad form.
 To protect against loading themes containing malicious code, Emacs
 displays the source file and asks for confirmation from the user
-before loading any non-built-in theme for the first time.
+before loading any non-built-in theme for the first time.  As
+such, themes are not ordinarily byte-compiled, and source files
+always take precedence when Emacs is looking for a theme to load.
 
   The following functions are useful for programmatically enabling and
 disabling themes:
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index bd1f671225c..fbf943a08c7 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4599,7 +4599,7 @@ first character in the group of consecutive characters that have the
 same @code{display} property.  The space width is the pixel width of
 that character, multiplied by @var{factor}.  (On text-mode terminals,
 the ``pixel width'' of a character is usually 1, but it could be more
-for @key{TAB}s and double-width CJK characters.)
+for TABs and double-width CJK characters.)
 
 @item :align-to @var{hpos}
 Specifies that the space should be wide enough to reach @var{hpos}.
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index c3e5dc0eb5b..9090956d837 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2098,7 +2098,7 @@ to verify that using @code{defun} actually has performance problems.
   After an inline function is defined, its inline expansion can be
 performed later on in the same file, just like macros.
 
-  It's possible to use @code{defsubst} to define a macro to expand
+  It's possible to use @code{defmacro} to define a macro to expand
 into the same code that an inline function would execute
 (@pxref{Macros}).  But the macro would be limited to direct use in
 expressions---a macro cannot be called with @code{apply},
diff --git a/lisp/imenu.el b/lisp/imenu.el
index b766d0e624c..f56e7b50396 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -224,8 +224,8 @@ If non-nil this pattern is passed to `imenu--generic-function' to
 create a buffer index.
 
 For example, see the value of `fortran-imenu-generic-expression'
-used by `fortran-mode' with `imenu-syntax-alist' set locally to
-give the characters which normally have \"symbol\" syntax
+used by `fortran-mode' with `imenu-syntax-alist' set locally so that
+characters which normally have \"symbol\" syntax are considered to have
 \"word\" syntax during matching.")
 ;;;###autoload(put 'imenu-generic-expression 'risky-local-variable t)