Subject: bug#78806: [PATCH] (smerge-refine-region): Add support for a virtual "other cursor"

From: Stefan Monnier <[email-masked]>
Date: Sat, 21 Jun 2025 11:31:38 -0400

> Thanks.  I'm only a seasoned user of SMerge, but this description
> confuses me so completely that I have no idea what will this "shadow
> cursor" do for me:
>
>   +A "shadow cursor" is now drawn when point is inside a refined diff or
>   +refined conflict area, that corresponds to point's position in
>   +the other side of the diff or conflict, i.e. the position to which
>   +'smerge-refine-exchange-point' would jump.

I don't really know how to describe it.  I think it becomes obvious when
you see it.  Here's another attempt:

`smerge-refine` does a "fine diff" between two regions of text, which
works by finding similarities between those two regions.  So when point
is in one of the those two regions, the "shadow cursor" is placed in the
other region, at the location that the fine-diff considered as "most
similar".

> I guess this alludes to too much of other terms or features whose
> names don't tell enough: "the other side of the diff"?  "where
> smerge-refine-exchange-point would jump"?  Is it possible to provide
> something less cryptic?

Does the above clarify?  If so, do you have any suggestion how to turn
it into a form better adapted to NEWS and docstrings?

>> +  (with-demoted-errors "cursor-sensor--detect: %S"
> I'd appreciate a comment explaining why we demote these errors.

OK.

>> +(defcustom smerge-refine-shadow-cursor t
>> +  "If non-nil, display a shadow cursor on the other side of smerge refined regions."
> Please say more about the shadow cursor.  How about saying what it
> looks like, not only where?

I'll add a reference to the face.

>> +(defface smerge-refine-shadow-cursor
>> +  '((t :box (:line-width (-2 . -2))))
>> +  "Face used to highlight the shadow cursor.")
> Why "highlight"?  Isn't this the cursor itself, not its highlight?

I don't know how to say it clearly: this is the face used to highlight
a character where the highlighting itself is "the cursor".  Maybe:

    "Face placed on a character to highlight it as the shadow cursor."

?

        Stefan