[Emacs-diffs] trunk r115765: More doc updates

[Chong Yidong]

------------------------------------------------------------
revno: 115765
revision-id: address@hidden
parent: address@hidden
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2013-12-27 11:38:26 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/commands.texi      
commands.texi-20091113204419-o5vbwnq5f7feedwu-6165
  doc/lispref/eval.texi          eval.texi-20091113204419-o5vbwnq5f7feedwu-6178
  doc/lispref/functions.texi     
functions.texi-20091113204419-o5vbwnq5f7feedwu-6182
  doc/lispref/keymaps.texi       
keymaps.texi-20091113204419-o5vbwnq5f7feedwu-6190
  doc/lispref/nonascii.texi      
nonascii.texi-20091113204419-o5vbwnq5f7feedwu-6202
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  src/ChangeLog                  changelog-20091113204419-o5vbwnq5f7feedwu-1438
  src/data.c                     data.c-20091113204419-o5vbwnq5f7feedwu-251

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2013-12-26 03:27:45 +0000
+++ b/doc/lispref/ChangeLog     2013-12-27 03:38:26 +0000
@@ -1,3 +1,14 @@
+2013-12-27  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * advice.texi (Advising Functions, Defining Advice): Special forms

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2013-12-25 10:24:52 +0000
+++ b/doc/lispref/commands.texi 2013-12-27 03:38:26 +0000
@@ -2395,9 +2395,12 @@
 @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 address@hidden, it should be a
 string to display in the echo area as a prompt.  Otherwise,

=== modified file 'doc/lispref/eval.texi'
--- a/doc/lispref/eval.texi     2013-12-25 03:05:11 +0000
+++ b/doc/lispref/eval.texi     2013-12-27 03:38:26 +0000
@@ -242,11 +242,9 @@
 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
address@hidden 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 @@
 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
address@hidden into the function cell of @code{first}, and the symbol
address@hidden into the function cell of @code{erste}.
 
 @example
 @group

=== modified file 'doc/lispref/functions.texi'
--- a/doc/lispref/functions.texi        2013-09-12 12:22:17 +0000
+++ b/doc/lispref/functions.texi        2013-12-27 03:38:26 +0000
@@ -1001,12 +1001,12 @@
 
 @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
address@hidden, use @code{fboundp} (see below).
 
 @example
 @group
@@ -1026,10 +1026,10 @@
 @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,

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2013-12-25 10:24:52 +0000
+++ b/doc/lispref/keymaps.texi  2013-12-27 03:38:26 +0000
@@ -1551,32 +1551,36 @@
 
 @node Translation Keymaps
 @section Keymaps for Translating Sequences of Events
address@hidden 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.
address@hidden checks every subsequence of the key sequence
-being read, as it is read, against @code{input-decode-map}, then
address@hidden, 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
address@hidden, 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 @address@hidden 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'' @address@hidden O P} to @code{[pf1]} in
address@hidden, when using a VT100.
-
-Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
address@hidden O P}; later the function @code{read-key-sequence} translates
-this back into @kbd{C-c @key{PF1}}, which it returns as the vector
address@hidden 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
address@hidden in a key sequence, that sub-sequence is replaced with
+the events in @var{v}.
+
+  For example, VT100 terminals send @address@hidden 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'' @address@hidden O P} to @code{[pf1]} in
address@hidden  Thus, when you type @kbd{C-c @key{PF1}} on
+the terminal, the terminal emits the character sequence @kbd{C-c
address@hidden O P}, and @code{read-key-sequence} translates this back into
address@hidden @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
address@hidden).  @xref{Terminal I/O Encoding}.
 
 @defvar input-decode-map
 This variable holds a keymap that describes the character sequences sent
@@ -1664,10 +1668,6 @@
 @end group
 @end example
 
-  If you have enabled keyboard character set decoding using
address@hidden, 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

=== modified file 'doc/lispref/nonascii.texi'
--- a/doc/lispref/nonascii.texi 2013-12-25 10:24:52 +0000
+++ b/doc/lispref/nonascii.texi 2013-12-27 03:38:26 +0000
@@ -1807,24 +1807,23 @@
 @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
address@hidden, 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
address@hidden is @code{nil}, that means do not decode keyboard
address@hidden 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 @@
 
 @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
address@hidden is @code{nil}, terminal output is not encoded.  If
address@hidden is a frame, it means that frame's terminal; if it is
address@hidden, that means the currently selected frame's terminal.
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2013-12-26 22:02:49 +0000
+++ b/etc/NEWS  2013-12-27 03:38:26 +0000
@@ -917,10 +917,12 @@
 ** 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 @@
 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.
 

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2013-12-26 11:31:42 +0000
+++ b/src/ChangeLog     2013-12-27 03:38:26 +0000
@@ -1,3 +1,7 @@
+2013-12-27  Chong Yidong  <address@hidden>
+
+       * data.c (Fsymbol_function): Doc fix.
+
 2013-12-26  Martin Rudalics  <address@hidden>
 
        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.

=== modified file 'src/data.c'
--- a/src/data.c        2013-11-25 23:25:04 +0000
+++ b/src/data.c        2013-12-27 03:38:26 +0000
@@ -686,7 +686,7 @@
 }
 
 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);