Merge 'master' into noverlay

1 files changed, 140 insertions, 88 deletions

diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 5878e7da256..1a4abdc9ecd 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -1,6 +1,6 @@
 @c -*- coding: utf-8 -*-
 @c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2017 Free Software
+@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2022 Free Software
 @c Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node Basic
@@ -45,16 +45,16 @@ forward, so that point remains just after the inserted text.
 @cindex newline
 @c @findex electric-indent-just-newline
   To end a line and start a new one, type @key{RET} (@code{newline}).
-(The @key{RET} key may be labeled @key{Return} or @key{Enter} on your
-keyboard, but we refer to it as @key{RET} in this manual.)  This
-command inserts a newline character into the buffer, then indents
-(@pxref{Indentation}) according to the major mode.  If point is at the end
-of the line, the effect is to create a new blank line after it and
-indent the new line; if point is in the middle of a line, the line is
-split at that position.  To turn off the auto-indentation, you can
-either disable Electric Indent mode (@pxref{Indent Convenience}) or
-type @kbd{C-j}, which inserts just a newline, without any
-auto-indentation.
+(The @key{RET} key may be labeled @key{Return}, or @key{Enter}, or
+with a funny-looking left-pointing arrow on your keyboard, but we
+refer to it as @key{RET} in this manual.)  This command inserts a
+newline character into the buffer, then indents (@pxref{Indentation})
+according to the major mode.  If point is at the end of the line, the
+effect is to create a new blank line after it and indent the new line;
+if point is in the middle of a line, the line is split at that
+position.  To turn off the auto-indentation, you can either disable
+Electric Indent mode (@pxref{Indent Convenience}) or type @kbd{C-j},
+which inserts just a newline, without any auto-indentation.
 
   As we explain later in this manual, you can change the way Emacs
 handles text insertion by turning on @dfn{minor modes}.  For instance,
@@ -109,17 +109,17 @@ just like digits.  Case is ignored.
 @cindex Unicode characters, inserting
 @cindex insert Unicode character
 @cindex characters, inserting by name or code-point
-@cindex curly quotes
-@cindex curved quotes
+@cindex curly quotes, inserting
+@cindex curved quotes, inserting
   A few common Unicode characters can be inserted via a command
