History info in C-h f

[Stefan Monnier]

Not sure if we should install this, especially since it's far from
reliable, but I've just whipped up the code below and figured some of
you might like it.

With this hack (which can go into your ~/.emacs), `C-h f defmacro`
dutifully informs you that `defmacro` was added to Emacs-1.2 (at least,
if you're on `master` and have upgraded very recently), whereas `C-h
f advice-add` informs you that it was only introduced in Emacs-24.4.


        Stefan


diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index e15c96e6a3..a6c92103e6 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -574,6 +574,37 @@ help-fns--interactive-only
                          (t "."))
                    "\n")))))
 
+(add-hook 'help-fns-describe-function-functions #'help-fns--first-release)
+(defun help-fns--first-release (function)
+  "Try and find the first release that defined this function."
+  ;; Code below relies on the etc/NEWS* files.
+  ;; FIXME: Maybe we should also use the */ChangeLog* files when available.
+  ;; FIXME: Maybe we should also look for announcements of the addition
+  ;; of the *packages* in which the function is defined.
+  (when (symbolp function)
+    (let* ((name (symbol-name function))
+           (re (concat "\\_<" (regexp-quote name) "\\_>"))
+           (news (directory-files data-directory t "\\`NEWS.[1-9]"))
+           (first nil))
+      (with-temp-buffer
+        (dolist (f news)
+          (erase-buffer)
+          (insert-file-contents f)
+          (goto-char (point-min))
+          (search-forward "\n*")
+          (while (re-search-forward re nil t)
+            (save-excursion
+              (if (not (re-search-backward "^\\*.*in Emacs \\([0-9.]+\\)"
+                                           nil t))
+                  (error "Ref found in non-versioned section in %S"
+                         (file-name-nondirectory f))
+                (let ((version (match-string 1)))
+                  (when (or (null first) (version< version first))
+                    (setq first version))))))))
+      (when first
+        (insert (format "\nIntroduced at or before Emacs version %s.\n"
+                        first))))))
+
 (defun help-fns-short-filename (filename)
   (let* ((abbrev (abbreviate-file-name filename))
          (short abbrev))