bug#12325: 24.2.50; doc of `replace-match' for STRING case

bug#12325: 24.2.50; doc of `replace-match' for STRING case

[Drew Adams]

The doc, both the doc string and the Elisp manual entry, is not
sufficiently clear that for the non-nil STRING case `replace-match' does
NOT modify STRING but returns a new string.
 
That the function returns a new string is said, but that statement is
buried among other statements that give the impression that STRING is
modified.  Here are such misleading statements:
 
Doc string
----------
 
"STRING can be a string to modify."
 
No, STRING is never modified.
 
"returns a new string made by copying STRING and replacing
the part of STRING that was matched."
 
No, it does NOT replace any "part of STRING".  It replaces the part of
the *copy* that corresponds to the matched portion of STRING.
 
Elisp manual
------------
 
"This function replaces the text in the buffer (or in STRING) that was
matched by the last search.  It replaces that text with REPLACEMENT."
 
No, it never replaces any text in STRING.  It does not replace the text
in STRING that was matched - that matched text is a part of STRING and
stays as it was.  It replaces corresponding text in a *copy* of STRING.
 
"`replace-match' does the replacement by constructing and returning a
new string."
 
This is not as clear as it should be.  "Does the replacement" is
unclear.  What replacement?  A reader will easily assume here that we
mean a replacement in STRING, which is wrong.
 
It "does the replacement" IN a copy of string, and then returns the
modified copy.
 

For both the doc string and the manual, we should be very clear that
unlike the case where STRING is nil, where the original buffer text *is*
replaced, when STRING is a string it is left unmodified and the return
value is a copy of STRING with the text corresponding to the match in
STRING replaced by REPLACEMENT.
 
In the buffer case, `replace-match' modifies the target object (the
buffer).  In the string case, `replace-match' is a non-destructive
operation.
 
The doc does not make this sufficiently clear, seemingly because it
tries to treat the two cases together using the same wording, and with
the string case almost as an afterthought: "replaces the text in the
buffer (or in STRING)".
 
Treat the two cases separately, and make clear that one modifies the
target and the other does not.
 
In the STRING case it is really misleading to speak of "replacement",
since one naturally assumes that a replacement takes place in STRING.
Because of this, the doc needs to take pains to counter this, explicitly
emphasizing that in spite of the function name, and just as for the case
of other non-destructive functions with names such as `remove', this
function does not modify STRING.

In GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600)
 of 2012-08-26 on MARVIN
Bzr revision: 109788 dmantipov@yandex.ru-20120827041533-3cy7pdjdqz14o90c
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include
 -ID:/devel/emacs/libs/libiconv-1.13.1-1-dev/include
 -ID:/devel/emacs/libs/libxml2-2.7.8/include/libxml2'
 

bug#12325: 24.2.50; doc of `replace-match' for STRING case

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> The doc, both the doc string and the Elisp manual entry, is not
> sufficiently clear that for the non-nil STRING case `replace-match' does
> NOT modify STRING but returns a new string.
>  
> That the function returns a new string is said, but that statement is
> buried among other statements that give the impression that STRING is
> modified.

Fixed in trunk.