merge trunk

3 files changed, 309 insertions, 289 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index af0cb306245..77468f562c6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,29 @@
+2012-03-21  Chong Yidong  <cyd@gnu.org>
+
+        * display.texi (The Echo Area): Add xref to Output Streams.
+        (Displaying Messages): Improve doc of message.
+        (Echo Area Customization, Invisible Text): Copyedits.
+        (Invisible Text): Mention that spec comparison is done with eq.
+        (Width): Improve doc of char-width.
+        (Faces): Recommend using symbol instead of string for face name.
+        Minor clarifications.
+        (Defining Faces): Copyedits.  Update face example.
+        (Attribute Functions): Mark set-face-foreground etc as commands.
+        (Face Remapping): Mention text-scale-adjust.  Clarify
+        face-remapping-alist and related docs.
+        (Face Functions): Don't document make-face or copy-face.
+
+2012-03-20  Chong Yidong  <cyd@gnu.org>
+
+        * display.texi (Forcing Redisplay): Various rewrites to reflect
+        new value of redisplay-dont-pause.
+        (Truncation): Copyedits.
+
+2012-03-20  Glenn Morris  <rgm@gnu.org>
+
+        * os.texi (Startup Summary): Don't mention initial-buffer-choice = t.
+        Add summary table of some relevant command-line options.
+
 2012-03-18  Chong Yidong  <cyd@gnu.org>
 
         * internals.texi (Building Emacs, Garbage Collection): Copyedits.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index c70418be52b..dbcc1d1190b 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -86,59 +86,57 @@ attempt to redisplay, in the middle of Lisp code, without actually
 waiting for input.
 
 @defun redisplay &optional force
-This function tries immediately to redisplay, provided there are no
-pending input events.
-
-If the optional argument @var{force} is non-@code{nil}, it does all
-pending redisplay work even if input is available, with no
-pre-emption.
+This function tries immediately to redisplay.  The optional argument
+@var{force}, if non-@code{nil}, forces the redisplay to be performed,
+instead of being preempted, even if input is pending and the variable
+@code{redisplay-dont-pause} is @code{nil} (see below).  If
+@code{redisplay-dont-pause} is non-@code{nil} (the default), this
+function redisplays in any case, i.e.@: @var{force} does nothing.
 
 The function returns @code{t} if it actually tried to redisplay, and
 @code{nil} otherwise.  A value of @code{t} does not mean that
-redisplay proceeded to completion; it could have been pre-empted by
-newly arriving terminal input.
-@end defun
-
-  @code{redisplay} with no argument tries immediately to redisplay,
-but has no effect on the usual rules for what parts of the screen to
-redisplay.  By contrast, the following function adds certain windows
-to the pending redisplay work (as if their contents had completely
-changed), but doesn't immediately try to do any redisplay work.
-
-@defun force-window-update &optional object
-This function forces some or all windows to be updated on next
-redisplay.  If @var{object} is a window, it requires eventual
-redisplay of that window.  If @var{object} is a buffer or buffer name,
-it requires eventual redisplay of all windows displaying that buffer.
-If @var{object} is @code{nil} (or omitted), it requires eventual
-redisplay of all windows.
+redisplay proceeded to completion; it could have been preempted by
+newly arriving input.
 @end defun
 
-  @code{force-window-update} does not do a redisplay immediately.
-(Emacs will do that when it waits for input.)  Rather, its effect is
-to put more work on the queue to be done by redisplay whenever there
-is a chance.
-
 @defvar redisplay-dont-pause
-If this variable is non-@code{nil}, pending input does not prevent or
-halt redisplay; redisplay occurs, and finishes, regardless of whether
-input is available.  If it is @code{nil}, Emacs redisplay stops if
-input arrives, and does not happen at all if input is available before
-it starts.  The default is @code{t}.
+If this variable is @code{nil}, arriving input events preempt
+redisplay; Emacs avoids starting a redisplay, and stops any redisplay
+that is in progress, until the input has been processed.  In
+particular, @code{(redisplay)} returns @code{nil} without actually
+redisplaying, if there is pending input.
+
+The default value is @code{t}, which means that pending input does not
+preempt redisplay.
 @end defvar
 
 @defvar redisplay-preemption-period
-This variable specifies how many seconds Emacs waits between checks
-for new input during redisplay.  (The default is 0.1 seconds.)  If
-input has arrived when Emacs checks, it pre-empts redisplay and
-processes the available input before trying again to redisplay.
+If @code{redisplay-dont-pause} is @code{nil}, this variable specifies
+how many seconds Emacs waits between checks for new input during
+redisplay; if input arrives during this interval, redisplay stops and
+the input is processed.  The default value is 0.1; if the value is
+@code{nil}, Emacs does not check for input during redisplay.
+
+This variable has no effect when @code{redisplay-dont-pause} is
+non-@code{nil} (the default).
+@end defvar
 
