GNU bug report logs - #76313
New function `replace-region`

Previous Next

Full log

Message #99 received at 76313 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76313 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca, tsdh <at> gnu.org
Subject: Re: bug#76313: New function `replace-region`
Date: Fri, 7 Mar 2025 20:23:09 +0000

Eli Zaretskii <eliz <at> gnu.org> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.