bug#8951: 24.0.50; [PATCH] enhancement request: buttonize key names

[Drew Adams]

Sent to emacs-devel@gnu.org 2011/06/27:
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg01081.html
 
Submitting as enhancement request.  Patch attached.
 
Here is another patch for Emacs help functions.  It handles
`describe-mode', `describe-function', and `describe-variable',
and the same feature it provides can be applied to other help
commands where appropriate.
 
What is the feature?  Let users click a key description (i.e., a
key name, such as `C-f') in a buffer such as *Help* to see the
associated help.  This applies to key descriptions derived from
\[...] doc patterns (only).
 
`substitute-command-keys' converts a doc string that uses
patterns such as `\[COMMAND]' to COMMAND's key description.
For example, it might convert `\[mouse-yank-secondary]' to
`<M-mouse-2>'.  It interprets COMMAND's bindings relative to a
given KEYMAP if that `\[...]' pattern is preceded by a
`\<KEYMAP>' pattern.
 
Once this conversion is done, however, the COMMAND and its KEYMAP
are lost, missing from the resulting doc string.  More
importantly, this information is lost to the code that uses the
conversion result - the code for `describe-variable' etc.
 
(Yes, the original string might be available to the calling code,
but that code would need to parse it to figure out the
correspondence between COMMAND and resulting key description.
IOW, it would need to do much of what `substitute-command-keys'
already does.)
 
The user sees only the description `<M-mouse-2>' in buffer *Help*
where the substituted doc string is used.  What if s?he wants to
know more about what that key does in the documented context?
S?he can hit `C-h k' and then try the key, but that will work
only if the current mode has the same binding (e.g., with KEYMAP
active for COMMAND).
 
The aim of the feature provided by the attached patch is to
replace such simple key descriptions, which were derived from
rich info (COMMAND and KEYMAP) about a documented context, with
help buttons that use that info to link to descriptions of the
commands associated with the keys.
 
The feature has the effect of giving `substitute-command-keys' an
optional arg that, when non-nil, makes that function not only
substitute the key description for the command but also buttonize
the key-description part of the result string.
 
The effect is that if the result string is inserted in a buffer
(e.g. *Help*) then the user can click or hit `RET' on the key
description (e.g. `<M-mouse-2>') to get help on the associated
command (e.g. `mouse-yank-secondary').
 
Actually, I did not patch the `substitute-command-keys' C code to
give it an extra arg for this.  Instead, I wrote a Lisp version:
`help-substitute-command-keys'.  (For the part that handles
\{...}, this function just calls `substitute-command-keys'.)  If
someone wants to patch the C code instead, go for it.
 
Similarly, I wrote Lisp wrappers for `documentation' and
`documentation-property' that accept the same optional arg and
pass it to `help-substitute-command-keys'.
 
Then, in the body of commands `describe-variable' etc., I changed
`(documentation X)' to `(help-documentation nil t)' to get the
buttonized help string.
 
Give it a try.  If you decide to go for the idea then you might
prefer to just add the optional arg to `substitute-command-keys'
rather than creating a separate function.  (I didn't have that
choice as a Lisp user.)
 
However, even in that case you might decide to opt for a Lisp
version (why not?) - IOW, move `substitute-command-keys' to Lisp.
 
You can do that by renaming `substitute-command-keys' to
<something>, removing most of the <something> code, and renaming
`help-substitute-command-keys' to `substitute-command-keys'.  A
small amount of the <something> C code is still needed to handle
the \{..} case (no buttons).
 
If you want to try it without applying the patches, you can just
download this library and load it:
http://www.emacswiki.org/emacs/download/help-fns%2b.el.  (In that
case you will also see the automatic Info links discussed in
thread "adding manual cross-ref links to *Help*":
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html)
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-06-27 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/build/include'

help-2011-06-27.patch
Description: Binary data

help-fns-2011-06-27.patch
Description: Binary data