-starting with @kbd{C-x 8}.  For example, @kbd{C-x 8 [} inserts @t{‘}
-which is Unicode code-point @code{U+2018} LEFT SINGLE QUOTATION MARK,
+starting with @w{@kbd{C-x 8}}.  For example, @kbd{C-x 8 [} inserts @t{‘}
+which is Unicode code-point U+2018 @sc{left single quotation mark},
 sometimes called a left single ``curved quote'' or ``curly quote''.
-Similarly, @kbd{C-x 8 ]}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
+Similarly, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
 curved quotes @t{’}, @t{“} and @t{”}, respectively.  Also, a working
-Alt key acts like @kbd{C-x 8}; e.g., @kbd{A-[} acts like @kbd{C-x 8 [}
-and inserts @t{‘}.  To see which characters have @kbd{C-x 8}
-shorthands, type @kbd{C-x 8 C-h}.
+@key{Alt} key acts like @kbd{C-x 8} (unless followed by @key{RET});
+e.g., @kbd{A-[} acts like @kbd{C-x 8 [} and inserts @t{‘}.  To see
+which characters have @kbd{C-x 8} shorthands, type @kbd{C-x 8 C-h}.
 
   Alternatively, you can use the command @kbd{C-x 8 @key{RET}}
 (@code{insert-char}).  This prompts for the Unicode name or code-point
@@ -131,12 +131,6 @@ Unicode), or a number with a specified radix, e.g., @code{#o23072}
 Manual}.  The command then inserts the corresponding character into
 the buffer.
 
-  In some contexts, if you type a quotation using grave accent and
-apostrophe @t{`like this'}, it is converted to a form @t{‘like this’}
-using single quotation marks.  Similarly, typing a quotation @t{``like
-this''} using double grave accent and apostrophe converts it to a form
-@t{“like this”} using double quotation marks.  @xref{Quotation Marks}.
-
   For example, the following all insert the same character:
 
 @example
@@ -151,6 +145,19 @@ this''} using double grave accent and apostrophe converts it to a form
   A numeric argument to @kbd{C-q} or @kbd{C-x 8 ...} specifies
 how many copies of the character to insert (@pxref{Arguments}).
 
+  As an alternative to @kbd{C-x 8}, you can select the corresponding
+transient input method by typing @kbd{C-u C-x \ iso-transl @key{RET}},
+then temporarily activating this transient input method by typing
+@kbd{C-x \ [} will insert the same character @t{‘} (@pxref{transient
+input method}).
+
+  In addition, in some contexts, if you type a quotation using grave
+accent and apostrophe @kbd{`like this'}, it is converted to a form
+@t{‘like this’} using single quotation marks, even without @kbd{C-x 8}
+commands.  Similarly, typing a quotation @kbd{``like this''} using
+double grave accent and apostrophe converts it to a form @t{“like
+this”} using double quotation marks.  @xref{Quotation Marks}.
+
 @node Moving Point
 @section Changing the Location of Point
 
@@ -183,17 +190,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
@@ -203,12 +201,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}.  If @code{visual-order-cursor-movement}
-is non-@code{nil}, this command moves to the character that is to the
-left of the current screen position, moving to the previous or next
-screen line as appropriate.
+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}
@@ -230,21 +224,19 @@ preserves position within the line, like @kbd{C-n}.
 @item C-a
 @itemx @key{Home}
 @kindex C-a
-@kindex HOME key
+@kindex HOME
 @findex move-beginning-of-line
 Move to the beginning of the line (@code{move-beginning-of-line}).
 
 @item C-e
 @itemx @key{End}
 @kindex C-e
-@kindex END key
+@kindex END
 @findex move-end-of-line
 Move to the end of the line (@code{move-end-of-line}).
 
 @item M-f
-@kindex M-f
-@findex forward-word
-Move forward one word (@code{forward-word}).
+Move forward one word (@code{forward-word}).  @xref{Words}.
 
 @item C-@key{RIGHT}
 @itemx M-@key{RIGHT}
@@ -256,9 +248,7 @@ moves @emph{backward} by one word if the current paragraph is
 right-to-left.  @xref{Bidirectional Editing}.
 
 @item M-b
-@kindex M-b
-@findex backward-word
-Move backward one word (@code{backward-word}).
+Move backward one word (@code{backward-word}).  @xref{Words}.
 
 @item C-@key{LEFT}
 @itemx M-@key{LEFT}
@@ -289,21 +279,30 @@ 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-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}
 @itemx @key{next}
+@kindex C-v
+@kindex PageDown
+@kindex next
 Scroll the display one screen forward, and move point onscreen if
 necessary (@code{scroll-up-command}).  @xref{Scrolling}.
 
 @item M-v
 @itemx @key{PageUp}
 @itemx @key{prior}
+@kindex M-v
+@kindex PageUp
+@kindex prior
 Scroll one screen backward, and move point onscreen if necessary
 (@code{scroll-down-command}).  @xref{Scrolling}.
 
@@ -311,20 +310,31 @@ Scroll one screen backward, and move point onscreen if necessary
 @kindex M-g c
 @findex goto-char
 Read a number @var{n} and move point to buffer position @var{n}.
-Position 1 is the beginning of the buffer.
+Position 1 is the beginning of the buffer.  If point is on or just
+after a number in the buffer, that is the default for @var{n}.  Just
+type @key{RET} in the minibuffer to use it.  You can also specify
+@var{n} by giving @kbd{M-g c} a numeric prefix argument.
 
 @item M-g M-g
 @itemx M-g g
 @kindex M-g M-g
 @kindex M-g g
 @findex goto-line
+@findex goto-line-relative
 Read a number @var{n} and move point to the beginning of line number
 @var{n} (@code{goto-line}).  Line 1 is the beginning of the buffer.  If
 point is on or just after a number in the buffer, that is the default
 for @var{n}.  Just type @key{RET} in the minibuffer to use it.  You can
 also specify @var{n} by giving @kbd{M-g M-g} a numeric prefix argument.
 @xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it
-a plain prefix argument.
+a plain prefix argument.  Alternatively, you can use the command
+@code{goto-line-relative} to move point to the line relative to the
+accessible portion of the narrowed buffer.
+
+@code{goto-line} has its own history list (@pxref{Minibuffer
+History}).  You can have either a single list shared between all
+buffers (the default) or a separate list for each buffer, by
+customizing the user option @code{goto-line-history-local}.
 
 @item M-g @key{TAB}
 @kindex M-g TAB
@@ -337,11 +347,11 @@ move to the column number specified by the argument's numeric value.
 @kindex C-x C-n
 @findex set-goal-column
 Use the current column of point as the @dfn{semipermanent goal column}
-for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}) in the current
-buffer.  When a semipermanent goal column is in effect, those commands
-always try to move to this column, or as close as possible to it,
-after moving vertically.  The goal column remains in effect until
-canceled.
+(@code{set-goal-column}) in the current buffer.  When a semipermanent
+goal column is in effect, @kbd{C-n}, @kbd{C-p}, @kbd{<prior>} and
+@kbd{<next>} always try to move to this column, or as close as
+possible to it, after moving vertically.  The goal column remains in
+effect until canceled.
 
 @item C-u C-x C-n
 Cancel the goal column.  Henceforth, @kbd{C-n} and @kbd{C-p} try to
