History info in C-h f

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

Re: History info in C-h f

[Michael Albinus]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

Hi Stefan,

> 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.

Working on Tramp is much about compatibilty. I would appreciate this
funtionality in Emacs.

>         Stefan

Best regards, Michael.

Re: History info in C-h f

[John Shahid]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> 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.

That is very useful thanks.  I wanted to know the minimum version of
Emacs that introduced `string-join' recently and had to grep for it in
the NEWS file.  Although grepping isn't that hard, having that
information available on the help page is useful imho.

> 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.

Does it make sense to add a feature to `defun'.  I'm thinking another
optional min version arg that would set a property on the symbol.  That
can be used by "C-h f" to display the minimum version.  I can see that
being useful to package/library maintainers and not just Emacs.


[...]

> +                  (error "Ref found in non-versioned section in %S"
> +                         (file-name-nondirectory f))

I had to get rid of this error, otherwise "C-h f" won't work on
primitves (e.g. `defun' that is used to document other features) or
symbols that are found in NEWS.1-17

Re: History info in C-h f

[Elias Mårtenson]

[-- Attachment #1: Type: text/plain, Size: 418 bytes --]

On Sat, 29 Sep 2018, 23:19 John Shahid, <jvshahid@gmail.com> wrote:

>
> That is very useful thanks.  I wanted to know the minimum version of
> Emacs that introduced `string-join' recently and had to grep for it in
> the NEWS file.  Although grepping isn't that hard, having that
> information available on the help page is useful imho.
>

A declaration would make more sense. Like (declare (introduced-in "24.0"))

>

[-- Attachment #2: Type: text/html, Size: 913 bytes --]

Re: History info in C-h f

[Stefan Monnier]

>> 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.
> Does it make sense to add a feature to `defun'.  I'm thinking another
> optional min version arg that would set a property on the symbol.  That
> can be used by "C-h f" to display the minimum version.  I can see that
> being useful to package/library maintainers and not just Emacs.

I definitely don't want this to be something that needs manual
intervention, except maybe for some very rare cases.

> I had to get rid of this error, otherwise "C-h f" won't work on
> primitves (e.g. `defun' that is used to document other features) or
> symbols that are found in NEWS.1-17

That's what

    (at least, if you're on `master` and have upgraded very recently)

was referring to.  I fixed the etc/NEWS.1-17 and NEWS.18 to match the
expected format, but that's only in master and only pushed yesterday.


        Stefan

RE: History info in C-h f

[Drew Adams]

> 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.

Some such feature would be great.  It would be better
if it didn't depend on NEWS (which doesn't record all
new functions and variables), and if it were in fact
somehow completely automatic, e.g., set for a given
function or variable when a release is built (e.g.
comparing against a list of pre-existing such).