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

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Wed, 19 Jul 2023 07:02:21 +0000
> 
> This is a followup of https://orgmode.org/list/87ilag1pth.fsf@localhost
> 
> We recently ran into some subtleties of point adjustment near invisible
> regions with sticky 'invisible property.
> 
> The actual code in `set_point_both' makes sure to move point across
> invisible sticky region if point happens to end up right before front
> sticky invisible or right after rear sticky invisible region.
> 
> However, 22.6 Adjusting Point After Commands does not mention this
> scenario.
> 
> Further, `set_point_both' contains the following comments:
> 
>         /* If the preceding character is both intangible and invisible,
>            and the invisible property is `rear-sticky', perturb it so
>            that the search starts one character earlier -- this ensures
>            that point can never move to the end of an invisible/
>            intangible/rear-sticky region.  */
>         charpos = adjust_for_invis_intang (charpos, -1, -1, 1);
>           <...>
>                 /* If the following character is both intangible and 
> invisible,
>            and the invisible property is `front-sticky', perturb it so
>            that the search starts one character later -- this ensures
>            that point can never move to the beginning of an
>            invisible/intangible/front-sticky region.  */
>         charpos = adjust_for_invis_intang (charpos, 0, 1, 1);
> 
> However, 'intanglible text property is, in fact, not necessary to
> trigger the adjustment.
> 
> May you (1) document this behaviour in the manual; (2) clarify what's up
> with intanglible.

I think you confuse two different point-adjustment behaviors.  What
the ELisp manual describes is the one implemented in
adjust_point_for_property and the code which calls it from
command_loop_1.  set_point_both does a different job for different
situations, AFAIU.

If you ignore set_point_both, what exactly is wrong about that short
section in the manual?

Adding Stefan, in case he has comments.