GNU bug report logs - #72829
describe-function NEWS* scraper override

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 72829 in the body.
You can then email your comments to 72829 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattias.engdegard <at> gmail.com>
To: Emacs Bug Report <bug-gnu-emacs <at> gnu.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: describe-function NEWS* scraper override
Date: Tue, 27 Aug 2024 13:35:41 +0200

[Message part 1 (text/plain, inline)]

`describe-function` sometimes gives incorrect information about when certain functions were first introduced. NEWS.unknown can be used to fix some problems but it only works in one direction and is unable to help when a function name appears too early.

A robust solution would be to make NEWS* use a mark-up like @function{some-name} instead of just 'some-name' but meanwhile, here is a simple patch that replaces NEWS.unknown with a more structured file. This fixes the case for `always`.

[0001-Better-ad-hoc-Emacs-release-of-symbol-introduction-o.patch (application/octet-stream, attachment)]

Message #8 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattias.engdegard <at> gmail.com>,
 monnier <at> iro.umontreal.ca
Cc: 72829 <at> debbugs.gnu.org
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sat, 31 Aug 2024 13:10:24 +0300

> Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>
> From: Mattias Engdegård <mattias.engdegard <at> gmail.com>
> Date: Tue, 27 Aug 2024 13:35:41 +0200
> 
> `describe-function` sometimes gives incorrect information about when certain functions were first introduced. NEWS.unknown can be used to fix some problems but it only works in one direction and is unable to help when a function name appears too early.
> 
> A robust solution would be to make NEWS* use a mark-up like @function{some-name} instead of just 'some-name' but meanwhile, here is a simple patch that replaces NEWS.unknown with a more structured file. This fixes the case for `always`.

Thanks, I think I'm okay with this approach.

Should we perhaps mention this in some admin/notes/ files, like
perhaps the procedure described in make-tarball.txt?

Stefan, any comments?

Message #11 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 72829 <at> debbugs.gnu.org,
 Mattias Engdegård <mattias.engdegard <at> gmail.com>
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sat, 31 Aug 2024 10:06:27 -0400

> Stefan, any comments?

No, that looks fine to me.


        Stefan

Message #14 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattias.engdegard <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 72829 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sat, 31 Aug 2024 19:13:48 +0200

31 aug. 2024 kl. 12.10 skrev Eli Zaretskii <eliz <at> gnu.org>:

> Should we perhaps mention this in some admin/notes/ files, like
> perhaps the procedure described in make-tarball.txt?

Not sure what to say and where so I'll leave that for others. This hack is a bit reactive in nature, but could become a little version database if we decided to enter new symbols here systematically.

Now pushed to master. Maybe it should be back-ported to emacs-30, maybe not.

Message #17 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattias.engdegard <at> gmail.com>
Cc: 72829 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sat, 31 Aug 2024 20:43:59 +0300

> From: Mattias Engdegård <mattias.engdegard <at> gmail.com>
> Date: Sat, 31 Aug 2024 19:13:48 +0200
> Cc: monnier <at> iro.umontreal.ca,
>  72829 <at> debbugs.gnu.org
> 
> 31 aug. 2024 kl. 12.10 skrev Eli Zaretskii <eliz <at> gnu.org>:
> 
> > Should we perhaps mention this in some admin/notes/ files, like
> > perhaps the procedure described in make-tarball.txt?
> 
> Not sure what to say and where so I'll leave that for others. This hack is a bit reactive in nature, but could become a little version database if we decided to enter new symbols here systematically.
> 
> Now pushed to master. Maybe it should be back-ported to emacs-30, maybe not.

No, it should stay on master.

Message #22 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Mattias Engdegård <mattias.engdegard <at> gmail.com>, 
 72829 <at> debbugs.gnu.org
Cc: steve <at> sanityinc.com, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sat, 31 Aug 2024 15:26:58 -0700

Mattias Engdegård <mattias.engdegard <at> gmail.com> writes:

> `describe-function` sometimes gives incorrect information about when
> certain functions were first introduced. NEWS.unknown can be used to
> fix some problems but it only works in one direction and is unable to
> help when a function name appears too early.
>
> A robust solution would be to make NEWS* use a mark-up like
> @function{some-name} instead of just 'some-name' but meanwhile, here
> is a simple patch that replaces NEWS.unknown with a more structured
> file. This fixes the case for `always`.

