Merge from origin/emacs-28

e3427faf55 Fix typos and improve consistency in ERC manual
0bf10d5082 * test/Makefile.in (check-declare): Add missing --batch.
34f5656137 Document the subtleties of the 'cursor' text property

2 files changed, 38 insertions, 28 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index b49a9987355..03adb541f9b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3722,14 +3722,14 @@ Consecutive characters with the same @code{field} property constitute a
 @kindex cursor @r{(text property)}
 Normally, the cursor is displayed at the beginning or the end of any
 overlay and text property strings present at the current buffer
-position.  You can place the cursor on any desired character of these
-strings by giving that character a non-@code{nil} @code{cursor} text
-property.  In addition, if the value of the @code{cursor} property is
-an integer, it specifies the number of buffer's character
-positions, starting with the position where the overlay or the
-@code{display} property begins, for which the cursor should be
-displayed on that character.  Specifically, if the value of the
-@code{cursor} property of a character is the number @var{n}, the
+position.  You can instead tell Emacs to place the cursor on any
+desired character of these strings by giving that character a
+non-@code{nil} @code{cursor} text property.  In addition, if the value
+of the @code{cursor} property is an integer, it specifies the number
+of buffer's character positions, starting with the position where the
+overlay or the @code{display} property begins, for which the cursor
+should be displayed on that character.  Specifically, if the value of
+the @code{cursor} property of a character is the number @var{n}, the
 cursor will be displayed on this character for any buffer position in
 the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
 is the overlay's starting position given by @code{overlay-start}
@@ -3738,14 +3738,23 @@ text property begins in the buffer.
 
 In other words, the string character with the @code{cursor} property
 of any non-@code{nil} value is the character where to display the
-cursor.  The value of the property says for which buffer positions to
-display the cursor there.  If the value is an integer @var{n},
-the cursor is displayed there when point is anywhere between the
-beginning of the overlay or @code{display} property and @var{n}
-positions after that.  If the value is anything else and
-non-@code{nil}, the cursor is displayed there only when point is at
-the beginning of the @code{display} property or at
-@code{overlay-start}.
+cursor when the overlay or display string make point not visible on
+display.  The value of the property says for which buffer positions to
+display the cursor there.  If the value is an integer @var{n}, the
+cursor is displayed there when point is anywhere between the beginning
+of the overlay or @code{display} property and @var{n} positions after
+that.  If the value is anything else and non-@code{nil}, the cursor is
+displayed there only when point is at the buffer position that is the
+beginning of the @code{display} property, or at @code{overlay-start}
+if that position is not visible on display.  Note that an integer
+value of the @code{cursor} property could mean that the cursor is
+displayed on that character even when point is visible on display.
+
+One subtlety of this property is that it doesn't work to put this
+property on a newline character that is part of a display or overlay
+string.  That's because the newline doesn't have a graphic
+representation on the screen for Emacs to find when it looks for a
+character on display with that @code{cursor} property.
 
 @cindex cursor position for @code{display} properties and overlays
 When the buffer has many overlay strings (e.g., @pxref{Overlay
diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index 7dbb5f0970d..e7286d2ebe3 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -72,7 +72,7 @@ and modified without restriction.
 
 Getting Started
 
-* Sample Session::              Example of connecting to the #emacs channel
+* Sample Session::              Example of connecting to the @samp{#emacs} channel
 * Special Features::            Differences from standalone IRC clients
 
 Advanced Usage
@@ -159,14 +159,15 @@ customize-variable @key{RET} erc-modules @key{RET}}.
 @section Sample Session
 
 This is an example ERC session which shows how to connect to the
-#emacs channel on Libera.Chat.  Another IRC channel on Libera.Chat
-that may be of interest is #erc, which is a channel where ERC users
-and developers hang out.  These channels used to live on the Freenode
-IRC network until June 2021, when they---along with the official IRC
-channels of the GNU Project, the Free Software Foundation, and many
-other free software communities---relocated to the Libera.Chat network
-in the aftermath of changes in governance and policies of Freenode in
-May and June 2021.  GNU and FSF's announcements about this are at
+@samp{#emacs} channel on Libera.Chat.  Another IRC channel on
+Libera.Chat that may be of interest is @samp{#erc}, which is a channel
+where ERC users and developers hang out.  These channels used to live
+on the Freenode IRC network until June 2021, when they---along with
+the official IRC channels of the GNU Project, the Free Software
+Foundation, and many other free software communities---relocated to
+the Libera.Chat network in the aftermath of changes in governance and
+policies of Freenode in May and June 2021.  GNU and FSF's
+announcements about this are at
 @uref{https://lists.gnu.org/archive/html/info-gnu/2021-06/msg00005.html},
 @uref{https://lists.gnu.org/archive/html/info-gnu/2021-06/msg00007.html},
 and
@@ -176,7 +177,7 @@ and
 
 @item Connect to Libera.Chat
 
-Run @kbd{M-x erc}.  Use ``irc.libera.chat as the IRC server, ``6667''
+Run @kbd{M-x erc}.  Use ``irc.libera.chat'' as the IRC server, ``6667''
 as the port, and choose a nickname.
 
 @item Get used to the interface
@@ -291,7 +292,7 @@ new command in capital letters.
 If the connection goes away at some point, ERC will try to reconnect
 automatically.  If it fails to reconnect, and you want to try to
 manually reestablish the connection at some later point, switch to an
-ERC  buffer and run the @code{/RECONNECT} command.
+ERC buffer and run the @code{/RECONNECT} command.
 
 @end itemize
 
@@ -958,7 +959,7 @@ over the project entirely.''
 So we happily hacked away on ERC, and soon after (September 2001)
 released the next "stable" version, 2.1.
 
-Most of the development of the new ERC happened on #emacs on
+Most of the development of the new ERC happened on @samp{#emacs} on
 irc.openprojects.net.  Over time, many people contributed code, ideas,
 bugfixes, and a lot of alpha/beta/gamma testing.