13 files changed, 386 insertions, 127 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 85a5f506739..1b9aabffe46 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,51 @@
+2003-12-25  Markus Rost  <rost@mathematik.uni-bielefeld.de>
+
+        * display.texi (Fringes): Fix typo "set-buffer-window".
+
+2003-12-24  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * display.texi, eval.texi, help.texi, internals.texi, loading.texi:
+        * nonascii.texi, processes.texi, tips.texi, variables.texi:
+        Add or change various xrefs and anchors.
+
+        * commands.texi: Replace all occurrences of @acronym{CAR} with
+        @sc{car}, for consistency with the rest of the Elisp manual.
+        `car' and `cdr' are historically acronyms, but are no longer
+        widely thought of as such.
+
+        * internals.texi (Pure Storage): Mention that `purecopy' does not
+        copy text properties.
+        (Object Internals): Now 29 bits are used (in most implementations)
+        to address Lisp objects.
+
+        * variables.texi (Variables with Restricted Values): New node.
+
+        * objects.texi (Lisp Data Types): Mention that certain variables
+        can only take on a restricted set of values and add an xref to
+        the new node "Variables with Restricted Values".
+
+        * eval.texi (Function Indirection): Describe the errors that
+        `indirect-function' can signal.
+        (Eval): Clarify the descriptions of `eval-region' and `values'.
+        Describe `eval-buffer' instead of `eval-current-buffer' and
+        mention `eval-current-buffer' as an alias for `current-buffer'.
+        Correct the description and mention all optional arguments.
+
+        * nonascii.texi : Various small changes in addition to the
+        following.
+        (Converting Representations): Clarify behavior of
+        `string-make-multibyte' and `string-to-multibyte' for unibyte all
+        ASCII arguments.
+        (Character Sets): Document the variable `charset-list' and adapt
+        the definition of the function `charset-list' accordingly.
+        (Translation of Characters): Clarify use of generic characters in
+        `make-translation-table'.  Clarify and correct the description of
+        the use of translation tables in encoding and decoding.
+        (User-Chosen Coding Systems): Correct and clarify the description
+        of `select-safe-coding-system'.
+        (Default Coding Systems): Clarify description of
+        `file-coding-system-alist'.
+
 2003-11-30  Luc Teirlinck  <teirllm@auburn.edu>
 
         * strings.texi (Text Comparison): Correctly describe when two
@@ -42,7 +90,7 @@
 
 2003-11-20  Luc Teirlinck  <teirllm@auburn.edu>
 
-        * positions.texi (Positions): Mention that, if a marker is used a
+        * positions.texi (Positions): Mention that, if a marker is used as
         a position, its buffer is ignored.
 
         * markers.texi (Overview of Markers): Mention it here too.
diff --git a/lispref/commands.texi b/lispref/commands.texi
index a2838c68bb9..a8350b88d82 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -1096,7 +1096,7 @@ arguments to the key-binding lookup and modification functions.
 
 Emacs supports four kinds of mouse events: click events, drag events,
 button-down events, and motion events.  All mouse events are represented
-as lists.  The @acronym{CAR} of the list is the event type; this says which
+as lists.  The @sc{car} of the list is the event type; this says which
 mouse button was involved, and which modifier keys were used with it.
 The event type can also distinguish double or triple button presses
 (@pxref{Repeat Events}).  The rest of the list elements give position
@@ -1172,7 +1172,7 @@ which the click occurred.  It is one of the symbols @code{mode-line},
 
 @item @var{x}, @var{y}
 These are the pixel-denominated coordinates of the click, relative to
-the top left corner of @var{window}, which is @code{(0 . 0)}.  
+the top left corner of @var{window}, which is @code{(0 . 0)}.
 For the mode or header line, @var{y} does not have meaningful data.
 For the vertical line, @var{x} does not have meaningful data.
 
@@ -1188,7 +1188,7 @@ an image object as returned by @code{find-image} if click was in an image.
 
 @item @var{string}
 This is the string on which the click occurred, including any
-properties.  
+properties.
 
 @item @var{string-pos}
 This is the position in the string on which the click occurred,
@@ -1560,7 +1560,7 @@ into another window.  That produces a pair of events like these:
 key binding purposes.  For a keyboard event, the event type equals the
 event value; thus, the event type for a character is the character, and
 the event type for a function key symbol is the symbol itself.  For
-events that are lists, the event type is the symbol in the @acronym{CAR} of
+events that are lists, the event type is the symbol in the @sc{car} of
 the list.  Thus, the event type is always a symbol or a character.
 
   Two events of the same type are equivalent where key bindings are
@@ -2583,7 +2583,7 @@ This function returns the numeric meaning of a valid raw prefix argument
 value, @var{arg}.  The argument may be a symbol, a number, or a list.
 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
 value @minus{}1 is returned; if it is a number, that number is returned;
-if it is a list, the @acronym{CAR} of that list (which should be a number) is
+if it is a list, the @sc{car} of that list (which should be a number) is
 returned.
 @end defun
 
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 8621cb65662..90600f410b7 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/customize
 @node Customization, Loading, Macros, Top
@@ -373,6 +373,7 @@ equivalent to @code{(string)}.
 * Composite Types::
 * Splicing into Lists::
 * Type Keywords::
+* Defining New Types::
 @end menu
 
 All customization types are implemented as widgets; see @ref{Top, ,
@@ -1056,6 +1057,76 @@ arguments, which will be used when creating the @code{radio-button} or
 @end ignore
 @end table
 
+@node Defining New Types
+@subsection Defining New Types
+
+In the previous sections we have described how to construct elaborate
+type specifications for @code{defcustom}.  In some cases you may want to
+give such a type specification a name.  The obvious case is when you are
+using the same type for many user options, rather than repeat the
+specification for each option, you can give the type specification a
+name once, and use that name each @code{defcustom}.  The other case is
+when a user option accept a recursive datastructure.  To make it
+possible for a datatype to refer to itself, it needs to have a name.
+
+Since custom types are implemented as widgets, the way to define a new
+customize type is to define a new widget.  We are not going to describe
+the widget interface here in details, see @ref{Top, , Introduction,
+widget, The Emacs Widget Library}, for that.  Instead we are going to
+demonstrate the minimal functionality needed for defining new customize
+types by a simple example.
+
+@example
+(define-widget 'binary-tree-of-string 'lazy
+  "A binary tree made of cons-cells and strings."
+  :offset 4
+  :tag "Node"
+  :type '(choice (string :tag "Leaf" :value "")
+                 (cons :tag "Interior"
+                       :value ("" . "") 
+                       binary-tree-of-string
+                       binary-tree-of-string)))
+
+(defcustom foo-bar ""
+  "Sample variable holding a binary tree of strings."
+  :type 'binary-tree-of-string)
+@end example
+
+The function to define a new widget is name @code{define-widget}.  The
+first argument is the symbol we want to make a new widget type.  The
+second argument is a symbol representing an existing widget, the new
+widget is going to be defined in terms of difference from the existing
+widget.  For the purpose of defining new customization types, the
+@code{lazy} widget is perfect, because it accept a @code{:type} keyword
+argument with the same syntax as the keyword argument to
+@code{defcustom} with the same name.  The third argument is a
+documentation string for the new widget.  You will be able to see that
+string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
+@key{ret}} command.  
+
+After these mandatory arguments follows the keyword arguments.  The most
+important is @code{:type}, which describes the datatype we want to match
+with this widget.  Here a @code{binary-tree-of-string} is described as
+being either a string, or a cons-cell whose car and cdr are themselves
+both @code{binary-tree-of-string}.  Note the reference to the widget
+type we are currently in the process of defining.  The @code{:tag}
+attribute is a string to name the widget in the user interface, and the
+@code{:offset} argument are there to ensure that child nodes are
+indented four spaces relatively to the parent node, making the tree
+structure apparent in the customization buffer.
+
+The @code{defcustom} shows how the new widget can be used as an ordinary
+customization type. 
+
+If you wonder about the name @code{lazy}, know that the other composite
+widgets convert their inferior widgets to internal form when the widget
+is instantiated in a buffer.  This conversion is recursive, so the
+inferior widgets will convert @emph{their} inferior widgets.  If the
+datastructure is itself recursive, this conversion will go on forever,
+or at least until Emacs run out of stack space.  The @code{lazy} widget
+stop this recursion, it will only convert its @code{:type} argument when
+needed.
+
 @ignore
    arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
 @end ignore
diff --git a/lispref/display.texi b/lispref/display.texi
index 186703b13b0..abbbab0ce79 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -805,8 +805,9 @@ If the @var{forms} do not change the major mode in the output buffer,
 so that it is still Help mode at the end of their execution, then
 @code{with-output-to-temp-buffer} makes this buffer read-only at the
 end, and also scans it for function and variable names to make them
-into clickable cross-references.  @xref{Documentation Tips, , Tips for
-Documentation Strings}.
+into clickable cross-references.  @xref{Docstring hyperlinks, , Tips
+for Documentation Strings}, in particular the item on hyperlinks in
+documentation strings, for more details.
 
 The string @var{buffer-name} specifies the temporary buffer, which
 need not already exist.  The argument must be a string, not a buffer.
@@ -2527,7 +2528,7 @@ fringe in pixels.
 
   The values of these variables take effect when you display the
 buffer in a window.  If you change them while the buffer is visible,
-you can call @code{set-buffer-window} to display it in a window again.
+you can call @code{set-window-buffer} to display it in a window again.
 
 @defun set-window-fringes window left &optional right outside-margins
 This function sets the fringe widthes of window @var{window}.
diff --git a/lispref/eval.texi b/lispref/eval.texi
index 165889e75ed..fcfde5849dd 100644
--- a/lispref/eval.texi
+++ b/lispref/eval.texi
@@ -319,6 +319,10 @@ This function returns the meaning of @var{function} as a function.  If
 definition and starts over with that value.  If @var{function} is not a
 symbol, then it returns @var{function} itself.
 
+This function signals a @code{void-function} error if the final
+symbol is unbound and a @code{cyclic-function-indirection} error if
+there is a loop in the chain of symbols.
+
 Here is how you could define @code{indirect-function} in Lisp:
 
 @smallexample
@@ -625,32 +629,51 @@ The number of currently active calls to @code{eval} is limited to
 @code{max-lisp-eval-depth} (see below).
 @end defun
 
+@anchor{Definition of eval-region}
 @deffn Command eval-region start end &optional stream read-function
 This function evaluates the forms in the current buffer in the region
 defined by the positions @var{start} and @var{end}.  It reads forms from
 the region and calls @code{eval} on them until the end of the region is
 reached, or until an error is signaled and not handled.
 
-If @var{stream} is non-@code{nil}, the values that result from
-evaluating the expressions in the region are printed using @var{stream}.
-@xref{Output Streams}.
-
-If @var{read-function} is non-@code{nil}, it should be a function, which
-is used instead of @code{read} to read expressions one by one.  This
-function is called with one argument, the stream for reading input.  You
-can also use the variable @code{load-read-function} (@pxref{How Programs
-Do Loading}) to specify this function, but it is more robust to use the
+By default, @code{eval-region} does not produce any output.  However,
+if @var{stream} is non-@code{nil}, any output produced by output
+functions (@pxref{Output Functions}), as well as the values that
+result from evaluating the expressions in the region are printed using
+@var{stream}.  @xref{Output Streams}.
+
+If @var{read-function} is non-@code{nil}, it should be a function,
+which is used instead of @code{read} to read expressions one by one.
+This function is called with one argument, the stream for reading
+input.  You can also use the variable @code{load-read-function}
+(@pxref{Definition of load-read-function,, How Programs Do Loading})
+to specify this function, but it is more robust to use the
 @var{read-function} argument.
 
-@code{eval-region} always returns @code{nil}.
+@code{eval-region} does not move point.  It always returns @code{nil}.
 @end deffn
 
 @cindex evaluation of buffer contents
-@deffn Command eval-current-buffer &optional stream
-This is like @code{eval-region} except that it operates on the whole
-buffer.
+@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
+This is similar to @code{eval-region}, but the arguments provide
+different optional features.  @code{eval-buffer} operates on the
+entire accessible portion of buffer @var{buffer-or-name}.
+@var{buffer-or-name} can be a buffer, a buffer name (a string), or
+@code{nil} (or omitted), which means to use the current buffer.
+@var{stream} is used as in @code{eval-region}, unless @var{stream} is
+@code{nil} and @var{print} non-@code{nil}.  In that case, values that
+result from evaluating the expressions are still discarded, but the
+output of the output functions is printed in the echo area.
+@var{filename} is the file name to use for @code{load-history}
+(@pxref{Unloading}), and defaults to @code{buffer-file-name}
+(@pxref{Buffer File Name}).  If @var{unibyte} is non-@code{nil},
+@code{read} converts strings to unibyte whenever possible.
+
+@findex eval-current-buffer
+@code{eval-current-buffer} is an alias for this command.
 @end deffn
 
+@anchor{Definition of max-lisp-eval-depth}
 @defvar max-lisp-eval-depth
 This variable defines the maximum depth allowed in calls to @code{eval},
 @code{apply}, and @code{funcall} before an error is signaled (with error
@@ -670,14 +693,17 @@ Entry to the Lisp debugger increases the value, if there is little room
 left, to make sure the debugger itself has room to execute.
 
 @code{max-specpdl-size} provides another limit on nesting.
-@xref{Local Variables}.
+@xref{Definition of max-specpdl-size,, Local Variables}.
 @end defvar
 
 @defvar values
 The value of this variable is a list of the values returned by all the
 expressions that were read, evaluated, and printed from buffers
-(including the minibuffer) by the standard Emacs commands which do this.
-The elements are ordered most recent first.
+(including the minibuffer) by the standard Emacs commands which do
+this.  (Note that this does @emph{not} include evaluation in
+@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
+@code{lisp-interaction-mode}.)  The elements are ordered most recent
+first.
 
 @example
 @group
diff --git a/lispref/help.texi b/lispref/help.texi
index 7675e38e81e..343ffb66078 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -259,6 +259,7 @@ as shown above for the @code{goal-column} variable, means that it is a
 user option; see the description of @code{defvar} in @ref{Defining
 Variables}.
 
+@anchor{Definition of Snarf-documentation}
 @defun Snarf-documentation filename
 This function is used only during Emacs initialization, just before
 the runnable Emacs is dumped.  It finds the file offsets of the
diff --git a/lispref/internals.texi b/lispref/internals.texi
index c8cf5ed0f7c..2a4572560a7 100644
--- a/lispref/internals.texi
+++ b/lispref/internals.texi
@@ -81,8 +81,9 @@ faster.  On modern machines, it is usually not advisable.
 
   After @file{loadup.el} reads @file{site-load.el}, it finds the
 documentation strings for primitive and preloaded functions (and
-variables) in the file @file{etc/DOC} where they are stored, by calling
-@code{Snarf-documentation} (@pxref{Accessing Documentation}).
+variables) in the file @file{etc/DOC} where they are stored, by
+calling @code{Snarf-documentation} (@pxref{Definition of
+Snarf-documentation,, Accessing Documentation}).
 
 @cindex @file{site-init.el}
   You can specify other Lisp expressions to execute just before dumping
@@ -151,10 +152,10 @@ preload additional libraries or add features to the standard ones.
 @defun purecopy object
 This function makes a copy in pure storage of @var{object}, and returns
 it.  It copies a string by simply making a new string with the same
-characters in pure storage.  It recursively copies the contents of
-vectors and cons cells.  It does not make copies of other objects such
-as symbols, but just returns them unchanged.  It signals an error if
-asked to copy markers.
+characters, but without text properties, in pure storage.  It
+recursively copies the contents of vectors and cons cells.  It does
+not make copies of other objects such as symbols, but just returns
+them unchanged.  It signals an error if asked to copy markers.
 
 This function is a no-op except while Emacs is being built and dumped;
 it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
@@ -367,7 +368,7 @@ until the subsequent garbage collection, at which time
 @code{garbage-collect} will set the threshold back to 10,000.
 @end defopt
 
-  The value return by @code{garbage-collect} describes the amount of
+  The value returned by @code{garbage-collect} describes the amount of
 memory used by Lisp data, broken down by data type.  By contrast, the
 function @code{memory-limit} provides information on the total amount of
 memory Emacs is currently using.
@@ -595,9 +596,9 @@ protected in the current function.  It is necessary to do this explicitly.
 GC-protected; as long as the object is not recycled, all pointers to
 it remain valid.  So if you are sure that a local variable points to
 an object that will be preserved by some other pointer, that local
-variable does not need a GCPRO.  (Formerly, strings were an exception
-to this rule; in older Emacs versions, every pointer to a string
-needed to be marked by GC.)
+variable does not need a @code{GCPRO}.  (Formerly, strings were an
+exception to this rule; in older Emacs versions, every pointer to a
+string needed to be marked by GC.)
 
   The macro @code{GCPRO1} protects just one local variable.  If you
 want to protect two, use @code{GCPRO2} instead; repeating
@@ -612,7 +613,7 @@ Alas, we can't explain all the tricky details here.
 accept two arguments at the C level: the number of Lisp arguments, and
 a @code{Lisp_Object *} pointer to a C vector containing those Lisp
 arguments.  This C vector may be part of a Lisp vector, but it need
-not be.  The responsibility for using GCPRO to protecting the Lisp
+not be.  The responsibility for using @code{GCPRO} to protect the Lisp
 arguments from GC if necessary rests with the caller in this case,
 since the caller allocated or found the storage for them.
 
@@ -651,6 +652,7 @@ file, add to it a @code{syms_of_@var{filename}} (e.g.,
 of these functions are called, and add a call to
 @code{syms_of_@var{filename}} there.
 
+@anchor{Defining Lisp variables in C}
 @vindex byte-boolean-vars
   The function @code{syms_of_@var{filename}} is also the place to define
 any C variables that are to be visible as Lisp variables.
@@ -761,9 +763,9 @@ knows about it.
 data are stored in a heap and the only access that programs have to it
 is through pointers.  Pointers are thirty-two bits wide in most
 implementations.  Depending on the operating system and type of machine
-for which you compile Emacs, twenty-eight bits are used to address the
-object, and the remaining four bits are used for a GC mark bit and the
-tag that identifies the object's type.
+for which you compile Emacs, twenty-nine bits are used to address the
+object, and the remaining three bits are used for the tag that
+identifies the object's type.
 
   Because Lisp objects are represented as tagged pointers, it is always
 possible to determine the Lisp data type of any object.  The C data type
diff --git a/lispref/loading.texi b/lispref/loading.texi
index 0865914c45d..e171fc70fdf 100644
--- a/lispref/loading.texi
+++ b/lispref/loading.texi
@@ -140,6 +140,7 @@ This variable is non-@code{nil} if Emacs is in the process of loading a
 file, and it is @code{nil} otherwise.
 @end defvar
 
+@anchor{Definition of load-read-function}
 @defvar load-read-function
 This variable specifies an alternate expression-reading function for
 @code{load} and @code{eval-region} to use instead of @code{read}.
@@ -150,7 +151,7 @@ functions should use @code{read}.
 
 Instead of using this variable, it is cleaner to use another, newer
 feature: to pass the function as the @var{read-function} argument to
-@code{eval-region}.  @xref{Eval}.
+@code{eval-region}.  @xref{Definition of eval-region,, Eval}.
 @end defvar
 
   For information about how @code{load} is used in building Emacs, see
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index 72dd46d19eb..e66c7d15757 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -96,13 +96,15 @@ default value to @code{nil} early in startup.
 @defun position-bytes position
 @tindex position-bytes
 Return the byte-position corresponding to buffer position @var{position}
-in the current buffer.
+in the current buffer.  If @var{position} is out of range, the value
+is @code{nil}.
 @end defun
 
 @defun byte-to-position byte-position
 @tindex byte-to-position
 Return the buffer position corresponding to byte-position
-@var{byte-position} in the current buffer.
+@var{byte-position} in the current buffer.  If @var{byte-position} is
+out of range, the value is @code{nil}.
 @end defun
 
 @defun multibyte-string-p string
@@ -173,6 +175,9 @@ multibyte character.  The value should be a char-table, or @code{nil}.
 If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
 @end defvar
 
+The next three functions either return the argument @var{string}, or a
+newly created string with no text properties.
+
 @defun string-make-unibyte string
 This function converts the text of @var{string} to unibyte
 representation, if it isn't already, and returns the result.  If
@@ -186,15 +191,23 @@ fails, this function takes just the low 8 bits of each character.
 @defun string-make-multibyte string
 This function converts the text of @var{string} to multibyte
 representation, if it isn't already, and returns the result.  If
-@var{string} is a multibyte string, it is returned unchanged.
-The function @code{unibyte-char-to-multibyte} is used to convert
-each unibyte character to a multibyte character.
+@var{string} is a multibyte string or consists entirely of
+@acronym{ASCII} characters, it is returned unchanged.  In particular,
+if @var{string} is unibyte and entirely @acronym{ASCII}, the returned
+string is unibyte.  (When the characters are all @acronym{ASCII},
+Emacs primitives will treat the string the same way whether it is
+unibyte or multibyte.)  If @var{string} is unibyte and contains
+non-@acronym{ASCII} characters, the function
+@code{unibyte-char-to-multibyte} is used to convert each unibyte
+character to a multibyte character.
 @end defun
 
 @defun string-to-multibyte string
 This function returns a multibyte string containing the same sequence
-of character codes as @var{string}.  If @var{string} is a multibyte
-string, the value is the equal to @var{string}.
+of character codes as @var{string}.  Unlike
+@code{string-make-multibyte}, this function unconditionally returns a
+multibyte string.  If @var{string} is a multibyte string, it is
+returned unchanged.
 @end defun
 
 @node Selecting a Representation
@@ -280,8 +293,8 @@ text representations.
 @end example
 
 If the optional argument @var{genericp} is non-@code{nil}, this
-function returns @code{t} if @var{charcode} is a generic character
-(@pxref{Splitting Characters}).
+function also returns @code{t} if @var{charcode} is a generic
+character (@pxref{Splitting Characters}).
 @end defun
 
 @node Character Sets
@@ -311,13 +324,19 @@ Returns @code{t} if @var{object} is a symbol that names a character set,
 @code{nil} otherwise.
 @end defun
 
+@defvar charset-list
+The value is a list of all defined character set names.
+@end defvar
+
 @defun charset-list
-This function returns a list of all defined character set names.
+This function returns the value of @code{charset-list}.  It is only
+provided for backward compatibility.
 @end defun
 
 @defun char-charset character
 This function returns the name of the character set that @var{character}
-belongs to.
+belongs to, or the symbol @code{unknown} if @var{character} is not a
+valid character.
 @end defun
 
 @defun charset-plist charset
@@ -378,6 +397,9 @@ Return a list containing the name of the character set of
 identify @var{character} within that character set.  The number of byte
 values is the character set's dimension.
 
+If @var{character} is invalid as a character code, @code{split-char}
+returns a list consisting of the symbol @code{unknown} and @var{character}.
+
 @example
 (split-char 2248)
      @result{} (latin-iso8859-1 72)
@@ -463,11 +485,11 @@ current buffer.
 @cindex character translation tables
 @cindex translation tables
 
-  A @dfn{translation table} specifies a mapping of characters
-into characters.  These tables are used in encoding and decoding, and
-for other purposes.  Some coding systems specify their own particular
-translation tables; there are also default translation tables which
-apply to all other coding systems.
+  A @dfn{translation table} is a char-table that specifies a mapping
+of characters into characters.  These tables are used in encoding and
+decoding, and for other purposes.  Some coding systems specify their
+own particular translation tables; there are also default translation
+tables which apply to all other coding systems.
 
 @defun make-translation-table &rest translations
 This function returns a translation table based on the argument
@@ -483,24 +505,30 @@ character, say @var{to-alt}, @var{from} is also translated to
 You can also map one whole character set into another character set with
 the same dimension.  To do this, you specify a generic character (which
 designates a character set) for @var{from} (@pxref{Splitting Characters}).
-In this case, @var{to} should also be a generic character, for another
-character set of the same dimension.  Then the translation table
-translates each character of @var{from}'s character set into the
-corresponding character of @var{to}'s character set.
+In this case, if @var{to} is also a generic character, its character
+set should have the same dimension as @var{from}'s.  Then the
+translation table translates each character of @var{from}'s character
+set into the corresponding character of @var{to}'s character set.  If
+@var{from} is a generic character and @var{to} is an ordinary
+character, then the translation table translates every character of
+@var{from}'s character set into @var{to}.
 @end defun
 
   In decoding, the translation table's translations are applied to the
 characters that result from ordinary decoding.  If a coding system has
-property @code{character-translation-table-for-decode}, that specifies
-the translation table to use.  Otherwise, if
-@code{standard-translation-table-for-decode} is non-@code{nil}, decoding
-uses that table.
+property @code{translation-table-for-decode}, that specifies the
+translation table to use.  (This is a property of the coding system,
+as returned by @code{coding-system-get}, not a property of the symbol
+that is the coding system's name. @xref{Coding System Basics,, Basic
+Concepts of Coding Systems}.)  Otherwise, if
+@code{standard-translation-table-for-decode} is non-@code{nil},
+decoding uses that table.
 
   In encoding, the translation table's translations are applied to the
 characters in the buffer, and the result of translation is actually
 encoded.  If a coding system has property
-@code{character-translation-table-for-encode}, that specifies the
-translation table to use.  Otherwise the variable
+@code{translation-table-for-encode}, that specifies the translation
+table to use.  Otherwise the variable
 @code{standard-translation-table-for-encode} specifies the translation
 table.
 
@@ -516,7 +544,8 @@ coding systems that don't specify any other translation table.
 
 @defvar translation-table-for-input
 Self-inserting characters are translated through this translation
-table before they are inserted.
+table before they are inserted.  This variable automatically becomes
+buffer-local when set.
 @end defvar
 
 @node Coding Systems
@@ -686,7 +715,7 @@ systems as well.
 
 @defun coding-system-p object
 This function returns @code{t} if @var{object} is a coding system
-name.
+name or @code{nil}.
 @end defun
 
 @defun check-coding-system coding-system
@@ -701,6 +730,9 @@ except for its eol conversion, which is specified by @code{eol-type}.
 @var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
 @code{nil}.  If it is @code{nil}, the returned coding system determines
 the end-of-line conversion from the data.
+
+@var{eol-type} may also be 0, 1 or 2, standing for @code{unix},
+@code{dos} and @code{mac}, respectively.
 @end defun
 
 @defun coding-system-change-text-conversion eol-coding text-coding
@@ -745,55 +777,79 @@ return value is just one coding system, the one that is highest in
 priority.
 
 If the region contains only @acronym{ASCII} characters, the value
-is @code{undecided} or @code{(undecided)}.
+is @code{undecided} or @code{(undecided)}, or a variant specifying
+end-of-line conversion, if that can be deduced from the text.
 @end defun
 
-@defun detect-coding-string string highest
+@defun detect-coding-string string &optional highest
 This function is like @code{detect-coding-region} except that it
 operates on the contents of @var{string} instead of bytes in the buffer.
 @end defun
 
-  @xref{Process Information}, for how to examine or set the coding
-systems used for I/O to a subprocess.
+  @xref{Coding systems for a subprocess,, Process Information}, in
+particular the description of the functions
+@code{process-coding-system} and @code{set-process-coding-system}, for
+how to examine or set the coding systems used for I/O to a subprocess.
 
 @node User-Chosen Coding Systems
 @subsection User-Chosen Coding Systems
 
 @cindex select safe coding system
-@defun select-safe-coding-system from to &optional default-coding-system accept-default-p
+@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file
 This function selects a coding system for encoding specified text,
 asking the user to choose if necessary.  Normally the specified text
-is the text in the current buffer between @var{from} and @var{to},
-defaulting to the whole buffer if they are @code{nil}.  If @var{from}
-is a string, the string specifies the text to encode, and @var{to} is
-ignored.
+is the text in the current buffer between @var{from} and @var{to}.  If
+@var{from} is a string, the string specifies the text to encode, and
+@var{to} is ignored.
 
 If @var{default-coding-system} is non-@code{nil}, that is the first
 coding system to try; if that can handle the text,
 @code{select-safe-coding-system} returns that coding system.  It can
 also be a list of coding systems; then the function tries each of them
-one by one.  After trying all of them, it next tries the user's most
-preferred coding system (@pxref{Recognize Coding,
-prefer-coding-system, the description of @code{prefer-coding-system},
-emacs, GNU Emacs Manual}), and after that the current buffer's value
-of @code{buffer-file-coding-system} (if it is not @code{undecided}).
+one by one.  After trying all of them, it next tries the current
+buffer's value of @code{buffer-file-coding-system} (if it is not
+@code{undecided}), then the value of
+@code{default-buffer-file-coding-system} and finally the user's most
+preferred coding system, which the user can set using the command
+@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing
+Coding Systems, emacs, The GNU Emacs Manual}).
 
 If one of those coding systems can safely encode all the specified
 text, @code{select-safe-coding-system} chooses it and returns it.
 Otherwise, it asks the user to choose from a list of coding systems
 which can encode all the text, and returns the user's choice.
 
+@var{default-coding-system} can also be a list whose first element is
+t and whose other elements are coding systems.  Then, if no coding
+system in the list can handle the text, @code{select-safe-coding-system}
+queries the user immediately, without trying any of the three
+alternatives described above.
+
 The optional argument @var{accept-default-p}, if non-@code{nil},
-should be a function to determine whether the coding system selected
-without user interaction is acceptable.  If this function returns
-@code{nil}, the silently selected coding system is rejected, and the
-user is asked to select a coding system from a list of possible
-candidates.
+should be a function to determine whether a coding system selected
+without user interaction is acceptable. @code{select-safe-coding-system}
+calls this function with one argument, the base coding system of the
+selected coding system.  If @var{accept-default-p} returns @code{nil},
+@code{select-safe-coding-system} rejects the silently selected coding
+system, and asks the user to select a coding system from a list of
+possible candidates.
 
 @vindex select-safe-coding-system-accept-default-p
 If the variable @code{select-safe-coding-system-accept-default-p} is
 non-@code{nil}, its value overrides the value of
 @var{accept-default-p}.
+
+As a final step, before returning the chosen coding system,
+@code{select-safe-coding-system} checks whether that coding system is
+consistent with what would be selected if the contents of the region
+were read from a file.  (If not, this could lead to data corruption in
+a file subsequently re-visited and edited.)  Normally,
+@code{select-safe-coding-system} uses @code{buffer-file-name} as the
+file for this purpose, but if @var{file} is non-@code{nil}, it uses
+that file instead (this can be relevant for @code{write-region} and
+similar functions).  If it detects an apparent inconsistency,
+@code{select-safe-coding-system} queries the user before selecting the
+coding system.
 @end defun
 
   Here are two functions you can use to let the user specify a coding
@@ -846,17 +902,19 @@ reading and writing particular files.  Each element has the form
 expression that matches certain file names.  The element applies to file
 names that match @var{pattern}.
 
-The @acronym{CDR} of the element, @var{coding}, should be either a coding
+The @sc{cdr} of the element, @var{coding}, should be either a coding
 system, a cons cell containing two coding systems, or a function name (a
 symbol with a function definition).  If @var{coding} is a coding system,
 that coding system is used for both reading the file and writing it.  If
-@var{coding} is a cons cell containing two coding systems, its @acronym{CAR}
-specifies the coding system for decoding, and its @acronym{cdr} specifies the
+@var{coding} is a cons cell containing two coding systems, its @sc{car}
+specifies the coding system for decoding, and its @sc{cdr} specifies the
 coding system for encoding.
 
-If @var{coding} is a function name, the function must return a coding
-system or a cons cell containing two coding systems.  This value is used
-as described above.
+If @var{coding} is a function name, the function should take one
+argument, a list of all arguments passed to
+@code{find-operation-coding-system}.  It must return a coding system
+or a cons cell containing two coding systems.  This value has the same
+meaning as described above.
 @end defvar
 
 @defvar process-coding-system-alist
@@ -923,7 +981,7 @@ performing @var{operation} with @var{arguments}.  The value has this
 form:
 
 @example
-(@var{decoding-system} @var{encoding-system})
+(@var{decoding-system} . @var{encoding-system})
 @end example
 
 The first element, @var{decoding-system}, is the coding system to use
@@ -948,7 +1006,6 @@ or port number.
 This function looks up the target in @code{file-coding-system-alist},
 @code{process-coding-system-alist}, or
 @code{network-coding-system-alist}, depending on @var{operation}.
-@xref{Default Coding Systems}.
 @end defun
 
 @node Specifying Coding Systems
@@ -1040,33 +1097,41 @@ decoding functions produce sequences of bytes; the encoding functions
 are meant to operate on sequences of bytes.  All of these functions
 discard text properties.
 
-@defun encode-coding-region start end coding-system
-This function encodes the text from @var{start} to @var{end} according
+@deffn Command encode-coding-region start end coding-system
+This command encodes the text from @var{start} to @var{end} according
 to coding system @var{coding-system}.  The encoded text replaces the
 original text in the buffer.  The result of encoding is logically a
 sequence of bytes, but the buffer remains multibyte if it was multibyte
 before.
-@end defun
 
-@defun encode-coding-string string coding-system
+This command returns the length of the encoded text.
+@end deffn
+
+@defun encode-coding-string string coding-system &optional nocopy
 This function encodes the text in @var{string} according to coding
 system @var{coding-system}.  It returns a new string containing the
-encoded text.  The result of encoding is a unibyte string.
+encoded text, except when @var{nocopy} is non-@code{nil}, in which
+case the function may return @var{string} itself if the encoding
+operation is trivial.  The result of encoding is a unibyte string.
 @end defun
 
-@defun decode-coding-region start end coding-system
-This function decodes the text from @var{start} to @var{end} according
+@deffn Command decode-coding-region start end coding-system
+This command decodes the text from @var{start} to @var{end} according
 to coding system @var{coding-system}.  The decoded text replaces the
 original text in the buffer.  To make explicit decoding useful, the text
 before decoding ought to be a sequence of byte values, but both
 multibyte and unibyte buffers are acceptable.
-@end defun
 
-@defun decode-coding-string string coding-system
+This command returns the length of the decoded text.
+@end deffn
+
+@defun decode-coding-string string coding-system &optional nocopy
 This function decodes the text in @var{string} according to coding
 system @var{coding-system}.  It returns a new string containing the
-decoded text.  To make explicit decoding useful, the contents of
-@var{string} ought to be a sequence of byte values, but a multibyte
+decoded text, except when @var{nocopy} is non-@code{nil}, in which
+case the function may return @var{string} itself if the decoding
+operation is trivial.  To make explicit decoding useful, the contents
+of @var{string} ought to be a sequence of byte values, but a multibyte
 string is acceptable.
 @end defun
 
@@ -1095,22 +1160,22 @@ This function returns the coding system that is in use for decoding
 keyboard input---or @code{nil} if no coding system is to be used.
 @end defun
 
-@defun set-keyboard-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to
+@deffn Command set-keyboard-coding-system coding-system
+This command specifies @var{coding-system} as the coding system to
 use for decoding keyboard input.  If @var{coding-system} is @code{nil},
 that means do not decode keyboard input.
-@end defun
+@end deffn
 
 @defun terminal-coding-system
 This function returns the coding system that is in use for encoding
 terminal output---or @code{nil} for no encoding.
 @end defun
 
-@defun set-terminal-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to use
+@deffn Command set-terminal-coding-system coding-system
+This command specifies @var{coding-system} as the coding system to use
 for encoding terminal output.  If @var{coding-system} is @code{nil},
 that means do not encode terminal output.
-@end defun
+@end deffn
 
 @node MS-DOS File Types
 @subsection MS-DOS File Types
@@ -1193,18 +1258,18 @@ in any fashion.)  It is @code{nil} if no input method is active in the
 buffer now.
 @end defvar
 
-@defvar default-input-method
+@defopt default-input-method
 This variable holds the default input method for commands that choose an
 input method.  Unlike @code{current-input-method}, this variable is
 normally global.
-@end defvar
+@end defopt
 
-@defun set-input-method input-method
-This function activates input method @var{input-method} for the current
+@deffn Command set-input-method input-method
+This command activates input method @var{input-method} for the current
 buffer.  It also sets @code{default-input-method} to @var{input-method}.
-If @var{input-method} is @code{nil}, this function deactivates any input
+If @var{input-method} is @code{nil}, this command deactivates any input
 method for the current buffer.
-@end defun
+@end deffn
 
 @defun read-input-method-name prompt &optional default inhibit-null
 This function reads an input method name with the minibuffer, prompting
@@ -1240,7 +1305,8 @@ it is good for.
 @end defvar
 
   The fundamental interface to input methods is through the
-variable @code{input-method-function}.  @xref{Reading One Event}.
+variable @code{input-method-function}.  @xref{Reading One Event},
+and @ref{Invoking the Input Method}.
 
 @node Locales
 @section Locales
@@ -1294,14 +1360,14 @@ through @code{MON_12}).
 
 @item paper
 Return a list @code{(@var{width} @var{height})} for the default paper
-size measured in milimeters (locale items @code{PAPER_WIDTH} and
+size measured in millimeters (locale items @code{PAPER_WIDTH} and
 @code{PAPER_HEIGHT}).
 @end table
 
 If the system can't provide the requested information, or if
 @var{item} is not one of those symbols, the value is @code{nil}.  All
 strings in the return value are decoded using
-@code{locale-coding-system}.  @xref{Locales,,, libc, GNU Libc Manual},
+@code{locale-coding-system}.  @xref{Locales,,, libc, The GNU Libc Manual},
 for more information about locales and locale items.
 @end defun
 
diff --git a/lispref/objects.texi b/lispref/objects.texi
index 4c905cb969e..6cb5adb72b8 100644
--- a/lispref/objects.texi
+++ b/lispref/objects.texi
@@ -42,7 +42,9 @@ it as a number; Lisp knows it is a vector, not a number.
 variable, and the type is known by the compiler but not represented in
 the data.  Such type declarations do not exist in Emacs Lisp.  A Lisp
 variable can have any type of value, and it remembers whatever value
-you store in it, type and all.
+you store in it, type and all.  (Actually, a small number of Emacs
+Lisp variables can only take on values of a certain type.
+@xref{Variables with Restricted Values}.)
 
   This chapter describes the purpose, printed representation, and read
 syntax of each of the standard types in GNU Emacs Lisp.  Details on how
diff --git a/lispref/processes.texi b/lispref/processes.texi
index c991cf300e3..8e32962de67 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -676,6 +676,7 @@ instead of a terminal (see @code{process-connection-type} in
 @ref{Asynchronous Processes}).
 @end defun
 
+@anchor{Coding systems for a subprocess}
 @defun process-coding-system process
 This function returns a cons cell describing the coding systems in use
 for decoding output from @var{process} and for encoding input to
diff --git a/lispref/tips.texi b/lispref/tips.texi
index 1b40685ba5d..ec53dc420dd 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -647,6 +647,7 @@ The argument FOO can be either a number
 This prevents the open-parenthesis from being treated as the start of a
 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
 
+@anchor{Docstring hyperlinks}
 @item
 @iftex
 When a documentation string refers to a Lisp symbol, write it as it
diff --git a/lispref/variables.texi b/lispref/variables.texi
index 36cc2e47fe4..bbe7358b5d7 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -43,6 +43,8 @@ variable.
 * Future Local Variables::  New kinds of local values we might add some day.
 * Variable Aliases::      Variables that are aliases for other variables.
 * File Local Variables::  Handling local variable lists in files.
+* Variables with Restricted Values::  Non-constant variables whose value can
+                                        @emph{not} be an arbitrary Lisp object.
 @end menu
 
 @node Global Variables
@@ -258,19 +260,21 @@ These kinds of bindings work somewhat like ordinary local bindings, but
 they are localized depending on ``where'' you are in Emacs, rather than
 localized in time.
 
+@anchor{Definition of max-specpdl-size}
 @defvar max-specpdl-size
 @cindex variable limit error
 @cindex evaluation error
 @cindex infinite recursion
 This variable defines the limit on the total number of local variable
-bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
-that are allowed before signaling an error (with data @code{"Variable
-binding depth exceeds max-specpdl-size"}).
+bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
+Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
+error (with data @code{"Variable binding depth exceeds
+max-specpdl-size"}).
 
 This limit, with the associated error when it is exceeded, is one way
 that Lisp avoids infinite recursion on an ill-defined function.
 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
-@xref{Eval}.
+@xref{Definition of max-lisp-eval-depth,, Eval}.
 
 The default value is 600.  Entry to the Lisp debugger increases the
 value, if there is little room left, to make sure the debugger itself
@@ -1813,6 +1817,41 @@ could include functions to call.  So Emacs discards all text
 properties from string values specified in a file's local variables
 list.
 
+@node Variables with Restricted Values
+@section Variables with Restricted Values
+
+  Ordinary Lisp variables can be assigned any value that is a valid
+Lisp object.  However, certain Lisp variables are not defined in Lisp,
+but in C.  Most of these variables are defined in the C code using
+@code{DEFVAR_LISP}.  Like variables defined in Lisp, these can take on
+any value.  However, some variables are defined using
+@code{DEFVAR_INT} or @code{DEFVAR_BOOL}.  @xref{Defining Lisp
+variables in C,, Writing Emacs Primitives}, in particular the
+description of functions of the type @code{syms_of_@var{filename}},
+for a brief discussion of the C implementation.
+
+  Variables of type @code{DEFVAR_BOOL} can only take on the values
+@code{nil} or @code{t}.  Attempting to assign them any other value
+will set them to @code{t}:
+
+@example
+(let ((display-hourglass 5))
+  display-hourglass)
+     @result{} t
+@end example
+
+@defvar byte-boolean-vars
+This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
+@end defvar
+
+  Variables of type @code{DEFVAR_INT} can only take on integer values.
+Attempting to assign them any other value will result in an error:
+
+@example
+(setq window-min-height 5.0)
+@error{} Wrong type argument: integerp, 5.0
+@end example
+
 @ignore
    arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
 @end ignore