How to find when a feature was introduced

How to find when a feature was introduced

[Rusi]

Student sent me this

Symbol's function definition is void: with-eval-after-load

Figured this came from a slightly oldish ubuntu

Then found the with-eval-after-load in gnu-apl-mode

So now I need to tell my students gnu-apl-mode will not run in emacsen less than
version X

How to find out X?

Re: How to find when a feature was introduced

[Kaushal Modi]

For not know a better way, I would just grep the NEWS* files in the etc/
directory for the function/variable name.

For this particular example, the info is in NEWS.24 file.

===
* Lisp Changes in Emacs 24.4
...
** New macro `with-eval-after-load'.
This is like the old `eval-after-load', but better behaved.
===

So this macro was introduced in emacs 24.4.

On Fri, Jul 8, 2016 at 12:30 AM Rusi <rustompmody@gmail.com> wrote:

> Student sent me this
>
> Symbol's function definition is void: with-eval-after-load
>
> Figured this came from a slightly oldish ubuntu
>
> Then found the with-eval-after-load in gnu-apl-mode
>
> So now I need to tell my students gnu-apl-mode will not run in emacsen
> less than
> version X
>
> How to find out X?
>
-- 

-- 
Kaushal Modi

Re: How to find when a feature was introduced

[Paul Rankin]

Kaushal Modi <kaushal.modi@gmail.com> on Fri, 08 Jul 2016 04:41 +0000:
> For not know a better way, I would just grep the NEWS* files in the etc/
> directory for the function/variable name.
> 
> ...
>
> On Fri, Jul 8, 2016 at 12:30 AM Rusi <rustompmody@gmail.com> wrote:
> 
> > Student sent me this
> >
> > Symbol's function definition is void: with-eval-after-load
> >
> > Figured this came from a slightly oldish ubuntu
> >
> > Then found the with-eval-after-load in gnu-apl-mode
> >
> > So now I need to tell my students gnu-apl-mode will not run in emacsen
> > less than
> > version X
> >
> > How to find out X?

Within Emacs...

M-x view-emacs-news RET

C-s FEATURE

-- 
Paul W. Rankin
www.paulwrankin.com

RE: How to find when a feature was introduced

[Drew Adams]

> > > So now I need to tell my students gnu-apl-mode will not run in emacsen
> > > less than version X   How to find out X?
> 
> M-x view-emacs-news RET C-s FEATURE

That works for some features/functions/variables/..., but not for
others.  It depends on how well and even whether the thing in question
is called out clearly in the NEWS.


FWIW -

I keep multiple Emacs binaries and check them when needed.  But I do
that because I maintain some of my libraries across multiple releases.
(Many people will not bother to do this.)

If I have a library that fundamentally makes use of some feature that
is only available starting with release N.M then that's the minimum
release I support for that library - e.g., `apu.el' is Emacs 24+ 
because it is all about Unicode.

But if a library just makes incidental use of some feature - it is
not essential to the library, then I support older releases that
don't provide that feature, and I conditionalize its use within
the library using `fboundp', `boundp', `featurep', or even a
release-number check, whichever is most specific but still
sufficient to distinguish whatever is involved.

Yes, that means extra maintenance work.  But there are lots of
Emacs users (most!) who do _not_ use the latest release.  I see
too many libraries (IMHO) that evolve to gratuitously use recent
constructs, which means some of their users can lose the
possibility of using them.

By "gratuitously" here I mean that the library maintainer and the
library itself do not really gain anything important by such a
change.  Obviously, if a new feature enables you to do something
really different (e.g. bidi support) or really better, then there
is no reason not to take advantage of it.

But many changes I see are little more than cosmetic, and if such
a case throws library users by the wayside then I think that's a
waste.  On the other hand, it can make things easier for a library
maintainer not to have to worry about supporting more than the
latest release...

YMMV

RE: How to find when a feature was introduced

[Drew Adams]

> I see too many libraries (IMHO) that evolve to gratuitously use
> recent constructs, which means some of their users can lose the
> possibility of using them.
> 
> By "gratuitously" here I mean that the library maintainer and the
> library itself do not really gain anything important by such a
> change.  Obviously, if a new feature enables you to do something
> really different (e.g. bidi support) or really better, then there
> is no reason not to take advantage of it.
> 
> But many changes I see are little more than cosmetic, and if such
> a case throws library users by the wayside then I think that's a
> waste.  On the other hand, it can make things easier for a library
> maintainer not to have to worry about supporting more than the
> latest release...

And to circle back to the original question and its use case:
Choosing to use macro `with-eval-after-load' instead of function
`eval-after-load' is a good example of an evolution for a
library to undergo that is often essentially gratuitous, IMO.

If there is another, better or significant reason to require
a version of Emacs that is recent enough that it includes
`with-eval-after-load', then using that macro is _not_ just
gratuitous.  But on its own, as the sole reason for requiring
that recent a version of Emacs, it is likely to be so.

