Subject: Re: bug#76313: New function `replace-region`

From: Stefan Kangas <[email-masked]>
Date: Fri, 7 Mar 2025 20:23:09 +0000

Eli Zaretskii <[email-masked]> writes:

>> To make things even clearer, we could consider renaming
>> `replace-region-contents` to `carefully-replace-region`, or something
>> along those lines.  Its docstring and manual entry should emphasize it's
>> specialized nature.  Then, we have only one API that we really recommend
>> for this, plus the specialized function for the rare cases when you
>> really need it.
>
> I'm not opposed to renaming too much (although it does have its
> non-negligible price),

Fully agreed.  It's more painful to rename things that are used often,
of course.

> but it doesn't solve the problem, either: the
> other APIs still exist, so the potential confusion what to use when is
> still there.  I very much doubt that you will be able to catch all the
> subtleties in our documentation to avoid the confusion, but feel free
> to try convincing me otherwise.

I don't fully understand what exactly you are asking for here.  Would
you like me to propose a documentation patch on top of Stefan Monnier's
patch?

I don't know if this is sufficient, but I suggest putting
`replace-region` at the top of (info "(elisp) Replacing").  I don't
think it will be very hard to explain the specialized nature of a
renamed `replace-region-carefully`.  It's doable even if we don't rename
it, I think, although the `replace-region-contents` name is a fair bit
less self-explanatory.

I'm sure that we can come up with good documentation if we collaborate
to make it so; we usually do.