RE: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598)

[Drew Adams <drew.adams@oracle.com>]

> > > Okay.  Then how about
> > >
> > > Return a string equal to @var{instring} with every occurence of
> > > @var{fromstring} replaced by @var{tostring}.
> >
> > Return a new string equal...
> 
> The "equal" part is extremely confusing, IMNSHO.  Why do we need it
> here?

What do you find extremely confusing about it?

I'm not the one who proposed that "equal" part, but
I'd say that it helps if we draw _some_ relation
between the returned string to INSTRING.

And the relation needs to express that (1) they
don't share structure and (2) they're equal except
for the specified diffs.

What do we mean by "equal", there?  Predicate `equal'
(or `string-equal', if you prefer - they amount to
the same thing here).

We don't want to say "replace" presumably, as that
can suggest modification.

You can say "Return a string obtained by copying
INSTRING and replacing each occurrence of FROMSTRING
in that copy by TOSTRING" (which is long but can be
split).  Mentioning copying means you don't have to
say "new".

Or you can say something else.  But the point is:

(1) The returned string is obtained from INSTRING.
(2) The returned string is a new string (INSTRING
    isn't modified).
(3) The returned string is equal to INSTRING, except
    for the indicated differences.