Here is the definition of macro `with-eval-after-load':

(defmacro with-eval-after-load (file &rest body)
  `(eval-after-load ,file (lambda () ,@body)))

It just wraps the BODY in a lambda and calls `eval-after-load'.
The lambda form is funcalled after FILE is loaded.

Why was this macro added to Emacs?  (Its addition was a good
thing, BTW.)

(1) Because the most common use case of `eval-after-load' passes
a quoted sexp as the BODY, and some users were leaving off the
quote and then wondering why their code did not work.

And (2) because a quoted BODY returns a sexp, and that sexp
(to be evaluated later as code) is just constant _data_ at
compile time; it is not byte-compiled as code.

Both are good reasons for adding `with-eval-after-load' to
Emacs.  Are they good reasons for replacing `eval-after-load'
in your library?

IMO it depends on (a) whether byte-compiling the particular
BODY form really makes a difference for your code and, if not,
(b) whether there is anyway another reason for the library to
be usable only with an Emacs version that is recent enough to
have `with-eval-after-load'.

(And for (a), if the BODY sexp is complex enough that you
care about it being compiled, it is usually enough to just 
define a function that encapsulates that sexp, and use the
function name as BODY.  The function definition is compiled.)

This macro was introduced in Emacs 24.4.  And immediately,
I suspect, libraries all over the place started using it,
even sometimes replacing correct uses of `eval-after-load'.

Are all such updates needed? useful?  Are some of them what
I would call gratuitous?

My own approach is to require Emacs 24.4 or later only when
the code in my library really needs it or can really take
advantage of it.  I generally would not do that just to be
able to use macro `with-eval-after-load'.

As usual, it's a tradeoff: Do you want users with an older
Emacs version to be able to use your library?  Do you want
to take advantage of what the new feature (macro, in this
case) offers?

Sometimes a new library starts out more or less as a set
of personal Emacs customizations.  In that context, the
library author typically does not care about supporting
versions of Emacs older than the one s?he uses.

And that unconcern for older-version use can then become
a habit.  And it certainly is easier, in terms of
maintenance.  I think this explains most lack of support
for multiple Emacs versions.

---

There is also this consideration, BTW, from (elisp) `Coding
Conventions', but it is orthogonal to my point here.

  Avoid using 'eval-after-load' and 'with-eval-after-load'
  in libraries and packages (*note Hooks for Loading::).
  This feature is meant for personal customizations; using
  it in a Lisp program is unclean, because it modifies the
  behavior of another Lisp file in a way that's not visible
  in that file.  This is an obstacle for debugging, much
  like advising a function in the other package.

That is of course reasonable advice, though it simplifies
and overstates the case.  Running a hook, in this case
after loading a Lisp file, does _not_ necessarily modify
the behavior of that file.  What is true is that whatever
the hook function does is not something that is visible
in that Lisp file.

It's OK - that text is not bad.  But it is a case of a 
recommendation in the doc that you want to _understand_
and not just take literally as gospel.

Re: How to find when a feature was introduced

[Kaushal Modi]

Hi Rustom,

Here's a quick update on the code snippets I emailed earlier.

If you use the counsel package and ag, I recently requested a PR and that
got accepted. If you use the latest version of counsel from Melpa, the
function to search in all NEWS files is now simply this:

  (defun counsel-ag-news (&optional initial-input)
    "Search for a pattern in NEWS files using ag.
INITIAL-INPUT can be given as the initial minibuffer input."
    (interactive)
    (counsel-ag initial-input data-directory " -G '/NEWS'" "Search NEWS"))
-- 

-- 
Kaushal Modi

Re: How to find when a feature was introduced

[Rusi]

On Saturday, July 9, 2016 at 11:52:06 PM UTC+5:30, Kaushal Modi wrote:
> Hi Rustom,
> 
> Here's a quick update on the code snippets I emailed earlier.
> 
> If you use the counsel package and ag, I recently requested a PR and that
> got accepted. If you use the latest version of counsel from Melpa, the
> function to search in all NEWS files is now simply this:
> 
>   (defun counsel-ag-news (&optional initial-input)
>     "Search for a pattern in NEWS files using ag.
> INITIAL-INPUT can be given as the initial minibuffer input."
>     (interactive)
>     (counsel-ag initial-input data-directory " -G '/NEWS'" "Search NEWS"))