@@ -404,9 +414,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
@@ -451,12 +464,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
@@ -466,6 +478,15 @@ Normally, this command undoes the last change, moving point back to
 where it was before the change.  The undo command applies only to
 changes in the buffer; you can't use it to undo cursor motion.
 
+  On a terminal that supports the @key{Control} modifier on all other
+keys, the easiest way to invoke @code{undo} is with @kbd{C-/}, since
+that doesn't need the @key{Shift} modifier.  On terminals which allow
+only the ASCII control characters, @kbd{C-/} does not exist, but for
+many of them @kbd{C-/} still works because it actually sends @kbd{C-_}
+to Emacs, while many others allow you to omit the @key{Shift} modifier
+when you type @kbd{C-_} (in effect pressing @kbd{C--}), making that
+the most convenient way to invoke @code{undo}.
+
   Although each editing command usually makes a separate entry in the
 undo records, very simple commands may be grouped together.
 Sometimes, an entry may cover just part of a complex command.
@@ -590,7 +611,6 @@ earlier, @kbd{C-n} (@code{next-line}) and @kbd{C-p}
 (@code{previous-line}) are special exceptions: they move point down
 and up, respectively, by one screen line (@pxref{Moving Point}).
 
-@cindex truncation
 @cindex line truncation, and fringes
   Emacs can optionally @dfn{truncate} long logical lines instead of
 continuing them.  This means that every logical line occupies a single
@@ -607,15 +627,14 @@ before they get too long, by inserting newlines.  If you prefer, you
 can make Emacs insert a newline automatically when a line gets too
 long, by using Auto Fill mode.  @xref{Filling}.
 
-@cindex word wrap
   Sometimes, you may need to edit files containing many long logical
 lines, and it may not be practical to break them all up by adding
 newlines.  In that case, you can use Visual Line mode, which enables
 @dfn{word wrapping}: instead of wrapping long lines exactly at the
 right window edge, Emacs wraps them at the word boundaries (i.e.,
 space or tab characters) nearest to the right window edge.  Visual
-Line mode also redefines editing commands such as @code{C-a},
-@code{C-n}, and @code{C-k} to operate on screen lines rather than
+Line mode also redefines editing commands such as @kbd{C-a},
+@kbd{C-n}, and @kbd{C-k} to operate on screen lines rather than
 logical lines.  @xref{Visual Line Mode}.
 
 @node Position Info
@@ -634,14 +653,14 @@ Toggle automatic display of the current line number or column number.
 displayed before each line, see @ref{Display Custom}.
 
 @item M-=
-Display the number of lines, words, and characters that are present in
-the region (@code{count-words-region}).  @xref{Mark}, for information
-about the region.
+Display the number of lines, sentences, words, and characters that are
+present in the region (@code{count-words-region}).  @xref{Mark}, for
+information about the region.
 
 @item M-x count-words
-Display the number of lines, words, and characters that are present in
-the buffer.  If the region is active (@pxref{Mark}), display the
-numbers for the region instead.
+Display the number of lines, sentences, words, and characters that are
+present in the buffer.  If the region is active (@pxref{Mark}),
+display the numbers for the region instead.
 
 @item C-x =
 Display the character code of character after point, character position of
