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

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

[Robert Pluim]

>>>>> On Sun, 27 Sep 2020 08:45:22 -0400 (EDT), Mattias Engdegård <mattiase@savannah.gnu.org> said:

    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. How about:

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


Robert
-- 

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!

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

[Robert Pluim]

>>>>> On Mon, 28 Sep 2020 11:59:43 +0200, Mattias Engdegård <mattiase@acm.org> said:

    Mattias> 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.

    Mattias> Thank you for scrutinising my changes!

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

OK, but in this case the 'have been replaced' is less direct than it
could be.

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

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

Emacs documentation spoils me: destructive modification is called out
explicitly when it can happen, which means I assume that if itʼs not
mentioned, it canʼt happen.

Robert
-- 

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

[Robert Pluim]

>>>>> On Mon, 28 Sep 2020 07:43:03 -0400, John Yates <john@yates-sheets.org> said:

    John> Is there a role for the imperative mood?
    John> Return @var{instring} after replacing every occurence of
    John> @var{fromstring} with @var{tostring}.

    John> I find it typically shorter and more contractual.

I think that fails to pass Mattias' requirement of making it clear
that the returned string is not a destructively modified 'instring'

Robert
-- 

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

[John Yates]

Okay.  Then how about

Return a string equal to @var{instring} with every occurence of
@var{fromstring} replaced by @var{tostring}.

On Mon, Sep 28, 2020 at 9:50 AM Robert Pluim <rpluim@gmail.com> wrote:
>
> >>>>> On Mon, 28 Sep 2020 07:43:03 -0400, John Yates <john@yates-sheets.org> said:
>
>     John> Is there a role for the imperative mood?
>     John> Return @var{instring} after replacing every occurence of
>     John> @var{fromstring} with @var{tostring}.
>
>     John> I find it typically shorter and more contractual.
>
> I think that fails to pass Mattias' requirement of making it clear
> that the returned string is not a destructively modified 'instring'
>
> Robert
> --



-- 
John Yates
505 Tremont St, #803
Boston, MA 02116

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

[Drew Adams]

> 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...
____


But do we really need to say this now, for every function?
In the past nondestructive was the default (implicit), and
we called out destructive exceptions.

I'm not saying we shouldn't, especially if it just means
adding a "new" here or there.  But if descriptions aren't
somewhat consistent then we risk increasing confusion,
rather than diminishing it.  If we go out of our way to
say here that the returned string is a new one, will we
start saying that everywhere?

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

[Eli Zaretskii]

> Date: Mon, 28 Sep 2020 09:49:47 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Mattias Engdegård <mattiase@acm.org>,
>  Emacs developers <emacs-devel@gnu.org>
> 
> > 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?

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

[Drew Adams]

> > > 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.

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

[Eli Zaretskii]

> Date: Mon, 28 Sep 2020 10:11:55 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: john@yates-sheets.org, rpluim@gmail.com, mattiase@acm.org,
>         emacs-devel@gnu.org
> 
> > > > 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?

The "equal" part.

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

[John Yates]

On Mon, Sep 28, 2020 at 2:12 PM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > What do you find extremely confusing about it?
>
> The "equal" part.

Return a string equivalent to @var{instring} with every occurence
of @var{fromstring} replaced by @var{tostring}.

This has the virtue that it does not commit to returning a string
distinct from @var{instring} when there are no replacements.

Interesting that we are wordsmithing new and equals.  Originally
I introduced this wording to solicit feedback on adopting the
imperative mood.  Cohorts of git users are being taught to use
it.  And as I stated in my first email, I find it emphasizes the
contractual aspect of an API.

/john

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

[Drew Adams]

> > > What do you find extremely confusing about it?
> >
> > The "equal" part.
> 
> Return a string equivalent to @var{instring} with every occurence
> of @var{fromstring} replaced by @var{tostring}.

"Equivalent" is unclear.  In what way equivalent?

`equal' and `string-equal' are clear.  They say just
what we mean here by "equivalent".

INSTRING and the returned string are `equal', modulo
the differences specified by FROMSTRING and TOSTRING.

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

[Eli Zaretskii]

> Date: Mon, 28 Sep 2020 15:47:52 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Robert Pluim <rpluim@gmail.com>,
>         Mattias Engdegård
>  <mattiase@acm.org>,
>         Emacs developers <emacs-devel@gnu.org>
> 
> INSTRING and the returned string are `equal', modulo
> the differences specified by FROMSTRING and TOSTRING.

So they are not equal, right?

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

[Drew Adams]

> > INSTRING and the returned string are `equal', modulo
> > the differences specified by FROMSTRING and TOSTRING.
> 
> So they are not equal, right?

Right.  I don't think anyone said they were.

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

[Eli Zaretskii]

On September 29, 2020 7:28:40 AM GMT+03:00, Drew Adams <drew.adams@oracle.com> wrote:
> > > INSTRING and the returned string are `equal', modulo
> > > the differences specified by FROMSTRING and TOSTRING.
> > 
> > So they are not equal, right?
> 
> Right.  I don't think anyone said they were.

You suggested to use "equal" in the doc string for strings which we now agree are not equal.  Such doc string would confusing.

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

[Drew Adams]

