bug#14088: 24.3.50; Document <t> or replace it in `substitute-command-keys'

[Drew Adams]

emacs -Q
 
Type in *scratch*:
(substitute-command-keys "\\{isearch-mode-map}")
C-u C-x C-e
 
Search for "isearch-other-control-char".  It is shown bound to the key
C-h <t>.  This is technically correct, as <t> corresponds to
 
(define-key isearch-mode-map [t] 'isearch-other-control-char)
 
But users will not understand the notation <t>.  It is mentioned nowhere
in any Emacs manual.  And there certainly is no function key `t'.
 
If a user searches well enough and reads a bit, s?he might understand
that <t> here corresponds to this text about `define-key' in (elisp)
`Changing Key Bindings':
 
     If KEY is `[t]', this sets the default binding in KEYMAP.  When an
     event has no binding of its own, the Emacs command loop uses the
     keymap's default binding, if there is one.
 
But users cannot be expected to do all that and make the necessary
connections.
 
User-friendly output here would use a simple description in place of
<t>.  Something like "Default key binding".  But such a user-friendly
description should really be moved out of the list, putting it either
before or after the list, since this is not a single binding of a
specific key.  This is a bit like our treatment of `Prefix command', but
in reverse: in this case it is the key column that needs the general
description.
 
But the case of `C-h <t>' shows that we need some descriptive text that can be
placed after a prefix key.  So perhaps instead of "Default key binding" we could
use "OTHER", making it a link to a sentence that says it stands for any key not
otherwise defined.  E.g.,

C-h OTHER

with OTHER linked to "footnote" text like this:

OTHER indicates any key not otherwise defined.

An alternative would be to have the manuals introduce <t> as meaning what we are
currently using it for.  That could be OK too, since one cannot define a
function key `t' in any case.  The manuals tell Lisp programmers what [t] means
for `define-key', but they don't tell users what <t> means as a key description.

This alternative is perhaps not as helpful for a newbie as using something like
C-h OTHER with an explanation.

But it would be useful anyway, not just as an alternative here, but for
completion of the doc.  Something like (kbd "<t>") might become less puzzling
etc.

One way or another, the current undocumented and unclear use of <t> needs to be
taken care of.
 

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-03-23 on VBOX
Bzr revision: 112115 eliz@gnu.org-20130323093300-rjs0dgskxm9u0ya4
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/emacs/libs/libXpm-3.5.10/include -IC:/emacs/libs/libXpm-3.5.10/src
 -IC:/emacs/libs/libpng-dev_1.4.3-1_win32/include
 -IC:/emacs/libs/zlib-dev_1.2.5-2_win32/include
 -IC:/emacs/libs/giflib-4.1.4-1-lib/include
 -IC:/emacs/libs/jpeg-6b-4-lib/include
 -IC:/emacs/libs/tiff-3.8.2-1-lib/include
 -IC:/emacs/libs/libxml2-2.7.8-w32-bin/include/libxml2
 -IC:/emacs/libs/gnutls-3.1.10-w32/include
 -IC:/emacs/libs/libiconv-1.14-2-mingw32-dev/include'