bug#64724: 30.0.50; Inconsistency between manual, comments in the code, and implementation of point adjustment

[Stefan Monnier]

Ihor Radchenko [2023-07-21 07:50:55] wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> So, there is no problem with this section of the manual. The problem is
>>> that manual does not describe the behavior with invisible text
>>> boundaries I was trying to figure out.
>>
>> Which aspects of the behavior you describe are not mentioned in the
>> manual.  It does refer to invisible text.
>
> It talks about "in the middle of a sequence .. that ... is invisible"
>
>     Emacs cannot display the cursor when point is in the middle of a
>     sequence of text that has the ‘display’ or ‘composition’ property, or is
>     invisible.  Therefore, after a command finishes and returns to the
>     command loop, if point is within such a sequence, the command loop
>     normally moves point to the edge of the sequence, making this sequence
>     effectively intangible.
>
> The situation I encountered is when point ends up not in the middle, but
> already on the edge. So, Emacs moving point to _other_ edge was
> surprising.

How 'bout the rephrasing below?


        Stefan


diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 037f42124cc..ca009d97b39 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1253,12 +1253,13 @@ Adjusting Point
 @cindex @code{display} property, and point display
 @cindex @code{composition} property, and point display
 
-  Emacs cannot display the cursor when point is in the middle of a
-sequence of text that has the @code{display} or @code{composition}
-property, or is invisible.  Therefore, after a command finishes and
-returns to the command loop, if point is within such a sequence, the
-command loop normally moves point to the edge of the sequence, making this
-sequence effectively intangible.
+  When point is in the middle of a sequence of text that has the
+@code{display} or @code{composition} property, or is invisible, Emacs
+there can be several buffer positions that result in the cursor being
+displayed at same place.  Therefore, after a command finishes and
+returns to the command loop, if point is in such a sequence, the
+command loop normally moves point to one of the two edges of the
+sequence, making this sequence effectively intangible.
 
   A command can inhibit this feature by setting the variable
 @code{disable-point-adjustment}: