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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 08 Mar 2025 10:48:59 +0200

> From: Stefan Kangas <[email-masked]>
> Date: Fri, 7 Mar 2025 20:23:09 +0000
> Cc: [email-masked], [email-masked], [email-masked]
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> > 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.

I'm saying that the documentation aspect of this is not the real
problem.  Once we agree on the code and API changes, updating the
documentation is a no-brainer, and I don't expect it to trigger an
argument.

The problem here is how to provide the functionality without
complicating Emacs with yet another API, where we already have two.