master 59e0b82776a: Better ad-hoc Emacs release of symbol introduction override

[Mattias Engdegård]

branch: master
commit 59e0b82776ade72680e7c369f6089eab4a74dc4a
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    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(-)

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 @@ the C sources, too."
     ))
 
 
+(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 @@ the C sources, too."
 ;;       (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))))))