[climacs-devel] Implementation proposal for a Describe Binding command.

[Troels Henriksen]

ESA has a builtin `describe-key-briefly'-command, but, as the name
implies, this only gives a very brief description of the keybinding
(and it doesn't work for syntax-specific bindings either). I have
written a complementary command inspired by Emacs' `describe-key' (C-h
k):

(in-package :climacs-gui)

(define-command (com-describe-binding :name t
				      :command-table help-table)
    ()
  "Display documentation for the command invoked by a giving gesture sequence.
   When invoked, this command will wait for user input. If the user inputs 
   a gesture sequence bound to a command available in the syntax of the current 
   buffer, documentation and other details will be displayed. Otherwise, Climacs
   will silently wait, and the user will have to press an abort gesture to get out
   of the gesture reading loop."
  (let ((command-table (esa:find-applicable-command-table *application-frame*)))
    (multiple-value-bind (command gestures)
	(esa::read-gestures-for-help command-table)
      (let* ((gesture-name (format nil "~{~A~#[~; ~; ~]~}" (mapcar #'esa::gesture-name gestures)))
	     (stream (typeout-window
		      (format nil "~10THelp: Describe binding for ~A" gesture-name)))
	     (command-name (or (command-line-name-for-command 
				(first command)
				command-table
				:errorp nil)
			       (first command))))
	(princ "The gesture " stream)
	(with-text-face (stream :italic)
			(princ gesture-name stream))
	(format stream " is bound to the ~:[command~;function~] " (symbolp command-name))
	(with-text-face (stream :italic) 
			(princ command-name stream))
	(format stream " in ~A.~%" (command-table-name command-table))
	(terpri stream)
	(format stream "~:[Not documented.~;~:*~A~]" (documentation command 'function))))))

(set-key 'com-describe-binding
	 'help-table 
	 '((#\h :control) (#\k)))

This command understands syntax-specific keybindings and displays
documentation for the given command as well (this is the reason for
the rather verbose docstring, I had to test the command on something).

I use two internal ESA symbols, though, `esa::read-gestures-for-help'
and `esa::gesture-name' - why are these internal? They seem like
functions that would be useful for most ESA-derived applications,
their interface is simple and they do not expose any internal ESA
details AFAICS. 

This command will only work in Climacs due to the use of a typeout
pane, but I think it should somehow be ported to pure ESA, as it is,
in my opinion, a necessary part of any Emacs-like application.

Finally, if this command is added to Climacs, we'll have new incentive
to add docstrings to the public commands. :-)
-- 
\  Troels "Athas" Henriksen
/\ - Insert witty signature