Subject: Re: bug#42296: 27.0.91; Correct manual entry for 'concat' w.r.t. allocation [PATCH]

From: Eli Zaretskii <[email-masked]>
Date: Fri, 10 Jul 2020 21:08:44 +0300

> From: Mattias Engdegård <[email-masked]>
> Date: Fri, 10 Jul 2020 19:04:48 +0200
> Cc: [email-masked]
> 
> 9 juli 2020 kl. 21.24 skrev Eli Zaretskii <[email-masked]>:
> 
> >  This function frequently, but not always, constructs a new string
> >  that is not @code{eq} to any existing string.  Lisp programs should
> >  not rely on the result being a new string nor on it being @code{eq}
> >  to an existing string.
> > 
> >  When this function returns a string @code{eq] to another, changing
> >  the result will also change that other string; to avoid that, use
> >  @code{copy-sequence} on the result.
> 
> Thank you! First a minor detail: the word 'frequently' doesn't convey any useful information since the user isn't supposed to take any chances -- either the returned value is always new and unaliased, or there is no such guarantee. The frequency isn't relevant, and we shouldn't encourage the user to act as if it were by talking about it.

"Frequently" describes what actually happens.  Describing facts is not
"encouraging" users to do anything, especially since the very next
sentence tells them not to draw any far-reaching conclusions.

IOW, we should treat our users as grown-up adults, not as children
from whom we need to hide information.

>  This function does not always allocate a new string.  Callers should
>  not rely on the result being a new string nor on it being @code{eq}
>  to an existing string.
> 
>  In particular, the returned value should not be altered. To obtain
>  a string that can be mutated, use @code{copy-sequence} on the result.

Fine with me, except that "should not be altered": I object to that,
unless we explain why.  My proposed text included such an explanation;
without it, this looks like another dogma that someone sooner or later
will come up and challenge.

Thanks.