From: Chong Yidong Date: Fri, 27 Dec 2013 03:38:26 +0000 (+0800) Subject: More doc updates X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~173 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0f1d29342f29e666bb6abe4073a30b425a63d26c;p=emacs.git 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. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 2956b907d77..c4fdfb18a9b 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2013-12-27 Chong Yidong + + * 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 * advice.texi (Advising Functions, Defining Advice): Special forms diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index a9322640880..95cad5c4666 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -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, diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 4a63ec2add1..a321bfce6f7 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -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 diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index f1d8c54f49c..b15d4ac1457 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -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, diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index c5ffbc964cc..b9d9aa6ec72 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -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 diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 7b499159d93..7763f5c788d 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -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 diff --git a/etc/NEWS b/etc/NEWS index 79004d091f1..a9fd1eac038 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -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. diff --git a/src/ChangeLog b/src/ChangeLog index 053a498392c..4e8c9a10223 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +2013-12-27 Chong Yidong + + * data.c (Fsymbol_function): Doc fix. + 2013-12-26 Martin Rudalics 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. diff --git a/src/data.c b/src/data.c index 1fe7a1c9b65..fecf9700ff2 100644 --- a/src/data.c +++ b/src/data.c @@ -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);