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

From: Stefan Kangas <[email-masked]>
Date: Wed, 5 Mar 2025 11:28:42 -0800

Eli Zaretskii <[email-masked]> writes:

>> From: Stefan Kangas <[email-masked]>
>> Date: Tue, 4 Mar 2025 19:58:05 -0800
>> Cc: Philipp Stephani <[email-masked]>, [email-masked], Eli Zaretskii <[email-masked]>,
>> 	Tassilo Horn <[email-masked]>
>>
>> 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]  This is orthogonal to adding `replace-region`,
but means that we only have one API.

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

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.

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

Footnotes:
[1]  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=76313#76