Commit 0f1d2934 authored by Chong Yidong's avatar Chong Yidong

More doc updates

* 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.
parent 9cab7521
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
......
......@@ -2395,9 +2395,12 @@ and key sequences read from keyboard macros being executed.
@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,
......
......@@ -242,11 +242,9 @@ it obtains a non-symbol. @xref{Function Names}, for more information
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
......@@ -255,12 +253,12 @@ a special form, or an autoload object. Each of these types is a case
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
......
......@@ -1001,12 +1001,12 @@ indirect-function}.
@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
......@@ -1026,10 +1026,10 @@ function.
@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,
......
......@@ -1551,32 +1551,36 @@ specifies a list of keymaps to search in. This argument is ignored if
@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
......@@ -1664,10 +1668,6 @@ to turn the character that follows into a Hyper character:
@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
......
......@@ -1807,24 +1807,23 @@ decoding, you can call this function.
@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}.
......@@ -1832,18 +1831,19 @@ 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
......
......@@ -917,10 +917,12 @@ whereas now it simply has higher precedence.
** 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'.
......@@ -930,10 +932,12 @@ to that past, it is still done before input-decode-map/function-key-map/...
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.
......@@ -7649,7 +7653,7 @@
* 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.
......
......@@ -686,7 +686,7 @@ Return SYMBOL. */)
}
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);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment