Mercurial > emacs

--- a/lispref/os.texi	Mon Jul 31 18:41:58 2006 +0000
+++ b/lispref/os.texi	Mon Jul 31 18:42:37 2006 +0000
@@ -28,8 +28,8 @@
 * Processor Run Time::  Getting the run time used by Emacs.
 * Time Calculations::   Adding, subtracting, comparing times, etc.
 * Timers::		Setting a timer to call a function at a certain time.
-* Terminal Input::      Recording terminal input for debugging.
-* Terminal Output::     Recording terminal output for debugging.
+* Terminal Input::      Accessing and recording terminal input.
+* Terminal Output::     Controlling and recording terminal output.
 * Sound Output::        Playing sounds on the computer's speaker.
 * X11 Keysyms::         Operating on key symbols for X Windows
 * Batch Mode::          Running Emacs without terminal interaction.
@@ -1521,8 +1521,6 @@

 @menu
 * Input Modes::		Options for how input is processed.
-* Translating Input::   Low level conversion of some characters or events
-			  into others.
 * Recording Input::	Saving histories of recent or all input events.
 @end menu

@@ -1587,204 +1585,6 @@
 @end table
 @end defun

-@node Translating Input
-@subsection Translating Input Events
-@cindex translating input events
-
-  This section describes features for translating input events into
-other input events before they become part of key sequences.  These
-features apply to each event in the order they are described here: each
-event is first modified according to @code{extra-keyboard-modifiers},
-then translated through @code{keyboard-translate-table} (if applicable),
-and finally decoded with the specified keyboard coding system.  If it is
-being read as part of a key sequence, it is then added to the sequence
-being read; then subsequences containing it are checked first with
-@code{function-key-map} and then with @code{key-translation-map}.
-
-@c Emacs 19 feature
-@defvar extra-keyboard-modifiers
-This variable lets Lisp programs ``press'' the modifier keys on the
-keyboard.  The value is a character.  Only the modifiers of the
-character matter.  Each time the user types a keyboard key, it is
-altered as if those modifier keys were held down.  For instance, if
-you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
-keyboard input characters typed during the scope of the binding will
-have the control and meta modifiers applied to them.  The character
-@code{?\C-@@}, equivalent to the integer 0, does not count as a control
-character for this purpose, but as a character with no modifiers.
-Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
-modification.
-
-When using a window system, the program can ``press'' any of the
-modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
-keys can be virtually pressed.
-
-Note that this variable applies only to events that really come from
-the keyboard, and has no effect on mouse events or any other events.
-@end defvar
-
-@defvar keyboard-translate-table
-This variable is the translate table for keyboard characters.  It lets
-you reshuffle the keys on the keyboard without changing any command
-bindings.  Its value is normally a char-table, or else @code{nil}.
-(It can also be a string or vector, but this is considered obsolete.)
-
-If @code{keyboard-translate-table} is a char-table
-(@pxref{Char-Tables}), then each character read from the keyboard is
-looked up in this char-table.  If the value found there is
-non-@code{nil}, then it is used instead of the actual input character.
-
-Note that this translation is the first thing that happens to a
-character after it is read from the terminal.  Record-keeping features
-such as @code{recent-keys} and dribble files record the characters after
-translation.
-
-Note also that this translation is done before the characters are
-supplied to input methods (@pxref{Input Methods}).  Use
-@code{translation-table-for-input} (@pxref{Translation of Characters}),
-if you want to translate characters after input methods operate.
-@end defvar
-
-@defun keyboard-translate from to
-This function modifies @code{keyboard-translate-table} to translate
-character code @var{from} into character code @var{to}.  It creates
-the keyboard translate table if necessary.
-@end defun
-
-  Here's an example of using the @code{keyboard-translate-table} to
-make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
-operations:
-
-@example
-(keyboard-translate ?\C-x 'control-x)
-(keyboard-translate ?\C-c 'control-c)
-(keyboard-translate ?\C-v 'control-v)
-(global-set-key [control-x] 'kill-region)
-(global-set-key [control-c] 'kill-ring-save)
-(global-set-key [control-v] 'yank)
-@end example
-
-@noindent
-On a graphical terminal that supports extended @acronym{ASCII} input,
-you can still get the standard Emacs meanings of one of those
-characters by typing it with the shift key.  That makes it a different
-character as far as keyboard translation is concerned, but it has the
-same usual meaning.
-
-  The remaining translation features translate subsequences of key
-sequences being read.  They are implemented in @code{read-key-sequence}
-and have no effect on input read with @code{read-event}.
-
-@defvar 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
-@var{v}, 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 @kbd{@key{ESC} 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'' @kbd{@key{ESC} O P} to @code{[pf1]} in
-@code{function-key-map}, when using a VT100.
-
-Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
-@key{ESC} O P}; later the function @code{read-key-sequence} translates
-this back into @kbd{C-c @key{PF1}}, which it returns as the vector
-@code{[?\C-c 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}.
-@end defvar
-
-@defvar 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
-@code{function-key-map} in two ways:
-
-@itemize @bullet
-@item
-@code{key-translation-map} goes to work after @code{function-key-map} is
-finished; it receives the results of translation by
-@code{function-key-map}.
-
-@item
-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
-@code{key-translation-map}, that translation takes effect even though
-@kbd{C-x f} also has a key binding in the global map.
-@end itemize
-
-Note however that actual key bindings can have an effect on
-@code{key-translation-map}, 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}.
-@end defvar
-
-@cindex 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:
-
-@example
-@group
-(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))))
-@end group
-@group
-    (if (symbolp e)
-        symbol
-      (cons symbol (cdr e)))))
-
-(define-key function-key-map "\C-ch" 'hyperify)
-@end group
-@end example
-
-Finally, if you have enabled keyboard character set decoding using
-@code{set-keyboard-coding-system}, decoding is done after the
-translations listed above.  @xref{Terminal I/O Encoding}.  In future
-Emacs versions, character set decoding may be done before the other
-translations.
-
 @node Recording Input
 @subsection Recording Input