17 files changed, 746 insertions, 154 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index de08e3fb459..85ceb0dd700 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,139 @@
+2006-06-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * tips.texi (Coding Conventions): Add `@end itemize'.
+
+2006-06-10  Richard Stallman  <rms@gnu.org>
+
+        * tips.texi (Coding Conventions): Explain use of coding systems
+        to ensure one decoding for strings.
+
+2006-06-09  Aidan Kehoe  <kehoea@parhasard.net>
+
+        * objects.texi (Character Type): Describe the\uABCD and \U00ABCDEF
+        syntax.
+
+2006-06-07  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Font Selection): Remove description of
+        clear-face-cache.
+
+        * compile.texi (Eval During Compile): Fix a typo.  Add index
+        entries for possible uses of eval-when-compile.
+
+2006-06-04  Thien-Thi Nguyen  <ttn@gnu.org>
+
+        * display.texi (Abstract Display): Fix typo.
+
+2006-06-03  Eli Zaretskii  <eliz@gnu.org>
+
+        * minibuf.texi (Minibuffer History) <history-add-new-input>:
+        Reword variable's description.
+
+2006-06-01  Richard Stallman  <rms@gnu.org>
+
+        * windows.texi (Splitting Windows): Clarify splitting nonselected
+        window.
+
+2006-05-31  Juri Linkov  <juri@jurta.org>
+
+        * minibuf.texi (Minibuffer History): Add history-add-new-input.
+
+2006-05-30  Richard Stallman  <rms@gnu.org>
+
+        * display.texi (Line Height): Fix errors in description of
+        default line height and line-height properyty.
+
+        * nonascii.texi (Default Coding Systems): Further clarification.
+
+2006-05-29  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * internals.texi (Pure Storage): Mention that an overflow in pure
+        space causes a memory leak.
+        (Garbage Collection): If there was an overflow in pure space,
+        `garbage-collect' returns nil.
+
+2006-05-30  Eli Zaretskii  <eliz@gnu.org>
+
+        * nonascii.texi (Default Coding Systems): Fix it some more.
+
+2006-05-29  Eli Zaretskii  <eliz@gnu.org>
+
+        * nonascii.texi (Default Coding Systems): Fix last change.
+
+2006-05-29  Kenichi Handa  <handa@m17n.org>
+
+        * nonascii.texi (find-operation-coding-system): Describe the new
+        argument format (FILENAME . BUFFER).
+
+2006-05-28  Richard Stallman  <rms@gnu.org>
+
+        * tips.texi (Coding Conventions): Better explain reasons not to
+        advise other packages or use `eval-after-load'.
+
+2006-05-29  Kim F. Storm  <storm@cua.dk>
+
+        * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to
+        `bindat-idx' and `bindat-raw' for clarity.
+
+2006-05-27  Thien-Thi Nguyen  <ttn@gnu.org>
+
+        * processes.texi (Bindat Spec): Expand on `repeat' handler.
+
+        * display.texi (Display): Add "Abstract Display" to menu.
+        (Abstract Display, Abstract Display Functions)
+        (Abstract Display Example): New nodes.
+        * elisp.texi (Top): Add "Abstract Display" to menu.
+
+2006-05-27  Chong Yidong  <cyd@stupidchicken.com>
+
+        * keymaps.texi (Key Sequences): Link to input events definition.
+        (Format of Keymaps): Delete material duplicated in Keymap Basics.
+
+        * files.texi (Changing Files): Document updated argument list for
+        copy-file.
+
+2006-05-27  Thien-Thi Nguyen  <ttn@gnu.org>
+
+        * processes.texi (Bindat Functions): Explain term "total length".
+        Use it in bindat-length and bindat-pack descriptions.
+
+2006-05-26  Eli Zaretskii  <eliz@gnu.org>
+
+        * tips.texi (Coding Conventions): Advise against using
+        eval-after-load in packages.  Add an index entry.
+
+2006-05-25  Juri Linkov  <juri@jurta.org>
+
+        * minibuf.texi (Text from Minibuffer): Undocument keep-all.
+
+        * modes.texi (%-Constructs): Add %e, %z, %Z.
+
+2006-05-25  Richard Stallman  <rms@gnu.org>
+
+        * elisp.texi (Top): Update subnode menu.
+
+        * keymaps.texi (Keymap Basics): New node, split out of Key Sequences.
+        (Keymaps): Update menu.
+
+2006-05-25  Chong Yidong  <cyd@stupidchicken.com>
+
+        * keymaps.texi (Key Sequences): Some clarifications.
+
+2006-05-25  Thien-Thi Nguyen  <ttn@gnu.org>
+
+        * processes.texi (Bindat Functions): Say "unibyte string"
+        explicitly for bindat-unpack and bindat-pack descriptions.
+        (Bindat Examples): Don't call `string-make-unibyte' in example.
+
+2006-05-25  Chong Yidong  <cyd@stupidchicken.com>
+
+        * keymaps.texi (Key Sequences): Renamed from Keymap Terminology.
+        Explain string and vector representations of key sequences
+
+        * keymaps.texi (Changing Key Bindings):
+        * commands.texi (Interactive Codes, Interactive Codes):
+        * help.texi (Describing Characters): Refer to it.
+
 2006-05-23  Luc Teirlinck  <teirllm@auburn.edu>
 
         * frames.texi (Pointer Shape): @end table -> @end defvar.
@@ -509,7 +645,7 @@
 
 2005-12-23  Eli Zaretskii  <eliz@gnu.org>
 
-        * text.texi (Undo): Remove dupliate descriptions of `apply
+        * text.texi (Undo): Remove duplicate descriptions of `apply
         funname' and `apply delta' elements of the undo list.
 
 2005-12-20  Richard M. Stallman  <rms@gnu.org>
diff --git a/lispref/commands.texi b/lispref/commands.texi
index fa5d95f0408..0723c368bba 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -362,7 +362,7 @@ An irrelevant argument.  This code always supplies @code{nil} as
 the argument's value.  No I/O.
 
 @item k
-A key sequence (@pxref{Keymap Terminology}).  This keeps reading events
+A key sequence (@pxref{Key Sequences}).  This keeps reading events
 until a command (or undefined command) is found in the current key
 maps.  The key sequence argument is represented as a string or vector.
 The cursor does not move into the echo area.  Prompt.