This is a welcome change.

For symbols that are in symbol-releases.eld, which means we are actually
sure about the addition, shouldn't the help text be changed from

    Probably introduced at or before Emacs version XX.Y.

to something more like

    Added in Emacs version XX.Y.

?  I mean, we should be sure about what we put in that file, presumably.

Steve Purcell (in Cc) has been maintaining a relatively complete symbol
to version database here:

    https://github.com/purcell/package-lint/blob/master/data/stdlib-changes

Note that his version keeps track of also of `feature`s, and not just
additions but removals as well.  It would be nice if our version could
be extended to do the same.  Perhaps Steve has some code or ideas that
he would be willing to contribute.

Message #25 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 72829 <at> debbugs.gnu.org,
 Mattias Engdegård <mattias.engdegard <at> gmail.com>,
 steve <at> sanityinc.com
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sat, 31 Aug 2024 21:20:09 -0400

> Note that his version keeps track of also of `feature`s, and not just
> additions but removals as well.  It would be nice if our version could
> be extended to do the same.  Perhaps Steve has some code or ideas that
> he would be willing to contribute.

Maybe we could offer some way to show all the matches in the various
NEWS files so the user can see all the changes to the calling
convention, the deprecations, etc...


        Stefan

Message #28 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 72829 <at> debbugs.gnu.org, mattias.engdegard <at> gmail.com,
 monnier <at> iro.umontreal.ca, steve <at> sanityinc.com
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sun, 01 Sep 2024 07:52:01 +0300

> Cc: steve <at> sanityinc.com, Stefan Monnier <monnier <at> iro.umontreal.ca>
> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sat, 31 Aug 2024 15:26:58 -0700
> 
> Steve Purcell (in Cc) has been maintaining a relatively complete symbol
> to version database here:
> 
>     https://github.com/purcell/package-lint/blob/master/data/stdlib-changes
> 
> Note that his version keeps track of also of `feature`s, and not just
> additions but removals as well.  It would be nice if our version could
> be extended to do the same.  Perhaps Steve has some code or ideas that
> he would be willing to contribute.

I'm not sure I understand how can removals help us in the Help
commands.  They could be used by a new command, which doesn't yet
exist, which would show when was a specified symbol removed and what
can be used in its stead, but that command needs to be written first,
I think (and I'm not sure it will be used enough to justify it, but
that's another matter).

Message #31 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattias.engdegard <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 72829 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>,
 steve <at> sanityinc.com
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Sun, 1 Sep 2024 14:01:49 +0200

1 sep. 2024 kl. 00.26 skrev Stefan Kangas <stefankangas <at> gmail.com>:

> For symbols that are in symbol-releases.eld, which means we are actually
> sure about the addition, shouldn't the help text be changed from
> 
>    Probably introduced at or before Emacs version XX.Y.
> 
> to something more like
> 
>    Added in Emacs version XX.Y.

That's how I did it first but then dropped it for simplicity, but it can certainly be added back in.
The file also contains information about some symbols whose first appearance is not exactly known but it hardly matters for non-historians.

Message #34 received at 72829 <at> debbugs.gnu.org (full text, mbox):

From: Steve Purcell <steve <at> sanityinc.com>
To: Mattias Engdegård <mattias.engdegard <at> gmail.com>
Cc: 72829 <at> debbugs.gnu.org, Stefan Kangas <stefankangas <at> gmail.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#72829: describe-function NEWS* scraper override
Date: Mon, 9 Sep 2024 15:43:01 +0100

Yep, happy to discuss. The case for removals is that some symbols were actually removed in one Emacs version and then re-added later.

My overall technique is to load everything that I can, dump all the symbols I found, and then diff those dumps between Emacs versions. Using my nix-emacs-ci builds makes this straightforward to automate.

Not all features shipped with an Emacs build can be loaded in that build, though, because some rely on native or optional features, e.g. Windows or Treesitter. As such, it’s hard to get an authoritative list of all the known symbols.

In practice, the lists I’ve generated have been good enough for package-lint, and I often use the `package-lint-describe-symbol-history` command when I’m curious about a given symbol.

-Steve

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.