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 _______________________________________________ emacs-pretest-bug mailing list [email protected] http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
