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

[Drew Adams]

> > > >  "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."
> 
> If this is never placed on the menu bar or on any pop-down menu, then
> what the manual says is not relevant, because redisplay only considers
> the menus that need to be displayed.

1. The manual's description of :filter is entirely
relevant to this use case - _except_ for that last
paragraph, which apparently erroneously assumes that
the only possible use of an extended menu item with
:filter is in a menu.

Extended menu items are not just for menus (in spite
of the name).

2. What you've added here is what needs to be added
there: a qualification to that caveat, that _when
used in a menu_, "Emacs can call ... redisplay ...
You should write it so it can safely be called at
any time".

3. And because this use case is important and not
at all obvious, the doc there should explicitly
point out this use case.

   a. You can bind an extended menu item that uses
      :filter to a keyboard key, to give it a
      dynamic binding (explaining what that means
      with an example).

   b. If the only bindings for that extended menu
      item are keyboard bindings then the admonition
      about redisplay (see #2) does not apply.
      Don't assume that readers will understand
      that if not placed on a menu then it doesn't
      apply.  The admonition is currently too
      blanket.

Wrt #3: An example for this use case should be
presented somewhere in the Elisp manual.  If you
can think of a better place than in the description
of :filter, fine.  If not, then that's the place.

4. As I said in the bug report, having to use an
extended menu item for this feature is a hack or
workaround.  There's no other possibility out of
the box.

Better than just documenting that you can use an
extended menu item with :filter to get this behavior
would be to provide the behavior in another way.
IOW, ideally it wouldn't be "hidden" under the
misleading notion of a menu.  :filter itself is not
about menus.

More generally, `menu-item' is not just about menus
and menu items.  This is not obvious.  And in
particular, it's not obvious that you can make good
use of :filter with a keyboard key.