improving describe-mode

[John S. Yates, Jr.]

I originally posted an earlier version of this message to
comp.emacs.  Eli Zaretskii suggested this list would be a
more appropriate forum.

-----

I have regularly been frustrated by the clash between my
ability to add key bindings to modes and the static nature
of the text displayed by describe-mode.  Some while ago I
snagged this fragment from the net:

(defun keymap-test (var)         ; internal function for keymap checking
  (and (boundp var)
       (keymapp (symbol-value var))))

(defun keymap-describe-map (map) ; display map binding
  "Display binding for MAP which must be a quoted keymap variable"
  (interactive     ; ***
   (list (intern (completing-read "Key map: " obarray 'keymap-test 1))))
  (let ((val (symbol-value map)))
    (or (keymapp val)
        (error "%s is not a keymap !" (symbol-name map)))
    (with-output-to-temp-buffer "*Help*"
      (princ (format "Binding for keymap %s is:\n" (symbol-name map)))
      (princ (substitute-command-keys "\\{val}" ))
      (print-help-return-message))))

The output from this function is sub-optimal since it often
displays obvious bindings for ESC, 10 decimal digits, etc.
OTOH it has the virtue of being complete and accurate.

I am neither an emacs architect nor even much of a lisp coder.
But I would love it if instead of packages coming with canned
text purporting to be that mode's key bindings we could evolve
towards a scheme in which the describe-mode text included a
cookie that signified "render keymap X here".  Ideally there
would be some ability to suppress certain bindings, sort and
group appropriately, etc.

/john

--
John Yates
40 Pine Street
Needham, MA 02492
781 444-2899