-If this variable is @code{nil}, Emacs does not check for input during
-redisplay, and redisplay cannot be preempted by input.
+  Although @code{redisplay} tries immediately to redisplay, it does
+not change how Emacs decides which parts of its frame(s) to redisplay.
+By contrast, the following function adds certain windows to the
+pending redisplay work (as if their contents had completely changed),
+but does not immediately try to perform redisplay.
 
-This variable is only obeyed on graphical terminals.  For
-text terminals, see @ref{Terminal Output}.
-@end defvar
+@defun force-window-update &optional object
+This function forces some or all windows to be updated the next time
+Emacs does a redisplay.  If @var{object} is a window, that window is
+to be updated.  If @var{object} is a buffer or buffer name, all
+windows displaying that buffer are to be updated.  If @var{object} is
+@code{nil} (or omitted), all windows are to be updated.
+
+This function does not do a redisplay immediately; Emacs does that as
+it waits for input, or when the function @code{redisplay} is called.
+@end defun
 
 @node Truncation
 @section Truncation
@@ -169,7 +167,7 @@ If this buffer-local variable is non-@code{nil}, lines that extend
 beyond the right edge of the window are truncated; otherwise, they are
 continued.  As a special exception, the variable
 @code{truncate-partial-width-windows} takes precedence in
