Elisp manual, nodes Format of Keymaps, Defining Menus etc.

[Drew Adams]

There are a few complex structures used in Emacs Lisp.  A keymap
is one (a face is another). It is important to describe such
structures completely and clearly, especially since they are not
treated as abstract data types, with accessor functions etc.  A
programmer must know the concrete structure well to be able to
use things like keymaps and faces, so s?he relies on the doc to
explain it well. In the case of keymaps, at least, I think the
doc could be improved.

1. Node Format of Keymaps - A format is not explained well
enough, if each of the terms used to depict it is not explained.
In particular, the format of BINDING is not described here, and I
see no cross reference that leads to its description (the way,
for instance, the cross reference to node Classifying Events will
help you understand the format of TYPE in (TYPE . BINDING).

Please describe the "keymap element" better, and please give a
general example, in particular, one which includes a menu keymap
element.

2. I think we need a term for a key-binding pair: (KEY
. BINDING).  The doc uses the term "keymap element" in passing,
without introducing it in quotes, as a defined term.  However,
"keymap element" refers not only to a key-binding pair but also
to an overall prompt string.

Key-binding pairs are sometimes referred to as "bindings" - for
example, in several places in node Format of Keymaps.  That
double use of "binding" is confusing.  I've mentioned this
before, and the answer given was that whichever is meant is
always understood by the context.  I don't agree that that is
always clear, and the context of this node is a good example.  We
should distinguish between the key-binding pair and the binding
portion of the pair (the binding of the binding, in the current
terminology!), using different terms. Otherwise, it is difficult
to understand the doc.

3. Node Format of Keymaps - A format is not explained well
enough, if some of the possible terms are missing. Menu keymap
elements seem to be missing from the list here, and there is not
even a cross reference to the relevant doc (presumably node
Defining Menus etc. - but see #4).  The description of a keymap
format is not complete as a result, and this is misleading.

4. Node Defining Menus and its subnodes, and node Menu Example -
I see nowhere a format depiction of a menu or a menu keymap.
There are depictions of (some) menu items, but not a complete
menu.  Please show a menu with a submenu.  Node Menu Example
shows how to define a menu, but not the result.  Even a casual
Emacs-Lisp programmer will need to understand the format of a
menu keymap.




In GNU Emacs 22.0.50.1 (i386-msvc-nt5.1.2600)
 of 2006-07-19 on BOS-CTHEWLAP2
X server distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-msvc (12.00)'

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  locale-coding-system: cp1252
  default-enable-multibyte-characters: t

Major mode: Dired by name

Minor modes in effect:
  encoded-kbd-mode: t
  tooltip-mode: t
  tool-bar-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  unify-8859-on-encoding-mode: t
  utf-translate-cjk-mode: t
  auto-compression-mode: t
  line-number-mode: t

Recent input:
<help-echo> <help-echo> <help-echo> <help-echo> <menu-bar>
<help-menu> <report-emacs-bug>

Recent messages:
(C:\Emacs-22-2006-07-19-Fran\bin\emacs.exe -q --no-site-file --debug-init
C:\drews-lisp-20)
Loading encoded-kb...done
For information about the GNU Project and its goals, type C-h C-p.
Loading dired...
Loading regexp-opt...done
Loading dired...done
Loading emacsbug...done