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

[Mattias Engdegård]

28 sep. 2020 kl. 11.42 skrev Robert Pluim <rpluim@gmail.com>:

>    Mattias>  @defun string-replace fromstring tostring instring
>    Mattias> -This function copies @var{instring} and replaces any occurrences 
> of
>    Mattias> -@var{fromstring} with @var{tostring}.
>    Mattias> +This function returns a string equal to @var{instring} where any
>    Mattias> +occurrences of @var{fromstring} have been replaced with
>    Mattias> +@var{tostring}.  It may return one of its arguments.
>    Mattias> +Case is significant, and text properties are ignored.
>    Mattias>  @end defun
> 
> 'equal'? Really? And itʼs kind of passive-voicey.

Thank you for scrutinising my changes!

For technical documentation, a declarative or functional style is often 
appropriate than a procedural one. We would prefer defining (+ A B) as the sum 
of A and B instead of saying that it takes A, then adds B, and finally returns 
the result.

>  How about:
> 
> This function replaces any occurences of @var{fromstring} with
> @var{tostring} in @var{instring} and returns the result.

That is probably fine. I wanted there to be no reason to misread it as a 
mutation of INSTRING, but the risk is probably minimal. I'll amend the text.

Thanks again!