bug#63398: 28.2; Doc or behavior of replacement commands (e.g. `replace-string')

[Eli Zaretskii <eliz@gnu.org>]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Tue, 9 May 2023 20:13:04 +0000
> 
> The doc also says this, however, regarding replacement:
> 
>   In addition, when the NEWSTRING argument is all or partly lower case,
>   replacement commands try to preserve the case pattern of each
>   occurrence.  Thus, the command
> 
>      M-x replace-string <RET> foo <RET> bar <RET>
> 
>   replaces a lower case 'foo' with a lower case 'bar', an all-caps 'FOO'
>   with 'BAR', and a capitalized 'Foo' with 'Bar'.  (These three
>   alternatives-lower case, all caps, and capitalized, are the only ones
>   that 'replace-string' can distinguish.)
> 
> My reading of this is that, since "test 1" is lower-case, the
> replacement should "try" (meaning what, exactly? under what
> circumstances does such a trial "fail"?) to preserve the case pattern of
> the first occurrence, chaning "Test 0" to "Test 1".  That doesn't
> happen.
> 
> Is the doc wrong?  Is my reading of it wrong?  If my reading and the doc
> are right, is the behavior wrong (bugged)?

The manual says "try", and for a good reason.  There's a heuristics
involved that tries to DTRT.  The "when the NEWSTRING argument is all
or partly lower case" part is relevant.  What you expect will happen
if the original text doesn't include digits, as in

  Testing
  testing

  M-x replace-string RET testing RET foobar RET

> [It's also not very good to refer to argument NEWSTRING in a topic/node
> that doesn't define it. Users have to look backward through the doc to
> see if they can find out which argument this is talking about.]\

Fixed.

> BTW, it's unfortunate that we use an em dash char here, with no
> preceding or following space chars.  Why?  Because it reads as if it
> were a hyphen, producing adjective "replace-provided" modifying noun
> `case-fold-search'.  Since we use fixed-width fonts by default, this is
> all the more apparent.  Please reword or surround the em dash with space
> chars.

In your post the em dash was the ASCII character '-', but on my system
it is an actual em dash -- a much longer character, thus the confusion
is unlikely.  As for why there are no spaces -- that's our style.