bug#14257: 24.3.50; (elisp) `Modifying Menus' - clarify second example

bug#14257: 24.3.50; (elisp) `Modifying Menus' - clarify second example

[Drew Adams]

It might help if some motivation were given for the second example:
 
 (define-key-after
   (lookup-key shell-mode-map [menu-bar signals])
   [work] '("Work" . work-command) 'break)
 
My guess is that that example was added to tell users how to deal with
the error that used to be raised if you used something like this:
 
 (define-key-after minibuffer-local-completion-map
   [menu-bar minibuf foo]
   '(menu-item "Foo" foo) 'quit)
 
Instead of this:
 
 (define-key-after (lookup-key minibuffer-local-completion-map
                               [menu-bar minibuf])
   [foo]
   '(menu-item "Foo" foo) 'quit)
 
That error is no longer raised.  And the doc string has been updated to
no longer say this:
 
 "KEY must contain just one event type--that is to say, it must be a
  string or vector of length 1."
 
If the example still has a purpose (some other purpose), then consider
mentioning it.
 
And it would at least help to mention that the `lookup-key' sexp in the
example returns a keymap, not a key.  Without knowing that, the second
example would not make much sense (hence, some readers will guess it,
but it would still help to mention it).
 
 
 

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-04-17 on ODIEONE
Bzr revision: 112320 monnier@iro.umontreal.ca-20130418001233-g6wsqi5bpq2hsd0k
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

bug#14257: 24.3.50; (elisp) `Modifying Menus' - clarify second example

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> It might help if some motivation were given for the second example:
>
>  (define-key-after
>    (lookup-key shell-mode-map [menu-bar signals])
>    [work] '("Work" . work-command) 'break)
>
> My guess is that that example was added to tell users how to deal with
> the error that used to be raised if you used something like this:
>
>  (define-key-after minibuffer-local-completion-map
>    [menu-bar minibuf foo]
>    '(menu-item "Foo" foo) 'quit)
>
> Instead of this:
>
>  (define-key-after (lookup-key minibuffer-local-completion-map
>                                [menu-bar minibuf])
>    [foo]
>    '(menu-item "Foo" foo) 'quit)
>
> That error is no longer raised.

I've now altered the second example to be more like the first example in
Emacs 28.  It's perhaps useful to illustrate the other syntax, too, but
the first syntax is to be encouraged, I guess.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no