bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Adam Porter]

Hi,

Continuing with the theme of requesting the unobsoleting of some
generalized variable forms (see [#65555] and [earlier discussion]), and
given Eli's recently [mentioning] the upcoming cut of the Emacs 30
release branch, I'd like to request now that `buffer-substring' be
unmarked as obsolete.

This form makes some operations much more concise than they would
otherwise be.  For example, if one wants to update the text in a
`magit-section' section, the code could be as simple as this:

┌────
│ (let ((inhibit-read-only t))
│   (setf (buffer-substring (oref (magit-current-section) start)
│                           (oref (magit-current-section) end))
│         "foobar\n"))
└────

Otherwise, one would have to use `delete-region' and then `insert',
which is more cumbersome and error-prone.

As well, code exists in the wild which uses this form: for example,
[pcre2el], a very useful library which I use in `magit-todos' to convert
regexp between Elisp and Perl-styles.

Overall, it's a useful paradigm that makes code more readable and
concise, and I'm not aware of any drawbacks to using it; if there are
any, I think they should be discussed publicly before marking the form
as obsolete.

As I've mentioned in earlier discussions, the mass-marking of several GV
forms as obsolete in commit 48aacbf292fbe8d4be7761f83bf87de93497df27
happened apparently without public discussion, as well as without
checking the extent to which they are used outside of emacs.git.

By the way, I'd also like to request that the `point' and `window-point'
GV forms be unobsoleted, for the same reasons.  If it's permissible, I'd
like to do so here rather than file separate bug reports for each of
those, but if the maintainers prefer, I will do so.

Thanks for your consideration, and your work on Emacs.

–Adam


[#65555] <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=65555>

[earlier discussion]
<https://lists.gnu.org/archive/html/emacs-devel/2022-11/msg01408.html>

[mentioning]
<https://lists.gnu.org/archive/html/emacs-devel/2024-06/msg00042.html>

[pcre2el]
<https://github.com/joddie/pcre2el/blob/380723b2701cceb75c266440fb8db918f3340d50/pcre2el.el#L663>

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Eli Zaretskii]

> Date: Tue, 4 Jun 2024 20:33:13 -0500
> From: Adam Porter <adam@alphapapa.net>
> 
> Continuing with the theme of requesting the unobsoleting of some
> generalized variable forms (see [#65555] and [earlier discussion]), and
> given Eli's recently [mentioning] the upcoming cut of the Emacs 30
> release branch, I'd like to request now that `buffer-substring' be
> unmarked as obsolete.

I think it's too late to do this now, not without a very good reason.
Unless such a good reason emerges VSN, this will need to wait till
Emacs 31 at least.

> This form makes some operations much more concise than they would
> otherwise be.  For example, if one wants to update the text in a
> `magit-section' section, the code could be as simple as this:
> 
> ┌────
> │ (let ((inhibit-read-only t))
> │   (setf (buffer-substring (oref (magit-current-section) start)
> │                           (oref (magit-current-section) end))
> │         "foobar\n"))
> └────
> 
> Otherwise, one would have to use `delete-region' and then `insert',
> which is more cumbersome and error-prone.

I don't understand why it would be cumbersome, let alone error-prone.
Less convenient than using setf, yes, but "cumbersome"?  We've been
doing that for decades.

Use of those specific forms as GV was obsoleted in 48aacbf29 because
they are rarely if ever used as GV.  Unless this and the other two
requests suddenly get crowds of people demanding to un-obsolete them
(probably unlikely, since where were those people for the last 2
years?), I think Lars's decision to obsolete them is still solid.

IOW, this is just a matter of convenience, nothing more.

> As I've mentioned in earlier discussions, the mass-marking of several GV
> forms as obsolete in commit 48aacbf292fbe8d4be7761f83bf87de93497df27
> happened apparently without public discussion, as well as without
> checking the extent to which they are used outside of emacs.git.

We don't discuss obsoletion, because it is never final.  The rationale
for obsoleting those forms is explained in the log message, so I think
the implied accusation here is misplaced.

> By the way, I'd also like to request that the `point' and `window-point'
> GV forms be unobsoleted, for the same reasons.  If it's permissible, I'd
> like to do so here rather than file separate bug reports for each of
> those, but if the maintainers prefer, I will do so.

Let's see how many people want that now.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> ┌────
>> │ (let ((inhibit-read-only t))
>> │   (setf (buffer-substring (oref (magit-current-section) start)
>> │                           (oref (magit-current-section) end))
>> │         "foobar\n"))
>> └────
>> 
>> Otherwise, one would have to use `delete-region' and then `insert',
>> which is more cumbersome and error-prone.
>
> I don't understand why it would be cumbersome, let alone error-prone.
> Less convenient than using setf, yes, but "cumbersome"?  We've been
> doing that for decades.

setf is still a lot more convenient. It is also fairly commonly used -
Org mode did use it; github search reveals pretty frequent use in
packages and configs; I stumbled upon this warning a number of times
when compiling the packages I load in my config.

So, if the only reason to obsolete `buffer-substring' is that it is
unused, I'd prefer it not to be obsoleted.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Adam Porter]

Hi Eli,

On 6/5/24 06:52, Eli Zaretskii wrote:
>> Date: Tue, 4 Jun 2024 20:33:13 -0500 From: Adam Porter 
>> <adam@alphapapa.net>
>> 
>> Continuing with the theme of requesting the unobsoleting of some 
>> generalized variable forms (see [#65555] and [earlier discussion]),
>> and given Eli's recently [mentioning] the upcoming cut of the Emacs
>> 30 release branch, I'd like to request now that `buffer-substring'
>> be unmarked as obsolete.
> 
> I think it's too late to do this now, not without a very good
> reason. Unless such a good reason emerges VSN, this will need to wait
> till Emacs 31 at least.

That would mean years more of unnecessary compilation warnings' annoying
users when they install packages that use this form.  Some of these
users misunderstand them as bugs and report them to package developers,
which wastes everyone's time.  It also clutters lint/build logs on CI,
sometimes making it impossible to have a clean linting pass (which
requires the developer to manually inspect every "failed" run to see if
it's just another of these warnings).

>> This form makes some operations much more concise than they would 
>> otherwise be.  For example, if one wants to update the text in a 
>> `magit-section' section, the code could be as simple as this:
>> 
>> ┌──── │ (let ((inhibit-read-only t)) │   (setf (buffer-substring 
>> (oref (magit-current-section) start) │ (oref 
>> (magit-current-section) end)) │         "foobar\n")) └────
>> 
>> Otherwise, one would have to use `delete-region' and then
>> `insert', which is more cumbersome and error-prone.
> 
> I don't understand why it would be cumbersome, let alone
> error-prone. Less convenient than using setf, yes, but "cumbersome"?
> We've been doing that for decades.

The alternative means having to bind positions in variables, use
`goto-char' and `delete-region' and `insert' in a larger, more complex
form.  To me that seems much more cumbersome than this elegant GV form
which is a simple way of saying, "Replace that region with these contents."

> IOW, this is just a matter of convenience, nothing more.

*shrug*  Convenient code abstractions are easier to understand and
maintain; that's why I like to use this form, and why I like to use Lisp.

>> As I've mentioned in earlier discussions, the mass-marking of 
>> several GV forms as obsolete in commit 
>> 48aacbf292fbe8d4be7761f83bf87de93497df27 happened apparently 
>> without public discussion, as well as without checking the extent 
>> to which they are used outside of emacs.git.
> 
> We don't discuss obsoletion, because it is never final.  The 
> rationale for obsoleting those forms is explained in the log message,
> so I think the implied accusation here is misplaced.

It was not meant as an accusation--just a statement of fact, an
observation; if I was incorrect, I'll be happy to be corrected.  My
point, of course, is that the marking--and creation of these new 
compilation warnings--happened without asking if anyone would be 
affected by it.

>> By the way, I'd also like to request that the `point' and 
>> `window-point' GV forms be unobsoleted, for the same reasons.  If 
>> it's permissible, I'd like to do so here rather than file separate
>>  bug reports for each of those, but if the maintainers prefer, I 
>> will do so.
> 
> Let's see how many people want that now.

In fairness to them, most probably don't monitor emacs-bugs and are
unlikely to see this report, so I don't know if looking for replies here
would be an accurate indicator of interest.

> Use of those specific forms as GV was obsoleted in 48aacbf29 because 
> they are rarely if ever used as GV.  Unless this and the other two 
> requests suddenly get crowds of people demanding to un-obsolete them 
> (probably unlikely, since where were those people for the last 2 
> years?), I think Lars's decision to obsolete them is still solid.

I don't understand how an apparent lack of internal use is a good reason
to obsolete something useful.  There are parts of Emacs that seem to get 
  less use than these forms which are not marked obsolete.  As an Elisp
developer and tutor, I would like to see these forms used more
frequently, both inside and outside of emacs.git.  Emacs and Elisp are
so large that it takes years for knowledge about new or little-known
features to become widespread, and GVs in general are already a more 
advanced sub-topic.  I feel like obsoleting these forms is hardly giving 
them a chance, and doing so because they aren't yet widely used is like 
a catch-22.

--Adam

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Eli Zaretskii]

> Date: Wed, 5 Jun 2024 09:16:53 -0500
> Cc: 71370@debbugs.gnu.org
> From: Adam Porter <adam@alphapapa.net>
> 
> > I think it's too late to do this now, not without a very good
> > reason. Unless such a good reason emerges VSN, this will need to wait
> > till Emacs 31 at least.
> 
> That would mean years more of unnecessary compilation warnings' annoying
> users when they install packages that use this form.

Please also look at this from where I stand: if we keep adding
last-minute changes that no one tried for long enough time, we will
never start the Emacs 30 release cycle, because doing that with an
unstable master branch is a very bad idea, and delaying the branch is
the only way of knowing whether the master branch is okay after each
change.

So I must draw the line in the sand at some point (pun intended), and
I just did, a few weeks ago.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Adam Porter]

Hi Eli,

On 6/5/24 09:58, Eli Zaretskii wrote:
>> Date: Wed, 5 Jun 2024 09:16:53 -0500
>> Cc: 71370@debbugs.gnu.org
>> From: Adam Porter <adam@alphapapa.net>
>>
>>> I think it's too late to do this now, not without a very good
>>> reason. Unless such a good reason emerges VSN, this will need to wait
>>> till Emacs 31 at least.
>>
>> That would mean years more of unnecessary compilation warnings' annoying
>> users when they install packages that use this form.
> 
> Please also look at this from where I stand: if we keep adding
> last-minute changes that no one tried for long enough time, we will
> never start the Emacs 30 release cycle, because doing that with an
> unstable master branch is a very bad idea, and delaying the branch is
> the only way of knowing whether the master branch is okay after each
> change.
> 
> So I must draw the line in the sand at some point (pun intended), and
> I just did, a few weeks ago.

Of course, I would not argue with that.  I thought that un-marking these 
forms as obsolete, and thereby removing the warnings, would merely be a 
reversion that would not constitute a change in functionality, i.e. it 
would not risk any breakage, so it would be a safe change to make at 
this point.  If that is not the case, or not in your judgment, I won't 
argue with you; and I would ask that the change be made in the following 
version.

Thanks,
Adam

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Adam Porter <adam@alphapapa.net> writes:

> ┌────
> │ (let ((inhibit-read-only t))
> │   (setf (buffer-substring (oref (magit-current-section) start)
> │                           (oref (magit-current-section) end))
> │         "foobar\n"))
> └────
>
> Otherwise, one would have to use `delete-region' and then `insert',
> which is more cumbersome and error-prone.

I guess alternatively you could define a helper function and make that
`setf'able, like

#+begin_src emacs-lisp
(defalias 'magit-buffer-substring #'buffer-substring)
(gv-define-simple-setter magit-buffer-substring
                         cl--set-buffer-substring)
#+end_src


Michael.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Adam Porter]

Hi Michael,

On 6/19/24 18:44, Michael Heerdegen wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>> ┌────
>> │ (let ((inhibit-read-only t))
>> │   (setf (buffer-substring (oref (magit-current-section) start)
>> │                           (oref (magit-current-section) end))
>> │         "foobar\n"))
>> └────
>>
>> Otherwise, one would have to use `delete-region' and then `insert',
>> which is more cumbersome and error-prone.
> 
> I guess alternatively you could define a helper function and make that
> `setf'able, like
> 
> #+begin_src emacs-lisp
> (defalias 'magit-buffer-substring #'buffer-substring)
> (gv-define-simple-setter magit-buffer-substring
>                           cl--set-buffer-substring)
> #+end_src

I guess one could, but that would seem like making use of the 
marked-obsolete functionality in a roundabout way, and I'd guess that if 
it were eventually deprecated and removed, that would stop working, too 
(which one could work around by importing all of the old code, but it 
would be simpler to not obsolete it in the first place).

--Adam,
   who will one day be marked obsolete,
   but whose time has not yet come,
   either.  ;)

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Adam Porter <adam@alphapapa.net> writes:

> (which one could work around by importing all of the old code, but

Come on, those are four lines:

#+begin_src emacs-lisp
(defun cl--set-buffer-substring (start end val)
  "Delete region from START to END and insert VAL."
  (save-excursion (delete-region start end)
		  (goto-char start)
		  (insert val)
		  val))
#+end_src

> it would be simpler to not obsolete it in the first place).

For you.  But there were reasons why this had been deprecated.  Let's
stop shadow boxing.

Any arguments why this gv is different from the others that had been
deprecated?


TIA,

Michael.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Ihor Radchenko]

Michael Heerdegen via "Bug reports for GNU Emacs, the Swiss army knife
of text editors" <bug-gnu-emacs@gnu.org> writes:

> Any arguments why this gv is different from the others that had been
> deprecated?

It is one of the commonly used gvs.
https://github.com/search?q=%22%28setf+%28buffer-substring%22&type=code
gives 500+ hits (and it is not all forks of one or two popular packages)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Andrea Corallo]

Ihor Radchenko <yantar92@posteo.net> writes:

> Michael Heerdegen via "Bug reports for GNU Emacs, the Swiss army knife
> of text editors" <bug-gnu-emacs@gnu.org> writes:
>
>> Any arguments why this gv is different from the others that had been
>> deprecated?
>
> It is one of the commonly used gvs.
> https://github.com/search?q=%22%28setf+%28buffer-substring%22&type=code
> gives 500+ hits (and it is not all forks of one or two popular packages)

Interesting, I took the time to apply your methodology to all GV
obsoleted by the same commit and this is the result:

| GV                           | file occurrences |
|                              |        in github |
|------------------------------+------------------|
| buffer-file-name             |                5 |
| buffer-modified-p            |                7 |
| buffer-name                  |               48 |
| buffer-string                |              142 |
| buffer-substring             |              512 |
| current-buffer               |              234 |
| current-column               |                3 |
| current-global-map           |                0 |
| current-input-mode           |                0 |
| current-local-map            |                0 |
| current-window-configuration |                0 |
| default-file-modes           |                0 |
| current-window-configuration |                0 |
| default-file-modes           |                0 |
| documentation-property       |                8 |
| frame-height                 |               38 |
| frame-visible-p              |                0 |
| global-key-binding           |                3 |
| local-key-binding            |                0 |
| mark                         |                4 |
| mark-marker                  |                0 |
| marker-position              |               16 |
| mouse-position               |                7 |
| point                        |               32 |
| point-marker                 |                0 |
| point-max                    |                0 |
| point-min                    |               40 |
| read-mouse-position          |                0 |
| screen-height                |                4 |
| screen-width                 |               15 |
| selected-window              |                4 |
| selected-screen              |                0 |
| selected-frame               |                0 |
| standard-case-table          |                0 |
| syntax-table                 |                0 |
| visited-file-modtime         |                0 |
| window-height                |               13 |
| window-width                 |                9 |
| x-get-secondary-selection    |                0 |

While some of them are rarely/not used some others looks quite popular.
This is an indication that the popular ones are probably a good
abstraction or they are just convenient.

I don't know what would be the risk of un-obsoleting the popular ones
now, but if is not possible I think we should consider doing it for the
next release cycle.

  Andrea

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Andrea Corallo <acorallo@gnu.org> writes:

> [...]
> Interesting, I took the time to apply your methodology to all GV
> obsoleted by the same commit and this is the result:
>
> | GV                           | file occurrences |
> |                              |        in github |
> |------------------------------+------------------|
>   [... I picked the lines with 100+ matches ...]
> | buffer-string                |              142 |
> | buffer-substring             |              512 |
> | current-buffer               |              234 |
> [...]

> While some of them are rarely/not used some others looks quite popular.
> This is an indication that the popular ones are probably a good
> abstraction or they are just convenient.

More of the latter I would say.  Nonetheless that's one aspect that
counts.

But especially `buffer-substring' doesn't convince me as a gv because
semantics are very doubtful:

- You say (setf (buffer-substring START END) STRING).  The first thing
  that is not crystal clear is the question whether STRING will be
  added, or will replace, existing text.

- The END argument is either redundant, or, if text is replaced (which
  is what the current implementation does), it is unclear what happens
  if STRING has a length different from (- END START).  The current
  implementation doesn't even fulfill the most _basic_ assumption about
  places: if STRING has a different length, after
  (setf (buffer-substring START END) STRING),
  (buffer-substring START END) will _not_ be equal to STRING.  This is
  very bad, conceptually.

- For this reason resetting the place to the old "value" will not
  always restore the old situation.

- With `cl-letf' the generalized variable gets even more doubtful: if
  you edit the buffer contents inside the scope of the binding,
  reverting a `buffer-substring' gv binding will give surprising
  results, especially if START and END were specified as integers then
  pointing to unrelated positions.

These were exactly the kind of problems why those place expressions had
been obsoleted.  Adding a little helper function with clear semantics
really looks more appropriate in this case in my opinion, even if you
have to remember one more name.


Michael.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Ihor Radchenko]

Michael Heerdegen <michael_heerdegen@web.de> writes:

>> While some of them are rarely/not used some others looks quite popular.
>> This is an indication that the popular ones are probably a good
>> abstraction or they are just convenient.
>
> More of the latter I would say.  Nonetheless that's one aspect that
> counts.
>
> But especially `buffer-substring' doesn't convince me as a gv because
> semantics are very doubtful:
> ...

> These were exactly the kind of problems why those place expressions had
> been obsoleted.

Do note that the original reason of obsoletion was different:

   48aacbf292fbe8d4be7761f83bf87de93497df27
    Make many seldom-used generalized variables obsolete
    
    The vast majority of these are unused in-tree, and many of them
    perform actions that aren't obvious when reading the code.

No arguments have been listed about "actions that aren't obvious" wrt
`buffer-substring' generalized variable. And, as we see, "unused" is
only true for Emacs sources, but not for third-party libs.

> - You say (setf (buffer-substring START END) STRING).  The first thing
>   that is not crystal clear is the question whether STRING will be
>   added, or will replace, existing text.
>
> - The END argument is either redundant, or, if text is replaced (which
>   is what the current implementation does), it is unclear what happens
>   if STRING has a length different from (- END START).  The current
>   implementation doesn't even fulfill the most _basic_ assumption about
>   places: if STRING has a different length, after
>   (setf (buffer-substring START END) STRING),
>   (buffer-substring START END) will _not_ be equal to STRING.  This is
>   very bad, conceptually.
>
> - For this reason resetting the place to the old "value" will not
>   always restore the old situation.
>
> - With `cl-letf' the generalized variable gets even more doubtful: if
>   you edit the buffer contents inside the scope of the binding,
>   reverting a `buffer-substring' gv binding will give surprising
>   results, especially if START and END were specified as integers then
>   pointing to unrelated positions.

FYI, I never had this kind of confusion. It is perfectly expected for
_buffers_ that any kind of modification may render point positions
inaccurate. If one needs to track specific region even when
modifications are performed, this is what markers are for. And markers
do work when used as arguments for buffer-substring.

> ...  Adding a little helper function with clear semantics
> really looks more appropriate in this case in my opinion, even if you
> have to remember one more name.

Maybe. But I would argue that `buffer-substring' is already _the most
popular_ among obsoleted generized variables. Clearly, people do find it
useful; and, clearly, obsoleting it forces many library authors to do
extra work that is not justified.

I would be ok with adding a helper _in addition_ to generalized
variable, but I do not see it justified to make it replace it (at least,
not until we see that the added new helper is vastly more popular)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Eli Zaretskii]

> Cc: Adam Porter <adam@alphapapa.net>, 71370@debbugs.gnu.org,
>  Andrea Corallo <acorallo@gnu.org>
> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Sat, 22 Jun 2024 06:05:10 +0000
> 
> Michael Heerdegen <michael_heerdegen@web.de> writes:
> 
> > These were exactly the kind of problems why those place expressions had
> > been obsoleted.
> 
> Do note that the original reason of obsoletion was different:

Commit log messages are not a legal document, so treating them as if
they were the truth, the whole truth, and nothing but the truth is not
TRT.  (I'm guessing that Org commit log messages don't necessarily
tell the whole story behind the changes, either, at least not in all
cases.)

While having some reason in the commit log message can be used as
evidence that its author had that in mind, the absence of a reason can
NOT and should not be used as evidence that it was NOT in the author's
mind.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Do note that the original reason of obsoletion was different:
> ...
> Commit log messages are not a legal document, so treating them as if
> they were the truth, the whole truth, and nothing but the truth is not
> TRT.

I am not saying that commit message is the full truth.
But I did not find any other relevant discussion about
`buffer-substring' on the mailing list. (And commit message did not
contain any reference to such discussion)

So, I simply used information that was available to me to check
Michaels' claim.

If you have a link to the discussion leading to obsolete of
`buffer-substring', feel free to share it.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: michael_heerdegen@web.de, adam@alphapapa.net, 71370@debbugs.gnu.org,
>  acorallo@gnu.org
> Date: Sat, 22 Jun 2024 08:39:14 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Do note that the original reason of obsoletion was different:
> > ...
> > Commit log messages are not a legal document, so treating them as if
> > they were the truth, the whole truth, and nothing but the truth is not
> > TRT.
> 
> I am not saying that commit message is the full truth.
> But I did not find any other relevant discussion about
> `buffer-substring' on the mailing list. (And commit message did not
> contain any reference to such discussion)
> 
> So, I simply used information that was available to me to check
> Michaels' claim.
> 
> If you have a link to the discussion leading to obsolete of
> `buffer-substring', feel free to share it.

I respectfully suggest to consider this discussion as relevant
evidence.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Eli Zaretskii]

> Cc: Adam Porter <adam@alphapapa.net>, 71370@debbugs.gnu.org,
>  Ihor Radchenko <yantar92@posteo.net>
> Date: Sat, 22 Jun 2024 00:52:43 +0200
> From:  Michael Heerdegen via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> These were exactly the kind of problems why those place expressions had
> been obsoleted.  Adding a little helper function with clear semantics
> really looks more appropriate in this case in my opinion, even if you
> have to remember one more name.

Agreed.

bug#71370: 30.0.50; Please un-obsolete buffer-substring as a generalized variable

[Adam Porter]

Hi Michael,

On 6/19/24 18:44, Michael Heerdegen wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>> ┌────
>> │ (let ((inhibit-read-only t))
>> │   (setf (buffer-substring (oref (magit-current-section) start)
>> │                           (oref (magit-current-section) end))
>> │         "foobar\n"))
>> └────
>>
>> Otherwise, one would have to use `delete-region' and then `insert',
>> which is more cumbersome and error-prone.
> 
> I guess alternatively you could define a helper function and make that
> `setf'able, like
> 
> #+begin_src emacs-lisp
> (defalias 'magit-buffer-substring #'buffer-substring)
> (gv-define-simple-setter magit-buffer-substring
>                           cl--set-buffer-substring)
> #+end_src

One could, but it would seem tedious and wasteful to have do that across 
tens or hundreds of Elisp packages that use this setter and have for years.

The minor ambiguities you point out in one of your later messages are 
fair to note; however, they aren't new, and they don't appear to have 
discouraged use of this form in practice.  On the contrary, the form 
appears to be widely useful and understood easily enough.

Given that Emacs is full of idiosyncrasies which are much more impactful 
and challenging to understand, I'd think that it would be sufficient to 
document this one in the Elisp manual, like others are.  I'd certainly 
rather do that than deprive users of this useful, simple idiom which is 
already widely used.

--Adam