> > > So they are not equal, right?
> >
> > Right.  I don't think anyone said they were.
> 
> You suggested to use "equal" in the doc string
> for strings which we now agree are not equal.
> Such doc string would confusing.

We're going 'round and 'round.

As I said before, I am not the one who suggested
to use "equal":

   I'm not the one who proposed that "equal" part

And the suggestions were _never_ to say that the
input and result strings are equal.  It was to
say that the input string _with the changes
applied_ is equal (in fact `equal') to the
returned string.  Which is true.

https://lists.gnu.org/archive/html/emacs-devel/2020-09/msg02159.html

I suggest you maybe reread what the suggestions were.

This incessant back & forth quibbling is tiring.
I'm done with this one.

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

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Mon, 28 Sep 2020 18:36:24 -0400
> Cc: Drew Adams <drew.adams@oracle.com>, Robert Pluim <rpluim@gmail.com>, 
> 	Mattias Engdegård <mattiase@acm.org>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> On Mon, Sep 28, 2020 at 2:12 PM Eli Zaretskii <eliz@gnu.org> wrote:
> >
> > > What do you find extremely confusing about it?
> >
> > The "equal" part.
> 
> Return a string equivalent to @var{instring} with every occurence
> of @var{fromstring} replaced by @var{tostring}.

Thanks, this is better.  But "equivalent" is too vague to be useful.

What's wrong with the below?  That's the natural way I'd say that.

  Replace every occurrence of FROMSTRING with TOSTRING in INSTRING,
  and return the result.

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

[Robert Pluim]

>>>>> On Tue, 29 Sep 2020 05:37:18 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: John Yates <john@yates-sheets.org>
    >> Date: Mon, 28 Sep 2020 18:36:24 -0400
    >> Cc: Drew Adams <drew.adams@oracle.com>, Robert Pluim <rpluim@gmail.com>, 
    >> Mattias Engdegård <mattiase@acm.org>, 
    >> Emacs developers <emacs-devel@gnu.org>
    >> 
    >> On Mon, Sep 28, 2020 at 2:12 PM Eli Zaretskii <eliz@gnu.org> wrote:
    >> >
    >> > > What do you find extremely confusing about it?
    >> >
    >> > The "equal" part.
    >> 
    >> Return a string equivalent to @var{instring} with every occurence
    >> of @var{fromstring} replaced by @var{tostring}.

    Eli> Thanks, this is better.  But "equivalent" is too vague to be useful.

    Eli> What's wrong with the below?  That's the natural way I'd say that.

    Eli>   Replace every occurrence of FROMSTRING with TOSTRING in INSTRING,
    Eli>   and return the result.

Thatʼs the 'imperative' version of what I originally proposed. I like
it.

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: John Yates <john@yates-sheets.org>,  drew.adams@oracle.com,
>   mattiase@acm.org,  emacs-devel@gnu.org
> Date: Tue, 29 Sep 2020 09:12:09 +0200
> 
>     Eli> What's wrong with the below?  That's the natural way I'd say that.
> 
>     Eli>   Replace every occurrence of FROMSTRING with TOSTRING in INSTRING,
>     Eli>   and return the result.
> 
> Thatʼs the 'imperative' version of what I originally proposed. I like
> it.

Who did NOT like it, and why?

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

[Robert Pluim]

>>>>> On Tue, 29 Sep 2020 17:26:55 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Cc: John Yates <john@yates-sheets.org>,  drew.adams@oracle.com,
    >> mattiase@acm.org,  emacs-devel@gnu.org
    >> Date: Tue, 29 Sep 2020 09:12:09 +0200
    >> 
    Eli> What's wrong with the below?  That's the natural way I'd say that.
    >> 
    Eli> Replace every occurrence of FROMSTRING with TOSTRING in INSTRING,
    Eli> and return the result.
    >> 
    >> Thatʼs the 'imperative' version of what I originally proposed. I like
    >> it.

    Eli> Who did NOT like it, and why?

Iʼm not going to go back over this already too long thread, but there
were various calls to have the word 'equal' appear, when my whole
starting point was that the result string would not be equal to the
original (except when it is :-))

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: mattiase@acm.org,  emacs-devel@gnu.org,  drew.adams@oracle.com,
>   john@yates-sheets.org
> Date: Tue, 29 Sep 2020 17:23:58 +0200
> 
>     Eli> Who did NOT like it, and why?
> 
> Iʼm not going to go back over this already too long thread, but there
> were various calls to have the word 'equal' appear, when my whole
> starting point was that the result string would not be equal to the
> original (except when it is :-))

Right.

I will let others voice objections, and will make the change if none
come up.

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

[John Yates]

Is it guaranteed to be new if no replacements happen?

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

[Lars Ingebrigtsen]

John Yates <john@yates-sheets.org> writes:

> Is it guaranteed to be new if no replacements happen?

Nope.  It used to be, but it's unnecessary and more inefficient.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Mattias Engdegård]

29 sep. 2020 kl. 15.40 skrev Lars Ingebrigtsen <larsi@gnus.org>:

>> Is it guaranteed to be new if no replacements happen?
> 
> Nope.  It used to be, but it's unnecessary and more inefficient.

The returned string is not guaranteed to be new even if replacements took place, for that matter.