[Emacs-diffs] emacs-26 26f6441: Another set of improvements in the Emacs manual

[Eli Zaretskii]

branch: emacs-26
commit 26f64410fd6845cde1a06373eea05e256b87513d
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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 <address@hidden> in
    address@hidden
    
    * doc/emacs/glossary.texi (Glossary): Document that "c.f." is a
    misspelling.  Reported by Robert Pluim <address@hidden>.
    Various minor wording improvements.  Suggested by Toon Claes
    <address@hidden> in address@hidden
    More minor changes.  Suggested by Michael Albinus
    <address@hidden> in address@hidden
    
    * 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.
---
 doc/emacs/basic.texi      | 22 ++++------------------
 doc/emacs/building.texi   | 14 +++++++-------
 doc/emacs/cmdargs.texi    | 17 ++++++++---------
 doc/emacs/frames.texi     |  2 +-
 doc/emacs/glossary.texi   | 47 +++++++++++++++++++++++++++--------------------
 doc/emacs/macos.texi      |  6 +++---
 doc/emacs/mark.texi       |  2 +-
 doc/emacs/msdos-xtra.texi |  2 +-
 doc/emacs/msdos.texi      |  2 +-
 doc/emacs/mule.texi       | 34 ++++++++++++++++++++++++++++++----
 10 files changed, 83 insertions(+), 65 deletions(-)

diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 8a8298b..4db3855 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
address@hidden visual-order-cursor-movement
address@hidden 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 address@hidden, 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.
address@hidden Editing}.
-
-The variable @code{visual-order-cursor-movement} affects this like
address@hidden, 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 f61e333..f2819c6 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 @address@hidden
 `}}, @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 e463e7c..d18de8e 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 @address@hidden@@@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 @address@hidden@@@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 2c1a55b..b2ec574 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 7a34692..a912019 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}.
 
address@hidden Alt
address@hidden @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 @address@hidden
@@ -160,10 +160,11 @@ right away when you press down on a mouse button.  
@xref{Mouse Buttons}.
 @item Byte Compilation
 @xref{Glossary---Compilation}.
 
address@hidden c.f.
address@hidden cf.
address@hidden cf.
address@hidden 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}.
 
address@hidden 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-}
address@hidden in the name of a character is an abbreviation for @key{Meta},
address@hidden 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.
address@hidden
 
 @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 28a5f90..bf37d67 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
address@hidden  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
address@hidden  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 7cb48a6..0ffa9f7 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 541e29a..39d003c 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 9c47f47..032e82e 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 address@hidden 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 4989982..dc80bc9 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
address@hidden to a address@hidden value, cursor
-motion by the arrow keys follows the visual order on screen
-(@pxref{Moving Point, visual-order movement}).
+programs that support bidirectional text.
+
address@hidden address@hidden, and bidirectional text}
address@hidden address@hidden, and bidirectional text}
address@hidden address@hidden, and bidirectional text}
address@hidden address@hidden, and bidirectional text}
+  Cursor motion commands bound to arrow keys, such as @key{LEFT} and
address@hidden@key{RIGHT}}, are sensitive to the base direction of the
+current paragraph.  In a left-to-right paragraph, commands bound to
address@hidden with or without modifiers move @emph{forward} through
+buffer text, but in a right-to-left paragraph they move
address@hidden 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.
+
address@hidden visual-order-cursor-movement
address@hidden cursor, visual-order motion
+  By default, @key{LEFT} and @key{RIGHT} move in the logical order,
+but if @code{visual-order-cursor-movement} is address@hidden, 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.