From: "Mattias Engdegård" <mattias.engdegard@gmail.com>
To: 72829@debbugs.gnu.org
Cc: Stefan Monnier <monnier@iro.umontreal.ca>
Subject: bug#72829: describe-function NEWS* scraper override
Date: Tue, 27 Aug 2024 13:35:41 +0200 [thread overview]
Message-ID: <79C79924-4870-4E55-9920-3D2C08A1E765@gmail.com> (raw)
[-- Attachment #1: Type: text/plain, Size: 496 bytes --]
`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`.
[-- Attachment #2: 0001-Better-ad-hoc-Emacs-release-of-symbol-introduction-o.patch --]
[-- Type: application/octet-stream, Size: 5943 bytes --]
From bfa7f11acb8aeeeaa07af29ec18dd30f77e933b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Mon, 26 Aug 2024 17:18:25 +0200
Subject: [PATCH] Better ad-hoc Emacs release of symbol introduction override
The file etc/symbol-releases.eld now contains explicit version
information for selected symbols that our NEWS* scraper doesn't
resolve correctly.
* etc/NEWS.unknown: Remove this file, replaced with...
* etc/symbol-releases.eld: ...this new file.
* lisp/help-fns.el (help-fns--first-release-override)
(help-fns--mention-first-function-release)
(help-fns--mention-first-variable-release): New.
(help-fns--mention-first-release): Try the override information first
before scraping the NEWS* files.
---
etc/NEWS.unknown | 31 -------------------------------
etc/symbol-releases.eld | 36 ++++++++++++++++++++++++++++++++++++
lisp/help-fns.el | 33 ++++++++++++++++++++++++++++-----
3 files changed, 64 insertions(+), 36 deletions(-)
delete mode 100644 etc/NEWS.unknown
create mode 100644 etc/symbol-releases.eld
diff --git a/etc/NEWS.unknown b/etc/NEWS.unknown
deleted file mode 100644
index eafdc953cac..00000000000
--- a/etc/NEWS.unknown
+++ /dev/null
@@ -1,31 +0,0 @@
-This file contains mentions of functions and variables whose
-version of introduction would otherwise be guessed incorrectly
-by 'M-x describe-function'.
-
-Since much of early Emacs source history is lost, these versions are
-conservative estimates: the actual version of first appearance may very
-well be much earlier.
-
-* Changes in Emacs 19.7
-** 'defsubst'
-
-* Changes in Emacs 18.59
-** 'mark'
-
-* Changes in Emacs 13.8
-This may be the earliest surviving version with source code, although
-damaged. See
-https://github.com/larsbrinkhoff/emacs-history/decuslib.com/decus/vax85b/gnuemax
-
-** 'nthcdr'
-** 'nreverse
-** 'let*'
-** 'rassq'
-** '>='
-** 'transpose-sexps'
-** 'buffer-modified-p'
-** 'current-column'
-** 'downcase'
-** 'previous-line'
-** 'catch', 'throw'
-** 'count-lines'
diff --git a/etc/symbol-releases.eld b/etc/symbol-releases.eld
new file mode 100644
index 00000000000..dc991ae5747
--- /dev/null
+++ b/etc/symbol-releases.eld
@@ -0,0 +1,36 @@
+;; Emacs versions when certain symbols and variables were first introduced,
+;; for use in `describe-function'.
+;;
+;; This file is used to explicitly override the heuristic scraping NEWS*
+;; files, when that would result in misleading information.
+;;
+;; It should contain a single list of (VERSION TYPE SYMBOL), where
+;; VERSION is the Emacs version when SYMBOL was introduced as a TYPE,
+;; TYPE being `fun' or `var'.
+
+(
+ ("28.1" fun always)
+
+;; Since much of early Emacs source history is lost, these versions are
+;; conservative estimates: the actual version of first appearance may very
+;; well be much earlier.
+;; 13.8 may be the earliest surviving version with source code, although
+;; damaged. See
+;; https://github.com/larsbrinkhoff/emacs-history/decuslib.com/decus/vax85b/gnuemax
+
+ ("19.7" fun defsubst)
+ ("18.59" fun mark)
+ ("13.8" fun nthcdr)
+ ("13.8" fun nreverse)
+ ("13.8" fun let*)
+ ("13.8" fun rassq)
+ ("13.8" fun >=)
+ ("13.8" fun transpose-sexps)
+ ("13.8" fun buffer-modified-p)
+ ("13.8" fun current-column)
+ ("13.8" fun downcase)
+ ("13.8" fun previous-line)
+ ("13.8" fun catch)
+ ("13.8" fun throw)
+ ("13.8" fun count-lines)
+ )
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 8a2ae79736f..3d3b841d827 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -869,6 +869,21 @@ help-fns--first-release-regexp
))
+(defun help-fns--first-release-override (symbol type)
+ "The first release defining SYMBOL of TYPE, or nil.
+TYPE indicates the namespace and is `fun' or `var'."
+ (let* ((sym-rel-file (expand-file-name "symbol-releases.eld" data-directory))
+ (tuples
+ (with-temp-buffer
+ (ignore-errors
+ (insert-file-contents sym-rel-file)
+ (goto-char (point-min))
+ (read (current-buffer))))))
+ (unless (cl-every (lambda (x) (and (= (length x) 3) (stringp (car x))))
+ tuples)
+ (error "Bad %s format" sym-rel-file))
+ (car (rassoc (list type symbol) tuples))))
+
(defun help-fns--first-release (symbol)
"Return the likely first release that defined SYMBOL, or nil."
;; Code below relies on the etc/NEWS* files.
@@ -949,16 +964,24 @@ help-fns--first-release
;; (display-buffer (current-buffer)))))
(add-hook 'help-fns-describe-function-functions
- #'help-fns--mention-first-release)
+ #'help-fns--mention-first-function-release)
(add-hook 'help-fns-describe-variable-functions
- #'help-fns--mention-first-release)
-(defun help-fns--mention-first-release (object)
+ #'help-fns--mention-first-variable-release)
+
+(defun help-fns--mention-first-function-release (object)
+ (help-fns--mention-first-release object 'fun))
+
+(defun help-fns--mention-first-variable-release (object)
;; Don't output anything if we've already output the :version from
;; the `defcustom'.
(unless (memq 'help-fns--customize-variable-version
help-fns--activated-functions)
- (when-let ((first (and (symbolp object)
- (help-fns--first-release object))))
+ (help-fns--mention-first-release object 'var)))
+
+(defun help-fns--mention-first-release (object type)
+ (when (symbolp object)
+ (when-let ((first (or (help-fns--first-release-override object type)
+ (help-fns--first-release object))))
(with-current-buffer standard-output
(insert (format " Probably introduced at or before Emacs version %s.\n"
first))))))
--
2.32.0 (Apple Git-132)
next reply other threads:[~2024-08-27 11:35 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-08-27 11:35 Mattias Engdegård [this message]
2024-08-31 10:10 ` bug#72829: describe-function NEWS* scraper override Eli Zaretskii
2024-08-31 14:06 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-08-31 17:13 ` Mattias Engdegård
2024-08-31 17:43 ` Eli Zaretskii
2024-08-31 22:26 ` Stefan Kangas
2024-09-01 1:20 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-09-01 4:52 ` Eli Zaretskii
2024-09-01 12:01 ` Mattias Engdegård
2024-09-09 14:43 ` Steve Purcell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=79C79924-4870-4E55-9920-3D2C08A1E765@gmail.com \
--to=mattias.engdegard@gmail.com \
--cc=72829@debbugs.gnu.org \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).