@@ -660,7 +679,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,
@@ -670,7 +689,7 @@ narrowed region and the line number relative to the whole buffer.
 @kindex M-=
 @findex count-words-region
   @kbd{M-=} (@code{count-words-region}) displays a message reporting
-the number of lines, words, and characters in the region
+the number of lines, sentences, words, and characters in the region
 (@pxref{Mark}, for an explanation of the region).  With a prefix
 argument, @kbd{C-u M-=}, the command displays a count for the entire
 buffer.
@@ -703,6 +722,15 @@ position as a percentage of the total.  After @samp{column=} is the
 horizontal position of point, in columns counting from the left edge
 of the window.
 
+@vindex what-cursor-show-names
+  If the user option @code{what-cursor-show-names} is non-@code{nil},
+the name of the character, as defined by the Unicode Character
+Database, is shown as well.  The part in parentheses would then become:
+
+@smallexample
+(99, #o143, #x63, LATIN SMALL LETTER C)
+@end smallexample
+
   If the buffer has been narrowed, making some of the text at the
 beginning and the end temporarily inaccessible, @kbd{C-x =} displays
 additional text describing the currently accessible range.  For
@@ -717,6 +745,9 @@ where the two extra numbers give the smallest and largest character
 position that point is allowed to assume.  The characters between
 those two positions are the accessible ones.  @xref{Narrowing}.
 
+  Related, but different feature is @code{display-line-numbers-mode}
+(@pxref{Display Custom}).
+
 @node Arguments
 @section Numeric Arguments
 @cindex numeric arguments
@@ -738,7 +769,7 @@ direction.
 @findex digit-argument
 @findex negative-argument
   The easiest way to specify a numeric argument is to type a digit
-and/or a minus sign while holding down the @key{META} key.  For
+and/or a minus sign while holding down the @key{Meta} key.  For
 example,
 
 @example
@@ -752,7 +783,7 @@ well as @kbd{M--}, are bound to commands (@code{digit-argument} and
 command.  @kbd{M--} without digits normally means @minus{}1.
 
 If you enter more than one digit, you need not hold down the
-@key{META} key for the second and subsequent digits.  Thus, to move
+@key{Meta} key for the second and subsequent digits.  Thus, to move
 down fifty lines, type
 
 @example
@@ -788,12 +819,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})
@@ -802,7 +833,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}
@@ -820,16 +851,19 @@ more convenient, and they are documented in that command's
 documentation string.
 
   We use the term @dfn{prefix argument} to emphasize that you type
-such arguments before the command, and to distinguish them from
-minibuffer arguments (@pxref{Minibuffer}), which are entered after
-invoking the command.
+such arguments @emph{before} the command, and to distinguish them from
+minibuffer arguments (@pxref{Minibuffer}), which are entered
+@emph{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
 
   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
@@ -844,10 +878,28 @@ 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
 additional times, to delete a total of 80 characters, by typing @kbd{C-x
 z z z}.  The first @kbd{C-x z} repeats the command once, and each
 subsequent @kbd{z} repeats it once again.
+
+@findex repeat-mode
+@vindex repeat-exit-key
+@vindex repeat-exit-timeout
+  Also you can activate @code{repeat-mode} that temporarily enables a
+transient mode with short keys after a limited number of commands.
+Currently supported shorter key sequences are @kbd{C-x u u} instead of
+@kbd{C-x u C-x u} to undo many changes, @kbd{C-x o o} instead of
+@kbd{C-x o C-x o} to switch several windows, @kbd{C-x @{ @{ @} @} ^ ^
+v v} to resize the selected window interactively, @kbd{M-g n n p p} to
+navigate @code{next-error} matches, and @kbd{C-x ] ] [ [} to navigate
+through pages.  Any other key exits transient mode and then is
+executed normally.  The user option @code{repeat-exit-key} defines an
+additional key to exit this transient mode.  Also it's possible to
+break the repetition chain automatically after some idle time by
+customizing the user option @code{repeat-exit-timeout} to specify the
+idle time in seconds after which this transient mode will be turned
+off.