diff --git a/lispref/compile.texi b/lispref/compile.texi
index 4b796697731..1b18e0ee284 100644
--- a/lispref/compile.texi
+++ b/lispref/compile.texi
@@ -435,15 +435,16 @@ compiler becomes a constant which appears in the compiled program.  If
 you load the source file, rather than compiling it, @var{body} is
 evaluated normally.
 
+@cindex compile-time constant
 If you have a constant that needs some calculation to produce,
-@code{eval-when-compile} can do that done at compile-time.  For
-example,
+@code{eval-when-compile} can do that at compile-time.  For example,
 
 @lisp
 (defvar my-regexp
   (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
 @end lisp
 
+@cindex macros, at compile time
 If you're using another package, but only need macros from it (the
 byte compiler will expand those), then @code{eval-when-compile} can be
 used to load it for compiling, but not executing.  For example,
diff --git a/lispref/display.texi b/lispref/display.texi
index a77c895276e..1b8e66ec23e 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -29,6 +29,7 @@ that Emacs presents to the user.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
 * Buttons::             Adding clickable buttons to Emacs buffers.
+* Abstract Display::    Emacs' Widget for Object Collections.
 * Blinking::            How Emacs shows the matching open parenthesis.
 * Usual Display::       The usual conventions for displaying nonprinting chars.
 * Display Tables::      How to specify other conventions.
@@ -1581,41 +1582,41 @@ equal to or less than the display width of @var{ellipsis}.  If
 @cindex line height
 
   The total height of each display line consists of the height of the
-contents of the line, and additional vertical line spacing below the
-display row.
+contents of the line, plus optional additional vertical line spacing
+above or below the display line.
 
-  The height of the line contents is normally determined from the
-maximum height of any character or image on that display line,
-including the final newline if there is one.  (A line that is
-continued doesn't include a final newline.)  In the most common case,
-the line height equals the height of the default frame font.
+  The height of the line contents is the maximum height of any
+character or image on that display line, including the final newline
+if there is one.  (A display line that is continued doesn't include a
+final newline.)  That is the default line height, if you do nothing to
+specify a greater height.  (In the most common case, this equals the
+height of the default frame font.)
 
-  There are several ways to explicitly control or change the line
-height, either by specifying an absolute height for the display line,
-or by adding additional vertical space below one or all lines.
+  There are several ways to explicitly specify a larger line height,
+either by specifying an absolute height for the display line, or by
+specifying vertical space.  However, no matter what you specify, the
+actual line height can never be less than the default.
 
 @kindex line-height @r{(text property)}
   A newline can have a @code{line-height} text or overlay property
 that controls the total height of the display line ending in that
 newline.
 
-  If the property value is a list @code{(@var{height} @var{total})},
-then @var{height} is used as the actual property value for the
-@code{line-height}, and @var{total} specifies the total displayed
-height of the line, so the line spacing added below the line equals
-the @var{total} height minus the actual line height.  In this case,
-the other ways to specify the line spacing are ignored.
+  If the property value is @code{t}, the newline character has no
+effect on the displayed height of the line---the visible contents
+alone determine the height.  This is useful for tiling small images
+(or image slices) without adding blank areas between the images.
 
-  If the property value is @code{t}, the displayed height of the
-line is exactly what its contents demand; no line-spacing is added.
-This case is useful for tiling small images or image slices without
-adding blank areas between the images.
+  If the property value is a list of the form @code{(@var{height}
+@var{total})}, that adds extra space @emph{below} the display line.
+First Emacs uses @var{height} as a height spec to control extra space
+@emph{above} the line; then it adds enough space @emph{below} the line
+to bring the total line height up to @var{total}.  In this case, the
+other ways to specify the line spacing are ignored.
 
-  If the property value is not @code{t}, it is a height spec.  A height
-spec stands for a numeric height value; this height spec specifies the
-actual line height, @var{line-height}.  There are several ways to
-write a height spec; here's how each of them translates into a numeric
-height:
+  Any other kind of property value is a height spec, which translates
+into a number---the specified line height.  There are several ways to
+write a height spec; here's how each of them translates into a number:
 
 @table @code
 @item @var{integer}
@@ -1633,11 +1634,10 @@ If the height spec is a cons of the format shown, the numeric height
 is @var{ratio} times the height of the contents of the line.
 @end table
 
-  Thus, any valid non-@code{t} property value specifies a height in pixels,
-@var{line-height}, one way or another.  If the line contents' height
-is less than @var{line-height}, Emacs adds extra vertical space above
-the line to achieve the total height @var{line-height}.  Otherwise,
-@var{line-height} has no effect.
+  Thus, any valid height spec determines the height in pixels, one way
+or another.  If the line contents' height is less than that, Emacs
+adds extra vertical space above the line to achieve the specified
+total height.
 
   If you don't specify the @code{line-height} property, the line's
 height consists of the contents' height plus the line spacing.
@@ -1662,9 +1662,9 @@ height.  This overrides line spacings specified for the frame.
 
 @kindex line-spacing @r{(text property)}
   Finally, a newline can have a @code{line-spacing} text or overlay
-property that controls the height of the display line ending with that
-newline.  The property value overrides the default frame line spacing
-and the buffer local @code{line-spacing} variable.
+property that overrides the default frame line spacing and the buffer
+local @code{line-spacing} variable, for the display line ending in
+that newline.
 
   One way or another, these mechanisms specify a Lisp value for the
 spacing of each line.  The value is a height spec, and it translates
@@ -2381,13 +2381,6 @@ expression in the list.  For example,
 allows the use of scalable fonts with registry @code{muleindian-2}.
 @end defvar
 
-@defun clear-face-cache &optional unload-p
-@tindex clear-face-cache
-This function clears the face cache for all frames.
-If @var{unload-p} is non-@code{nil}, that means to unload
-all unused fonts as well.
-@end defun
-
 @defvar face-font-rescale-alist
 This variable specifies scaling for certain faces.  Its value should
 be a list of elements of the form
@@ -4621,6 +4614,339 @@ buffer.  If @var{count-current} is non-@code{nil}, count any button at
 @var{pos} in the search, instead of starting at the next button.
 @end defun
 
+@node Abstract Display
+@section Abstract Display
+@cindex ewoc
+@cindex display, abstract
+@cindex display, arbitrary objects
+@cindex model/view/controller
+@cindex view part, model/view/controller
+
+  The Ewoc package constructs buffer text that represents a structure
+of Lisp objects, and updates the text to follow changes in that
+structure.  This is like the ``view'' component in the
+``model/view/controller'' design paradigm.
+
+  An @dfn{ewoc} is a structure that organizes information required to
+construct buffer text that represents certain Lisp data.  The buffer
+text of the ewoc has three parts, in order: first, fixed @dfn{header}
+text; next, textual descriptions of a series of data elements (Lisp
+objects that you specify); and last, fixed @dfn{footer} text.
+Specifically, an ewoc contains information on:
+
+@itemize @bullet
+@item
+The buffer which its text is generated in.
+
+@item
+The text's start position in the buffer.
+
+@item
+The header and footer strings.
+
+@item
+A doubly-linked chain of @dfn{nodes}, each of which contains:
+
+@itemize
+@item
+A @dfn{data element}, a single Lisp object.
+
+@item
+Links to the preceding and following nodes in the chain.
+@end itemize
+
+@item
+A @dfn{pretty-printer} function which is responsible for
+inserting the textual representation of a data
+element value into the current buffer.
+@end itemize
+
+  Typically, you define an ewoc with @code{ewoc-create}, and then pass
+the resulting ewoc structure to other functions in the Ewoc package to
+build nodes within it, and display it in the buffer.  Once it is
+displayed in the buffer, other functions determine the correspondance
+between buffer positions and nodes, move point from one node's textual
+representation to another, and so forth.  @xref{Abstract Display
+Functions}.
+
+  A node @dfn{encapsulates} a data element much the way a variable
+holds a value.  Normally, encapsulation occurs as a part of adding a
+node to the ewoc.  You can retrieve the data element value and place a
+new value in its place, like so:
+
+@lisp
+(ewoc-data @var{node})
+@result{} value
+
+(ewoc-set-data @var{node} @var{new-value})
+@result{} @var{new-value}
+@end lisp
+
+@noindent
+You can also use, as the data element value, a Lisp object (list or
+vector) that is a container for the ``real'' value, or an index into
+some other structure.  The example (@pxref{Abstract Display Example})
+uses the latter approach.
+
+  When the data changes, you will want to update the text in the
+buffer.  You can update all nodes by calling @code{ewoc-refresh}, or
+just specific nodes using @code{ewoc-invalidate}, or all nodes
+satisfying a predicate using @code{ewoc-map}.  Alternatively, you can
+delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
+and add new nodes in their place.  Deleting a node from an ewoc deletes
+its associated textual description from buffer, as well.
+
+@menu
+* Abstract Display Functions::
+* Abstract Display Example::
+@end menu
+
+@node Abstract Display Functions
+@subsection Abstract Display Functions
+
+  In this subsection, @var{ewoc} and @var{node} stand for the
+structures described above (@pxref{Abstract Display}), while
+@var{data} stands for an arbitrary Lisp object used as a data element.
+
+@defun ewoc-create pretty-printer &optional header footer nosep
+This constructs and returns a new ewoc, with no nodes (and thus no data
+elements).  @var{pretty-printer} should be a function that takes one
+argument, a data element of the sort you plan to use in this ewoc, and
+inserts its textual description at point using @code{insert} (and never
+@code{insert-before-markers}, because that would interfere with the
+Ewoc package's internal mechanisms).
+
+Normally, a newline is automatically inserted after the header,
+the footer and every node's textual description.  If @var{nosep}
+is non-@code{nil}, no newline is inserted.  This may be useful for
+displaying an entire ewoc on a single line, for example, or for
+making nodes ``invisible'' by arranging for @var{pretty-printer}
+to do nothing for those nodes.
+
+An ewoc maintains its text in the buffer that is current when
+you create it, so switch to the intended buffer before calling
+@code{ewoc-create}.
+@end defun
+
+@defun ewoc-buffer ewoc
+This returns the buffer where @var{ewoc} maintains its text.
+@end defun
+
+@defun ewoc-get-hf ewoc
+This returns a cons cell @code{(@var{header} . @var{footer})}
+made from @var{ewoc}'s header and footer.
+@end defun
+
+@defun ewoc-set-hf ewoc header footer
+This sets the header and footer of @var{ewoc} to the strings
+@var{header} and @var{footer}, respectively.
+@end defun
+
+@defun ewoc-enter-first ewoc data
+@defunx ewoc-enter-last ewoc data
+These add a new node encapsulating @var{data}, putting it, respectively,
+at the beginning or end of @var{ewoc}'s chain of nodes.
+@end defun
+
+@defun ewoc-enter-before ewoc node data
+@defunx ewoc-enter-after ewoc node data
+These add a new node encapsulating @var{data}, adding it to
+@var{ewoc} before or after @var{node}, respectively.
+@end defun
+
+@defun ewoc-prev ewoc node
+@defunx ewoc-next ewoc node
+These return, respectively, the previous node and the next node of @var{node}
+in @var{ewoc}.
+@end defun
+
+@defun ewoc-nth ewoc n
+This returns the node in @var{ewoc} found at zero-based index @var{n}.
+A negative @var{n} means count from the end.  @code{ewoc-nth} returns
+@code{nil} if @var{n} is out of range.
+@end defun
+
+@defun ewoc-data node
+This extracts the data encapsulated by @var{node} and returns it.
+@end defun
+
+@defun ewoc-set-data node data
+This sets the data encapsulated by @var{node} to @var{data}.
+@end defun
+
+@defun ewoc-locate ewoc &optional pos guess
+This determines the node in @var{ewoc} which contains point (or
+@var{pos} if specified), and returns that node.  If @var{ewoc} has no
+nodes, it returns @code{nil}.  If @var{pos} is before the first node,
+it returns the first node; if @var{pos} is after the last node, it returns
+the last node.  The optional third arg @var{guess}
+should be a node that is likely to be near @var{pos}; this doesn't
+alter the result, but makes the function run faster.
+@end defun
+
+@defun ewoc-location node
+This returns the start position of @var{node}.
+@end defun
+
+@defun ewoc-goto-prev ewoc arg
+@defunx ewoc-goto-next ewoc arg
+These move point to the previous or next, respectively, @var{arg}th node
+in @var{ewoc}.  @code{ewoc-goto-prev} does not move if it is already at
+the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
+moves past the last node, returning @code{nil}.  Excepting this special
+case, these functions return the node moved to.
+@end defun
+
+@defun ewoc-goto-node ewoc node
+This moves point to the start of @var{node} in @var{ewoc}.
+@end defun
+
+@defun ewoc-refresh ewoc
+This function regenerates the text of @var{ewoc}.  It works by
+deleting the text between the header and the footer, i.e., all the
+data elements' representations, and then calling the pretty-printer
+function for each node, one by one, in order.
+@end defun
+
+@defun ewoc-invalidate ewoc &rest nodes
+This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
+@var{ewoc} are updated instead of the entire set.
+@end defun
+
+@defun ewoc-delete ewoc &rest nodes
+This deletes each node in @var{nodes} from @var{ewoc}.
+@end defun
+
+@defun ewoc-filter ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc} and
+deletes those nodes for which @var{predicate} returns @code{nil}.
+Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-collect ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc}
+and returns a list of those elements for which @var{predicate}
+returns non-@code{nil}.  The elements in the list are ordered
+as in the buffer.  Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-map map-function ewoc &rest args
+This calls @var{map-function} for each data element in @var{ewoc} and
+updates those nodes for which @var{map-function} returns non-@code{nil}.
+Any @var{args} are passed to @var{map-function}.
+@end defun
+
+@node Abstract Display Example
+@subsection Abstract Display Example
+
+  Here is a simple example using functions of the ewoc package to
+implement a ``color components display'', an area in a buffer that
+represents a vector of three integers (itself representing a 24-bit RGB
+value) in various ways.
+
+@example
+(setq colorcomp-ewoc nil
+      colorcomp-data nil
+      colorcomp-mode-map nil
+      colorcomp-labels ["Red" "Green" "Blue"])
+
+(defun colorcomp-pp (data)
+  (if data
+      (let ((comp (aref colorcomp-data data)))
+        (insert (aref colorcomp-labels data) "\t: #x"
+                (format "%02X" comp) " "
+                (make-string (ash comp -2) ?#) "\n"))
+    (let ((cstr (format "#%02X%02X%02X"
+                        (aref colorcomp-data 0)
+                        (aref colorcomp-data 1)
+                        (aref colorcomp-data 2)))
+          (samp " (sample text) "))
+      (insert "Color\t: "
+              (propertize samp 'face `(foreground-color . ,cstr))
+              (propertize samp 'face `(background-color . ,cstr))
+              "\n"))))
+
+(defun colorcomp (color)
+  "Allow fiddling with COLOR in a new buffer.
+The buffer is in Color Components mode."
+  (interactive "sColor (name or #RGB or #RRGGBB): ")
+  (when (string= "" color)
+    (setq color "green"))
+  (unless (color-values color)
+    (error "No such color: %S" color))
+  (switch-to-buffer
+   (generate-new-buffer (format "originally: %s" color)))
+  (kill-all-local-variables)
+  (setq major-mode 'colorcomp-mode
+        mode-name "Color Components")
+  (use-local-map colorcomp-mode-map)
+  (erase-buffer)
+  (buffer-disable-undo)
+  (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
+                                     (color-values color))))
+        (ewoc (ewoc-create 'colorcomp-pp
+                           "\nColor Components\n\n"
+                           (substitute-command-keys
+                            "\n\\@{colorcomp-mode-map@}"))))
+    (set (make-local-variable 'colorcomp-data) data)
+    (set (make-local-variable 'colorcomp-ewoc) ewoc)
+    (ewoc-enter-last ewoc 0)
+    (ewoc-enter-last ewoc 1)
+    (ewoc-enter-last ewoc 2)
+    (ewoc-enter-last ewoc nil)))
+@end example
+
+@cindex controller part, model/view/controller
+  This example can be extended to be a ``color selection widget'' (in
+other words, the controller part of the ``model/view/controller''
+design paradigm) by defining commands to modify @code{colorcomp-data}
+and to ``finish'' the selection process, and a keymap to tie it all
+together conveniently.
+
+@example
+(defun colorcomp-mod (index limit delta)
+  (let ((cur (aref colorcomp-data index)))
+    (unless (= limit cur)
+      (aset colorcomp-data index (+ cur delta)))
+    (ewoc-invalidate
+     colorcomp-ewoc
+     (ewoc-nth colorcomp-ewoc index)
+     (ewoc-nth colorcomp-ewoc -1))))
+
+(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
+(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
+(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
+(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
+(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
+(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
+
+(defun colorcomp-copy-as-kill-and-exit ()
+  "Copy the color components into the kill ring and kill the buffer.
+The string is formatted #RRGGBB (hash followed by six hex digits)."
+  (interactive)
+  (kill-new (format "#%02X%02X%02X"
+                    (aref colorcomp-data 0)
+                    (aref colorcomp-data 1)
+                    (aref colorcomp-data 2)))
+  (kill-buffer nil))
+
+(setq colorcomp-mode-map
+      (let ((m (make-sparse-keymap)))
+        (suppress-keymap m)
+        (define-key m "i" 'colorcomp-R-less)
+        (define-key m "o" 'colorcomp-R-more)
+        (define-key m "k" 'colorcomp-G-less)
+        (define-key m "l" 'colorcomp-G-more)
+        (define-key m "," 'colorcomp-B-less)
+        (define-key m "." 'colorcomp-B-more)
+        (define-key m " " 'colorcomp-copy-as-kill-and-exit)
+        m))
+@end example
+
+Note that we never modify the data in each node, which is fixed when the
+ewoc is created to be either @code{nil} or an index into the vector
+@code{colorcomp-data}, the actual color components.
+
 @node Blinking
 @section Blinking Parentheses
 @cindex parenthesis matching
diff --git a/lispref/elisp.texi b/lispref/elisp.texi
index 7d7bfa0ab6e..5d667c0fd14 100644
--- a/lispref/elisp.texi
+++ b/lispref/elisp.texi
@@ -590,7 +590,8 @@ Defining Commands
 
 Keymaps
 
-* Keymap Terminology::          Definitions of terms pertaining to keymaps.
+* Key Sequences::               Key sequences as Lisp objects.
+* Keymap Basics::               Basic concepts of keymaps.
 * Format of Keymaps::           What a keymap looks like as a Lisp object.
 * Creating Keymaps::            Functions to create and copy keymaps.
 * Inheritance and Keymaps::     How one keymap can inherit the bindings
@@ -1006,6 +1007,7 @@ Emacs Display
 * Display Property::        Enabling special display features.
 * Images::                  Displaying images in Emacs buffers.
 * Buttons::                 Adding clickable buttons to Emacs buffers.
+* Abstract Display::        Emacs' Widget for Object Collections.
 * Blinking::                How Emacs shows the matching open parenthesis.
 * Usual Display::           The usual conventions for displaying nonprinting chars.
 * Display Tables::          How to specify other conventions.
diff --git a/lispref/files.texi b/lispref/files.texi
index 0d944771a2e..f7af725f191 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -1431,7 +1431,7 @@ with @code{add-name-to-file} and then deleting @var{filename} has the
 same effect as renaming, aside from momentary intermediate states.
 @end deffn
 
-@deffn Command copy-file oldname newname &optional ok-if-exists time mustbenew
+@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
 This command copies the file @var{oldname} to @var{newname}.  An
 error is signaled if @var{oldname} does not exist.  If @var{newname}
 names a directory, it copies @var{oldname} into that directory,
@@ -1440,16 +1440,18 @@ preserving its final name component.
 If @var{time} is non-@code{nil}, then this function gives the new file
 the same last-modified time that the old one has.  (This works on only
 some operating systems.)  If setting the time gets an error,
-@code{copy-file} signals a @code{file-date-error} error.
+@code{copy-file} signals a @code{file-date-error} error.  In an
+interactive call, a prefix argument specifies a non-@code{nil} value
+for @var{time}.
 
 This function copies the file modes, too.
 
-In an interactive call, a prefix argument specifies a non-@code{nil}
-value for @var{time}.
-
-The argument @var{mustbenew} controls whether an existing file can be
-overwritten.  It works like the similarly-named argument of
-@code{write-region} (@pxref{Writing to Files, mustbenew}).
+If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
+system decide the user and group ownership of the new file (this is
+usually set to the user running Emacs).  If @var{preserve-uid-gid} is
+non-@code{nil}, we attempt to copy the user and group ownership of the
+file.  This works only on some operating systems, and only if you have
+the correct permissions to do so.
 @end deffn
 
 @deffn Command make-symbolic-link filename newname  &optional ok-if-exists
diff --git a/lispref/help.texi b/lispref/help.texi
index 0fe996dfd7c..6173c746d1e 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -497,7 +497,7 @@ can also be used as a rough inverse for @code{key-description}.  You
 call it with a string containing key descriptions, separated by spaces;
 it returns a string or vector containing the corresponding events.
 (This may or may not be a single valid key sequence, depending on what
-events you use; @pxref{Keymap Terminology}.)  If @var{need-vector} is
+events you use; @pxref{Key Sequences}.)  If @var{need-vector} is
 non-@code{nil}, the return value is always a vector.
 @end defun
 
diff --git a/lispref/internals.texi b/lispref/internals.texi
index bc35e215574..fa96687d1d8 100644
--- a/lispref/internals.texi
+++ b/lispref/internals.texi
@@ -160,7 +160,8 @@ the preloaded libraries, @file{temacs} allocates dynamic memory for
 the part that didn't fit.  If that happens, you should increase the
 compilation parameter @code{PURESIZE} in the file
 @file{src/puresize.h} and rebuild Emacs, even though the resulting
-image will work.  Such an overflow normally won't happen unless you
+image will work: garbage collection is disabled in this situation,
+causing a memory leak.  Such an overflow normally won't happen unless you
 try to preload additional libraries or add features to the standard
 ones.  Emacs will display a warning about the overflow when it
 starts.
@@ -348,6 +349,10 @@ operating system, but which are currently not in use.  (A string
 object consists of a header and the storage for the string text
 itself; the latter is only allocated when the string is created.)
 @end table
+
+If there was overflow in pure space (see the previous section),
+@code{garbage-collect} returns @code{nil}, because a real garbage
+collection can not be done in this situation.
 @end deffn
 
 @defopt garbage-collection-messages
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index 39a57eddf13..f6779b247d0 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -16,7 +16,8 @@ to look up the next input event; this continues until a command is
 found.  The whole process is called @dfn{key lookup}.
 
 @menu
-* Keymap Terminology::          Definitions of terms pertaining to keymaps.
+* Key Sequences::               Key sequences as Lisp objects.
+* Keymap Basics::               Basic concepts of keymaps.
 * Format of Keymaps::           What a keymap looks like as a Lisp object.
 * Creating Keymaps::            Functions to create and copy keymaps.
 * Inheritance and Keymaps::     How one keymap can inherit the bindings
@@ -37,32 +38,80 @@ found.  The whole process is called @dfn{key lookup}.
 * Menu Keymaps::                Defining a menu as a keymap.
 @end menu
 
-@node Keymap Terminology
-@section Keymap Terminology
+@node Key Sequences
+@section Key Sequences
 @cindex key
 @cindex keystroke
+@cindex key sequence
+
+  A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
+or more input events that form a unit.  Input events include
+characters, function keys, and mouse actions (@pxref{Input Events}).
+The Emacs Lisp representation for a key sequence is a string or
+vector.  Unless otherwise stated, any Emacs Lisp function that accepts
+a key sequence as an argument can handle both representations.
+
+  In the string representation, alphanumeric characters ordinarily
+stand for themselves; for example, @code{"a"} represents @kbd{a} and
+and @code{"2"} represents @kbd{2}.  Control character events are
+prefixed by the substring @code{"\C-"}, and meta characters by
+@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
+In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
+are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and
+@code{"\d"} respectively.  The string representation of a complete key
+sequence is the concatenation of the string representations of the
+constituent events; thus, @code{"\C-xl"} represents the key sequence
+@kbd{C-x l}.
+
+  Key sequences containing function keys, mouse button events, or
+non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+represented as strings; they have to be represented as vectors.
+
+  In the vector representation, each element of the vector represents
+an input event, in its Lisp form.  @xref{Input Events}.  For example,
+the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}.
+
+  For examples of key sequences written in string and vector
+representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}.
+
+@defmac kbd keyseq-text
+This macro converts the text @var{keyseq-text} (a string constant)
+into a key sequence (a string or vector constant).  The contents of
+@var{keyseq-text} should describe the key sequence using almost the same
+syntax used in this manual.  More precisely, it uses the same syntax
+that Edit Macro mode uses for editing keyboard macros (@pxref{Edit
+Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround
+function key names with @samp{<@dots{}>}.
+
+@example
+(kbd "C-x") @result{} "\C-x"
+(kbd "C-x C-f") @result{} "\C-x\C-f"
+(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
+(kbd "X") @result{} "X"
+(kbd "RET") @result{} "\^M"
+(kbd "C-c SPC") @result{} "\C-c@ "
+(kbd "<f1> SPC") @result{} [f1 32]
+(kbd "C-M-<down>") @result{} [C-M-down]
+@end example
+@end defmac
+
+@node Keymap Basics
+@section Keymap Basics
 @cindex key binding
 @cindex binding of a key
 @cindex complete key
 @cindex undefined key
 
-  A @dfn{keymap} is a table mapping event types to definitions (which
-can be any Lisp objects, though only certain types are meaningful for
-execution by the command loop).  Given an event (or an event type) and a
-keymap, Emacs can get the event's definition.  Events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
-
-  A sequence of input events that form a unit is called a
-@dfn{key sequence}, or @dfn{key} for short.  A sequence of one event
-is always a key sequence, and so are some multi-event sequences.
+  A keymap is a Lisp data structure that specifies @dfn{key bindings}
+for various key sequences.
 
-  A keymap determines a binding or definition for any key sequence.  If
-the key sequence is a single event, its binding is the definition of the
-event in the keymap.  The binding of a key sequence of more than one
-event is found by an iterative process: the binding of the first event
-is found, and must be a keymap; then the second event's binding is found
-in that keymap, and so on until all the events in the key sequence are
-used up.
+  A single keymap directly specifies definitions for individual
+events.  When a key sequence consists of a single event, its binding
+in a keymap is the keymap's definition for that event.  The binding of
+a longer key sequence is found by an iterative process: first find the
+definition of the first event (which must itself be a keymap); then
+find the second event's definition in that keymap, and so on until all
+the events in the key sequence have been processed.
 
   If the binding of a key sequence is a keymap, we call the key sequence
 a @dfn{prefix key}.  Otherwise, we call it a @dfn{complete key} (because
@@ -98,30 +147,6 @@ precedence over) the corresponding global bindings.  The minor mode
 keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
 for details.
 
-  The Emacs Lisp representation for a key sequence is a string or vector.
-You can enter key sequence constants using the ordinary string or vector
-representation; it is also convenient to use @code{kbd}:
-
-@defmac kbd keyseq-text
-This macro converts the text @var{keyseq-text} (a string constant)
-into a key sequence (a string or vector constant).  The contents
-of @var{keyseq-text} should describe the key sequence using the syntax
-used in this manual.  More precisely, it uses the same syntax that
-Edit Macro mode uses for editing keyboard macros (@pxref{Edit Keyboard
-Macro,,, emacs, The GNU Emacs Manual}).
-
-@example
-(kbd "C-x") @result{} "\C-x"
-(kbd "C-x C-f") @result{} "\C-x\C-f"
-(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
-(kbd "X") @result{} "X"
-(kbd "RET") @result{} "\^M"
-(kbd "C-c SPC") @result{} "\C-c@ "
-(kbd "<f1> SPC") @result{} [f1 32]
-(kbd "C-M-<down>") @result{} [C-M-down]
-@end example
-@end defmac
-
 @node Format of Keymaps
 @section Format of Keymaps
 @cindex format of keymaps
@@ -129,7 +154,7 @@ Macro,,, emacs, The GNU Emacs Manual}).
 @cindex full keymap
 @cindex sparse keymap
 
-  A keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
+  Each keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
 remaining elements of the list define the key bindings of the keymap.
 A symbol whose function definition is a keymap is also a keymap.  Use
 the function @code{keymapp} (see below) to test whether an object is a
@@ -1197,8 +1222,8 @@ numeric codes for the modifier bits don't appear in compiled files.
   For the functions below, an error is signaled if @var{keymap} is not
 a keymap or if @var{key} is not a string or vector representing a key
 sequence.  You can use event types (symbols) as shorthand for events
-that are lists.  The @code{kbd} macro (@pxref{Keymap Terminology}) is
-a convenient way to specify the key sequence.
+that are lists.  The @code{kbd} macro (@pxref{Key Sequences}) is a
+convenient way to specify the key sequence.
 
 @defun define-key keymap key binding
 This function sets the binding for @var{key} in @var{keymap}.  (If
diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index f69cf03deac..20a049f037b 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -110,7 +110,7 @@ middle of a Lisp function.  Instead, do all minibuffer input as part of
 reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
-@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method keep-all
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
 This function is the most general way to get input through the
 minibuffer.  By default, it accepts arbitrary text and returns it as a
 string; however, if @var{read} is non-@code{nil}, then it uses
@@ -162,9 +162,6 @@ the setting of @code{enable-multibyte-characters} (@pxref{Text
 Representations}) from whichever buffer was current before entering the
 minibuffer.
 
-If @var{keep-all} is non-@code{nil}, even empty and duplicate inputs
-are added to the history list.
-
 Use of @var{initial-contents} is mostly deprecated; we recommend using
 a non-@code{nil} value only in conjunction with specifying a cons cell
 for @var{hist}.  @xref{Initial Input}.
@@ -463,6 +460,14 @@ However, if @var{keep-all} is non-@code{nil}, that says not to remove
 duplicates, and to add @var{newelt} to the list even if it is empty.
 @end defun
 
+@defvar history-add-new-input
+If the value of this variable is @code{nil}, standard functions that
+read from the minibuffer don't add new elements to the history list.
+This lets Lisp programs explicitly manage input history by using
+@code{add-to-history}.  By default, @code{history-add-new-input} is
+set to a non-@code{nil} value.
+@end defvar
+
 @defvar history-length
 The value of this variable specifies the maximum length for all
 history lists that don't specify their own maximum lengths.  If the
diff --git a/lispref/modes.texi b/lispref/modes.texi
index 9e55ca847fc..7c4896d9532 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -1927,6 +1927,10 @@ The current buffer name, obtained with the @code{buffer-name} function.
 @item %c
 The current column number of point.
 
+@item %e
+When Emacs is nearly out of memory for Lisp objects, a brief message
+saying so.  Otherwise, this is empty.
+
 @item %f
 The visited file name, obtained with the @code{buffer-file-name}
 function.  @xref{Buffer File Name}.
@@ -1972,6 +1976,12 @@ Whether the visited file is a text file or a binary file.  This is a
 meaningful distinction only on certain operating systems (@pxref{MS-DOS
 File Types}).
 
+@item %z
+The mnemonics of buffer, terminal, and keyboard coding systems.
+
+@item %Z
+Like @samp{%z}, but including the end-of-line format.
+
 @item %*
 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index 0f4a70404af..2224fdbd436 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -1103,11 +1103,11 @@ The argument @var{operation} should be a symbol, any one of
 @code{insert-file-contents}, @code{write-region},
 @code{start-process}, @code{call-process}, @code{call-process-region},
 or @code{open-network-stream}.  These are the names of the Emacs I/O
-primitives that can do coding system conversion.
+primitives that can do character code and eol conversion.
 
 The remaining arguments should be the same arguments that might be given
-to that I/O primitive.  Depending on the primitive, one of those
-arguments is selected as the @dfn{target}.  For example, if
+to the corresponding I/O primitive.  Depending on the primitive, one
+of those arguments is selected as the @dfn{target}.  For example, if
 @var{operation} does file I/O, whichever argument specifies the file
 name is the target.  For subprocess primitives, the process name is the
 target.  For @code{open-network-stream}, the target is the service name
@@ -1115,7 +1115,19 @@ or port number.
 
 Depending on @var{operation}, this function looks up the target in
 @code{file-coding-system-alist}, @code{process-coding-system-alist},
-or @code{network-coding-system-alist}.
+or @code{network-coding-system-alist}.  If the target is found in the
+alist, @code{find-operation-coding-system} returns its association in
+the alist; otherwise it returns @code{nil}.
+
+If @var{operation} is @code{insert-file-contents}, the argument
+corresponding to the target may be a cons cell of the form
+@code{(@var{filename} . @var{buffer})}).  In that case, @var{filename}
+is a file name to look up in @code{file-coding-system-alist}, and
+@var{buffer} is a buffer that contains the file's contents (not yet
+decoded).  If @code{file-coding-system-alist} specifies a function to
+call for this file, and that function needs to examine the file's
+contents (as it usually does), it should examine the contents of
+@var{buffer} instead of reading the file.
 @end defun
 
 @node Specifying Coding Systems
diff --git a/lispref/objects.texi b/lispref/objects.texi
index 5665e5beee6..688fd0be398 100644
--- a/lispref/objects.texi
+++ b/lispref/objects.texi
@@ -431,6 +431,19 @@ Numerically, the
 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
 @end ifnottex
 
+@cindex unicode character escape
+  Emacs provides a syntax for specifying characters by their Unicode
+code points.  @code{?\u@var{nnnn}} represents a character that maps to
+the Unicode code point @samp{U+@var{nnnn}}.  There is a slightly
+different syntax for specifying characters with code points above
+@code{#xFFFF}; @code{\U00@var{nnnnnn}} represents the character whose
+Unicode code point is @samp{U+@var{nnnnnn}}, if such a character
+is supported by Emacs.
+
+  Unlike in some other programming languages, in Emacs Lisp this
+syntax is available for character literals, and (see later) in
+strings, but not elsewhere.
+
 @cindex @samp{\} in character constant
 @cindex backslash in character constant
 @cindex octal character code
diff --git a/lispref/processes.texi b/lispref/processes.texi
index 9eb733236a9..0f0b617e36c 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -2185,11 +2185,11 @@ field name is specified, the value is bound to that field name.
 @var{form} can access and update these dynamically bound variables:
 
 @table @code
-@item raw-data
+@item bindat-raw
 The data as a byte array.
 
-@item pos
-Current position of the unpacking or packing operation.
+@item bindat-idx
+Current index into bindat-raw of the unpacking or packing operation.
 
 @item struct
 Alist.
@@ -2231,23 +2231,26 @@ of @var{form}.  A non-@code{nil} result indicates a match.
 @end itemize
 
 @item repeat @var{count} @var{field-spec}@dots{}
+Process the set of @var{field-spec}s recursively, in order, and loop
+starting from the first one, for @var{count} times overall (looping
+@code{@var{count} @minus{} 1} times).
 @var{count} may be an integer, or a list of one element naming a
 previous field.  For correct operation, each @var{field-spec} must
 include a name.
-@c ??? What does it MEAN?
 @end table
 
 @node Bindat Functions
 @subsection Functions to Unpack and Pack Bytes
 
   In the following documentation, @var{spec} refers to a data layout
-specification, @code{raw-data} to a byte array, and @var{struct} to an
+specification, @code{bindat-raw} to a byte array, and @var{struct} to an
 alist representing unpacked field data.
 
-@defun bindat-unpack spec raw-data &optional pos
-This function unpacks data from the byte array @code{raw-data}
+@defun bindat-unpack spec bindat-raw &optional bindat-idx
+This function unpacks data from the unibyte string or byte
+array @code{bindat-raw}
 according to @var{spec}.  Normally this starts unpacking at the
-beginning of the byte array, but if @var{pos} is non-@code{nil}, it
+beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
 specifies a zero-based starting position to use instead.
 
 The value is an alist or nested alist in which each element describes
@@ -2267,23 +2270,29 @@ field @code{c} in the third element of subfield @code{b} of field
 @code{a}.  (This corresponds to @code{struct.a.b[2].c} in C.)
 @end defun
 
+  Although packing and unpacking operations change the organization of
+data (in memory), they preserve the data's @dfn{total length}, which is
+the sum of all the fields' lengths, in bytes.  This value is not
+generally inherent in either the specification or alist alone; instead,
+both pieces of information contribute to its calculation.  Likewise, the
+length of a string or array being unpacked may be longer than the data's
+total length as described by the specification.
+
 @defun bindat-length spec struct
-@c ??? I don't understand this at all -- rms
-This function returns the length in bytes of @var{struct}, according
-to @var{spec}.
+This function returns the total length of the data in @var{struct},
+according to @var{spec}.
 @end defun
 
-@defun bindat-pack spec struct &optional raw-data pos
+@defun bindat-pack spec struct &optional bindat-raw bindat-idx
 This function returns a byte array packed according to @var{spec} from
 the data in the alist @var{struct}.  Normally it creates and fills a
-new byte array starting at the beginning.  However, if @var{raw-data}
-is non-@code{nil}, it specifies a pre-allocated string or vector to
-pack into.  If @var{pos} is non-@code{nil}, it specifies the starting
-offset for packing into @code{raw-data}.
+new byte array starting at the beginning.  However, if @var{bindat-raw}
+is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
+pack into.  If @var{bindat-idx} is non-@code{nil}, it specifies the starting
+offset for packing into @code{bindat-raw}.
 
-@c ??? Isn't this a bug?  Shouldn't it always be unibyte?
-Note: The result is a multibyte string; use @code{string-make-unibyte}
-on it to make it unibyte if necessary.
+When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
+meets or exceeds the total length to avoid an out-of-range error.
 @end defun
 
 @defun bindat-ip-to-string ip
@@ -2367,18 +2376,17 @@ COOKIES, indicates the border between entries."
     (with-temp-buffer
       (set-buffer-multibyte nil)
       (insert
-       (string-make-unibyte
-        (bindat-pack
-         fcookie-index-spec
-         `((:version . 2)
-           (:count . ,count)
-           (:longest . ,max)
-           (:shortest . ,min)
-           (:flags . 0)
-           (:delim . ,delim)
-           (:offset . ,(mapcar (lambda (o)
-                                 (list (cons :foo o)))
-                               (nreverse offsets)))))))
+       (bindat-pack
+        fcookie-index-spec
+        `((:version . 2)
+          (:count . ,count)
+          (:longest . ,max)
+          (:shortest . ,min)
+          (:flags . 0)
+          (:delim . ,delim)
+          (:offset . ,(mapcar (lambda (o)
+                                (list (cons :foo o)))
+                              (nreverse offsets))))))
       (let ((coding-system-for-write 'raw-text-unix))
         (write-file (or index (concat cookies ".dat")))))))
 @end lisp
diff --git a/lispref/text.texi b/lispref/text.texi
index c9f1a83a74c..426ec1ef00f 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -2967,7 +2967,8 @@ time you want to specify a particular attribute for certain text.
 @item
 A cons cell of the form @code{(foreground-color . @var{color-name})} or
 @code{(background-color . @var{color-name})}.  These elements specify
-just the foreground color or just the background color.
+just the foreground color or just the background color.  @xref{Color
+Names}, for the supported forms of @var{color-name}.
 
 @code{(foreground-color . @var{color-name})} is equivalent to
 specifying @code{(:foreground @var{color-name})}, and likewise for the
diff --git a/lispref/tips.texi b/lispref/tips.texi
index 889ac3e6a6d..6ad1c166e5b 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -35,6 +35,7 @@ all.
 @node Coding Conventions
 @section Emacs Lisp Coding Conventions
 
+@cindex coding conventions in Emacs Lisp
   Here are conventions that you should follow when writing Emacs Lisp
 code intended for widespread use:
 
@@ -52,9 +53,9 @@ don't postpone it.
 @item
 Since all global variables share the same name space, and all
 functions share another name space, you should choose a short word to
-distinguish your program from other Lisp programs.@footnote{The
+distinguish your program from other Lisp programs@footnote{The
 benefits of a Common Lisp-style package system are considered not to
-outweigh the costs.}  Then take care to begin the names of all global
+outweigh the costs.}.  Then take care to begin the names of all global
 variables, constants, and functions in your program with the chosen
 prefix.  This helps avoid name conflicts.
 
@@ -173,9 +174,28 @@ compatibility issues.
 @end example
 
 @item
-Redefining (or advising) an Emacs primitive is discouraged.  It may do
+Redefining (or advising) an Emacs primitive is a bad idea.  It may do
 the right thing for a particular program, but there is no telling what
-other programs might break as a result.
+other programs might break as a result.  In any case, it is a problem
+for debugging, because the two advised function doesn't do what its
+source code says it does.  If the programmer investigating the problem
+is unaware that there is advice on the function, the experience can be
+very frustrating.
+
+We hope to remove all the places in Emacs that advise primitives.
+In the mean time, please don't add any more.
+
+@item
+It is likewise a bad idea for one Lisp package to advise a function
+in another Lisp package.
+
+@item
+Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
+Loading}) in libraries and packages.  This feature is meant for
+personal customizations; using it in a Lisp program is unclean because
+it modifies the behavior of another Lisp file in an invisible way.
+This is an obstacle for debugging, much like advising a function in
+the other package.
 
 @item
 If a file does replace any of the functions or library programs of
@@ -204,6 +224,32 @@ only for special-purpose buffers.)  The users will find Emacs more
 coherent if all libraries use the same conventions.
 
 @item
+If your program contains non-ASCII characters in string or character
+constants, you should make sure Emacs always decodes these characters
+the same way, regardless of the user's settings.  There are two ways
+to do that:
+
+@itemize -
+@item
+Use coding system @code{emacs-mule}, and specify that for
+@code{coding} in the @samp{-*-} line or the local variables list.
+
+@example
+;; XXX.el  -*- coding: emacs-mule; -*-
+@end example
+
+@item
+Use one of the coding systems based on ISO 2022 (such as
+iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at
+the end for @code{coding}.  (The @samp{!} turns off any possible
+character translation.)
+
+@example
+;; XXX.el -*- coding: iso-latin-2!; -*-
+@end example
+@end itemize
+
+@item
 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
 default indentation parameters.
 
diff --git a/lispref/windows.texi b/lispref/windows.texi
index a2746889633..af73339a311 100644
--- a/lispref/windows.texi
+++ b/lispref/windows.texi
@@ -161,10 +161,8 @@ The two ``halves'' of the split window initially display the same buffer
 previously visible in the window that was split.
 
 @deffn Command split-window &optional window size horizontal
-This function splits @var{window} into two windows.  The original
-window @var{window} remains the selected window, but occupies only
-part of its former screen area.  The rest is occupied by a newly created
-window which is returned as the value of this function.
+This function splits a new window out of @var{window}'s screen area.
+It returns the new window.
 
 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
 two side by side windows.  The original window @var{window} keeps the
@@ -175,11 +173,13 @@ lines to the new window.  The original window is therefore the
 left-hand or upper of the two, and the new window is the right-hand or
 lower.
 
-If @var{window} is omitted or @code{nil}, then the selected window is
-split.  If @var{size} is omitted or @code{nil}, then @var{window} is
-divided evenly into two parts.  (If there is an odd line, it is
-allocated to the new window.)  When @code{split-window} is called
-interactively, all its arguments are @code{nil}.
+If @var{window} is omitted or @code{nil}, that stands for the selected
+window.  When you split the selected window, it remains selected.
+
+If @var{size} is omitted or @code{nil}, then @var{window} is divided
+evenly into two parts.  (If there is an odd line, it is allocated to
+the new window.)  When @code{split-window} is called interactively,
+all its arguments are @code{nil}.
 
 If splitting would result in making a window that is smaller than
 @code{window-min-height} or @code{window-min-width}, the function