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.

doc/lispref/ChangeLog

@@ -1,3 +1,14 @@
+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

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,

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

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,

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}.
+  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).
 
-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.
+  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}.
 
-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 @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]}.
 
-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]}.
+  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

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

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.
 

src/ChangeLog

@@ -1,3 +1,7 @@
+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.

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);