[Emacs-diffs] Changes to emacs/lispref/keymaps.texi,v

[Richard M. Stallman]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Richard M. Stallman <rms>       06/07/31 18:37:18

Index: keymaps.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/keymaps.texi,v
retrieving revision 1.82
retrieving revision 1.83
diff -u -b -r1.82 -r1.83
--- keymaps.texi        18 Jul 2006 00:02:35 -0000      1.82
+++ keymaps.texi        31 Jul 2006 18:37:18 -0000      1.83
@@ -33,6 +33,7 @@
 * Functions for Key Lookup::    How to request key lookup.
 * Changing Key Bindings::       Redefining a key in a keymap.
 * Remapping Commands::          Bindings that translate one command to another.
+* Translation Keymaps::         Keymaps for translating sequences of events.
 * Key Binding Commands::        Interactive interfaces for redefining keys.
 * Scanning Keymaps::            Looking through all keymaps, for printing help.
 * Menu Keymaps::               Defining a menu as a keymap.
@@ -642,7 +643,7 @@
 and exit commands.  @xref{Intro to Minibuffers}.
 
   Emacs has other keymaps that are used in a different way---translating
-events within @code{read-key-sequence}.  @xref{Translating Input}.
+events within @code{read-key-sequence}.  @xref{Translation Keymaps}.
 
   @xref{Standard Keymaps}, for a list of standard keymaps.
 
@@ -682,7 +683,7 @@
 @node Searching Keymaps
 @section Searching the Active Keymaps
 
-  After translation of the input events (@pxref{Translating Input})
+  After translation of event subsequences (@pxref{Translation Keymaps})
 Emacs looks for them in the active keymaps.  Here is a pseudo-Lisp
 description of the order in which the active keymaps are searched:
 
@@ -1472,6 +1473,125 @@
 @code{nil}.
 @end defun
 
address@hidden Translation Keymaps
address@hidden Keymaps for Translating Sequences of Events
+
+  This section describes keymaps that are used during reading a key
+sequence, to translate certain event sequences into others.
address@hidden checks every subsequence of the key sequence
+being read, as it is read, against @code{function-key-map} and then
+against @code{key-translation-map}.
+
address@hidden function-key-map
+This variable holds a keymap that describes the character sequences sent
+by function keys on an ordinary character terminal.  This keymap has the
+same structure as other keymaps, but is used differently: it specifies
+translations to make while reading key sequences, rather than bindings
+for key sequences.
+
+If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
address@hidden, then when @var{k} appears as a subsequence @emph{anywhere} in a
+key sequence, it is replaced with the events in @var{v}.
+
+For example, VT100 terminals send @address@hidden O P} when the
+keypad @key{PF1} key is pressed.  Therefore, we want Emacs to translate
+that sequence of events into the single event @code{pf1}.  We accomplish
+this by ``binding'' @address@hidden O P} to @code{[pf1]} in
address@hidden, when using a VT100.
+
+Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
address@hidden O P}; later the function @code{read-key-sequence} translates
+this back into @kbd{C-c @key{PF1}}, which it returns as the vector
address@hidden pf1]}.
+
+Entries in @code{function-key-map} are ignored if they conflict with
+bindings made in the minor mode, local, or global keymaps.  The intent
+is that the character sequences that function keys send should not have
+command bindings in their own right---but if they do, the ordinary
+bindings take priority.
+
+The value of @code{function-key-map} is usually set up automatically
+according to the terminal's Terminfo or Termcap entry, but sometimes
+those need help from terminal-specific Lisp files.  Emacs comes with
+terminal-specific files for many common terminals; their main purpose is
+to make entries in @code{function-key-map} beyond those that can be
+deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
address@hidden defvar
+
address@hidden key-translation-map
+This variable is another keymap used just like @code{function-key-map}
+to translate input events into other events.  It differs from
address@hidden in two ways:
+
address@hidden @bullet
address@hidden
address@hidden goes to work after @code{function-key-map} is
+finished; it receives the results of translation by
address@hidden
+
address@hidden
+Non-prefix bindings in @code{key-translation-map} override actual key
+bindings.  For example, if @kbd{C-x f} has a non-prefix binding in
address@hidden, that translation takes effect even though
address@hidden f} also has a key binding in the global map.
address@hidden itemize
+
+Note however that actual key bindings can have an effect on
address@hidden, even though they are overridden by it.
+Indeed, actual key bindings override @code{function-key-map} and thus
+may alter the key sequence that @code{key-translation-map} receives.
+Clearly, it is better to avoid this type of situation.
+
+The intent of @code{key-translation-map} is for users to map one
+character set to another, including ordinary characters normally bound
+to @code{self-insert-command}.
address@hidden defvar
+
address@hidden key translation function
+You can use @code{function-key-map} or @code{key-translation-map} for
+more than simple aliases, by using a function, instead of a key
+sequence, as the ``translation'' of a key.  Then this function is called
+to compute the translation of that key.
+
+The key translation function receives one argument, which is the prompt
+that was specified in @code{read-key-sequence}---or @code{nil} if the
+key sequence is being read by the editor command loop.  In most cases
+you can ignore the prompt value.
+
+If the function reads input itself, it can have the effect of altering
+the event that follows.  For example, here's how to define @kbd{C-c h}
+to turn the character that follows into a Hyper character:
+
address@hidden
address@hidden
+(defun hyperify (prompt)
+  (let ((e (read-event)))
+    (vector (if (numberp e)
+                (logior (lsh 1 24) e)
+              (if (memq 'hyper (event-modifiers e))
+                  e
+                (add-event-modifier "H-" e))))))
+
+(defun add-event-modifier (string e)
+  (let ((symbol (if (symbolp e) e (car e))))
+    (setq symbol (intern (concat string
+                                 (symbol-name symbol))))
address@hidden group
address@hidden
+    (if (symbolp e)
+        symbol
+      (cons symbol (cdr e)))))
+
+(define-key function-key-map "\C-ch" 'hyperify)
address@hidden group
address@hidden example
+
+  If you have enabled keyboard character set decoding using
address@hidden, decoding is done after the
+translations listed above.  @xref{Terminal I/O Encoding}.  However, in
+future Emacs versions, character set decoding may be done at an
+earlier stage.
+
 @node Key Binding Commands
 @section Commands for Binding Keys