Thanks Kaushal for the efforts
I just followed Drew's suggestion and replaced with-eval-after-load with
eval-after-load (!!)
And its working on the older installations

Re: How to find when a feature was introduced

[Eli Zaretskii]

> Date: Thu, 7 Jul 2016 21:28:06 -0700 (PDT)
> From: Rusi <rustompmody@gmail.com>
> 
> So now I need to tell my students gnu-apl-mode will not run in emacsen less than
> version X
> 
> How to find out X?

First, try the NEWS method that someone else pointed to.

If that doesn't work, and the symbol is a defcustom, it should have a
:version tag (if it isn't, report that as a bug).

If that doesn't work either, or is inapplicable, the most elaborate
method that _always_ works is this:

  . C-h f SOMETHING or C-h v SOMETHING
  . note the place in the sources where SOMETHING is defined
  . go to the nearest Emacs Git repository and use Git facilities to
    find out the date on which the code was added
  . consult etc/HISTORY to see which Emacs release the date
    corresponds to

Notes:
(1) The Git facilities are "git annotate" and "git log -L".
(2) Due to branching before the release, a date that is before a
release doesn't necessarily mean the feature was in that release, you
will have to see when the release branch was cut; there should be a
Git tag at the branch point.

Re: How to find when a feature was introduced

[Kaushal Modi]

Rustom's question inspired me to come up with this little counsel function
to quickly search through *all* NEWS files. The dependencies are the
'counsel' package and 'ag' executable (below can be adapted to use grep
instead of ag if desired).

It looks like this: http://i.imgur.com/GYT7gln.png

Below code is derived from the counsel-ag implementation in counsel.el:
https://github.com/abo-abo/swiper/blob/4dbd8c30d5bf0bf7154ca39712bf66ab6f580de7/counsel.el#L1442-1476

=====
;; NEWS search
(defun counsel-news-function (regexp)
  "Search in all NEWS files for REGEXP."
  (if (< (length regexp) 3)
      (counsel-more-chars 3)
    (let ((default-directory data-directory)
          (regex (counsel-unquote-regex-parens (setq ivy--old-re
(ivy--regex regexp)))))
      (counsel--async-command
       (format (concat counsel-ag-base-command " -G '/NEWS.*'")
               (shell-quote-argument regex)))
      nil)))

(defun counsel-news (&optional initial-input)
  "Grep for a pattern in regr*list files using ag.
INITIAL-INPUT can be given as the initial minibuffer input."
  (interactive)
  (require 'counsel)
  (setq counsel--git-grep-dir data-directory)
  (ivy-read "Search NEWS: " 'counsel-news-function
            :initial-input initial-input
            :dynamic-collection t
            :history 'counsel-git-grep-history
            :action #'counsel-git-grep-action
            :unwind (lambda ()
                      (counsel-delete-process)
                      (swiper--cleanup))
            :caller 'counsel-news))
=====

I have bound counsel-news to C-h n.

Full code:
https://github.com/kaushalmodi/.emacs.d/blob/master/setup-files/setup-news.el

On Fri, Jul 8, 2016 at 2:44 AM Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Thu, 7 Jul 2016 21:28:06 -0700 (PDT)
> > From: Rusi <rustompmody@gmail.com>
> >
> > So now I need to tell my students gnu-apl-mode will not run in emacsen
> less than
> > version X
> >
> > How to find out X?
>
> First, try the NEWS method that someone else pointed to.
>
> If that doesn't work, and the symbol is a defcustom, it should have a
> :version tag (if it isn't, report that as a bug).
>
> If that doesn't work either, or is inapplicable, the most elaborate
> method that _always_ works is this:
>
>   . C-h f SOMETHING or C-h v SOMETHING
>   . note the place in the sources where SOMETHING is defined
>   . go to the nearest Emacs Git repository and use Git facilities to
>     find out the date on which the code was added
>   . consult etc/HISTORY to see which Emacs release the date
>     corresponds to
>
> Notes:
> (1) The Git facilities are "git annotate" and "git log -L".
> (2) Due to branching before the release, a date that is before a
> release doesn't necessarily mean the feature was in that release, you
> will have to see when the release branch was cut; there should be a
> Git tag at the branch point.
>
> --

-- 
Kaushal Modi