Another set of improvements in the Emacs manual

* doc/emacs/msdos-xtra.texi (MS-DOS Keyboard):
* doc/emacs/msdos.texi (Windows Keyboard):
* doc/emacs/mark.texi (Using Region):
* doc/emacs/frames.texi (Menu Mouse Clicks):
* doc/emacs/macos.texi (Mac / GNUstep Basics): Fix spelling of
keys.  Reported by Michael Albinus <michael.albinus@gmx.de> in
emacs-manual-bugs@gnu.org.

* doc/emacs/glossary.texi (Glossary): Document that "c.f." is a
misspelling.  Reported by Robert Pluim <rpluim@gmail.com>.
Various minor wording improvements.  Suggested by Toon Claes
<toon@iotcl.com> in emacs-manual-bugs@gnu.org.
More minor changes.  Suggested by Michael Albinus
<michael.albinus@gmx.de> in emacs-manual-bugs@gnu.org.

* doc/emacs/cmdargs.texi (Title X): Improve wording.

* doc/emacs/building.texi (Grep Searching, Compilation): Avoid
passive tense.

* doc/emacs/basic.texi (Moving Point): Move the description of the
bidi-related effects of the arrow keys from here ...
* doc/emacs/mule.texi (Bidirectional Editing): ... to here.
Explain the behavior of arrow keys between paragraphs.

10 files changed, 83 insertions, 65 deletions

diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 8a8298bc2c4..4db3855dd9c 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -184,18 +184,8 @@ Move forward one character (@code{forward-char}).
 @item @key{RIGHT}
 @kindex RIGHT
 @findex right-char
-@vindex visual-order-cursor-movement
-@cindex cursor, visual-order motion
-This command (@code{right-char}) behaves like @kbd{C-f}, with one
-exception: when editing right-to-left scripts such as Arabic, it
-instead moves @emph{backward} if the current paragraph is a
-right-to-left paragraph.  @xref{Bidirectional Editing}.
-
-If @code{visual-order-cursor-movement} is non-@code{nil}, this command
-moves to the character that is to the right of the current screen
-position, moving to the next or previous screen line as appropriate.
-Note that this might potentially move point many buffer positions
-away, depending on the surrounding bidirectional context.
+This command (@code{right-char}) behaves like @kbd{C-f}, except when
+point is in a right-to-left paragraph (@pxref{Bidirectional Editing}).
 
 @item C-b
 @kindex C-b
@@ -205,12 +195,8 @@ Move backward one character (@code{backward-char}).
 @item @key{LEFT}
 @kindex LEFT
 @findex left-char
-This command (@code{left-char}) behaves like @kbd{C-b}, except it
-moves @emph{forward} if the current paragraph is right-to-left.
-@xref{Bidirectional Editing}.
-
-The variable @code{visual-order-cursor-movement} affects this like
-@key{RIGHT}, but moving left instead of right on the screen.
+This command (@code{left-char}) behaves like @kbd{C-b}, except if the
+current paragraph is right-to-left (@pxref{Bidirectional Editing}).
 
 @item C-n
 @itemx @key{DOWN}
diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index f61e3335770..f2819c67c5d 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -90,9 +90,9 @@ inserted above point, which remains at the end.  Otherwise, point
 remains fixed while compilation output is added at the end of the
 buffer.
 
-  While compilation proceeds, the mode line is updated to show the
-number of errors, warnings, and informational messages that have been
-seen so far.
+  While compilation proceeds, the mode line shows the number of
+errors, warnings, and informational messages emitted by the compiler
+so far.
 
 @cindex compilation buffer, keeping point at end
 @vindex compilation-scroll-output