-@dfn{partial-width} windows (i.e., windows that do not occupy the
+@dfn{partial-width} windows (i.e.@: windows that do not occupy the
 entire frame width).
 @end defopt
 
@@ -192,37 +190,37 @@ a window, that forces truncation.
 
 @defvar wrap-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
-``prefix'' that is prepended to every continuation line at
-display time.  (If lines are truncated, the wrap-prefix is never
-used.)  It may be a string or an image (@pxref{Other Display Specs}),
-or a stretch of whitespace such as specified by the @code{:width} or
-@code{:align-to} display properties (@pxref{Specified Space}).  The
-value is interpreted in the same way as a @code{display} text
-property.  @xref{Display Property}.
-
-A wrap-prefix may also be specified for regions of text, using the
+@dfn{wrap prefix} which Emacs displays at the start of every
+continuation line.  (If lines are truncated, @code{wrap-prefix} is
+never used.)  Its value may be a string or an image (@pxref{Other
+Display Specs}), or a stretch of whitespace such as specified by the
+@code{:width} or @code{:align-to} display properties (@pxref{Specified
+Space}).  The value is interpreted in the same way as a @code{display}
+text property.  @xref{Display Property}.
+
+A wrap prefix may also be specified for regions of text, using the
 @code{wrap-prefix} text or overlay property.  This takes precedence
 over the @code{wrap-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
 @defvar line-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
-``prefix'' that is prepended to every non-continuation line at
-display time.  It may be a string or an image (@pxref{Other Display
-Specs}), or a stretch of whitespace such as specified by the
-@code{:width} or @code{:align-to} display properties (@pxref{Specified
-Space}).  The value is interpreted in the same way as a @code{display}
-text property.  @xref{Display Property}.
-
-A line-prefix may also be specified for regions of text using the
+@dfn{line prefix} which Emacs displays at the start of every
+non-continuation line.  Its value may be a string or an image
+(@pxref{Other Display Specs}), or a stretch of whitespace such as
+specified by the @code{:width} or @code{:align-to} display properties
+(@pxref{Specified Space}).  The value is interpreted in the same way
+as a @code{display} text property.  @xref{Display Property}.
+
+A line prefix may also be specified for regions of text using the
 @code{line-prefix} text or overlay property.  This takes precedence
 over the @code{line-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
   If your buffer contains @emph{very} long lines, and you use
 continuation to display them, computing the continuation lines can
-make Emacs redisplay slow.  The column computation and indentation
-functions also become slow.  Then you might find it advisable to set
+make redisplay slow.  The column computation and indentation functions
+also become slow.  Then you might find it advisable to set
 @code{cache-long-line-scans} to @code{t}.
 
 @defvar cache-long-line-scans
@@ -245,14 +243,12 @@ This variable is automatically buffer-local in every buffer.
 (@pxref{Errors}), for messages made with the @code{message} primitive,
 and for echoing keystrokes.  It is not the same as the minibuffer,
 despite the fact that the minibuffer appears (when active) in the same
-place on the screen as the echo area.  The @cite{GNU Emacs Manual}
-specifies the rules for resolving conflicts between the echo area and
-the minibuffer for use of that screen space (@pxref{Minibuffer,, The
-Minibuffer, emacs, The GNU Emacs Manual}).
+place on the screen as the echo area.  @xref{Minibuffer,, The
+Minibuffer, emacs, The GNU Emacs Manual}.
 
-  You can write output in the echo area by using the Lisp printing
-functions with @code{t} as the stream (@pxref{Output Functions}), or
-explicitly.
+  Apart from the functions documented in this section, you can print
+Lisp objects to the echo area by specifying @code{t} as the output
+stream.  @xref{Output Streams}.
 
 @menu
 * Displaying Messages:: Explicitly displaying text in the echo area.
@@ -265,27 +261,26 @@ explicitly.
 @subsection Displaying Messages in the Echo Area
 @cindex display message in echo area
 
-  This section describes the functions for explicitly producing echo
-area messages.  Many other Emacs features display messages there, too.
+  This section describes the standard functions for displaying
+messages in the echo area.
 
 @defun message format-string &rest arguments
-This function displays a message in the echo area.  The argument
-@var{format-string} is similar to a C language @code{printf} format
-string.  See @code{format} in @ref{Formatting Strings}, for the details
-on the conversion specifications.  @code{message} returns the
-constructed string.
-
-In batch mode, @code{message} prints the message text on the standard
-error stream, followed by a newline.
+This function displays a message in the echo area.
+@var{format-string} is a format string, and @var{arguments} are the
+objects for its format specifications, like in the @code{format}
+function (@pxref{Formatting Strings}).  The resulting formatted string
+is displayed in the echo area; if it contains @code{face} text
+properties, it is displayed with the specified faces (@pxref{Faces}).
+The string is also added to the @samp{*Messages*} buffer, but without
+text properties (@pxref{Logging Messages}).
+
+In batch mode, the message is printed to the standard error stream,
+followed by a newline.
 
-If @var{format-string}, or strings among the @var{arguments}, have
-@code{face} text properties, these affect the way the message is displayed.
-
-@c Emacs 19 feature
 If @var{format-string} is @code{nil} or the empty string,
 @code{message} clears the echo area; if the echo area has been
-expanded automatically, this brings it back to its normal size.
-If the minibuffer is active, this brings the minibuffer contents back
+expanded automatically, this brings it back to its normal size.  If
+the minibuffer is active, this brings the minibuffer contents back
 onto the screen immediately.
 
 @example
@@ -561,13 +556,13 @@ If the value is zero, then command input is not echoed.
 Normally, displaying a long message resizes the echo area to display
 the entire message.  But if the variable @code{message-truncate-lines}
 is non-@code{nil}, the echo area does not resize, and the message is
-truncated to fit it, as in Emacs 20 and before.
+truncated to fit it.
 @end defvar
 
   The variable @code{max-mini-window-height}, which specifies the
 maximum height for resizing minibuffer windows, also applies to the
-echo area (which is really a special use of the minibuffer window.
-@xref{Minibuffer Misc}.).
+echo area (which is really a special use of the minibuffer window;
+@pxref{Minibuffer Misc}).
 
 @node Warnings
 @section Reporting Warnings
@@ -764,10 +759,11 @@ that warning is not logged.
 @cindex invisible text
 You can make characters @dfn{invisible}, so that they do not appear on
 the screen, with the @code{invisible} property.  This can be either a
-text property (@pxref{Text Properties}) or a property of an overlay
+text property (@pxref{Text Properties}) or an overlay property
 (@pxref{Overlays}).  Cursor motion also partly ignores these
-characters; if the command loop finds point within them, it moves
-point to the other side of them.
+characters; if the command loop finds that point is inside a range of
+invisible text after a command, it relocates point to the other side
+of the text.
 
 In the simplest case, any non-@code{nil} @code{invisible} property makes
 a character invisible.  This is the default case---if you don't alter
@@ -807,13 +803,15 @@ the character is invisible.  The list can have two kinds of elements:
 
 @table @code
 @item @var{atom}
-A character is invisible if its @code{invisible} property value
-is @var{atom} or if it is a list with @var{atom} as a member.
+A character is invisible if its @code{invisible} property value is
+@var{atom} or if it is a list with @var{atom} as a member; comparison
+is done with @code{eq}.
 
 @item (@var{atom} . t)
 A character is invisible if its @code{invisible} property value is
-@var{atom} or if it is a list with @var{atom} as a member.  Moreover,
-a sequence of such characters displays as an ellipsis.
+@var{atom} or if it is a list with @var{atom} as a member; comparison
+is done with @code{eq}.  Moreover, a sequence of such characters
+displays as an ellipsis.
 @end table
 @end table
 @end defvar
@@ -848,7 +846,7 @@ major mode should use the mode's own name as an element of
 (overlay-put (make-overlay beginning end)
              'invisible 'my-symbol)
 
-;; @r{When done with the overlays:}
+;; @r{When done with the invisibility:}
 (remove-from-invisibility-spec '(my-symbol . t))
 ;; @r{Or respectively:}
 (remove-from-invisibility-spec 'my-symbol)
@@ -874,15 +872,16 @@ ignore invisible newlines if @code{line-move-ignore-invisible} is
 non-@code{nil} (the default), but only because they are explicitly
 programmed to do so.
 
-  However, if a command ends with point inside or at the boundary of invisible
-text, the main editing loop moves point to one of the two ends of the invisible
-text.  Which end to move to is chosen based on the following factors: make sure
-that the overall movement of the command is still in the same direction, and
-prefer a position where an inserted char would not inherit the @code{invisible}
-property.  Additionally, if the text is not replaced by an ellipsis and the
-command only moved within the invisible text, then point is moved one extra
-character so as to try and reflect the command's movement by a visible movement
-of the cursor.
+  However, if a command ends with point inside or at the boundary of
+invisible text, the main editing loop relocates point to one of the
+two ends of the invisible text.  Emacs chooses the direction of
+relocation so that it is the same as the overall movement direction of
+the command; if in doubt, it prefers a position where an inserted char
+would not inherit the @code{invisible} property.  Additionally, if the
+text is not replaced by an ellipsis and the command only moved within
+the invisible text, then point is moved one extra character so as to
+try and reflect the command's movement by a visible movement of the
+cursor.
 
   Thus, if the command moved point back to an invisible range (with the usual
 stickiness), Emacs moves point back to the beginning of that range.  If the
@@ -1668,8 +1667,11 @@ check the width of a character.  @xref{Primitive Indent}, and
 @ref{Screen Lines}, for related functions.
 
 @defun char-width char
-This function returns the width in columns of the character @var{char},
-if it were displayed in the current buffer and the selected window.
+This function returns the width in columns of the character
+@var{char}, if it were displayed in the current buffer (i.e.@: taking
+into account the buffer's display table, if any; @pxref{Display
+Tables}).  The width of a tab character is usually @code{tab-width}
+(@pxref{Usual Display}).
 @end defun
 
 @defun string-width string
@@ -1815,26 +1817,27 @@ height.
 @section Faces
 @cindex faces
 
-  A @dfn{face} is a collection of graphical attributes for displaying
-text: font, foreground color, background color, optional underlining,
-and so on.  Faces control how buffer text is displayed, and how some
-parts of the frame, such as the mode-line, are displayed.
+  A @dfn{face} is a collection of graphical @dfn{attributes} for
+displaying text: font, foreground color, background color, optional
+underlining, and so on.  Faces control how Emacs displays text in
+buffers, as well as other parts of the frame such as the mode line.
 @xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
 faces Emacs normally comes with.
 
 @cindex face id
   For most purposes, you refer to a face in Lisp programs using its
-@dfn{face name}.  This is either a string or (equivalently) a Lisp
-symbol whose name is equal to that string.
+@dfn{face name}, which is usually a Lisp symbol.  For backward
+compatibility, a face name can also be a string, which is equivalent
+to a Lisp symbol of the same name.
 
 @defun facep object
 This function returns a non-@code{nil} value if @var{object} is a Lisp
 symbol or string that names a face.  Otherwise, it returns @code{nil}.
 @end defun
 
-  Each face name is meaningful for all frames, and by default it has
-the same meaning in all frames.  But you can arrange to give a
-particular face name a special meaning in one frame if you wish.
+  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
 * Defining Faces::      How to define a face with @code{defface}.
@@ -1857,9 +1860,8 @@ particular face name a special meaning in one frame if you wish.
 @subsection Defining Faces
 
   The way to define a new face is with @code{defface}.  This creates a
-kind of customization item (@pxref{Customization}) which the user can
-customize using the Customization buffer (@pxref{Easy Customization,,,
-emacs, The GNU Emacs Manual}).
+kind of customization item which the user can customize using the
+Customization buffer (@pxref{Customization}).
 
   People are sometimes tempted to create variables whose values specify
 which faces to use (for example, Font-Lock does this).  In the vast
@@ -1885,14 +1887,16 @@ exactly what the @code{defface} says.
 
 The purpose of @var{spec} is to specify how the face should appear on
 different kinds of terminals.  It should be an alist whose elements
-have the form @code{(@var{display} @var{atts})}.  Each element's
-@sc{car}, @var{display}, specifies a class of terminals.  (The first
-element, if its @sc{car} is @code{default}, is special---it specifies
-defaults for the remaining elements).  The element's @sc{cadr},
-@var{atts}, is a list of face attributes and their values; it
-specifies what the face should look like on that kind of terminal.
-The possible attributes are defined in the value of
-@code{custom-face-attributes}.
+have the form @code{(@var{display} @var{atts})}.  @var{display}
+specifies a class of terminals (see below), while @var{atts} is a
+property list of face attributes and their values, specifying the
+appearance of the face on matching terminals
+@iftex
+(see the next section for details about face attributes).
+@end iftex
+@ifnottex
+(@pxref{Face Attributes}, for details about face attributes).
+@end ifnottex
 
 The @var{display} part of an element of @var{spec} determines which
 frames the element matches.  If more than one element of @var{spec}
@@ -1954,29 +1958,23 @@ frame must match one of the @var{value}s specified for it in
 @end table
 @end defmac
 
-  Here's how the standard face @code{region} is defined:
+  Here's how the standard face @code{highlight} is defined:
 
 @example
-@group
-(defface region
-  '((((class color) (min-colors 88) (background dark))
-     :background "blue3")
-@end group
-    (((class color) (min-colors 88) (background light))
-     :background "lightgoldenrod2")
-    (((class color) (min-colors 16) (background dark))
-     :background "blue3")
+(defface highlight
+  '((((class color) (min-colors 88) (background light))
+     :background "darkseagreen2")
+    (((class color) (min-colors 88) (background dark))
+     :background "darkolivegreen")
     (((class color) (min-colors 16) (background light))
-     :background "lightgoldenrod2")
+     :background "darkseagreen2")
+    (((class color) (min-colors 16) (background dark))
+     :background "darkolivegreen")
     (((class color) (min-colors 8))
-     :background "blue" :foreground "white")
-    (((type tty) (class mono))
-     :inverse-video t)
-    (t :background "gray"))
-@group
-  "Basic face for highlighting the region."
+     :background "green" :foreground "black")
+    (t :inverse-video t))
+  "Basic face for highlighting."
   :group 'basic-faces)
