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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 06 Mar 2025 10:47:40 +0200

> From: Stefan Kangas <[email-masked]>
> Date: Wed, 5 Mar 2025 11:28:42 -0800
> Cc: [email-masked], [email-masked], [email-masked]
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> >> FWIW, I think that I'd personally rather see another function than
> >> complicating the `replace-region` interface just for this.
> >
> > And I'm of the directly opposite opinion.  I think having 2 APIs for
> > this is too much; adding a 3rd is overboard.
> >
> > I proposed some ways to avoid adding yet another API.  Yes, they are
> > less than ideal, but then we don't develop Emacs from scratch here, so
> > compromises are unavoidable.  (And it bothers me that two of the most
> > prolific Emacs contributors don't see t5he terrible downsides of
> > exponential explosion in the number of Emacs functions and variables.)
> 
> My proposal is to obsolete `replace-buffer-contents`, as per Stefan
> Monnier's suggestion.[1]

Why would we obsolete a function that is used in half a dozen places
in our own sources?

And anyway, obsoleting a function doesn't remove it from Emacs until
many years in the future.

> Adding `replace-region` would then bring us up to 2 APIs.  This is the
> same as what we have now.

This trick doesn't solve my problem, sorry.

> 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), 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.

> (BTW, since `replace-region-contents` is currently unused in our tree,
> maybe we don't even need it.  OTOH, if we rename it, it shouldn't hurt
> to leave it alone, in case it will be needed again in the future.)

OTOH, my suggestion to extend replace-buffer-contents instead was
rejected by Stefan Monnier more strongly than the suggestion to extend
replace-region-contents.  So it sounds like Stefan favors
replace-region-contents.