@@ -384,16 +384,16 @@ grep -nH -e foo *.el | grep bar | grep toto
 can find the corresponding lines in the original files using @w{@kbd{C-x
 `}}, @key{RET}, and so forth, just like compilation errors.
 
-  As with compilation commands (@pxref{Compilation}), while the grep
-command runs, the mode line is updated to show the number of matches
-that have been seen so far.
-
   Some grep programs accept a @samp{--color} option to output special
 markers around matches for the purpose of highlighting.  You can make
 use of this feature by setting @code{grep-highlight-matches} to
 @code{t}.  When displaying a match in the source buffer, the exact
 match will be highlighted, instead of the entire source line.
 
+  As with compilation commands (@pxref{Compilation}), while the grep
+command runs, the mode line shows the running number of matches found
+and highlighted so far.
+
   The @command{grep} commands will offer to save buffers before
 running.  This is controlled by the @code{grep-save-buffers} variable.
 The possible values are either @code{nil} (don't save), @code{ask}
diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index e463e7c8194..d18de8e7a02 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -1104,15 +1104,14 @@ border is 2.
 @node Title X
 @appendixsec Frame Titles
 
-  An Emacs frame may or may not have a specified title.  The frame
-title, if specified, appears in window decorations and icons as the
-name of the frame.  If an Emacs frame has no specified title, the
-default title has the form @samp{@var{invocation-name}@@@var{machine}}
-(if there is only one frame) or the selected window's buffer name (if
-there is more than one frame).
-
-  You can specify a title for the initial Emacs frame with a command
-line option:
+  Each Emacs frame always has a title, which appears in window
+decorations and icons as the name of the frame.  The default title is
+of the form @samp{@var{invocation-name}@@@var{machine}} (if there is
+only one frame) or shows the selected window's buffer name (if there
+is more than one frame).
+
+  You can specify a non-default title for the initial Emacs frame with
+a command line option:
 
 @table @samp
 @item -T @var{title}
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 2c1a55b7dc6..b2ec5746a0e 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -312,7 +312,7 @@ button.
 @node Menu Mouse Clicks
 @section Mouse Clicks for Menus
 
-  Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers
+  Several mouse clicks with the @key{Ctrl} and @key{SHIFT} modifiers
 bring up menus.
 
 @table @kbd
diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi
index 7a34692dc53..a9120194a49 100644
--- a/doc/emacs/glossary.texi
+++ b/doc/emacs/glossary.texi
@@ -24,7 +24,7 @@ Setting the mark (q.v.@:) at a position in the text also activates it.
 When the mark is active, we call the region an active region.
 @xref{Mark}.
 
-@item Alt
+@item @key{Alt}
 Alt is the name of a modifier bit that a keyboard input character may
 have.  To make a character Alt, type it while holding down the @key{Alt}
 key.  Such characters are given names that start with @kbd{@key{Alt}-}
@@ -160,10 +160,11 @@ right away when you press down on a mouse button.  @xref{Mouse Buttons}.
 @item Byte Compilation
 @xref{Glossary---Compilation}.
 
-@item c.f.
-@itemx cf.
+@item cf.
+@itemx c.f.
 Short for ``confer'' in Latin, which means ``compare with'' or
-``compare to''.
+``compare to''.  The second variant, ``c.f.'', is a widespread
+misspelling.
 
 @anchor{Glossary---C-}
 @item @kbd{C-}
@@ -192,7 +193,7 @@ other input events as well).  @xref{User Input}.
 
 @item Character Folding
 Character folding means ignoring differences between similarly looking
-characters, such as between @code{a}, and @code{@:a} and @code{@'a}.
+characters, such as between @code{a}, and @code{@"a} and @code{@'a}.
 Emacs performs character folding by default in text search.  @xref{Lax
 Search}.
 
@@ -225,14 +226,16 @@ text to or from a variety of coding systems when reading or writing it.
 @xref{Coding Systems}.
 
 @item Command
-A command is a Lisp function specially defined to be able to serve as a
-key binding in Emacs.  When you type a key sequence (q.v.), its
-binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find
-the command to run.  @xref{Commands}.
+A command is a Lisp function specially defined to be able to serve as
+a key binding in Emacs or to be invoked by its name
+(@pxref{Glossary---Command Name}).  When you type a key sequence
+(q.v.), its binding (q.v.@:) is looked up in the relevant keymaps
+(q.v.@:) to find the command to run.  @xref{Commands}.
 
 @item Command History
 @xref{Glossary---Minibuffer History}.
 
+@anchor{Glossary---Command Name}
 @item Command Name
 A command name is the name of a Lisp symbol that is a command
 (@pxref{Commands}).  You can invoke any command by its name using
@@ -255,7 +258,8 @@ Compilation is the process of creating an executable program from source
 code.  Emacs has commands for compiling files of Emacs Lisp code
 (@pxref{Byte Compilation,,, elisp, the Emacs Lisp
 Reference Manual}) and programs in C and other languages
-(@pxref{Compilation}).
+(@pxref{Compilation}).  Byte-compiled Emacs Lisp code loads and
+executes faster.
 
 @item Complete Key
 A complete key is a key sequence that fully specifies one action to be
@@ -875,7 +879,7 @@ A local value of a variable (q.v.@:) applies to only one buffer.
 @xref{Locals}.
 
 @item @kbd{M-}
-@kbd{M-} in the name of a character is an abbreviation for @key{Meta},
+@kbd{M-} in the name of a character is an abbreviation for @key{META},
 one of the modifier keys that can accompany any character.
 @xref{User Input,M-}.
 
@@ -933,15 +937,15 @@ a keyboard interface to navigate it.  @xref{Menu Bars}.
 
 @item Meta
 Meta is the name of a modifier bit which you can use in a command
-character.  To enter a meta character, you hold down the @key{Meta}
+character.  To enter a meta character, you hold down the @key{META}
 key while typing the character.  We refer to such characters with
 names that start with @kbd{Meta-} (usually written @kbd{M-} for
-short).  For example, @kbd{M-<} is typed by holding down @key{Meta}
+short).  For example, @kbd{M-<} is typed by holding down @key{META}
 and at the same time typing @kbd{<} (which itself is done, on most
 terminals, by holding down @key{SHIFT} and typing @kbd{,}).
 @xref{User Input,Meta}.
 
-On some terminals, the @key{Meta} key is actually labeled @key{Alt}
+On some terminals, the @key{META} key is actually labeled @key{Alt}
 or @key{Edit}.
 
 @item Meta Character
@@ -1139,8 +1143,8 @@ one corner and putting the mark at the diagonally opposite corner.
 A recursive editing level is a state in which part of the execution of
 a command involves asking you to edit some text.  This text may
 or may not be the same as the text to which the command was applied.
-The mode line indicates recursive editing levels with square brackets
-(@samp{[} and @samp{]}).  @xref{Recursive Edit}.
+The mode line (q.v.@:) indicates recursive editing levels with square
+brackets (@samp{[} and @samp{]}).  @xref{Recursive Edit}.
 
 @item Redisplay
 Redisplay is the process of correcting the image on the screen to
@@ -1168,7 +1172,7 @@ digits.  @xref{Regexps}.
 @item Remote File
 A remote file is a file that is stored on a system other than your own.
 Emacs can access files on other computers provided that they are
-connected to the same network as your machine, and (obviously) that
+reachable from your machine over the network, and (obviously) that
 you have a supported method to gain access to those files.
 @xref{Remote Files}.
 
@@ -1190,8 +1194,9 @@ newline into the text.  It is also used to terminate most arguments
 read in the minibuffer (q.v.).  @xref{User Input,Return}.
 
 @item Reverting
-Reverting means returning to the original state.  Emacs lets you
-revert a buffer by re-reading its file from disk.  @xref{Reverting}.
+Reverting means returning to the original state.  For example, Emacs
+lets you revert a buffer by re-reading its file from disk.
+@xref{Reverting}.
 
 @c Seems too obvious, also there is nothing special about the format
 @c these days.
@@ -1363,6 +1368,7 @@ Emacs does not make a termscript file unless you tell it to.
 @xref{Bugs}.
 
 @item Text
+
 ``Text'' has two meanings (@pxref{Text}):
 
 @itemize @bullet
@@ -1371,6 +1377,7 @@ Data consisting of a sequence of characters, as opposed to binary
 numbers, executable programs, and the like.  The basic contents of an
 Emacs buffer (aside from the text properties, q.v.@:) are always text
 in this sense.
+
 @item
 Data consisting of written human language (as opposed to programs),
 or following the stylistic conventions of human language.
@@ -1473,7 +1480,7 @@ where they can be edited.  @xref{Visiting}.
 
 @item Whitespace
 Whitespace is any run of consecutive formatting characters (space,
-tab, newline, and backspace).
+tab, newline, backspace, etc.).
 
 @item Widening
 Widening is removing any restriction (q.v.@:) on the current buffer;
diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi
index 28a5f9041ab..bf37d67b642 100644
--- a/doc/emacs/macos.texi
+++ b/doc/emacs/macos.texi
@@ -34,8 +34,8 @@ Support}), but we hope to improve it in the future.
 @node Mac / GNUstep Basics
 @section Basic Emacs usage under macOS and GNUstep
 
-  By default, the @key{alt} and @key{option} keys are the same as
-@key{Meta}.  The Mac @key{Cmd} key is the same as @key{Super}, and
+  By default, the @key{Alt} and @key{Option} keys are the same as
+@key{META}.  The Mac @key{Cmd} key is the same as @key{Super}, and
 Emacs provides a set of key bindings using this modifier key that mimic
 other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}).  You
 can change these bindings in the usual way (@pxref{Key Bindings}).
@@ -43,7 +43,7 @@ can change these bindings in the usual way (@pxref{Key Bindings}).
 @vindex ns-alternate-modifier
 @vindex ns-right-alternate-modifier
   The variable @code{ns-right-alternate-modifier} controls the
-behavior of the right @key{alt} and @key{option} keys.  These keys
+behavior of the right @key{Alt} and @key{Option} keys.  These keys
 behave like the left-hand keys if the value is @code{left} (the
 default).  A value of @code{control}, @code{meta}, @code{alt},
 @code{super}, or @code{hyper} makes them behave like the corresponding
diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
index 7cb48a67e7c..0ffa9f74ac6 100644
--- a/doc/emacs/mark.texi
+++ b/doc/emacs/mark.texi
@@ -260,7 +260,7 @@ change the variable @code{use-empty-active-region} to @code{t}.
 
 @vindex delete-active-region
   As described in @ref{Erasing}, the @key{DEL}
-(@code{backward-delete-char}) and @key{delete}
+(@code{backward-delete-char}) and @key{Delete}
 (@code{delete-forward-char}) commands also act this way.  If the mark
 is active, they delete the text in the region.  (As an exception, if
 you supply a numeric argument @var{n}, where @var{n} is not one, these
diff --git a/doc/emacs/msdos-xtra.texi b/doc/emacs/msdos-xtra.texi
index 541e29aa25f..39d003c453c 100644
--- a/doc/emacs/msdos-xtra.texi
+++ b/doc/emacs/msdos-xtra.texi
@@ -84,7 +84,7 @@ a running command and for emergency escape
 @vindex dos-super-key
 @vindex dos-hyper-key
   The PC keyboard maps use the left @key{Alt} key as the @key{META} key.
-You have two choices for emulating the @key{SUPER} and @key{HYPER} keys:
+You have two choices for emulating the @key{SUPER} and @key{Hyper} keys:
 choose either the right @key{Ctrl} key or the right @key{Alt} key by
 setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1
 or 2 respectively.  If neither @code{dos-super-key} nor
diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi
index 9c47f47a736..032e82eb621 100644
--- a/doc/emacs/msdos.texi
+++ b/doc/emacs/msdos.texi
@@ -575,7 +575,7 @@ keys (it converts lower-case characters to their upper-case
 variants).  However, if you set the variable
 @code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the
 @key{CapsLock} key will affect non-character keys as well, as if you
-pressed the @key{Shift} key while typing the non-character key.
+pressed the @key{SHIFT} key while typing the non-character key.
 
 @vindex w32-enable-caps-lock
   If the variable @code{w32-enable-caps-lock} is set to a @code{nil}
diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index 4989982eca0..dc80bc92172 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -1841,7 +1841,33 @@ sometimes jump when point traverses reordered bidirectional text.
 Similarly, a highlighted region covering a contiguous range of
 character positions may look discontinuous if the region spans
 reordered text.  This is normal and similar to the behavior of other
-programs that support bidirectional text.  If you set
-@code{visual-order-cursor-movement} to a non-@code{nil} value, cursor
-motion by the arrow keys follows the visual order on screen
-(@pxref{Moving Point, visual-order movement}).
+programs that support bidirectional text.
+
+@kindex RIGHT@r{, and bidirectional text}
+@kindex LEFT@r{, and bidirectional text}
+@findex right-char@r{, and bidirectional text}
+@findex left-char@r{, and bidirectional text}
+  Cursor motion commands bound to arrow keys, such as @key{LEFT} and
+@kbd{C-@key{RIGHT}}, are sensitive to the base direction of the
+current paragraph.  In a left-to-right paragraph, commands bound to
+@key{RIGHT} with or without modifiers move @emph{forward} through
+buffer text, but in a right-to-left paragraph they move
+@emph{backward} instead.  This reflects the fact that in a
+right-to-left paragraph buffer positions predominantly increase when
+moving to the left on display.
+
+  When you move out of a paragraph, the meaning of the arrow keys
+might change if the base direction of the preceding or the following
+paragraph is different from the paragraph out of which you moved.
+When that happens, you need to adjust the arrow key you press to the
+new base direction.
+
+@vindex visual-order-cursor-movement
+@cindex cursor, visual-order motion
+  By default, @key{LEFT} and @key{RIGHT} move in the logical order,
+but if @code{visual-order-cursor-movement} is non-@code{nil}, these
+commands move to the character that is, correspondingly, to the left
+or right of the current screen position, moving to the next or
+previous screen line as appropriate.  Note that this might potentially
+move point many buffer positions away, depending on the surrounding
+bidirectional context.