-@end group
 @end example
 
   Internally, @code{defface} uses the symbol property
@@ -2012,8 +2010,8 @@ doesn't specify that attribute.  In face merging, when the first face
 fails to specify a particular attribute, the next face gets a chance.
 However, the @code{default} face must specify all attributes.
 
-  Some of these font attributes are meaningful only on certain kinds
-of displays.  If your display cannot handle a certain attribute, the
+  Some of these attributes are meaningful only on certain kinds of
+displays.  If your display cannot handle a certain attribute, the
 attribute is ignored.
 
 @table @code
@@ -2218,20 +2216,18 @@ This function sets one or more attributes of @var{face} for
 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 corresponding values.
-Thus,
+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
-                    :underline "red")
+                    :weight 'bold)
 @end example
 
 @noindent
-sets the attributes @code{:width}, @code{:weight} and @code{:underline}
-to the corresponding values.
+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
@@ -2308,54 +2304,51 @@ If @var{value1} is a relative value for the face attribute
 face attribute @var{attribute}, returns @var{value1} unchanged.
 @end defun
 
-  The following functions provide compatibility with Emacs 20 and
-below.  They work by calling @code{set-face-attribute}.  Values of
-@code{t} and @code{nil} for their @var{frame} argument are handled
-just like @code{set-face-attribute} and @code{face-attribute}.
+  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
+their @var{frame} argument are handled just like
+@code{set-face-attribute} and @code{face-attribute}.  The commands
+read their arguments using the minibuffer, if called interactively.
 
