* commands.texi (Reading One Event): Mention keyboard coding.
* functions.texi (Function Cells):
* eval.texi (Function Indirection): Update for the fact that
symbol-function no longer signals an error.
* keymaps.texi (Translation Keymaps, Translation Keymaps):
* nonascii.texi (Terminal I/O Encoding): Copyedits.
* data.c (Fsymbol_function): Doc fix.
+2013-12-27 Chong Yidong <cyd@gnu.org>
+
+ * functions.texi (Function Cells):
+ * eval.texi (Function Indirection): Update for the fact that
+ symbol-function no longer signals an error.
+
+ * commands.texi (Reading One Event): Mention keyboard coding.
+
+ * keymaps.texi (Translation Keymaps, Translation Keymaps):
+ * nonascii.texi (Terminal I/O Encoding): Copyedits.
+
2013-12-26 Chong Yidong <cyd@gnu.org>
* advice.texi (Advising Functions, Defining Advice): Special forms
@code{read-char}, and @code{read-char-exclusive}.
@defun read-event &optional prompt inherit-input-method seconds
-This function reads and returns the next event of command input, waiting
-if necessary until an event is available. Events can come directly from
-the user or from a keyboard macro.
+This function reads and returns the next event of command input,
+waiting if necessary until an event is available.
+
+The returned event may come directly from the user, or from a keyboard
+macro. It is not decoded by the keyboard's input coding system
+(@pxref{Terminal I/O Encoding}).
If the optional argument @var{prompt} is non-@code{nil}, it should be a
string to display in the echo area as a prompt. Otherwise,
about symbol function indirection.
One possible consequence of this process is an infinite loop, in the
-event that a symbol's function cell refers to the same symbol. Or a
-symbol may have a void function cell, in which case the subroutine
-@code{symbol-function} signals a @code{void-function} error. But if
-neither of these things happens, we eventually obtain a non-symbol,
-which ought to be a function or other suitable object.
+event that a symbol's function cell refers to the same symbol.
+Otherwise, we eventually obtain a non-symbol, which ought to be a
+function or other suitable object.
@kindex invalid-function
More precisely, we should now have a Lisp function (a lambda
described in one of the following sections. If the object is not one
of these types, Emacs signals an @code{invalid-function} error.
- The following example illustrates the symbol indirection process. We
-use @code{fset} to set the function cell of a symbol and
+ The following example illustrates the symbol indirection process.
+We use @code{fset} to set the function cell of a symbol and
@code{symbol-function} to get the function cell contents
-(@pxref{Function Cells}). Specifically, we store the symbol @code{car}
-into the function cell of @code{first}, and the symbol @code{first} into
-the function cell of @code{erste}.
+(@pxref{Function Cells}). Specifically, we store the symbol
+@code{car} into the function cell of @code{first}, and the symbol
+@code{first} into the function cell of @code{erste}.
@example
@group
@defun symbol-function symbol
@kindex void-function
-This returns the object in the function cell of @var{symbol}. If the
-symbol's function cell is void, a @code{void-function} error is
-signaled.
+This returns the object in the function cell of @var{symbol}. It does
+not check that the returned object is a legitimate function.
-This function does not check that the returned object is a legitimate
-function.
+If the function cell is void, the return value is @code{nil}. To
+distinguish between a function cell that is void and one set to
+@code{nil}, use @code{fboundp} (see below).
@example
@group
@end defun
@cindex void function cell
- If you have never given a symbol any function definition, we say that
-that symbol's function cell is @dfn{void}. In other words, the function
-cell does not have any Lisp object in it. If you try to call such a symbol
-as a function, it signals a @code{void-function} error.
+ If you have never given a symbol any function definition, we say
+that that symbol's function cell is @dfn{void}. In other words, the
+function cell does not have any Lisp object in it. If you try to call
+the symbol as a function, Emacs signals a @code{void-function} error.
Note that void is not the same as @code{nil} or the symbol
@code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
@node Translation Keymaps
@section Keymaps for Translating Sequences of Events
+@cindex translation keymap
@cindex keymaps for translating events
- This section describes keymaps that are used during reading a key
-sequence, to translate certain event sequences into others.
-@code{read-key-sequence} checks every subsequence of the key sequence
-being read, as it is read, against @code{input-decode-map}, then
-@code{local-function-key-map}, and then against @code{key-translation-map}.
-
-These keymaps have the same structure as other keymaps, but they are used
-differently: they specify translations to make while reading key sequences,
-rather than bindings for key sequences.
-
-If one of these keymaps ``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{input-decode-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]}.
+ When the @code{read-key-sequence} function reads a key sequence
+(@pxref{Key Sequence Input}), it uses @dfn{translation keymaps} to
+translate certain event sequences into others. The translation
+keymaps are @code{input-decode-map}, @code{local-function-key-map},
+and @code{key-translation-map} (in order of priority).
+
+ Translation keymaps have the same structure as other keymaps, but
+are used differently: they specify translations to make while reading
+key sequences, rather than bindings for complete key sequences. As
+each key sequence is read, it is checked against each translation
+keymap. If one of the translation keymaps ``binds'' @var{k} to a
+vector @var{v}, then whenever @var{k} appears as a sub-sequence
+@emph{anywhere} in a key sequence, that sub-sequence is replaced with
+the events in @var{v}.
+
+ For example, VT100 terminals send @kbd{@key{ESC} O P} when the
+keypad key @key{PF1} is pressed. On such terminals, Emacs must
+translate that sequence of events into a single event @code{pf1}.
+This is done by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
+@code{input-decode-map}. Thus, when you type @kbd{C-c @key{PF1}} on
+the terminal, the terminal emits the character sequence @kbd{C-c
+@key{ESC} O P}, and @code{read-key-sequence} translates this back into
+@kbd{C-c @key{PF1}} and returns it as the vector @code{[?\C-c pf1]}.
+
+ Translation keymaps take effect only after Emacs has decoded the
+keyboard input (via the input coding system specified by
+@code{keyboard-coding-system}). @xref{Terminal I/O Encoding}.
@defvar input-decode-map
This variable holds a keymap that describes the character sequences sent
@end group
@end example
- If you have enabled keyboard character set decoding using
-@code{set-keyboard-coding-system}, decoding is done before the
-translations listed above. @xref{Terminal I/O Encoding}.
-
@subsection Interaction with normal keymaps
The end of a key sequence is detected when that key sequence either is bound
@node Terminal I/O Encoding
@subsection Terminal I/O Encoding
- Emacs can decode keyboard input using a coding system, and encode
+ Emacs can use coding systems to decode keyboard input and encode
terminal output. This is useful for terminals that transmit or
-display text using a particular encoding such as Latin-1. Emacs does
-not set @code{last-coding-system-used} for encoding or decoding of
+display text using a particular encoding, such as Latin-1. Emacs does
+not set @code{last-coding-system-used} when encoding or decoding
terminal I/O.
@defun keyboard-coding-system &optional terminal
-This function returns the coding system that is in use for decoding
-keyboard input from @var{terminal}---or @code{nil} if no coding system
-is to be used for that terminal. If @var{terminal} is omitted or
-@code{nil}, it means the selected frame's terminal. @xref{Multiple
-Terminals}.
+This function returns the coding system used for decoding keyboard
+input from @var{terminal}. A value of @code{no-conversion} means no
+decoding is done. If @var{terminal} is omitted or @code{nil}, it
+means the selected frame's terminal. @xref{Multiple Terminals}.
@end defun
@deffn Command set-keyboard-coding-system coding-system &optional terminal
This command specifies @var{coding-system} as the coding system to use
for decoding keyboard input from @var{terminal}. If
-@var{coding-system} is @code{nil}, that means do not decode keyboard
+@var{coding-system} is @code{nil}, that means not to decode keyboard
input. If @var{terminal} is a frame, it means that frame's terminal;
if it is @code{nil}, that means the currently selected frame's
terminal. @xref{Multiple Terminals}.
@defun terminal-coding-system &optional terminal
This function returns the coding system that is in use for encoding
-terminal output from @var{terminal}---or @code{nil} if the output is
-not encoded. If @var{terminal} is a frame, it means that frame's
-terminal; if it is @code{nil}, that means the currently selected
-frame's terminal.
+terminal output from @var{terminal}. A value of @code{no-conversion}
+means no encoding is done. If @var{terminal} is a frame, it means
+that frame's terminal; if it is @code{nil}, that means the currently
+selected frame's terminal.
@end defun
@deffn Command set-terminal-coding-system coding-system &optional terminal
This command specifies @var{coding-system} as the coding system to use
for encoding terminal output from @var{terminal}. If
-@var{coding-system} is @code{nil}, terminal output is not encoded. If
-@var{terminal} is a frame, it means that frame's terminal; if it is
-@code{nil}, that means the currently selected frame's terminal.
+@var{coding-system} is @code{nil}, that means not to encode terminal
+output. If @var{terminal} is a frame, it means that frame's terminal;
+if it is @code{nil}, that means the currently selected frame's
+terminal.
@end deffn
@node Input Methods
** Default process filters and sentinels are not nil any more.
Instead they default to a function which does what the nil value used to do.
++++
** `read-event' does not return decoded chars in ttys any more.
-Just as was the case in Emacs-22 and before, decoding of tty input according to
-keyboard-coding-system is not performed in read-event any more. But contrary
-to that past, it is still done before input-decode-map/function-key-map/...
+As was the case in Emacs 22 and before, the decoding of terminal
+input, according to `keyboard-coding-system', is not performed in
+`read-event' any more. But unlike in Emacs 22, this decoding is still
+done before input-decode-map, function-key-map, etc.
---
** Removed `inhibit-local-menu-bar-menus'.
More specifically, the redisplay does not bother to check for a frame-local
value when looking up variables.
++++
** nil and "unbound" are indistinguishable in `symbol-function'.
-`symbol-function' never signals `void-function' any more.
-`fboundp' returns non-nil if the symbol was `fset' to nil.
+`symbol-function' does not signal a `void-function' error any more.
+To determine if a symbol's function definition is void, use `fboundp'.
++++
** `defadvice' does not honor the `freeze' flag and cannot advise
special-forms any more.
+2013-12-27 Chong Yidong <cyd@gnu.org>
+
+ * data.c (Fsymbol_function): Doc fix.
+
2013-12-26 Martin Rudalics <rudalics@gmx.at>
Some more tinkering with Bug#16051.
* keyboard.c: Apply keyboard decoding only to events that come directly
from the tty, not from unread-command-events (bug#14368).
- (read_event_from_main_queue): New function, extracted from read_char).
+ (read_event_from_main_queue): New function, extracted from read_char.
(read_decoded_char): Remove.
(read_decoded_event_from_main_queue): New function to replace it.
(read_char): Use it.
}
DEFUN ("symbol-function", Fsymbol_function, Ssymbol_function, 1, 1, 0,
- doc: /* Return SYMBOL's function definition. Error if that is void. */)
+ doc: /* Return SYMBOL's function definition, or nil if that is void. */)
(register Lisp_Object symbol)
{
CHECK_SYMBOL (symbol);