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

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

> >  "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."
> 
> That doesn't explain anything to me, sorry.

Sorry.  Does an example help?

(global-set-key
 "\C-o" 
 '`(menu-item
   "" forward-char
   :filter (lambda (cmd)
             (if (integerp prefix-arg) nil cmd))))

Stefan (cc'd), in particular, mentions this case
from time to time.  Here are some examples from him:

In emacs-devel thread "Proposed patch for lookup-key"
(2017-12-14):

  "bindings which are made dynamically conditional
   using a :filter function"

In help-gnu-emacs thread "How to define minor-mode
keybindings conditional on buffer's major-mode?"
(2013-10-04):

 (define-key minor-mode-map
   "<<key-binding1>>"
   `(menu-item
     "" minor-mode-command
     :filter ,(lambda (cmd)
                (if (eq major-mode 'xyz-mode) cmd))))
 (define-key minor-mode-map
   "<<key-binding2>>"
   `(menu-item
     "" minor-mode-command
     :filter ,(lambda (cmd)
                (if (not (eq major-mode 'xyz-mode)) cmd))))

In help-gnu-emacs thread "Commands with more than
one keybinding in menus" (2013-08-14):

 You can use dynamic key-bindings, i.e. instead of
 binding your key to
 (lambda () (interactive) (if foo (CMD))),
 bind it to
 (menu-item "" CMD :filter (lambda (cmd) (if foo cmd))).

In help-gnu-emacs thread "Shor-circuiting keybindings"
(2010-12-09):

 You can create conditional key bindings:
  (define-key map
    [?\C-b]
    '(menu-item "dummy" <command>
      :filter (lambda (binding)
                (if <condition> binding))))
                                      
 The filter function will receive <command> as
 argument (this is so that the same filter function
 can be used for several bindings) and can opt to
 return it or not or to return anything else (so
 you can create dynamic bindings, which is
 typically used to construct dynamic menus, such as
 the Buffers menu).
 The <command> you put as the "static binding" that
 gets passed to the filter is only used in cases
 such as where-is.

In help-gnu-emacs thread "HELP: One Bindkey for Two
Different Commands" (2007-11-30):

 How 'bout some neat hack like:
  (global-set-key "\M-o"
    '(menu-item "Foo" bar
      :filter (lambda (x)
                (if (cdr (window-list))
                    'other-window
                  'switch-to-buffer))))

> > Define "menu function", please.

?  (I don't think you answered that.  If you still
want to make a point about it, maybe let me know
what you mean by it.)

> > the case being discussed: an extended menu
> > item that's bound only to a keyboard key, i.e.,
> > that's not used in any menu?
> 
> I still don't understand what that means in practice.

Do the examples above help?  It's about using the
:filter mechanism designed for menu items with a
keyboard key instead, to create a key binding
that's "dynamic", i.e., conditional at the time
you use the key.

> > > could be called whenever the display engine needs to
> > > recalculate the contents and the dimensions of the menu, and that
> > > could basically be every redisplay cycle, depending on circumstances.
> >
> > See above.  There's no menu involved in the case
> > being discussed (at least none that's visible to
> > users, AFAIK).  So there should be no need or
> > possibility of recalculating menu contents and
> > dimensions.
> 
> Then you already know the answer and don't need any help, it seems.
> But if you do, please explain more about the specific use case you
> worry about.

Please reread what I said.  I'm not _aware_ of any
actual menu being involved in the keyboard-key case.
IF none is used, then I'm GUESSING that recalculating
menu contents (what menu?) doesn't happen.

But my point is only about having the doc address
this specific use case - use of :filter when only a
keyboard binding is used.  IF that in fact doesn't
involve any menus then shouldn't that paragraph be
clarified to exclude that case in its caveat?