-@defun set-face-foreground face color &optional frame
-@defunx set-face-background face color &optional frame
-These functions set the @code{:foreground} attribute (or
-@code{:background} attribute, respectively) of @var{face} to
-@var{color}.
-@end defun
+@deffn Command set-face-foreground face color &optional frame
+@deffnx Command set-face-background face color &optional frame
+These set the @code{:foreground} attribute (or @code{:background}
+attribute, respectively) of @var{face} to @var{color}.
+@end deffn
 
-@defun set-face-stipple face pattern &optional frame
-This function sets the @code{:stipple} attribute of @var{face} to
+@deffn Command set-face-stipple face pattern &optional frame
+This sets the @code{:stipple} attribute of @var{face} to
 @var{pattern}.
-@end defun
+@end deffn
 
-@defun set-face-font face font &optional frame
-This function sets the @code{:font} attribute of @var{face} to
-@var{font}.
-@end defun
+@deffn Command set-face-font face font &optional frame
+This sets the @code{:font} attribute of @var{face} to @var{font}.
+@end deffn
 
 @defun set-face-bold-p face bold-p &optional frame
-This function sets the @code{:weight} attribute of @var{face} to
-@var{normal} if @var{bold-p} is @code{nil}, and to @var{bold}
-otherwise.
+This sets the @code{:weight} attribute of @var{face} to @var{normal}
+if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
 @end defun
 
 @defun set-face-italic-p face italic-p &optional frame
