13 files changed, 292 insertions, 187 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 7455881518a..8f675bfcda6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,10 +1,66 @@
-2013-03-16  Glenn Morris  <rgm@gnu.org>
+2013-05-29  Stefan Monnier  <monnier@iro.umontreal.ca>
 
-        * elisp.texi: Add some stuff specific to www.gnu.org.
+        * functions.texi (Lambda Expressions): Lambda expressions don't
+        evaluate to themselves in general (bug#11782).
+
+2013-05-15  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * loading.texi (Autoload):
+        * help.texi (Documentation Basics, Accessing Documentation)
+        (Accessing Documentation, Accessing Documentation): DOC-* is now DOC.
+
+2013-04-23  Glenn Morris  <rgm@gnu.org>
+
+        * internals.texi (Writing Emacs Primitives): Remove obvious example.
+        Tweak other to avoid overly long line.
+
+2013-04-21  Xue Fuqiao  <xfq.free@gmail.com>
+
+        * internals.texi (Writing Emacs Primitives): Remove unnecessary
+        references to the sources. (Bug#13800)
+
+        * searching.texi (Regexp Backslash): Doc fix for backslash
+        constructs in regular expressions.
+
+2013-04-15  Christopher Schmidt  <christopher@ch.ristopher.com>
+
+        * tips.texi (Coding Conventions): Mention separation of package
+        descriptor and name of internal symbols by two hyphens.
+
+2013-04-13  Stephen Berman  <stephen.berman@gmx.net>
+
+        * windows.texi (Splitting Windows): Change category of
+        split-window from a command to a function.
+
+2013-04-06  Chong Yidong  <cyd@gnu.org>
+
+        * display.texi (Faces): Minor clarifications.
+        (Defining Faces): Clarify default vs custom face specs.
+        Document face-spec-set.
+
+        * display.texi (Overlay Properties):
+        * text.texi (Special Properties): Use the "anonymous face"
+        terminology.  Describe foreground-color and background-color forms
+        as compatibility-only.
+
+2013-03-24  Eli Zaretskii  <eliz@gnu.org>
+
+        * compile.texi (Byte-Code Objects): Add index entry.
+        (Disassembly): Add cross-references.
+
+2013-03-23  Eli Zaretskii  <eliz@gnu.org>
+
+        * frames.texi (Size Parameters): More accurate description of the
+        difference between 'fullboth' and 'maximized'.  (Bug#13935)
+
+2013-03-17  Christopher Schmidt  <christopher@ch.ristopher.com>
+
+        * symbols.texi (Standard Properties): Document pure.  (Bug#13823)
 
 2013-03-16  Glenn Morris  <rgm@gnu.org>
 
-        * Version 24.3 released.
+        * elisp.texi: Add some stuff specific to www.gnu.org.
+
 2013-03-11  Teodor Zlatanov  <tzz@lifelogs.com>
 
         * control.texi (Pattern matching case statement): Fix typo.
@@ -2005,8 +2061,8 @@
 
 2012-02-04  Chong Yidong  <cyd@gnu.org>
 
-        * functions.texi (What Is a Function): Add closures.  Mention
-        "return value" terminology.  Add xref for command-execute.
+        * functions.texi (What Is a Function): Add closures.
+        Mention "return value" terminology.  Add xref for command-execute.
         Remove unused "keystroke command" terminology.
         (Lambda Expressions): Give a different example than in the
         following subsection.  Add xref to Anonymous Functions.
@@ -11553,7 +11609,7 @@
 
 2002-05-13  Kim F. Storm  <storm@cua.dk>
 
-        * variables.texi (Intro to Buffer-Local): Updated warning and
+        * variables.texi (Intro to Buffer-Local): Update warning and
         example relating to changing buffer inside let.
 
 2002-03-10  Jan Djärv  <jan.h.d@swipnet.se>
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index d60ffebae70..522a88da61e 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -514,6 +514,7 @@ one you intend to suppress.
 @section Byte-Code Function Objects
 @cindex compiled function
 @cindex byte-code function
+@cindex byte-code object
 
   Byte-compiled functions have a special data type: they are
 @dfn{byte-code function objects}.  Whenever such an object appears as
@@ -606,8 +607,9 @@ name of an existing buffer.  Then the output goes there, at point, and
 point is left before the output.
 
 The argument @var{object} can be a function name, a lambda expression
-or a byte-code object.  If it is a lambda expression, @code{disassemble}
-compiles it and disassembles the resulting compiled code.
+(@pxref{Lambda Expressions}), or a byte-code object (@pxref{Byte-Code
+Objects}).  If it is a lambda expression, @code{disassemble} compiles
+it and disassembles the resulting compiled code.
 @end deffn
 
   Here are two examples of using the @code{disassemble} function.  We
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index eae6af9969d..4adcfdf8f4f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1510,31 +1510,31 @@ of the symbol serve as defaults for the properties of the overlay.
 
 @item face
 @kindex face @r{(overlay property)}
-This property controls the way text is displayed---for example, which
-font and which colors.  @xref{Faces}, for more information.
-
-In the simplest case, the value is a face name.  It can also be a list;
-then each element can be any of these possibilities:
+This property controls the appearance of the text (@pxref{Faces}).
+The value of the property can be the following:
 
 @itemize @bullet
 @item
 A face name (a symbol or string).
 
 @item
-A property list of face attributes.  This has the form (@var{keyword}
-@var{value} @dots{}), where each @var{keyword} is a face attribute
-name and @var{value} is a meaningful value for that attribute.  With
-this feature, you do not need to create a face each time you want to
-specify a particular attribute for certain text.  @xref{Face
-Attributes}.
+An anonymous face: a property list of the form @code{(@var{keyword}
+@var{value} @dots{})}, where each @var{keyword} is a face attribute
+name and @var{value} is a value for that attribute.
 
 @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.
+A list of faces.  Each list element should be either a face name or an
+anonymous face.  This specifies a face which is an aggregate of the
+attributes of each of the listed faces.  Faces occurring earlier in
+the list have higher priority.
 
-@code{(foreground-color . @var{color-name})} has the same effect as
-@code{(:foreground @var{color-name})}; likewise for the background.
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}.  This specifies the
+foreground or background color, similar to @code{(:foreground
+@var{color-name})} or @code{(:background @var{color-name})}.  This
+form is supported for backward compatibility only, and should be
+avoided.
 @end itemize
 
 @item mouse-face
@@ -1901,44 +1901,39 @@ height.
 @section Faces
 @cindex faces
 
-  A @dfn{face} is a collection of graphical @dfn{attributes} for
-displaying text: font, foreground color, background color, optional
-underlining, etc.  Faces control how Emacs displays text in buffers,
-as well as other parts of the frame such as the mode line.
+  A @dfn{face} is a collection of graphical attributes for displaying
+text: font, foreground color, background color, optional underlining,
+etc.  Faces control how Emacs displays text in buffers, as well as
+other parts of the frame such as the mode line.
 
 @cindex anonymous face
   One way to represent a face is as a property list of attributes,
-like @code{(:foreground "red" :weight bold)}.  For example, you can
-assign such an @dfn{anonymous face} as the value of the @code{face}
-text property; this causes Emacs to display the underlying text with
-the specified attributes.  @xref{Special Properties}.
+like @code{(:foreground "red" :weight bold)}.  Such a list is called
+an @dfn{anonymous face}.  For example, you can assign an anonymous
+face as the value of the @code{face} text property, and Emacs will
+display the underlying text with the specified attributes.
+@xref{Special Properties}.
 
 @cindex face name
   More commonly, a face is referred to via a @dfn{face name}: a Lisp
-symbol which is associated with a set of face attributes.  Named faces
-are defined using the @code{defface} macro (@pxref{Defining Faces}).
-Emacs defines several standard named faces; @xref{Standard Faces,,,
-emacs, The GNU Emacs Manual}.
-
-  Many parts of Emacs require named faces, and do not accept anonymous
-faces.  These include the functions documented in @ref{Attribute
-Functions}, and the variable @code{font-lock-keywords}
+symbol associated with a set of face attributes@footnote{For backward
+compatibility, you can also use a string to specify a face name; that
+is equivalent to a Lisp symbol with the same name.}.  Named faces are
+defined using the @code{defface} macro (@pxref{Defining Faces}).
+Emacs comes with several standard named faces (@pxref{Basic Faces}).
+
+  Many parts of Emacs required named faces, and do not accept
+anonymous faces.  These include the functions documented in
+@ref{Attribute Functions}, and the variable @code{font-lock-keywords}
 (@pxref{Search-based Fontification}).  Unless otherwise stated, we
 will use the term @dfn{face} to refer only to named faces.
 
-  For backward compatibility, you can also use a string to specify a
-face name; that is equivalent to a Lisp symbol with the same name.
-
 @defun facep object
 This function returns a non-@code{nil} value if @var{object} is a
 named face: a Lisp symbol or string which serves as a face name.
 Otherwise, it returns @code{nil}.
 @end defun
 
-  By default, each face name corresponds to the same set of attributes
-in all frames.  But you can also assign a face name a special set of
-attributes in one frame (@pxref{Attribute Functions}).
-
 @menu
 * Face Attributes::     What is in a face?
 * Defining Faces::      How to define a face.
@@ -2178,32 +2173,47 @@ suitable for use with @code{:stipple} (see above).  It returns
 @node Defining Faces
 @subsection Defining Faces
 
+@cindex face spec
   The usual way to define a face is through the @code{defface} macro.
-This macro defines a face name, and associates that name with a set of
-face attributes.  It also sets up the face so that the user can
-customize it via the Customize interface (@pxref{Customization}).
+This macro associates a face name (a symbol) with a default @dfn{face
+spec}.  A face spec is a construct which specifies what attributes a
+face should have on any given terminal; for example, a face spec might
+specify one foreground color on high-color terminals, and a different
+foreground color on low-color terminals.
+
+  People are sometimes tempted to create a variable whose value is a
+face name.  In the vast majority of cases, this is not necessary; the
+usual procedure is to define a face with @code{defface}, and then use
+its name directly.
 
 @defmac defface face spec doc [keyword value]@dots{}
-This macro declares @var{face} as a customizable face whose default
-attributes are given by @var{spec}.  You should not quote the symbol
-@var{face}, and it should not end in @samp{-face} (that would be
-redundant).  The argument @var{doc} is a documentation string for the
-face.  The additional @var{keyword} arguments have the same meanings
-as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
-
-When @code{defface} executes, it defines the face according to
-@var{spec}, then uses any customizations that were read from the
-init file (@pxref{Init File}) to override that specification.
-
-When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
-Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
-overrides any customizations of the face.  This way, the face reflects
-exactly what the @code{defface} says.
-
-@cindex face specification
-The @var{spec} argument is a @dfn{face specification}, which states
-how the face should appear on different kinds of terminals.  It should
-be an alist whose elements each have the form
+This macro declares @var{face} as a named face whose default face spec
+is given by @var{spec}.  You should not quote the symbol @var{face},
+and it should not end in @samp{-face} (that would be redundant).  The
+argument @var{doc} is a documentation string for the face.  The
+additional @var{keyword} arguments have the same meanings as in
+@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+
+If @var{face} already has a default face spec, this macro does
+nothing.
+
+The default face spec determines @var{face}'s appearance when no
+customizations are in effect (@pxref{Customization}).  If @var{face}
+has already been customized (via Custom themes or via customizations
+read from the init file), its appearance is determined by the custom
+face spec(s), which override the default face spec @var{spec}.
+However, if the customizations are subsequently removed, the
+appearance of @var{face} will again be determined by its default face
+spec.
+
+As an exception, if you evaluate a @code{defface} form with
+@kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature
+of @code{eval-defun} overrides any custom face specs on the face,
+causing the face to reflect exactly what the @code{defface} says.
+
+The @var{spec} argument is a @dfn{face spec}, which states how the
+face should appear on different kinds of terminals.  It should be an
+alist whose elements each have the form
 
 @example
 (@var{display} . @var{plist})
@@ -2275,7 +2285,8 @@ terminal must match one of the @var{value}s specified for it in
 @end table
 @end defmac
 
-  Here's how the standard face @code{highlight} is defined:
+  For example, here's the definition of the standard face
+@code{highlight}:
 
 @example
 (defface highlight
@@ -2294,65 +2305,56 @@ terminal must match one of the @var{value}s specified for it in
   :group 'basic-faces)
 @end example
 
-  Internally, Emacs stores the face's default specification in its
+  Internally, Emacs stores each face's default spec in its
 @code{face-defface-spec} symbol property (@pxref{Symbol Properties}).
-The @code{saved-face} property stores the face specification saved by
-the user, using the customization buffer; the @code{customized-face}
-property stores the face specification customized for the current
-session, but not saved; and the @code{theme-face} property stores an
-alist associating the active customization settings and Custom themes
-with their specifications for that face.  The face's documentation
-string is stored in the @code{face-documentation} property.  But
-normally you should not try to set any of these properties directly.
-@xref{Applying Customizations}, for the @code{custom-set-faces}
-function, which is used to apply customized face settings.
-
-  People are sometimes tempted to create variables whose values
-specify a face to use.  In the vast majority of cases, this is not
-necessary; it is preferable to simply use faces directly.
+The @code{saved-face} property stores any face spec saved by the user
+using the customization buffer; the @code{customized-face} property
+stores the face spec customized for the current session, but not
+saved; and the @code{theme-face} property stores an alist associating
+the active customization settings and Custom themes with the face
+specs for that face.  The face's documentation string is stored in the
+@code{face-documentation} property.
+
+  Normally, a face is declared just once, using @code{defface}, and
+any further changes to its appearance are applied using the Customize
+framework (e.g., via the Customize user interface or via the
+@code{custom-set-faces} function; @pxref{Applying Customizations}), or
+by face remapping (@pxref{Face Remapping}).  In the rare event that
+you need to change a face spec directly from Lisp, you can use the
+@code{face-spec-set} function.
+
+@defun face-spec-set face spec &optional spec-type
+This function applies @var{spec} as a face spec for @code{face}.
+@var{spec} should be a face spec, as described in the above
+documentation for @code{defface}.
+
+@cindex override spec @r{(for a face)}
+The argument @var{spec-type} determines which spec to set.  If it is
+@code{nil} or @code{face-override-spec}, this function sets the
+@dfn{override spec}, which overrides over all other face specs on
+@var{face}.  If it is @code{face-defface-spec}, this function sets the
+default face spec (the same one set by @code{defface}).  If it is
+@code{reset}, this function clears out all customization specs and
+override specs from @var{face} (in this case, the value of @var{spec}
+is ignored).  Any other value of @var{spec-type} is reserved for
+internal use.
+@end defun
 
 @node Attribute Functions
 @subsection Face Attribute Functions
 
-  This section describes the functions for accessing and modifying the
-attributes of an existing named face.
-
-@defun set-face-attribute face frame &rest arguments
-This function sets one or more attributes of @var{face} for
-@var{frame}.  The attributes you specify this way override whatever
-the @code{defface} says.
-
-The extra arguments @var{arguments} specify the attributes to set, and
-the values for them.  They should consist of alternating attribute
-names (such as @code{:family} or @code{:underline}) and values.  Thus,
-
-@example
-(set-face-attribute 'foo nil
-                    :width 'extended
-                    :weight 'bold)
-@end example
-
-@noindent
-sets the attribute @code{:width} to @code{extended} and the attribute
-@code{:weight} to @code{bold}.
-
-If @var{frame} is @code{t}, this function sets the default attributes
-for new frames.  Default attribute values specified this way override
-the @code{defface} for newly created frames.
-
-If @var{frame} is @code{nil}, this function sets the attributes for
-all existing frames, and the default for new frames.
-@end defun
+  This section describes functions for directly accessing and
+modifying the attributes of a named face.
 
 @defun face-attribute face attribute &optional frame inherit
-This returns the value of the @var{attribute} attribute of @var{face}
-on @var{frame}.  If @var{frame} is @code{nil}, that means the selected
-frame (@pxref{Input Focus}).
+This function returns the value of the @var{attribute} attribute for
+@var{face} on @var{frame}.
 
-If @var{frame} is @code{t}, this returns whatever new-frames default
-value you previously specified with @code{set-face-attribute} for the
-@var{attribute} attribute of @var{face}.  If you have not specified
-one, it returns @code{nil}.
+If @var{frame} is @code{nil}, that means the selected frame
+(@pxref{Input Focus}).  If @var{frame} is @code{t}, this function
+returns the value of the specified attribute for newly-created frames
+(this is normally @code{unspecified}, unless you have specified some
+value using @code{set-face-attribute}; see below).
 
 If @var{inherit} is @code{nil}, only attributes directly defined by
 @var{face} are considered, so the return value may be
@@ -2411,6 +2413,36 @@ If @var{value1} is a relative value for the face attribute
 face attribute @var{attribute}, returns @var{value1} unchanged.
 @end defun
 
+  Normally, Emacs uses the face specs of each face to automatically
+calculate its attributes on each frame (@pxref{Defining Faces}).  The
+function @code{set-face-attribute} can override this calculation by
+directly assigning attributes to a face, either on a specific frame or
+for all frames.  This function is mostly intended for internal usage.
+
+@defun set-face-attribute face frame &rest arguments
+This function sets one or more attributes of @var{face} for
+@var{frame}.  The attributes specifies in this way override the face
+spec(s) belonging to @var{face}.
+
+The extra arguments @var{arguments} specify the attributes to set, and
+the values for them.  They should consist of alternating attribute
+names (such as @code{:family} or @code{:underline}) and values.  Thus,
+
+@example
+(set-face-attribute 'foo nil :weight 'bold :slant 'italic)
+@end example
+
+@noindent
+sets the attribute @code{:weight} to @code{bold} and the attribute
+@code{:slant} to @code{italic}.
+
+
+If @var{frame} is @code{t}, this function sets the default attributes
+for newly created frames.  If @var{frame} is @code{nil}, this function
+sets the attributes for all existing frames, as well as for newly
+created frames.
+@end defun
+
   The following commands and functions mostly provide compatibility
 with old versions of Emacs.  They work by calling
 @code{set-face-attribute}.  Values of @code{t} and @code{nil} for
@@ -2457,16 +2489,17 @@ This sets the @code{:inverse-video} attribute of @var{face} to
 This swaps the foreground and background colors of face @var{face}.
 @end deffn
 
-  The following functions examine the attributes of a face.  If you
-don't specify @var{frame}, they refer to the selected frame; @code{t}
-refers to the default data for new frames.  They return the symbol
-@code{unspecified} if the face doesn't define any value for that
-attribute.  If @var{inherit} is @code{nil}, only an attribute directly
-defined by the face is returned.  If @var{inherit} is non-@code{nil},
-any faces specified by its @code{:inherit} attribute are considered as
-well, and if @var{inherit} is a face or a list of faces, then they are
-also considered, until a specified attribute is found.  To ensure that
-the return value is always specified, use a value of @code{default} for
+  The following functions examine the attributes of a face.  They
+mostly provide compatibility with old versions of Emacs.  If you don't
+specify @var{frame}, they refer to the selected frame; @code{t} refers
+to the default data for new frames.  They return @code{unspecified} if
+the face doesn't define any value for that attribute.  If
+@var{inherit} is @code{nil}, only an attribute directly defined by the
+face is returned.  If @var{inherit} is non-@code{nil}, any faces
+specified by its @code{:inherit} attribute are considered as well, and
+if @var{inherit} is a face or a list of faces, then they are also
+considered, until a specified attribute is found.  To ensure that the
+return value is always specified, use a value of @code{default} for
 @var{inherit}.
 
 @defun face-font face &optional frame
@@ -2576,13 +2609,13 @@ The value of this variable is an alist whose elements have the form
 any text having the face @var{face} with @var{remapping}, rather than
 the ordinary definition of @var{face}.
 
-@var{remapping} may be any face specification suitable for a
-@code{face} text property: either a face (i.e., a face name or a
-property list of attribute/value pairs), or a list of faces.  For
-details, see the description of the @code{face} text property in
-@ref{Special Properties}.  @var{remapping} serves as the complete
-specification for the remapped face---it replaces the normal
-definition of @var{face}, instead of modifying it.
+@var{remapping} may be any face spec suitable for a @code{face} text
+property: either a face (i.e., a face name or a property list of
+attribute/value pairs), or a list of faces.  For details, see the
+description of the @code{face} text property in @ref{Special
+Properties}.  @var{remapping} serves as the complete specification for
+the remapped face---it replaces the normal definition of @var{face},
+instead of modifying it.
 
 If @code{face-remapping-alist} is buffer-local, its local value takes
 effect only within that buffer.
@@ -2629,7 +2662,7 @@ and @code{face-remap-reset-base} functions; it is intended for major
 modes to remap faces in the buffers they control.
 
 @defun face-remap-add-relative face &rest specs
-This functions adds the face specifications in @var{specs} as relative
+This functions adds the face spec in @var{specs} as relative
 remappings for face @var{face} in the current buffer.  The remaining
 arguments, @var{specs}, should form either a list of face names, or a
 property list of attribute/value pairs.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 7d56d38ffad..01d2d1d6c45 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -632,8 +632,9 @@ possible.  The value @code{fullboth} specifies that both the width and
 the height shall be set to the size of the screen.  The value
 @code{maximized} specifies that the frame shall be maximized.  The
 difference between @code{maximized} and @code{fullboth} is that the
-former still has window manager decorations while the latter really
-covers the whole screen.
+former can still be resized by dragging window manager decorations
+with the mouse, while the latter really covers the whole screen and
+does not allow resizing by mouse dragging.
 @end table
 
 @node Layout Parameters
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 999923f5b84..7768c147827 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -196,9 +196,8 @@ an example:
 @end example
 
 @noindent
-In Emacs Lisp, such a list is valid as an expression---it evaluates to
-itself.  But its main use is not to be evaluated as an expression, but
-to be called as a function.
+In Emacs Lisp, such a list is a valid expression which evaluates to
+a function object.
 
   A lambda expression, by itself, has no name; it is an @dfn{anonymous
 function}.  Although lambda expressions can be used this way
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 9fe069b84d0..aa77ba1f36d 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -93,13 +93,12 @@ When you define a variable with a @code{defvar} or related form
 (@pxref{Defining Variables}), the documentation is stored in the
 variable's @code{variable-documentation} property.
 
-@cindex @file{DOC-@var{version}} (documentation) file
+@cindex @file{DOC} (documentation) file
 @item
 To save memory, the documentation for preloaded functions and
 variables (including primitive functions and autoloaded functions) is
 not kept in memory, but in the file
-@file{emacs/etc/DOC-@var{version}}, where @var{version} is the Emacs
-version number (@pxref{Version Info}).
+@file{emacs/etc/DOC}).
 
 @item
 When a function or variable is loaded from a byte-compiled file during
@@ -126,7 +125,7 @@ customization groups (but for function documentation, use the
 @code{documentation} command, below).
 
 If the value recorded in the property list refers to a documentation
-string stored in a @file{DOC-@var{version}} file or a byte-compiled
+string stored in a @file{DOC} file or a byte-compiled
 file, it looks up that string and returns it.  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 as a Lisp expression to obtain a string.
@@ -296,12 +295,12 @@ memory in the function definitions and variable property lists.
 Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
 When the dumped Emacs is later executed, the same file will be looked
 for in the directory @code{doc-directory}.  Usually @var{filename} is
-@code{"DOC-@var{version}"}.
+@code{"DOC"}.
 @end defun
 
 @defvar doc-directory
 This variable holds the name of the directory which should contain the
-file @code{"DOC-@var{version}"} that contains documentation strings for
+file @code{"DOC"} that contains documentation strings for
 built-in and preloaded functions and variables.
 
 In most cases, this is the same as @code{data-directory}.  They may be
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 3269776b626..06375c1e18e 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -661,15 +661,25 @@ equivalent of @code{&rest}).  Both @code{UNEVALLED} and @code{MANY} are
 macros.  If @var{max} is a number, it must be more than @var{min} but
 less than 8.
 
+@cindex interactive specification in primitives
 @item interactive
-This is an interactive specification, a string such as might be used as
-the argument of @code{interactive} in a Lisp function.  In the case of
-@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be
-called interactively.  A value of @code{""} indicates a function that
-should receive no arguments when called interactively.  If the value
-begins with a @samp{(}, the string is evaluated as a Lisp form.
-For examples of the last two forms, see @code{widen} and
-@code{narrow-to-region} in @file{editfns.c}.
+This is an interactive specification, a string such as might be used
+as the argument of @code{interactive} in a Lisp function.  In the case
+of @code{or}, it is 0 (a null pointer), indicating that @code{or}
+cannot be called interactively.  A value of @code{""} indicates a
+function that should receive no arguments when called interactively.
+If the value begins with a @samp{"(}, the string is evaluated as a
+Lisp form.  For example:
+
+@example
+@group
+DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED,
+       "(list (read-char-by-name \"Insert character: \")\
+              (prefix-numeric-value current-prefix-arg)\
+              t))",
+  doc: /* @dots{} /*)
+@end group
+@end example
 
 @item doc
 This is the documentation string.  It uses C comment syntax rather
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 51a060bc6c6..5c92307f7d5 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -483,7 +483,7 @@ For example,
 @noindent
 In this case, @code{"prolog"} is the name of the file to load, 169681
 refers to the documentation string in the
-@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
+@file{emacs/etc/DOC} file (@pxref{Documentation Basics}),
 @code{t} means the function is interactive, and @code{nil} that it is
 not a macro or a keymap.
 @end defun
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 87d4051d6f0..386d5bdde4c 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -589,10 +589,8 @@ through @samp{f} and @samp{A} through @samp{F}.
 
   For the most part, @samp{\} followed by any character matches only
 that character.  However, there are several exceptions: certain
-two-character sequences starting with @samp{\} that have special
-meanings.  (The character after the @samp{\} in such a sequence is
-always ordinary when used on its own.)  Here is a table of the special
-@samp{\} constructs.
+sequences starting with @samp{\} that have special meanings.  Here is
+a table of the special @samp{\} constructs.
 
 @table @samp
 @item \|
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 9f916549902..82dfa0f4917 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -539,8 +539,9 @@ deleted from the local value of a hook variable when changing major
 modes.  @xref{Setting Hooks}.
 
 @item pure
-This property is used internally to mark certain named functions for
-byte compiler optimization.  Do not set it.
+If the value is non-@code{nil}, the named function is considered to be
+side-effect free.  Calls with constant arguments can be evaluated at
+compile time.  This may shift run time errors to compile time.
 
 @item risky-local-variable
 If the value is non-@code{nil}, the named variable is considered risky
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index c6cbfa5b3f8..6d5a39d887a 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3008,27 +3008,31 @@ character.
 @item face
 @cindex face codes of text
 @kindex face @r{(text property)}
-The @code{face} property controls the appearance of the character,
-such as its font and color.  @xref{Faces}.  The value of the property
-can be the following:
+The @code{face} property controls the appearance of the character
+(@pxref{Faces}).  The value of the property can be the following:
 
 @itemize @bullet
 @item
 A face name (a symbol or string).
 
 @item
-A property list of face attributes.  This has the form (@var{keyword}
-@var{value} @dots{}), where each @var{keyword} is a face attribute
-name and @var{value} is a meaningful value for that attribute.  With
-this feature, you do not need to create a face each time you want to
-specify a particular attribute for certain text.
+An anonymous face: a property list of the form @code{(@var{keyword}
+@var{value} @dots{})}, where each @var{keyword} is a face attribute
+name and @var{value} is a value for that attribute.
 
 @item
-A list of faces.  This specifies a face which is an aggregate of the
+A list of faces.  Each list element should be either a face name or an
+anonymous face.  This specifies a face which is an aggregate of the
 attributes of each of the listed faces.  Faces occurring earlier in
-the list have higher priority.  Each list element must have one of the
-two above forms (i.e., either a face name or a property list of face
-attributes).
+the list have higher priority.
+
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}.  This specifies the
+foreground or background color, similar to @code{(:foreground
+@var{color-name})} or @code{(:background @var{color-name})}.  This
+form is supported for backward compatibility only, and should be
+avoided.
 @end itemize
 
 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4c443da3af8..c40ae408f7f 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -51,13 +51,15 @@ don't postpone it.
 
 @item
 You should choose a short word to distinguish your program from other
-Lisp programs.  The names of all global variables, constants, and
-functions in your program should begin with that chosen prefix.
-Separate the prefix from the rest of the name with a hyphen, @samp{-}.
-This practice helps avoid name conflicts, since all global variables
-in Emacs Lisp share the same name space, and all functions share
-another name space@footnote{The benefits of a Common Lisp-style
-package system are considered not to outweigh the costs.}.
+Lisp programs.  The names of all global symbols in your program, that
+is the names of variables, constants, and functions, should begin with
+that chosen prefix.  Separate the prefix from the rest of the name
+with a hyphen, @samp{-}.  Use two hyphens if the symbol is not meant
+to be used by other packages.  This practice helps avoid name
+conflicts, since all global variables in Emacs Lisp share the same
+name space, and all functions share another name space@footnote{The
+benefits of a Common Lisp-style package system are considered not to
+outweigh the costs.}.
 
 Occasionally, for a command name intended for users to use, it is more
 convenient if some words come before the package's name prefix.  And
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 792002add81..f2a4b3849dd 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -717,7 +717,7 @@ window.
 This section describes functions for creating a new window by
 @dfn{splitting} an existing one.
 
-@deffn Command split-window &optional window size side
+@defun split-window &optional window size side
 This function creates a new live window next to the window
 @var{window}.  If @var{window} is omitted or @code{nil}, it defaults
 to the selected window.  That window is ``split'', and reduced in
@@ -767,7 +767,7 @@ called with the arguments @var{window}, @var{size}, and @var{side}, in
 lieu of the usual action of @code{split-window}.  Otherwise, this
 function obeys the @code{window-atom} or @code{window-side} window
 parameter, if any.  @xref{Window Parameters}.
-@end deffn
+@end defun
 
   As an example, here is a sequence of @code{split-window} calls that
 yields the window configuration discussed in @ref{Windows and Frames}.