1 files changed, 94 insertions, 4 deletions

diff --git a/lispref/commands.texi b/lispref/commands.texi
index 10cd97400f8..514b55205a1 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -1087,7 +1087,7 @@ Lisp programs by representing the former as the integer 9, and the
 latter as the symbol @code{tab}.
 
 Most of the time, it's not useful to distinguish the two.  So normally
-@code{function-key-map} (@pxref{Translating Input}) is set up to map
+@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map
 @code{tab} into 9.  Thus, a key binding for character code 9 (the
 character @kbd{C-i}) also applies to @code{tab}.  Likewise for the other
 symbols in this group.  The function @code{read-char} likewise converts
@@ -2051,14 +2051,14 @@ functions for event input are also available for use in Lisp programs.
 See also @code{momentary-string-display} in @ref{Temporary Displays},
 and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input}, for
 functions and variables for controlling terminal input modes and
-debugging terminal input.  @xref{Translating Input}, for features you
-can use for translating or modifying input events while reading them.
+debugging terminal input.
 
   For higher-level input facilities, see @ref{Minibuffers}.
 
 @menu
 * Key Sequence Input::          How to read one key sequence.
 * Reading One Event::           How to read just one event.
+* Event Mod::                   How Emacs modifies events as they are read.
 * Invoking the Input Method::   How reading an event uses the input method.
 * Quoted Character Input::      Asking the user to specify a character.
 * Event Input Misc::            How to reread or throw away input events.
@@ -2088,7 +2088,7 @@ events---characters, symbols, and lists.  The elements of the string or
 vector are the events in the key sequence.
 
 Reading a key sequence includes translating the events in various
-ways.  @xref{Translating Input}.
+ways.  @xref{Translation Keymaps}.
 
 The argument @var{prompt} is either a string to be displayed in the
 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
@@ -2229,6 +2229,15 @@ number of seconds; on these systems, @var{seconds} is rounded down.
 If @var{seconds} is @code{nil}, @code{read-event} waits as long as
 necessary for input to arrive.
 
+If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
+for user input to arrive.  Idle timers---those created with
+@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
+period.  However, if @var{seconds} is non-@code{nil}, the state of
+idleness remains unchanged.  If Emacs is non-idle when
+@code{read-event} is called, it remains non-idle throughout the
+operation of @code{read-event}; if Emacs is idle (which can happen if
+the call happens inside an idle timer), it remains idle.
+
 If @code{read-event} gets an event that is defined as a help character,
 then in some cases @code{read-event} processes the event directly without
 returning.  @xref{Help Functions}.  Certain other events, called
@@ -2290,6 +2299,87 @@ This variable holds the total number of input events received so far
 from the terminal---not counting those generated by keyboard macros.
 @end defvar
 
+@node Event Mod
+@subsection Modifying and Translating Input Events
+
+  Emacs modifies every event it reads according to
+@code{extra-keyboard-modifiers}, then translates it through
+@code{keyboard-translate-table} (if applicable), before returning it
+from @code{read-event}.
+
+@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.
+
+  @xref{Translation Keymaps}, for mechanisms that translate event sequences
+at the level of @code{read-key-sequence}.
+
 @node Invoking the Input Method
 @subsection Invoking the Input Method