-This function sets the @code{:slant} attribute of @var{face} to
-@var{normal} if @var{italic-p} is @code{nil}, and to @var{italic}
-otherwise.
+This sets the @code{:slant} attribute of @var{face} to @var{normal} if
+@var{italic-p} is @code{nil}, and to @var{italic} otherwise.
 @end defun
 
 @defun set-face-underline-p face underline &optional frame
-This function sets the @code{:underline} attribute of @var{face} to
+This sets the @code{:underline} attribute of @var{face} to
 @var{underline}.
 @end defun
 
 @defun set-face-inverse-video-p face inverse-video-p &optional frame
-This function sets the @code{:inverse-video} attribute of @var{face}
-to @var{inverse-video-p}.
+This sets the @code{:inverse-video} attribute of @var{face} to
+@var{inverse-video-p}.
 @end defun
 
-@defun invert-face face &optional frame
-This function swaps the foreground and background colors of face
-@var{face}.
-@end defun
+@deffn Command invert-face face &optional frame
+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}
@@ -2461,27 +2454,26 @@ steps, Emacs applies the attribute of the @code{default} face.
   If these various sources together specify more than one face for a
 particular character, Emacs merges the attributes of the various faces
 specified.  For each attribute, Emacs tries using the above order
-(i.e., first the face of any special glyph; then the face for region
-highlighting, if appropriate; then faces specified by overlays, then
-faces specified by text properties, then the @code{mode-line} or
-@code{mode-line-inactive} or @code{header-line} face, if appropriate,
-and finally the @code{default} face).
+(i.e.@: first the face of any special glyph; then the face for region
+highlighting, if appropriate; and so on).
 
 @node Face Remapping
 @subsection Face Remapping
 
   The variable @code{face-remapping-alist} is used for buffer-local or
-global changes in the appearance of a face.  For instance, it can be
-used to make the @code{default} face a variable-pitch face within a
-particular buffer.
+global changes in the appearance of a face.  For instance, it is used
+to implement the @code{text-scale-adjust} command (@pxref{Text
+Scale,,, emacs, The GNU Emacs Manual}).
 
 @defvar face-remapping-alist
-An alist whose elements have the form @code{(@var{face}
-@var{remapping...})}.  This causes Emacs to display text using the
-face @var{face} using @var{remapping...} instead of @var{face}'s
-ordinary definition.  @var{remapping...} may be any face specification
-suitable for a @code{face} text property: either a face name, or a
-property list of attribute/value pairs.  @xref{Special Properties}.
+The value of this variable is an alist whose elements have the form
+@code{(@var{face} . @var{remapping})}.  This causes Emacs to display
+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 name, or a property list of attribute/value pairs, or a list in
+which each element is either a face name or a property list
+(@pxref{Special Properties}).
 
 If @code{face-remapping-alist} is buffer-local, its local value takes
 effect only within that buffer.
@@ -2490,17 +2482,15 @@ Two points bear emphasizing:
 
 @enumerate
 @item
-The new definition @var{remapping...} is the complete
-specification of how to display @var{face}---it entirely replaces,
-rather than augmenting or modifying, the normal definition of that
-face.
+@var{remapping} serves as the complete specification for the remapped
+face---it replaces the normal definition of @var{face}, instead of
+modifying it.
 
 @item
-If @var{remapping...} recursively references the same face name
-@var{face}, either directly remapping entry, or via the
-@code{:inherit} attribute of some other face in @var{remapping...},
-then that reference uses the normal definition of @var{face} in the
-selected frame, instead of the ``remapped'' definition.
+If @var{remapping} references the same face name @var{face}, either
+directly or via the @code{:inherit} attribute of some other face in
+@var{remapping}, that reference uses the normal definition of
+@var{face}.  In other words, the remapping cannot be recursive.
 
 For instance, if the @code{mode-line} face is remapped using this
 entry in @code{face-remapping-alist}:
