bug#24237: 24.5; (elisp)`Extended Menu Items', :filter warning

[Drew Adams <drew.adams@oracle.com>]

> > The doc for :filter says this about the FILTER-FN:
> >
> >    Emacs can call this function at any time that it does redisplay or
> >    operates on menu data structures, so you should write it so it can
> >    safely be called at any time.
> >
> > Is this true in general, or only when the extended menu item is put on a
> > menu?
> >
> > A common idiom is to make use of a `menu-item' construct with a :filter
> > to create a conditional _keyboard_ key binding.  In such a case, the
> > `menu-item' construct is not a real menu item - it is not placed on any
> > menu.
> >
> > I'm guessing that in such a case this doc paragraph does not apply.  If
> > this guess is correct then please correct the paragraph, so that it says
> > something like "If an extended menu item that uses :filter is placed on
> > a menu then Emacs can call FILTER-FN when...".
> 
> I think making the documentation more specific here serves no purpose.
> The statement as is should be true: You should always write these filter
> functions as if they are called at any time.
> 
> > Also, is it really the case that FILTER-FN can be called anytime Emacs
> > does redisplay?  Shouldn't the doc say only that it can be called
> > anytime Emacs "operates on menu data structures"?  Does it get called by
> > redisplay other than when redisplay operates on menu data structures?
> > In the case mentioned above (binding to a keyboard key), would FILTER-FN
> > ever be called during redisplay?  I'm guessing that it would not.
> 
> I don't see why we should specify that at all.

The Elisp manual is not only for readers reading as
end users.  This information is needed by people
writing Lisp code that uses extended menu items.

And as the bug report points out, a very different
use case does not involve use of a menu at all.

Now perhaps Emacs should provide some alternative
to using an extended menu item, specifically for
this very different use case.  But until and unless
it does that, the behavior for this particular use
case should be covered in the doc.  In particular,
if the caveat that is written does NOT apply for
this use case, then that should be pointed out.

IF the guess is correct that this caveat does NOT
in fact apply to this use case then no, it is
NOT the case that "You should always write these
filter functions as if they are called at any time."
If that guess is correct then what you say as the
reason for not fixing this doc bug simply isn't
relevant.

This is not some obscure detail.  It goes to the
heart of the behavior and use of extended menu
items.  If you instead want to create a new Lisp
construct to achieve such filtering for non-menu
uses, great - that would take care of this lack in
a different, equally (maybe even more) acceptable
way.

Just ignoring this isn't TRT.  I, for one, would
like to know what the case really is wrt the
display engine problem when you use an extended
menu item without a menu.