Merged from miles@gnu.org--gnu-2005 (patch 423-434)

Patches applied:

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-423
   Update from CVS

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-424
   Update from CVS

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-425
   Remove "-face" suffix from gnus faces

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-426
   Update from CVS

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-427
   Update from CVS

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-428
   Remove "-face" suffix from MH-E faces

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-429
   Update from CVS

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-430
   Remove "-face" suffix from cc-mode faces

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-431
   Remove "-face" suffix from eshell faces

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-432
   Remove "-face" suffix from ediff faces

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-433
   Update from CVS

 * miles@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-434
   Update from CVS

git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-351

26 files changed, 868 insertions, 299 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index c565e8bdb5f..50bfc91479f 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,75 @@
+2005-06-19  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * lists.texi (Rings): Various minor clarifications and corrections.
+
+2005-06-18  Richard M. Stallman  <rms@gnu.org>
+
+        * functions.texi (Obsolete Functions): Simplify.
+
+        * variables.texi (Variable Aliases): Simplify.
+
+        * anti.texi, backups.texi, compile.texi, customization.texi:
+        * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi:
+        * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi:
+        * os.texi, processes.texi, searching.texi, strings.texi, text.texi:
+        * variables.texi: Fix formatting ugliness.
+
+        * elisp.texi: Add links to Rings and Byte Packing.
+        Update version and copyright years.
+
+        * minibuf.texi: Fix formatting ugliness.
+        (Completion Commands): Move keymap vars to the end
+        and vars completing-read binds to the top.
+
+2005-06-17  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * processes.texi: Fix typos.
+        (Bindat Spec): Correct Texinfo error.
+        (Byte Packing): Fix ungrammatical sentence.
+
+2005-06-17  Thien-Thi Nguyen  <ttn@gnu.org>
+
+        * lists.texi (Rings): New node.
+        (Lists): Add it to menu.
+
+        * processes.texi (Byte Packing): New node.
+        (Processes): Add it to menu.
+
+2005-06-17  Richard M. Stallman  <rms@gnu.org>
+
+        * syntax.texi (Parsing Expressions): Fix texinfo usage.
+
+        * help.texi (Documentation Basics): Explain the xref to
+        Documentation Tips.
+
+        * debugging.texi (Debugger Commands): Minor fix.
+
+2005-06-16  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * edebug.texi (Instrumenting): Eliminate duplicate link.
+        (Specification List): Replace references to "below", referring to
+        a later node, with one @ref to that node.
+
+        * os.texi (Timers): Timers should save and restore the match data
+        if they change it.
+
+        * debugging.texi (Debugger Commands): Mention that the Lisp
+        debugger can not step through primitive functions.
+
+2005-06-16  Juanma Barranquero  <lekktu@gmail.com>
+
+        * functions.texi (Obsolete Functions): Update argument names of
+        `make-obsolete' and `define-obsolete-function-alias'.
+
+        * variables.texi (Variable Aliases): Update argument names of
+        `defvaralias', `make-obsolete-variable' and
+        `define-obsolete-variable-alias'.
+
+2005-06-15  Kim F. Storm  <storm@cua.dk>
+
+        * searching.texi (Entire Match Data): Rephrase warnings about
+        evaporate arg to match-data and set-match-data.
+
 2005-06-14  Luc Teirlinck  <teirllm@auburn.edu>
 
         * elisp.texi (Top): Update detailed menu.
@@ -50,7 +122,7 @@
 
 2005-06-10  Luc Teirlinck  <teirllm@auburn.edu>
 
-        * syntax.texi (Parsing Exprssions): Fix Texinfo error.
+        * syntax.texi (Parsing Expressions): Fix Texinfo error.
 
 2005-06-10  Stefan Monnier  <monnier@iro.umontreal.ca>
 
diff --git a/lispref/anti.texi b/lispref/anti.texi
index 46375f3f157..c7a72f04df8 100644
--- a/lispref/anti.texi
+++ b/lispref/anti.texi
@@ -164,9 +164,10 @@ the sentinel.
 @item
 Many programming shortcuts have been deleted, to provide you with the
 enjoyment of ``rolling your own''.  The macros @code{while-no-input},
-@code{with-local-quit}, @code{with-selected-window},
-@code{dynamic-completion-table}, and @code{lazy-completion-table} no
-longer exist.  Also, there are no built-in progress reporters.
+@code{with-local-quit}, and @code{with-selected-window}, along with
+@code{dynamic-completion-table} and @code{lazy-completion-table} no
+longer exist.  Also, there are no built-in progress reporters;
+with Emacs, you can take progress for granted.
 
 @item
 Variable aliases are no longer supported.  Aliases are for functions,
diff --git a/lispref/backups.texi b/lispref/backups.texi
index 8db24665a54..1ba7ed1b931 100644
--- a/lispref/backups.texi
+++ b/lispref/backups.texi
@@ -589,10 +589,10 @@ This function auto-saves all buffers that need to be auto-saved.  It
 saves all buffers for which auto-saving is enabled and that have been
 changed since the previous auto-save.
 
-Normally, if any buffers are auto-saved, a message that says
-@samp{Auto-saving...} is displayed in the echo area while auto-saving is
-going on.  However, if @var{no-message} is non-@code{nil}, the message
-is inhibited.
+If any buffers are auto-saved, @code{do-auto-save} normally displays a
+message saying @samp{Auto-saving...} in the echo area while
+auto-saving is going on.  However, if @var{no-message} is
+non-@code{nil}, the message is inhibited.
 
 If @var{current-only} is non-@code{nil}, only the current buffer
 is auto-saved.
diff --git a/lispref/compile.texi b/lispref/compile.texi
index 91c0661a99e..951a090e0da 100644
--- a/lispref/compile.texi
+++ b/lispref/compile.texi
@@ -426,7 +426,7 @@ to what @code{eval-when-compile} does.
 @section Compiler Errors
 @cindex compiler errors
 
-  Byte compilation writes errors and warnings into the buffer
+  Byte compilation outputs all errors and warnings into the buffer
 @samp{*Compile-Log*}.  The messages include file names and line
 numbers that identify the location of the problem.  The usual Emacs
 commands for operating on compiler diagnostics work properly on
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 53c9fa92c32..baaceae47f0 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -658,7 +658,8 @@ means you should always list the most specific types first, and the
 most general last.  Here's an example of proper usage:
 
 @example
-(choice (const :tag "Off" nil) symbol (sexp :tag "Other"))
+(choice (const :tag "Off" nil)
+        symbol (sexp :tag "Other"))
 @end example
 
 @noindent
diff --git a/lispref/debugging.texi b/lispref/debugging.texi
index 739dd1fe298..66663aad131 100644
--- a/lispref/debugging.texi
+++ b/lispref/debugging.texi
@@ -350,7 +350,8 @@ structures of an interpreted function, but cannot do so in a
 byte-compiled function.  If you would like to step through a
 byte-compiled function, replace it with an interpreted definition of
 the same function.  (To do this, visit the source for the function and
-type @kbd{C-M-x} on its definition.)
+type @kbd{C-M-x} on its definition.)  You cannot use the Lisp debugger
+to step through a primitive function.
 
   Here is a list of Debugger mode commands:
 
@@ -470,15 +471,15 @@ entered--entering a function:} as a line of text at the top of the
 buffer.
 
 @item debug
-@code{debug} as first argument indicates a call to @code{debug}
-because of entry to a function that was set to debug on entry.  The
-debugger displays @samp{Debugger entered--entering a function:}, just
-as in the @code{lambda} case.  It also marks the stack frame for that
-function so that it will invoke the debugger when exited.
+@code{debug} as first argument means @code{debug} was called because
+of entry to a function that was set to debug on entry.  The debugger
+displays the string @samp{Debugger entered--entering a function:},
+just as in the @code{lambda} case.  It also marks the stack frame for
+that function so that it will invoke the debugger when exited.
 
 @item t
 When the first argument is @code{t}, this indicates a call to
-@code{debug} due to evaluation of a list form when
+@code{debug} due to evaluation of a function call form when
 @code{debug-on-next-call} is non-@code{nil}.  The debugger displays
 @samp{Debugger entered--beginning evaluation of function call form:}
 as the top line in the buffer.
diff --git a/lispref/display.texi b/lispref/display.texi
index 87520fb4d4f..930f8aa31bc 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -547,15 +547,15 @@ remaining time and clearly see that Emacs is busy working, not hung.
 reporting operation progress.  Here is a working example that does
 nothing useful:
 
-@example
+@smallexample
 (let ((progress-reporter
-       (make-progress-reporter "Collecting some mana for Emacs..."
+       (make-progress-reporter "Collecting mana for Emacs..."
                                0  500)))
   (dotimes (k 500)
     (sit-for 0.01)
     (progress-reporter-update progress-reporter k))
   (progress-reporter-done progress-reporter))
-@end example
+@end smallexample
 
 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
 This function creates and returns a @dfn{progress reporter}---an
@@ -1296,8 +1296,8 @@ 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.
 
-@code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+@code{(foreground-color . @var{color-name})} has the same effect as
+@code{(:foreground @var{color-name})}; likewise for the background.
 @end itemize
 
 @item mouse-face
@@ -2757,10 +2757,9 @@ For instance, this changes the default fontset to use a font of which
 registry name is @samp{JISX0208.1983} for all characters belonging to
 the charset @code{japanese-jisx0208}.
 
-@example
+@smallexample
 (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
-@end example
-
+@end smallexample
 @end defun
 
 @defun char-displayable-p char
@@ -3137,7 +3136,7 @@ single unit.  By contrast, characters that have similar but distinct
 Lisp objects as their @code{display} properties are handled
 separately.  Here's a function that illustrates this point:
 
-@example
+@smallexample
 (defun foo ()
   (goto-char (point-min))
   (dotimes (i 5)
@@ -3146,7 +3145,7 @@ separately.  Here's a function that illustrates this point:
       (forward-char 1)
       (put-text-property (point) (1+ (point)) 'display string)
       (forward-char 1))))
-@end example
+@end smallexample
 
 @noindent
 It gives each of the first ten characters in the buffer string
@@ -3158,7 +3157,7 @@ Likewise for each following pair of characters.  Thus, the ten
 characters appear as five A's.  This function would have the same
 results:
 
-@example
+@smallexample
 (defun foo ()
   (goto-char (point-min))
   (dotimes (i 5)
@@ -3166,7 +3165,7 @@ results:
       (put-text-property (point) (2+ (point)) 'display string)
       (put-text-property (point) (1+ (point)) 'display string)
       (forward-char 2))))
-@end example
+@end smallexample
 
 @noindent
 This illustrates that what matters is the property value for
@@ -3262,18 +3261,20 @@ as an absolute number of pixels.
 
   The following expressions are supported:
 
-@example
+@smallexample
 @group
   @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
   @var{num}  ::= @var{integer} | @var{float} | @var{symbol}
   @var{unit} ::= in | mm | cm | width | height
+@end group
+@group
   @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
         |  scroll-bar | text
   @var{pos}  ::= left | center | right
   @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
   @var{op}   ::= + | -
 @end group
-@end example
+@end smallexample
 
   The form @var{num} specifies a fraction of the default frame font
 height or width.  The form @code{(@var{num})} specifies an absolute
@@ -3331,7 +3332,7 @@ in the @code{display} text property.
 Display @var{string} instead of the text that has this property.
 
 @item (image . @var{image-props})
-This display specification is an image descriptor (@pxref{Images}).
+This kind of display specification is an image descriptor (@pxref{Images}).
 When used as a display specification, it means to display the image
 instead of the text that has the display specification.
 
diff --git a/lispref/edebug.texi b/lispref/edebug.texi
index 981afbb894c..f074cf3dbd5 100644
--- a/lispref/edebug.texi
+++ b/lispref/edebug.texi
@@ -203,14 +203,13 @@ function.
 @code{interactive} forms with an expression argument, anonymous lambda
 expressions, and other defining forms.  However, Edebug cannot determine
 on its own what a user-defined macro will do with the arguments of a
-macro call, so you must provide that information; see @ref{Edebug and
-Macros}, for details.
+macro call, so you must provide that information using Edebug
+specifications; see @ref{Edebug and Macros}, for details.
 
   When Edebug is about to instrument code for the first time in a
 session, it runs the hook @code{edebug-setup-hook}, then sets it to
 @code{nil}.  You can use this to load Edebug specifications
-(@pxref{Edebug and Macros}) associated with a package you are
-using, but only when you use Edebug.
+associated with a package you are using, but only when you use Edebug.
 
 @findex eval-expression @r{(Edebug)}
   To remove instrumentation from a definition, simply re-evaluate its
@@ -331,7 +330,7 @@ program to stop.
 Proceed to the stop point near where point is (@code{edebug-goto-here}).
 
 @item f
-Run the program forward over one expression
+Run the program for one expression
 (@code{edebug-forward-sexp}).
 
 @item o
@@ -463,9 +462,9 @@ point (@code{edebug-unset-breakpoint}).
 
 @item x @var{condition} @key{RET}
 Set a conditional breakpoint which stops the program only if
-@var{condition} evaluates to a non-@code{nil} value
-(@code{edebug-set-conditional-breakpoint}).  With a prefix argument, the
-breakpoint is temporary.
+evaluating @var{condition} produces a non-@code{nil} value
+(@code{edebug-set-conditional-breakpoint}).  With a prefix argument,
+the breakpoint is temporary.
 
 @item B
 Move point to the next breakpoint in the current definition
@@ -586,8 +585,8 @@ effect outside of Edebug.
 
 @table @kbd
 @item v
-View the outside window configuration (@code{edebug-view-outside}).
-Type @kbd{C-x X w} to return to Edebug.
+Switch to viewing the outside window configuration
+(@code{edebug-view-outside}).  Type @kbd{C-x X w} to return to Edebug.
 
 @item p
 Temporarily display the outside current buffer with point at its
@@ -1036,11 +1035,12 @@ saves (and later restores) these additional data:
 The current match data.  @xref{Match Data}.
 
 @item
-@code{last-command}, @code{this-command}, @code{last-command-char},
-@code{last-input-char}, @code{last-input-event},
-@code{last-command-event}, @code{last-event-frame},
-@code{last-nonmenu-event}, and @code{track-mouse}.  Commands used within
-Edebug do not affect these variables outside of Edebug.
+The variables @code{last-command}, @code{this-command},
+@code{last-command-char}, @code{last-input-char},
+@code{last-input-event}, @code{last-command-event},
+@code{last-event-frame}, @code{last-nonmenu-event}, and
+@code{track-mouse}.  Commands used within Edebug do not affect these
+variables outside of Edebug.
 
 The key sequence returned by @code{this-command-keys} is changed by
 executing commands within Edebug and there is no way to reset
@@ -1100,13 +1100,13 @@ macro.  To do this, add a @code{debug} declaration to the macro
 definition.  Here is a simple example that shows the specification for
 the @code{for} example macro (@pxref{Argument Evaluation}).
 
-@example
+@smallexample
 (defmacro for (var from init to final do &rest body)
   "Execute a simple \"for\" loop.
 For example, (for i from 1 to 10 do (print i))."
   (declare (debug (symbolp "from" form "to" form "do" &rest form)))
   ...)
-@end example
+@end smallexample
 
   The Edebug specification says which parts of a call to the macro are
 forms to be evaluated.  For simple macros, the @var{specification}
@@ -1185,7 +1185,8 @@ balanced parentheses, recursive processing of forms, and recursion via
 indirect specifications.
 
 Here's a table of the possible elements of a specification list, with
-their meanings:
+their meanings (see @ref{Specification Examples}, for the referenced
+examples):
 
 @table @code
 @item sexp
@@ -1221,7 +1222,7 @@ as one does not match, Edebug stops matching at this level.
 To make just a few elements optional followed by non-optional elements,
 use @code{[&optional @var{specs}@dots{}]}.  To specify that several
 elements must all match or none, use @code{&optional
-[@var{specs}@dots{}]}.  See the @code{defun} example below.
+[@var{specs}@dots{}]}.  See the @code{defun} example.
 
 @item &rest
 @c @kindex &rest @r{(Edebug)}
@@ -1262,15 +1263,14 @@ a list specification.
 @item nil
 This is successful when there are no more arguments to match at the
 current argument list level; otherwise it fails.  See sublist
-specifications and the backquote example below.
+specifications and the backquote example.
 
 @item gate
 @cindex preventing backtracking
 No argument is matched but backtracking through the gate is disabled
 while matching the remainder of the specifications at this level.  This
 is primarily used to generate more specific syntax error messages.  See
-@ref{Backtracking}, for more details.  Also see the @code{let} example
-below.
+@ref{Backtracking}, for more details.  Also see the @code{let} example.
 
 @item @var{other-symbol}
 @cindex indirect specifications
@@ -1281,7 +1281,7 @@ If the symbol has an Edebug specification, this @dfn{indirect
 specification} should be either a list specification that is used in
 place of the symbol, or a function that is called to process the
 arguments.  The specification may be defined with @code{def-edebug-spec}
-just as for macros. See the @code{defun} example below.
+just as for macros. See the @code{defun} example.
 
 Otherwise, the symbol should be a predicate.  The predicate is called
 with the argument and the specification fails if the predicate returns
@@ -1302,7 +1302,7 @@ of @var{symbol} is the @var{string}, but the string form is preferred.
 
 @item (vector @var{elements}@dots{})
 The argument should be a vector whose elements must match the
-@var{elements} in the specification.  See the backquote example below.
+@var{elements} in the specification.  See the backquote example.
 
 @item (@var{elements}@dots{})
 Any other list is a @dfn{sublist specification} and the argument must be
@@ -1315,7 +1315,7 @@ dotted list specification may be another sublist specification (via a
 grouping or an indirect specification, e.g., @code{(spec .  [(more
 specs@dots{})])}) whose elements match the non-dotted list arguments.
 This is useful in recursive specifications such as in the backquote
-example below.  Also see the description of a @code{nil} specification
+example.  Also see the description of a @code{nil} specification
 above for terminating such recursion.
 
 Note that a sublist specification written as @code{(specs .  nil)}
@@ -1327,7 +1327,7 @@ sublist-elements@dots{})}.
 @c Need to document extensions with &symbol and :symbol
 
 Here is a list of additional specifications that may appear only after
-@code{&define}.  See the @code{defun} example below.
+@code{&define}.  See the @code{defun} example.
 
 @table @code
 @item name
@@ -1364,7 +1364,7 @@ The argument is a single, highest-level form in a definition.  This is
 like @code{def-body}, except use this to match a single form rather than
 a list of forms.  As a special case, @code{def-form} also means that
 tracing information is not output when the form is executed.  See the
-@code{interactive} example below.
+@code{interactive} example.
 @end table
 
 @node Backtracking
diff --git a/lispref/elisp.texi b/lispref/elisp.texi
index 4be680969a1..0a4849c236b 100644
--- a/lispref/elisp.texi
+++ b/lispref/elisp.texi
@@ -6,7 +6,7 @@
 
 @c Version of the manual and of Emacs.
 @c Please remember to update the edition number in README as well.
-@set VERSION  2.9
+@set VERSION  2.7
 @set EMACSVER 22.0.50
 
 @dircategory Emacs
@@ -34,8 +34,8 @@ Published by the Free Software Foundation
 59 Temple Place, Suite 330
 Boston, MA  02111-1307  USA
 
-Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2005,@*
-              2000, 2002 Free Software Foundation, Inc.
+Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, @*
+              2000, 2002, 2003, 2004, 2005, Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -60,7 +60,7 @@ Software Foundation raise funds for GNU development.''
 @page
 @vskip 0pt plus 1filll
 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
-1999, 2000, 2002 Free Software Foundation, Inc.
+1999, 2000, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
 
 @sp 2
 Edition @value{VERSION} @*
@@ -288,6 +288,7 @@ Lists
 * Modifying Lists::         Storing new pieces into an existing list.
 * Sets And Lists::          A list can represent a finite mathematical set.
 * Association Lists::       A list can represent a finite relation or mapping.
+* Rings::                   Managing a fixed-size ring of objects.
 
 Modifying Existing List Structure
 
@@ -983,6 +984,7 @@ Processes
 * Datagrams::               UDP network connections.
 * Low-Level Network::       Lower-level but more general function
                               to create connections and servers.
+* Byte Packing::             Using bindat to pack and unpack binary data.
 
 Receiving Output from Processes
 
diff --git a/lispref/errors.texi b/lispref/errors.texi
index 8591fb9a45f..a246539b8fd 100644
--- a/lispref/errors.texi
+++ b/lispref/errors.texi
@@ -63,7 +63,7 @@ See @code{/} and @code{%} in @ref{Numbers}.
 @xref{Function Indirection}.
 
 @item cyclic-variable-indirection
-@code{"Symbol's chain of variable indirections contains a loop"}@*
+@code{"Symbol's chain of variable indirections\@* contains a loop"}@*
 @xref{Variable Aliases}.
 
 @item end-of-buffer
diff --git a/lispref/files.texi b/lispref/files.texi
index 766220aa882..93c104e6ccd 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -98,9 +98,9 @@ new buffer and reading the file into it.  It also returns that buffer.
 Aside from some technical details, the body of the @code{find-file}
 function is basically equivalent to:
 
-@example
+@smallexample
 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
-@end example
+@end smallexample
 
 @noindent
 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
@@ -2731,9 +2731,9 @@ This function tests whether @var{filename} is a remote file.  If
 If @var{filename} is indeed remote, the return value is a string that
 identifies the remote system.
 
-This identifier string may include a host name, a user name, and
-characters designating the method used to access the remote system.
-For example, the remote identifier string for the filename
+This identifier string can include a host name and a user name, as
+well as characters designating the method used to access the remote
+system.  For example, the remote identifier string for the filename
 @code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
 
 If @code{file-remote-p} returns the same identifier for two different
diff --git a/lispref/frames.texi b/lispref/frames.texi
index ffcc16f6289..10035b76f9f 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -1550,13 +1550,13 @@ clients.  It takes two optional arguments, @var{type} and
 The @var{data-type} argument specifies the form of data conversion to
 use, to convert the raw data obtained from another X client into Lisp
 data.  Meaningful values include @code{TEXT}, @code{STRING},
-@code{UTF8_STRING},
-@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
-@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
-@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
-@code{NAME}, @code{ATOM}, and @code{INTEGER}.  (These are symbols with
-upper-case names in accord with X conventions.)  The default for
-@var{data-type} is @code{STRING}.
+@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
+@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
+@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
+@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
+@code{INTEGER}.  (These are symbols with upper-case names in accord
+with X conventions.)  The default for @var{data-type} is
+@code{STRING}.
 @end defun
 
 @cindex cut buffer
@@ -1822,8 +1822,8 @@ xterm.vt100.background: yellow
 @end example
 
 @noindent
-in in your X resources file (usually named @file{~/.Xdefaults} or
-@file{~/.Xresources}).  Then:
+in in your X resources file (whose name is usually @file{~/.Xdefaults}
+or @file{~/.Xresources}).  Then:
 
 @example
 @group
diff --git a/lispref/functions.texi b/lispref/functions.texi
index bcdfc95cc1c..f58cad69bb7 100644
--- a/lispref/functions.texi
+++ b/lispref/functions.texi
@@ -525,9 +525,9 @@ defines the symbol @var{name} as a function that looks like this:
 @var{name}.  It returns the value @var{name}, but usually we ignore this
 value.
 
-As described previously (@pxref{Lambda Expressions}),
-@var{argument-list} is a list of argument names and may include the
-keywords @code{&optional} and @code{&rest}.  Also, the first two of the
+As described previously, @var{argument-list} is a list of argument
+names and may include the keywords @code{&optional} and @code{&rest}
+(@pxref{Lambda Expressions}).  Also, the first two of the
 @var{body-forms} may be a documentation string and an interactive
 declaration.
 
@@ -1157,13 +1157,14 @@ a function defined by another package, it is cleaner to use
 You can use @code{make-obsolete} to declare a function obsolete.  This
 indicates that the function may be removed at some stage in the future.
 
-@defun make-obsolete function new &optional when
+@defun make-obsolete obsolete-name current-name &optional when
 This function makes the byte compiler warn that the function
-@var{function} is obsolete.  If @var{new} is a symbol, the warning
-message says to use @var{new} instead of @var{function}.  @var{new}
-does not need to be an alias for @var{function}; it can be a different
-function with similar functionality.  If @var{new} is a string, it is
-the warning message.
+@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, the
+warning message says to use @var{current-name} instead of
+@var{obsolete-name}.  @var{current-name} does not need to be an alias for
+@var{obsolete-name}; it can be a different function with similar
+functionality.  If @var{current-name} is a string, it is the warning
+message.
 
 If provided, @var{when} should be a string indicating when the function
 was first made obsolete---for example, a date or a release number.
@@ -1172,20 +1173,14 @@ was first made obsolete---for example, a date or a release number.
 You can define a function as an alias and declare it obsolete at the
 same time using the macro @code{define-obsolete-function-alias}.
 
-@defmac define-obsolete-function-alias function new &optional when docstring
-This macro marks the function @var{function} obsolete and also defines
-it as an alias for the function @var{new}.  A typical call has the form:
+@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
+This macro marks the function @var{obsolete-name} obsolete and also
+defines it as an alias for the function @var{current-name}.  It is
+equivalent to the following:
 
 @example
-(define-obsolete-function-alias 'old-fun 'new-fun "22.1" "Doc.")
-@end example
-
-@noindent
-which is equivalent to the following two lines of code:
-
-@example
-(defalias 'old-fun 'new-fun "Doc.")
-(make-obsolete 'old-fun 'new-fun "22.1")
+(defalias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
 @end example
 @end defmac
 
diff --git a/lispref/help.texi b/lispref/help.texi
index dfbc6c220f3..2dbea2038cc 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -47,13 +47,15 @@ of a function or variable.  In a function definition, the documentation
 string follows the argument list.  In a variable definition, the
 documentation string follows the initial value of the variable.
 
-  When you write a documentation string, make the first line a complete
-sentence (or two complete sentences) since some commands, such as
-@code{apropos}, show only the first line of a multi-line documentation
-string.  Also, you should not indent the second line of a documentation
-string, if it has one, because that looks odd when you use @kbd{C-h f}
-(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}) to
-view the documentation string.  @xref{Documentation Tips}.
+  When you write a documentation string, make the first line a
+complete sentence (or two complete sentences) since some commands,
+such as @code{apropos}, show only the first line of a multi-line
+documentation string.  Also, you should not indent the second line of
+a documentation string, if it has one, because that looks odd when you
+use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
+(@code{describe-variable}) to view the documentation string.  There
+are many other conventions for doc strings; see @ref{Documentation
+Tips}.
 
   Documentation strings can contain several special substrings, which
 stand for key bindings to be looked up in the current keymaps when the
@@ -117,7 +119,7 @@ retrieves the text from a file if the value calls for that.  If the
 property value isn't @code{nil}, isn't a string, and doesn't refer to
 text in a file, then it is evaluated to obtain a string.
 
-Finally, @code{documentation-property} passes the string through
+The last thing this function does is pass the string through
 @code{substitute-command-keys} to substitute actual key bindings,
 unless @var{verbatim} is non-@code{nil}.
 
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index 63832ced1b4..79cbe478ea2 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -1335,10 +1335,10 @@ a key binding.
 instead of @code{kill-line} and @code{kill-word}.  It can establish
 this by making these two command-remapping bindings in its keymap:
 
-@example
+@smallexample
 (define-key my-mode-map [remap kill-line] 'my-kill-line)
 (define-key my-mode-map [remap kill-word] 'my-kill-word)
-@end example
+@end smallexample
 
 Whenever @code{my-mode-map} is an active keymap, if the user types
 @kbd{C-k}, Emacs will find the standard global binding of
@@ -1349,10 +1349,10 @@ so instead of running @code{kill-line}, Emacs runs
 
 Remapping only works through a single level.  In other words,
 
-@example
+@smallexample
 (define-key my-mode-map [remap kill-line] 'my-kill-line)
 (define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
-@end example
+@end smallexample
 
 @noindent
 does not have the effect of remapping @code{kill-line} into
diff --git a/lispref/lists.texi b/lispref/lists.texi
index ab7d496e461..a5a2c33bcce 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -24,6 +24,7 @@ the whole list.
 * Modifying Lists::     Storing new pieces into an existing list.
 * Sets And Lists::      A list can represent a finite mathematical set.
 * Association Lists::   A list can represent a finite relation or mapping.
+* Rings::               Managing a fixed-size ring of objects.
 @end menu
 
 @node Cons Cells
@@ -714,7 +715,7 @@ Some examples:
 primitives @code{setcar} and @code{setcdr}.  We call these ``destructive''
 operations because they change existing list structure.
 
-@cindex CL note---@code{rplaca} vrs @code{setcar}
+@cindex CL note---@code{rplaca} vs @code{setcar}
 @quotation
 @findex rplaca
 @findex rplacd
@@ -1676,6 +1677,94 @@ compares the @sc{cdr} of each @var{alist} association instead of the
 @sc{car}.
 @end defun
 
+@node Rings
+@section Managing a Fixed-Size Ring of Objects
+
+@cindex ring data structure
+  This section describes functions for operating on rings.  A
+@dfn{ring} is a fixed-size data structure that supports insertion,
+deletion, rotation, and modulo-indexed reference and traversal.
+
+@defun make-ring size
+This returns a new ring capable of holding @var{size} objects.
+@var{size} should be an integer.
+@end defun
+
+@defun ring-p object
+This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
+@end defun
+
+@defun ring-size ring
+This returns the maximum capacity of the @var{ring}.
+@end defun
+
+@defun ring-length ring
+This returns the number of objects that @var{ring} currently contains.
+The value will never exceed that returned by @code{ring-size}.
+@end defun
+
+@defun ring-elements ring
+This returns a list of the objects in @var{ring}, in no particular
+order.
+@end defun
+
+@defun ring-copy ring
+This returns a new ring which is a copy of @var{ring}.
+The new ring contains the same (@code{eq}) objects as @var{ring}.
+@end defun
+
+@defun ring-empty-p ring
+This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
+@end defun
+
+  The newest element in the ring always has index 0.  Higher indices
+correspond to older elements.  Indices are computed modulo the ring
+length.  Index @minus{}1 corresponds to the oldest element, @minus{}2
+to the next-oldest, and so forth.
+
+@defun ring-ref ring index
+This returns the object in @var{ring} found at index @var{index}.
+@var{index} may be negative or greater than the ring length.  If
+@var{ring} is empty, @code{ring-ref} signals an error.
+@end defun
+
+@defun ring-insert ring object
+This inserts @var{object} into @var{ring}, making it the newest
+element, and returns @var{object}.
+
+If the ring is full, insertion removes the oldest element to
+make room for the new element.
+@end defun
+
+@defun ring-remove ring &optional index
+Remove an object from @var{ring}, and return that object.  The
+argument @var{index} specifies which item to remove; if it is
+@code{nil}, that means to remove the oldest item.  If @var{ring} is
+empty, @code{ring-remove} signals an error.
+@end defun
+
+@defun ring-insert-at-beginning ring object
+This inserts @var{object} into @var{ring}, treating it as the oldest
+element.  The return value is not significant.
+
+If the ring is full, this function removes the newest element to make
+room for the inserted element.
+@end defun
+
+@cindex fifo data structure
+  If you are careful not to exceed the ring size, you can
+use the ring as a first-in-first-out queue.  For example:
+
+@lisp
+(let ((fifo (make-ring 5)))
+  (mapc (lambda (obj) (ring-insert fifo obj))
+        '(0 one "two"))
+  (list (ring-remove fifo) t
+        (ring-remove fifo) t
+        (ring-remove fifo)))
+     @result{} (0 t one t "two")
+@end lisp
+
 @ignore
    arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
 @end ignore
diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index cdba210b625..a6153fdaca2 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -414,10 +414,9 @@ symbol, not a list; it is a variable whose value is a list of strings
 inputs.  It's the Lisp programmer's job to specify the right history
 list for each use of the minibuffer.
 
-  The basic minibuffer input functions @code{read-from-minibuffer} and
-@code{completing-read} both accept an optional argument named @var{hist}
-which is how you specify the history list.  Here are the possible
-values:
+  You specify the history list with the optional @var{hist} argument
+to either @code{read-from-minibuffer} or @code{completing-read}.  Here
+are the possible values for it:
 
 @table @asis
 @item @var{variable}
@@ -587,10 +586,11 @@ for reading certain kinds of names with completion.
 @node Basic Completion
 @subsection Basic Completion Functions
 
-  The functions @code{try-completion}, @code{all-completions} and
-@code{test-completion} have nothing in themselves to do with
-minibuffers.  We describe them in this chapter so as to keep them near
-the higher-level completion features that do use the minibuffer.
+  The completion functions @code{try-completion},
+@code{all-completions} and @code{test-completion} have nothing in
+themselves to do with minibuffers.  We describe them in this chapter
+so as to keep them near the higher-level completion features that do
+use the minibuffer.
 
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
@@ -788,12 +788,12 @@ value @var{fun} returns becomes the permanent value of @var{var}.
 
 Here are two examples of use:
 
-@example
+@smallexample
 (defvar foo (lazy-completion-table foo make-my-alist 'global))
 
 (make-local-variable 'bar)
 (setq bar (lazy-completion-table foo make-my-alist 'local)
-@end example
+@end smallexample
 @end defmac
 
 @node Minibuffer Completion
@@ -879,12 +879,9 @@ Complete a foo: fo@point{}
 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
 @code{completing-read} returns @code{barfoo}.
 
-The @code{completing-read} function binds three variables to pass
-information to the commands that actually do completion.  These
-variables are @code{minibuffer-completion-table},
-@code{minibuffer-completion-predicate} and
-@code{minibuffer-completion-confirm}.  For more information about them,
-see @ref{Completion Commands}.
+The @code{completing-read} function binds variables to pass
+information to the commands that actually do completion.
+They are described in the following section.
 @end defun
 
 @node Completion Commands
@@ -898,55 +895,6 @@ some of the commands described below.  @xref{Completion Options,,,
 emacs, The GNU Emacs Manual}, for a short description of Partial
 Completion mode.
 
-@defvar minibuffer-local-completion-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is not required.  By default, this
-keymap makes the following bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}
-(@pxref{Definition of minibuffer-local-map}).
-@end defvar
-
-@defvar minibuffer-local-must-match-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is required.  Therefore, no keys
-are bound to @code{exit-minibuffer}, the command that exits the
-minibuffer unconditionally.  By default, this keymap makes the following
-bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-
-@item @kbd{C-j}
-@code{minibuffer-complete-and-exit}
-
-@item @key{RET}
-@code{minibuffer-complete-and-exit}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}.
-@end defvar
-
 @defvar minibuffer-completion-table
 The value of this variable is the collection used for completion in
 the minibuffer.  This is the global variable that contains what
@@ -960,6 +908,13 @@ passes to @code{try-completion}.  The variable is also used by the other
 minibuffer completion functions.
 @end defvar
 
+@defvar minibuffer-completion-confirm
+When the value of this variable is non-@code{nil}, Emacs asks for
+confirmation of a completion before exiting the minibuffer.
+@code{completing-read} binds this variable, and the function
+@code{minibuffer-complete-and-exit} checks the value before exiting.
+@end defvar
+
 @deffn Command minibuffer-complete-word
 This function completes the minibuffer contents by at most a single
 word.  Even if the minibuffer contents have only one completion,
@@ -980,13 +935,6 @@ immediately---the command is programmed to work without confirmation
 when run twice in succession.
 @end deffn
 
-@defvar minibuffer-completion-confirm
-When the value of this variable is non-@code{nil}, Emacs asks for
-confirmation of a completion before exiting the minibuffer.  The
-function @code{minibuffer-complete-and-exit} checks the value of this
-variable before it exits.
-@end defvar
-
 @deffn Command minibuffer-completion-help
 This function creates a list of the possible completions of the
 current minibuffer contents.  It works by calling @code{all-completions}
@@ -1025,6 +973,55 @@ automatically display a list of possible completions whenever nothing
 can be completed because the next character is not uniquely determined.
 @end defopt
 
+@defvar minibuffer-local-completion-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is not required.  By default, this
+keymap makes the following bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}
+(@pxref{Definition of minibuffer-local-map}).
+@end defvar
+
+@defvar minibuffer-local-must-match-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is required.  Therefore, no keys
+are bound to @code{exit-minibuffer}, the command that exits the
+minibuffer unconditionally.  By default, this keymap makes the following
+bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+
+@item @kbd{C-j}
+@code{minibuffer-complete-and-exit}
+
+@item @key{RET}
+@code{minibuffer-complete-and-exit}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}.
+@end defvar
+
 @node High-Level Completion
 @subsection High-Level Completion  Functions
 
diff --git a/lispref/modes.texi b/lispref/modes.texi
index 2366fca5b96..ac13e30b90c 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -395,7 +395,7 @@ setting up a buffer-local value for the variable
 @item
 The mode should specify how Imenu should find the definitions or
 sections of a buffer, by setting up a buffer-local value for the
-variable @code{imenu-generic-expression}, for the pair of variables
+variable @code{imenu-generic-expression}, for the two variables
 @code{imenu-prev-index-position-function} and
 @code{imenu-extract-index-name-function}, or for the variable
 @code{imenu-create-index-function} (@pxref{Imenu}).
@@ -2290,8 +2290,8 @@ A nested sub-alist element looks like this:
 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
 
 The default value of @code{imenu-create-index-function} is
-@code{imenu-default-create-index-function}.  This function uses
-@code{imenu-prev-index-position-function} and
+@code{imenu-default-create-index-function}.  This function calls the
+value of @code{imenu-prev-index-position-function} and the value of
 @code{imenu-extract-index-name-function} to produce the index alist.
 However, if either of these two variables is @code{nil}, the default
 function uses @code{imenu-generic-expression} instead.
@@ -2456,7 +2456,7 @@ highlighted (instead of the entire text that @var{matcher} matched).
 @end example
 
 If you use @code{regexp-opt} to produce the regular expression
-@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp
+@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
 Functions}) to calculate the value for @var{subexp}.
 
 @item (@var{matcher} . @var{facespec})
@@ -2657,8 +2657,7 @@ non-@code{nil} value, they are added at the end of
 Some modes provide specialized support you can use in additional
 highlighting patterns.  See the variables
 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
-@code{objc-font-lock-extra-types} and
-@code{java-font-lock-extra-types}, for example.
+and @code{java-font-lock-extra-types}, for example.
 
 @strong{Warning:} major mode functions must not call
 @code{font-lock-add-keywords} under any circumstances, either directly
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index aaa23e90a48..9683156541d 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -1067,11 +1067,11 @@ for decoding (in case @var{operation} does decoding), and
 @var{encoding-system} is the coding system for encoding (in case
 @var{operation} does encoding).
 
-The argument @var{operation} should be a symbol, one of
-@code{insert-file-contents}, @code{write-region}, @code{call-process},
-@code{call-process-region}, @code{start-process}, or
-@code{open-network-stream}.  These are the names of the Emacs I/O primitives
-that can do coding system conversion.
+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.
 
 The remaining arguments should be the same arguments that might be given
 to that I/O primitive.  Depending on the primitive, one of those
@@ -1081,9 +1081,9 @@ name is the target.  For subprocess primitives, the process name is the
 target.  For @code{open-network-stream}, the target is the service name
 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}.
+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}.
 @end defun
 
 @node Specifying Coding Systems
diff --git a/lispref/os.texi b/lispref/os.texi
index a1de8f09c36..7bc76799210 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -91,10 +91,10 @@ name is usually @file{site-start.el}.
 @cindex @file{site-start.el}
 
 @item
-It loads your init file (usually @file{~/.emacs}), unless @samp{-q}
-(or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was specified
-on the command line.  The @samp{-u} option can specify another user
-whose home directory should be used instead of @file{~}.
+It loads your init file (usually @file{~/.emacs}), unless the option
+@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
+specified on the command line.  The @samp{-u} option can specify
+another user whose home directory should be used instead of @file{~}.
 
 @item
 It loads the library @file{default} (if any), unless
@@ -606,9 +606,10 @@ through various functions.  These variables include the name of the
 system, the user's @acronym{UID}, and so on.
 
 @defvar system-configuration
-This variable holds the GNU configuration name for the hardware/software
-configuration of your system, as a string.  The convenient way to test
-parts of this string is with @code{string-match}.
+This variable holds the standard GNU configuration name for the
+hardware/software configuration of your system, as a string.  The
+convenient way to test parts of this string is with
+@code{string-match}.
 @end defvar
 
 @defvar system-type
@@ -1375,6 +1376,9 @@ both before and after changing the buffer, to separate the timer's
 changes from user commands' changes and prevent a single undo entry
 from growing to be quite large.
 
+  If a timer function calls functions that can change the match data,
+it should save and restore the match data.  @xref{Saving Match Data}.
+
 @deffn Command run-at-time time repeat function &rest args
 This sets up a timer that calls the function @var{function} with
 arguments @var{args} at time @var{time}.  If @var{repeat} is a number
diff --git a/lispref/processes.texi b/lispref/processes.texi
index 07a72886355..f88b2c46159 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -52,6 +52,7 @@ This function returns @code{t} if @var{object} is a process,
 * Datagrams::                UDP network connections.
 * Low-Level Network::        Lower-level but more general function
                                to create connections and servers.
+* Byte Packing::             Using bindat to pack and unpack binary data.
 @end menu
 
 @node Subprocess Creation
@@ -168,7 +169,7 @@ function.
 (shell-quote-argument "foo > bar")
      @result{} "foo\\ \\>\\ bar"
 
-;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
+;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
 (shell-quote-argument "foo > bar")
      @result{} "\"foo > bar\""
 @end example
@@ -766,9 +767,9 @@ specify the process to send input to, and the input data to send.  The
 data appears on the ``standard input'' of the subprocess.
 
   Some operating systems have limited space for buffered input in a
-@acronym{PTY}.  On these systems, Emacs sends an @acronym{EOF} periodically amidst
-the other characters, to force them through.  For most programs,
-these @acronym{EOF}s do no harm.
+@acronym{PTY}.  On these systems, Emacs sends an @acronym{EOF}
+periodically amidst the other characters, to force them through.  For
+most programs, these @acronym{EOF}s do no harm.
 
   Subprocess input is normally encoded using a coding system before the
 subprocess receives it, much like text written into a file.  You can use
@@ -972,7 +973,7 @@ primitive that waits.
 @defvar process-adaptive-read-buffering
 On some systems, when Emacs reads the output from a subprocess, the
 output data is read in very small blocks, potentially resulting in
-very poor performance.  This behaviour can be remedied to some extent
+very poor performance.  This behavior can be remedied to some extent
 by setting the variable @var{process-adaptive-read-buffering} to a
 non-@code{nil} value (the default), as it will automatically delay reading
 from such processes, thus allowing them to produce more output before
@@ -1559,7 +1560,7 @@ back to listening for more connection requests.
 keyword/argument pairs, for example @code{:server t} to create a
 server process, or @code{:type 'datagram} to create a datagram
 connection.  @xref{Low-Level Network}, for details.  You can also use
-the @code{open-network-stream} function descibed below.
+the @code{open-network-stream} function described below.
 
   You can distinguish process objects representing network connections
 and servers from those representing subprocesses with the
@@ -1823,7 +1824,8 @@ If you don't specify this keyword at all, the default
 is to determine the coding systems from the data.
 
 @item :noquery @var{query-flag}
-Initialize the process query flag to @var{query-flag}.  @xref{Query Before Exit}.
+Initialize the process query flag to @var{query-flag}.
+@xref{Query Before Exit}.
 
 @item :filter @var{filter}
 Initialize the process filter to @var{filter}.
@@ -1938,7 +1940,8 @@ and @var{remote-address} arguments to @code{make-network-process}.
 
 @defun network-interface-info ifname
 This function returns information about the network interface named
-@var{ifname}.  The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
+@var{ifname}.  The value is a list of the form
+@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
 
 @table @var
 @item addr
@@ -2015,7 +2018,411 @@ That particular network option is supported by
 @code{make-network-process} and @code{set-network-process-option}.
 @end table
 
+@node Byte Packing
+@section Packing and Unpacking Byte Arrays
+
+  This section describes how to pack and unpack arrays of bytes,
+usually for binary network protocols.  These functions convert byte arrays
+to alists, and vice versa.  The byte array can be represented as a
+unibyte string or as a vector of integers, while the alist associates
+symbols either with fixed-size objects or with recursive sub-alists.
+
+@cindex serializing
+@cindex deserializing
+@cindex packing
+@cindex unpacking
+  Conversion from byte arrays to nested alists is also known as
+@dfn{deserializing} or @dfn{unpacking}, while going in the opposite
+direction is also known as @dfn{serializing} or @dfn{packing}.
+
+@menu
+* Bindat Spec::         Describing data layout.
+* Bindat Functions::    Doing the unpacking and packing.
+* Bindat Examples::     Samples of what bindat.el can do for you!
+@end menu
+
+@node Bindat Spec
+@subsection Describing Data Layout
+
+  To control unpacking and packing, you write a @dfn{data layout
+specification}, a special nested list describing named and typed
+@dfn{fields}.  This specification controls length of each field to be
+processed, and how to pack or unpack it.
+
+@cindex endianness
+@cindex big endian
+@cindex little endian
+@cindex network byte ordering
+  A field's @dfn{type} describes the size (in bytes) of the object
+that the field represents and, in the case of multibyte fields, how
+the bytes are ordered within the field.  The two possible orderings
+are ``big endian'' (also known as ``network byte ordering'') and
+``little endian''.  For instance, the number @code{#x23cd} (decimal
+9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
+and in little endian, @code{#xcd} @code{#x23}.  Here are the possible
+type values:
+
+@table @code
+@item u8
+@itemx byte
+Unsigned byte, with length 1.
+
+@item u16
+@itemx word
+@itemx short
+Unsigned integer in network byte order, with length 2.
+
+@item u24
+Unsigned integer in network byte order, with length 3.
+
+@item u32
+@itemx dword
+@itemx long
+Unsigned integer in network byte order, with length 4.
+Note: These values may be limited by Emacs' integer implementation limits.
+
+@item u16r
+@itemx u24r
+@itemx u32r
+Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
+
+@item str @var{len}
+String of length @var{len}.
+
+@item strz @var{len}
+Zero-terminated string of length @var{len}.
+
+@item vec @var{len}
+Vector of @var{len} bytes.
+
+@item ip
+Four-byte vector representing an Internet address.  For example:
+@code{[127 0 0 1]} for localhost.
+
+@item bits @var{len}
+List of set bits in @var{len} bytes.  The bytes are taken in big
+endian order and the bits are numbered starting with @code{8 *
+@var{len} @minus{} 1} and ending with zero.  For example: @code{bits
+2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
+@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
+
+@item (eval @var{form})
+@var{form} is a Lisp expression evaluated at the moment the field is
+unpacked or packed.  The result of the evaluation should be one of the
+above-listed type specifications.
+@end table
+
+A field specification generally has the form @code{([@var{name}]
+@var{handler})}.  The square braces indicate that @var{name} is
+optional.  (Don't use names that are symbols meaningful as type
+specifications (above) or handler specifications (below), since that
+would be ambiguous.)  @var{name} can be a symbol or the expression
+@code{(eval @var{form})}, in which case @var{form} should evaluate to
+a symbol.
+
+@var{handler} describes how to unpack or pack the field and can be one
+of the following:
+
+@table @code
+@item @var{type}
+Unpack/pack this field according to the type specification @var{type}.
+
+@item eval @var{form}
+Evaluate @var{form}, a Lisp expression, for side-effect only.  If the
+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
+The data as a byte array.
+
+@item pos
+Current position of the unpacking or packing operation.
+
+@item struct
+Alist.
+
+@item last
+Value of the last field processed.
+@end table
+
+@item fill @var{len}
+Skip @var{len} bytes.  In packing, this leaves them unchanged,
+which normally means they remain zero.  In unpacking, this means
+they are ignored.
+
+@item align @var{len}
+Skip to the next multiple of @var{len} bytes.
+
+@item struct @var{spec-name}
+Process @var{spec-name} as a sub-specification.  This describes a
+structure nested within another structure.
+
+@item union @var{form} (@var{tag} @var{spec})@dots{}
+@c ??? I don't see how one would actually  use this.
+@c ??? what kind of expression would be useful for @var{form}?
+Evaluate @var{form}, a Lisp expression, find the first @var{tag}
+that matches it, and process its associated data layout specification
+@var{spec}.  Matching can occur in one of three ways:
+
+@itemize
+@item
+If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
+@var{expr} with the variable @code{tag} dynamically bound to the value
+of @var{form}.  A non-@code{nil} result indicates a match.
+
+@item
+@var{tag} matches if it is @code{equal} to the value of @var{form}.
+
+@item
+@var{tag} matches unconditionally if it is @code{t}.
+@end itemize
+
+@item repeat @var{count} @var{field-spec}@dots{}
+@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
+alist representing unpacked field data.
+
+@defun bindat-unpack spec raw-data &optional pos
+This function unpacks data from the byte array @code{raw-data}
+according to @var{spec}.  Normally this starts unpacking at the
+beginning of the byte array, but if @var{pos} 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
+one unpacked field.
+@end defun
+
+@defun bindat-get-field struct &rest name
+This function selects a field's data from the nested alist
+@var{struct}.  Usually @var{struct} was returned by
+@code{bindat-unpack}.  If @var{name} corresponds to just one argument,
+that means to extract a top-level field value.  Multiple @var{name}
+arguments specify repeated lookup of sub-structures.  An integer name
+acts as an array index.
+
+For example, if @var{name} is @code{(a b 2 c)}, that means to find
+field @code{c} in the second element of subfield @code{b} of field
+@code{a}.  (This corresponds to @code{struct.a.b[2].c} in C.)
+@end defun
+
+@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}.
+@end defun
+
+@defun bindat-pack spec struct &optional raw-data pos
+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}.
+
+@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.
+@end defun
+
+@defun bindat-ip-to-string ip
+Convert the Internet address vector @var{ip} to a string in the usual
+dotted notation.
+
+@example
+(bindat-ip-to-string [127 0 0 1])
+     @result{} "127.0.0.1"
+@end example
+@end defun
+
+@node Bindat Examples
+@subsection Examples of Byte Unpacking and Packing
+
+  Here is a complete example of byte unpacking and packing:
+
+@lisp
+(defvar fcookie-index-spec
+  '((:version  u32)
+    (:count    u32)
+    (:longest  u32)
+    (:shortest u32)
+    (:flags    u32)
+    (:delim    u8)
+    (:ignored  fill 3)
+    (:offset   repeat (:count)
+               (:foo u32)))
+  "Description of a fortune cookie index file's contents.")
+
+(defun fcookie (cookies &optional index)
+  "Display a random fortune cookie from file COOKIES.
+Optional second arg INDEX specifies the associated index
+filename, which is by default constructed by appending
+\".dat\" to COOKIES.  Display cookie text in possibly
+new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
+is COOKIES without the directory part."
+  (interactive "fCookies file: ")
+  (let* ((info (with-temp-buffer
+                 (insert-file-contents-literally
+                  (or index (concat cookies ".dat")))
+                 (bindat-unpack fcookie-index-spec
+                                (buffer-string))))
+         (sel (random (bindat-get-field info :count)))
+         (beg (cdar (bindat-get-field info :offset sel)))
+         (end (or (cdar (bindat-get-field info
+                                          :offset (1+ sel)))
+                  (nth 7 (file-attributes cookies)))))
+    (switch-to-buffer
+     (get-buffer-create
+      (format "*Fortune Cookie: %s*"
+              (file-name-nondirectory cookies))))
+    (erase-buffer)
+    (insert-file-contents-literally
+     cookies nil beg (- end 3))))
+
+(defun fcookie-create-index (cookies &optional index delim)
+  "Scan file COOKIES, and write out its index file.
+Optional second arg INDEX specifies the index filename,
+which is by default constructed by appending \".dat\" to
+COOKIES.  Optional third arg DELIM specifies the unibyte
+character which, when found on a line of its own in
+COOKIES, indicates the border between entries."
+  (interactive "fCookies file: ")
+  (setq delim (or delim ?%))
+  (let ((delim-line (format "\n%c\n" delim))
+        (count 0)
+        (max 0)
+        min p q len offsets)
+    (unless (= 3 (string-bytes delim-line))
+      (error "Delimiter cannot be represented in one byte"))
+    (with-temp-buffer
+      (insert-file-contents-literally cookies)
+      (while (and (setq p (point))
+                  (search-forward delim-line (point-max) t)
+                  (setq len (- (point) 3 p)))
+        (setq count (1+ count)
+              max (max max len)
+              min (min (or min max) len)
+              offsets (cons (1- p) offsets))))
+    (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)))))))
+      (let ((coding-system-for-write 'raw-text-unix))
+        (write-file (or index (concat cookies ".dat")))))))
+@end lisp
+
+Following is an example of defining and unpacking a complex structure.
+Consider the following C structures:
+
+@example
+struct header @{
+    unsigned long    dest_ip;
+    unsigned long    src_ip;
+    unsigned short   dest_port;
+    unsigned short   src_port;
+@};
+
+struct data @{
+    unsigned char    type;
+    unsigned char    opcode;
+    unsigned long    length;  /* In little endian order */
+    unsigned char    id[8];   /* null-terminated string  */
+    unsigned char    data[/* (length + 3) & ~3 */];
+@};
+
+struct packet @{
+    struct header    header;
+    unsigned char    items;
+    unsigned char    filler[3];
+    struct data      item[/* items */];
+
+@};
+@end example
+
+The corresponding data layout specification:
+
+@lisp
+(setq header-spec
+      '((dest-ip   ip)
+        (src-ip    ip)
+        (dest-port u16)
+        (src-port  u16)))
+
+(setq data-spec
+      '((type      u8)
+        (opcode    u8)
+        (length    u16r) ;; little endian order
+        (id        strz 8)
+        (data      vec (length))
+        (align     4)))
+
+(setq packet-spec
+      '((header    struct header-spec)
+        (items     u8)
+        (fill      3)
+        (item      repeat (items)
+                   (struct data-spec))))
+@end lisp
+
+A binary data representation:
+
+@lisp
+(setq binary-data
+      [ 192 168 1 100 192 168 1 101 01 28 21 32 2 0 0 0
+        2 3 5 0 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
+        1 4 7 0 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
+@end lisp
+
+The corresponding decoded structure:
+
+@lisp
+(setq decoded (bindat-unpack packet-spec binary-data))
+     @result{}
+((header
+  (dest-ip   . [192 168 1 100])
+  (src-ip    . [192 168 1 101])
+  (dest-port . 284)
+  (src-port  . 5408))
+ (items . 2)
+ (item ((data . [1 2 3 4 5])
+        (id . "ABCDEF")
+        (length . 5)
+        (opcode . 3)
+        (type . 2))
+       ((data . [6 7 8 9 10 11 12])
+        (id . "BCDEFG")
+        (length . 7)
+        (opcode . 4)
+        (type . 1))))
+@end lisp
+
+Fetching data from this structure:
+
+@lisp
+(bindat-get-field decoded 'item 1 'id)
+     @result{} "BCDEFG"
+@end lisp
+
 @ignore
    arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
 @end ignore
-
diff --git a/lispref/searching.texi b/lispref/searching.texi
index 15037068dd2..f2f21458506 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -244,16 +244,15 @@ first tries to match all three @samp{a}s; but the rest of the pattern is
 The next alternative is for @samp{a*} to match only two @samp{a}s.  With
 this choice, the rest of the regexp matches successfully.@refill
 
-Nested repetition operators can be extremely slow or loop infinitely
-if they use repetition operators inside repetition operators.  For
-example, it could take hours for the regular expression
-@samp{\(x+y*\)*a} to try to match the sequence
-@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately
-fails.  Emacs must try each way of grouping the 35 @samp{x}s before
-concluding that none of them can work.  Even worse, @samp{\(x*\)*} can
-match the null string in infinitely many ways, so it causes an
-infinite loop.  To avoid these problems, check nested repetitions
-carefully.
+Nested repetition operators take a long time, or even forever, if they
+lead to ambiguous matching.  For example, trying to match the regular
+expression @samp{\(x+y*\)*a} against the string
+@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could take hours before it
+ultimately fails.  Emacs must try each way of grouping the 35
+@samp{x}s before concluding that none of them can work.  Even worse,
+@samp{\(x*\)*} can match the null string in infinitely many ways, so
+it causes an infinite loop.  To avoid these problems, check nested
+repetitions carefully.
 
 @item @samp{+}
 @cindex @samp{+} in regexp
@@ -347,9 +346,10 @@ different characters.
 
 @item @samp{[^ @dots{} ]}
 @cindex @samp{^} in regexp
-@samp{[^} begins a @dfn{complemented character alternative}, which matches any
-character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
-all characters @emph{except} letters and digits.
+@samp{[^} begins a @dfn{complemented character alternative}.  This
+matches any character except the ones specified.  Thus,
+@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
+digits.
 
 @samp{^} is not special in a character alternative unless it is the first
 character.  The character following the @samp{^} is treated as if it
@@ -1531,8 +1531,9 @@ are reseated to point to nowhere, and if the value is @code{evaporate},
 the markers are put back on the free list.
 
 @strong{Warning:} When @code{evaporate} is specified for @var{reseat},
-no other references to the markers on the @var{reuse} list; otherwise,
-Emacs may crash during the next garbage collection.
+you must ensure that no other references to the markers on the
+@var{reuse} list exists; otherwise, Emacs may crash during the next
+garbage collection.
 
 As always, there must be no possibility of intervening searches between
 the call to a search function and the call to @code{match-data} that is
@@ -1563,8 +1564,9 @@ are reseated to point to nowhere, and if the value is @code{evaporate},
 the markers are put back on the free list.
 
 @strong{Warning:} When @code{evaporate} is specified for @var{reseat},
-no other references to the markers on the @var{match-list} list; otherwise,
-Emacs may crash during the next garbage collection.
+you must ensure that no other references to the markers on the
+@var{match-list} list exists; otherwise, Emacs may crash during the
+next garbage collection.
 
 @findex store-match-data
 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
diff --git a/lispref/strings.texi b/lispref/strings.texi
index b70e8d9f9d4..d0504684f82 100644
--- a/lispref/strings.texi
+++ b/lispref/strings.texi
@@ -298,7 +298,8 @@ useful.  If you need such a result, use an explicit value for
 @var{separators}:
 
 @example
-(split-string "  two words " split-string-default-separators)
+(split-string "  two words "
+              split-string-default-separators)
      @result{} ("" "two" "words" "")
 @end example
 
@@ -353,8 +354,8 @@ practice:
 @end defun
 
 @defvar split-string-default-separators
-The default value of @var{separators} for @code{split-string}, initially
-@w{@samp{"[ \f\t\n\r\v]+"}}.
+The default value of @var{separators} for @code{split-string}.  Its
+usual value is @w{@samp{"[ \f\t\n\r\v]+"}}.
 @end defvar
 
 @node Modifying Strings
diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index e8707709fe2..282cbca794d 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -754,10 +754,11 @@ necessary to flush the cache manually.
 @end defun
 
 @defvar syntax-begin-function
-If this is non-nil, it should be a function that moves to an earlier
-buffer position where the parser state is equivalent to @code{nil},
-i.e., a position outside of any comment, string, or parenthesis.
-@code{syntax-ppss} uses it to supplement its cache.
+If this is non-@code{nil}, it should be a function that moves to an
+earlier buffer position where the parser state is equivalent to
+@code{nil}---in other words, a position outside of any comment,
+string, or parenthesis.  @code{syntax-ppss} uses it to supplement its
+cache.
 @end defvar
 
 @defun scan-lists from count depth
diff --git a/lispref/text.texi b/lispref/text.texi
index cddeeb8fbde..5a4d743ab75 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -1497,10 +1497,10 @@ of justification.  It can be @code{left}, @code{right}, @code{full},
 follow specified justification style (see @code{current-justification},
 below).  @code{nil} means to do full justification.
 
-If @var{eop} is non-@code{nil}, that means do left-justification if
-@code{current-justification} specifies full justification.  This is used
-for the last line of a paragraph; even if the paragraph as a whole is
-fully justified, the last line should not be.
+If @var{eop} is non-@code{nil}, that means do only left-justification
+if @code{current-justification} specifies full justification.  This is
+used for the last line of a paragraph; even if the paragraph as a
+whole is fully justified, the last line should not be.
 
 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
 whitespace.
@@ -1727,12 +1727,11 @@ Adaptive Fill mode matches this regular expression against the text
 starting after the left margin whitespace (if any) on a line; the
 characters it matches are that line's candidate for the fill prefix.
 
-The default value of this variable is
-@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}}.  This
-matches a number enclosed in parentheses or followed by a period,
-or certain punctuation characters, or any sequence of these
-intermingled with whitespace.  In particular, it matches a sequence of
-whitespace, possibly empty.
+@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
+default value.  This matches a number enclosed in parentheses or
+followed by a period, or certain punctuation characters, or any
+sequence of these intermingled with whitespace.  In particular, it
+matches a sequence of whitespace, possibly empty.
 @end defopt
 
 @defopt adaptive-fill-first-line-regexp
@@ -2969,7 +2968,8 @@ A cons cell of the form @code{(foreground-color . @var{color-name})} or
 just the foreground color or just the background color.
 
 @code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+specifying @code{(:foreground @var{color-name})}, and likewise for the
+background.
 @end itemize
 
 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
@@ -3561,9 +3561,9 @@ The action code is always @code{t}.
 
 For example, here is how Info mode handles @key{Mouse-1}:
 
-@example
+@smallexample
 (define-key Info-mode-map [follow-link] 'mouse-face)
-@end example
+@end smallexample
 
 @item a function
 If the condition is a valid function, @var{func}, then a position
@@ -3574,11 +3574,11 @@ action code.
 For example, here is how pcvs enables @key{Mouse-1} to follow links on
 file names only:
 
-@example
+@smallexample
 (define-key map [follow-link]
   (lambda (pos)
-    (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
-@end example
+    (eq (get-char-property pos 'face) 'cvs-filename-face)))
+@end smallexample
 
 @item anything else
 If the condition value is anything else, then the position is inside a
diff --git a/lispref/variables.texi b/lispref/variables.texi
index 27f0f4a7029..8ee941892c9 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -1722,24 +1722,24 @@ be called later, or an expression that would be executed later, simply
 visiting a file could take over your Emacs.  To prevent this, Emacs
 takes care not to allow to set such file local variables.
 
-  For one thing, any variable whose name ends in @samp{-command},
-@samp{-frame-alist}, @samp{-function}, @samp{-functions},
-@samp{-hook}, @samp{-hooks}, @samp{-form}, @samp{-forms}, @samp{-map},
-@samp{-map-alist}, @samp{-mode-alist}, @samp{-program}, or
-@samp{-predicate} cannot be given a file local value.  In general,
-you should use such a name whenever it is appropriate for the
-variable's meaning.  The variables @samp{font-lock-keywords},
-@samp{font-lock-keywords-[0-9]}, and
-@samp{font-lock-syntactic-keywords} cannot be given file local values either.
-These rules can be overridden by giving the variable's
-name a non-@code{nil} @code{safe-local-variable} property.  If one
-gives it a @code{safe-local-variable} property of @code{t}, then one
-can give the variable any file local value.  One can also give any
-symbol, including the above, a @code{safe-local-variable} property
-that is a function taking exactly one argument.  In that case, giving
-a variable with that name a file local value is only allowed if the
-function returns non-@code{nil} when called with that value as
-argument.
+  For one thing, any variable whose name ends in any of
+@samp{-command}, @samp{-frame-alist}, @samp{-function},
+@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
+@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist},
+@samp{-program}, or @samp{-predicate} cannot be given a file local
+value.  In general, you should use such a name whenever it is
+appropriate for the variable's meaning.  The variables
+@samp{font-lock-keywords}, @samp{font-lock-keywords} followed by a
+digit, and @samp{font-lock-syntactic-keywords} cannot be given file
+local values either.  These rules can be overridden by giving the
+variable's name a non-@code{nil} @code{safe-local-variable} property.
+If one gives it a @code{safe-local-variable} property of @code{t},
+then one can give the variable any file local value.  One can also
+give any symbol, including the above, a @code{safe-local-variable}
+property that is a function taking exactly one argument.  In that
+case, giving a variable with that name a file local value is only
+allowed if the function returns non-@code{nil} when called with that
+value as argument.
 
   In addition, any variable whose name has a non-@code{nil}
 @code{risky-local-variable} property is also ignored.  So are all
@@ -1785,19 +1785,19 @@ chosen, or because its meaning has partly changed---it can be useful
 to keep the old name as an @emph{alias} of the new one for
 compatibility.  You can do this with @code{defvaralias}.
 
-@defun defvaralias alias-var base-var &optional docstring
-This function defines the symbol @var{alias-var} as a variable alias
-for symbol @var{base-var}. This means that retrieving the value of
-@var{alias-var} returns the value of @var{base-var}, and changing the
-value of @var{alias-var} changes the value of @var{base-var}.
+@defun defvaralias new-alias base-variable &optional docstring
+This function defines the symbol @var{new-alias} as a variable alias
+for symbol @var{base-variable}. This means that retrieving the value of
+@var{new-alias} returns the value of @var{base-variable}, and changing the
+value of @var{new-alias} changes the value of @var{base-variable}.
 
 If the @var{docstring} argument is non-@code{nil}, it specifies the
-documentation for @var{alias-var}; otherwise, the alias gets the same
-documentation as @var{base-var} has, if any, unless @var{base-var} is
-itself an alias, in which case @var{alias-var} gets the documentation
-of the variable at the end of the chain of aliases.
+documentation for @var{new-alias}; otherwise, the alias gets the same
+documentation as @var{base-variable} has, if any, unless
+@var{base-variable} is itself an alias, in which case @var{new-alias} gets
+the documentation of the variable at the end of the chain of aliases.
 
-This function returns @var{base-var}.
+This function returns @var{base-variable}.
 @end defun
 
   Variable aliases are convenient for replacing an old name for a
@@ -1805,12 +1805,12 @@ variable with a new name.  @code{make-obsolete-variable} declares that
 the old name is obsolete and therefore that it may be removed at some
 stage in the future.
 
-@defun make-obsolete-variable variable new &optional when
+@defun make-obsolete-variable obsolete-name current-name &optional when
 This function makes the byte-compiler warn that the variable
-@var{variable} is obsolete.  If @var{new} is a symbol, it is the
-variable's new name; then the warning message says to use @var{new}
-instead of @var{variable}.  If @var{new} is a string, this is the
-message and there is no replacement variable.
+@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, it is
+the variable's new name; then the warning message says to use
+@var{current-name} instead of @var{obsolete-name}.  If @var{current-name}
+is a string, this is the message and there is no replacement variable.
 
 If provided, @var{when} should be a string indicating when the
 variable was first made obsolete---for example, a date or a release
@@ -1820,20 +1820,14 @@ number.
   You can make two variables synonyms and declare one obsolete at the
 same time using the macro @code{define-obsolete-variable-alias}.
 
-@defmac define-obsolete-variable-alias variable new &optional when docstring
-This macro marks the variable @var{variable} as obsolete and also
-makes it an alias for the variable @var{new}.  A typical call has the form:
+@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring
+This macro marks the variable @var{obsolete-name} as obsolete and also
+makes it an alias for the variable @var{current-name}.  It is
+equivalent to the following:
 
 @example
-(define-obsolete-variable-alias 'old-var 'new-var "22.1" "Doc.")
-@end example
-
-@noindent
-which is equivalent to the following two lines of code:
-
-@example
-(defvaralias 'oldvar 'newvar "Doc.")
-(make-obsolete-variable 'old-var 'new-var "22.1")
+(defvaralias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when})
 @end example
 @end defmac