@@ -2514,82 +2504,72 @@ then the new definition of the @code{mode-line} face inherits from the
 @end enumerate
 @end defvar
 
-  A typical use of the @code{face-remapping-alist} is to change a
-buffer's @code{default} face; for example, the following changes a
-buffer's @code{default} face to use the @code{variable-pitch} face,
-with the height doubled:
-
-@example
-(set (make-local-variable 'face-remapping-alist)
-     '((default variable-pitch :height 2.0)))
-@end example
-
   The following functions implement a higher-level interface to
-@code{face-remapping-alist}, making it easier to use
-``cooperatively''.  They are mainly intended for buffer-local use, and
-so all make @code{face-remapping-alist} variable buffer-local as a
-side-effect.  They use entries in @code{face-remapping-alist} which
-have the general form:
+@code{face-remapping-alist}.  Most Lisp code should use these
+functions instead of setting @code{face-remapping-alist} directly, to
+avoid trampling on remappings applied elsewhere.  These functions are
+intended for buffer-local remappings, so they all make
+@code{face-remapping-alist} buffer-local as a side-effect. They manage
+@code{face-remapping-alist} entries of the form
 
 @example
-  (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
+  (@var{face} @var{relative-spec-1} @var{relative-spec-2} @var{...} @var{base-spec})
 @end example
 
-Everything except @var{face} is a ``face spec'': a list of face names
-or face attribute-value pairs.  All face specs are merged together,
-with earlier values taking precedence.
-
-The @var{relative_specs_}n values are ``relative specs'', and are
-added by @code{face-remap-add-relative} (and removed by
-@code{face-remap-remove-relative}.  These are intended for face
-modifications (such as increasing the size).  Typical users of these
-relative specs would be minor modes.
-
-@var{base_specs} is the lowest-priority value, and by default is just the
-face name, which causes the global definition of that face to be used.
-
-A non-default value of @var{base_specs} may also be set using
-@code{face-remap-set-base}.  Because this @emph{overwrites} the
-default base-spec value (which inherits the global face definition),
-it is up to the caller of @code{face-remap-set-base} to add such
-inheritance if it is desired.  A typical use of
-@code{face-remap-set-base} would be a major mode adding a face
-remappings, e.g., of the default face.
-
+@noindent
+where, as explained above, each of the @var{relative-spec-N} and
+@var{base-spec} is either a face name, or a property list of
+attribute/value pairs.  Each of the @dfn{relative remapping} entries,
+@var{relative-spec-N}, is managed by the
+@code{face-remap-add-relative} and @code{face-remap-remove-relative}
+functions; these are intended for simple modifications like changing
+the text size.  The @dfn{base remapping} entry, @var{base-spec}, has
+the lowest priority and is managed by the @code{face-remap-set-base}
+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 a face remapping entry of @var{face} to @var{specs}
-in the current buffer.
+This functions adds the face specifications 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.
+
+The return value is a Lisp object that serves as a ``cookie''; you can
+pass this object as an argument to @code{face-remap-remove-relative}
+if you need to remove the remapping later.
 
-It returns a ``cookie'' which can be used to later delete the remapping with
-@code{face-remap-remove-relative}.
+@example
+;; Remap the `escape-glyph' face into a combination
+;; of the `highlight' and `italic' faces:
+(face-remap-add-relative 'escape-glyph 'highlight 'italic)
 
-@var{specs} can be any value suitable for the @code{face} text
-property, including a face name, a list of face names, or a
-face-attribute property list.  The attributes given by @var{specs}
-will be merged with any other currently active face remappings of
-@var{face}, and with the global definition of @var{face} (by default;
-this may be changed using @code{face-remap-set-base}), with the most
-recently added relative remapping taking precedence.
+;; Increase the size of the `default' face by 50%:
+(face-remap-add-relative 'default :height 1.5)
+@end example
 @end defun
 
 @defun face-remap-remove-relative cookie
-This function removes a face remapping previously added by
-@code{face-remap-add-relative}.  @var{cookie} should be a return value
-from that function.
+This function removes a relative remapping previously added by
+@code{face-remap-add-relative}.  @var{cookie} should be the Lisp
+object returned by @code{face-remap-add-relative} when the remapping
+was added.
 @end defun
 
 @defun face-remap-set-base face &rest specs
-This function sets the ``base remapping'' of @var{face} in the current
+This function sets the base remapping of @var{face} in the current
 buffer to @var{specs}.  If @var{specs} is empty, the default base
-remapping is restored, which inherits from the global definition of
-@var{face}; note that this is different from @var{specs} containing a
+remapping is restored, similar to calling @code{face-remap-reset-base}
+(see below); note that this is different from @var{specs} containing a
 single value @code{nil}, which has the opposite result (the global
 definition of @var{face} is ignored).
+
+This overwrites the default @var{base-spec}, which inherits the global
+face definition, so it is up to the caller to add such inheritance if
+so desired.
 @end defun
 
 @defun face-remap-reset-base face
-This function sets the ``base remapping'' of @var{face} to its default
+This function sets the base remapping of @var{face} to its default
 value, which inherits from @var{face}'s global definition.
 @end defun
 
@@ -2598,29 +2578,8 @@ value, which inherits from @var{face}'s global definition.
 
   Here are additional functions for creating and working with faces.
 
-@defun make-face name
-This function defines a new face named @var{name}, initially with all
-attributes @code{nil}.  It does nothing if there is already a face named
-@var{name}.
-@end defun
-
 @defun face-list
-This function returns a list of all defined faces.
-@end defun
-
-@defun copy-face old-face new-name &optional frame new-frame
-This function defines a face named @var{new-name} as a copy of the existing
-face named @var{old-face}.  It creates the face @var{new-name} if that
-doesn't already exist.
-
-If the optional argument @var{frame} is given, this function applies
-only to that frame.  Otherwise it applies to each frame individually,
-copying attributes from @var{old-face} in each frame to @var{new-face}
-in the same frame.
-
-If the optional argument @var{new-frame} is given, then @code{copy-face}
-copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
-in @var{new-frame}.
+This function returns a list of all defined face names.
 @end defun
 
 @defun face-id face
@@ -2754,7 +2713,7 @@ these are used for messages in @samp{*Compilation*} buffers.
 @node Font Selection
 @subsection Font Selection
 
-  Before Emacs can draw a character on a particular display, it must
+  Before Emacs can draw a character on a graphical display, it must
 select a @dfn{font} for that character@footnote{In this context, the
 term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
 Mode}).}.  @xref{Fonts,,, emacs, The GNU Emacs Manual}.  Normally,
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 1021787a0f4..2563bc57aef 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -248,6 +248,9 @@ previous session.  @xref{Session Management}.
 
 @end enumerate
 
+@noindent
+The following options affect some aspects of the startup sequence.
+
 @defopt inhibit-startup-screen
 This variable, if non-@code{nil}, inhibits the startup screen.  In
 that case, Emacs typically displays the @samp{*scratch*} buffer; but
@@ -265,9 +268,13 @@ aliases for this variable.
 
 @defopt initial-buffer-choice
 This variable, if non-@code{nil}, determines a file or buffer for
-Emacs to display after starting up, instead of the startup screen.  If
-its value is @code{t}, Emacs displays the @samp{*scratch*} buffer.  If
-its value is a string, that specifies the name of a file for Emacs to
+Emacs to display after starting up, instead of the startup screen.
+@ignore
+@c I do not think this should be mentioned.  AFAICS it is just a dodge
+@c around inhibit-startup-screen not being settable on a site-wide basis.
+If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. 
+@end ignore
+If its value is a string, that specifies the name of a file for Emacs to
 visit.
 @end defopt
 
@@ -283,7 +290,7 @@ form to your init file:
 
 Emacs explicitly checks for an expression as shown above in your init
 file; your login name must appear in the expression as a Lisp string
-constant.  Other methods of setting
+constant.  You can also use the Custom interface.  Other methods of setting
 @code{inhibit-startup-echo-area-message} to the same value do not
 inhibit the startup message.  This way, you can easily inhibit the
 message for yourself if you wish, but thoughtless copying of your init
@@ -296,6 +303,34 @@ inserted into the @samp{*scratch*} buffer when Emacs starts up.  If it
 is @code{nil}, the @samp{*scratch*} buffer is empty.
 @end defopt
 
+@noindent
+The following command-line options affect some aspects of the startup
+sequence.  @xref{Initial Options,,, emacs, The GNU Emacs Manual}.
+
+@table @code
+@item --no-splash
+Do not display a splash screen.
+
+@item --batch
+Run without an interactive terminal.  @xref{Batch Mode}.
+
+@item --daemon
+Do not initialize any display; just start a server in the background.
+
+@item --no-init-file
+@itemx -Q
+Do not load either the init file, or the @file{default} library.
+
+@item --no-site-file
+Do not load the @file{site-start} library.
+
+@item --quick
+@itemx -Q
+Equivalent to @samp{-q --no-site-file --no-splash}.
+@c and --no-site-lisp, but let's not mention that here.
+@end table
+
+
 @node Init File
 @subsection The Init File
 @cindex init file