merge trunk

16 files changed, 460 insertions, 401 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
diff --git a/etc/NEWS b/etc/NEWS
index 78b306f057e..de5b865a54b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -123,6 +123,8 @@ and pops down the *Completions* buffer accordingly.
 *** Completion style can be set per-category `completion-category-overrides'.
 +++
 *** Completion of buffers now uses substring completion by default.
+---
+*** The `widget-complete-field' option has been removed.
 
 ** Mail changes
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a6f5a5fd525..ea7d81bb969 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,26 @@
+2012-03-21  Chong Yidong  <cyd@gnu.org>
+
+        * faces.el (make-face, make-empty-face, copy-face):
+        * face-remap.el (face-remap-add-relative, face-remap-set-base):
+        Doc fixes.
+
+2012-03-21  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * wid-edit.el (widget-complete-field): Remove (bug#11051).
+        (widget-complete): Remove broken use of it.
+
+2012-03-20  Chong Yidong  <cyd@gnu.org>
+
+        * emacs-lisp/tabulated-list.el (tabulated-list-print-entry):
+        Use string-width and truncate-string-width to handle arbitrary
+        characters.
+
+2012-03-20  Tassilo Horn  <tassilo@member.fsf.org>
+
+        * textmodes/artist.el (artist-menu-map): Bind Rectangle menu item
+        to draw rectangles, not squares.  (Regression introduced by revno
+        2011-03-02T03:48:01Z!cyd@stupidchicken.com)
+
 2012-03-18  Chong Yidong  <cyd@gnu.org>
 
         * faces.el (face-spec-reset-face): Don't call display-graphic-p if
@@ -5,8 +28,7 @@
 
 2012-03-18  Leo Liu  <sdl.web@gmail.com>
 
-        * net/rcirc.el (rcirc-cmd-quit): Allow quiting all servers with
-        prefix.
+        * net/rcirc.el (rcirc-cmd-quit): Allow quiting all servers with prefix.
 
 2012-03-17  Eli Zaretskii  <eliz@gnu.org>
 
@@ -36,7 +58,7 @@
         (hfy-fontify-buffer): Use above handlers.
         (hfy-face-to-css-default): Same as the earlier `hfy-face-to-css'.
         (hfy-face-to-css): Re-defined to be a variable.
-        (hfy-compile-stylesheet): Modified.  Allow stylesheet to be built
+        (hfy-compile-stylesheet): Modify.  Allow stylesheet to be built
         over multiple runs. This is made possible by having the caller let
         bind a special variable `hfy-user-sheet-assoc'.
         (htmlfontify-string): New defun.
@@ -60,10 +82,8 @@
         * progmodes/cc-engine.el (c-crosses-statement-barrier-p): Use a
         limit to a call of `c-literal-limits'.
         (c-determine-+ve-limit): New function.
-        (c-at-macro-vsemi-p): Move `c-in-literal' to the bottom of an
-        `and'.
-        (c-guess-basic-syntax): In macros, restrict a search limit to
-        2000.
+        (c-at-macro-vsemi-p): Move `c-in-literal' to the bottom of an `and'.
+        (c-guess-basic-syntax): In macros, restrict a search limit to 2000.
         In CASE 5B, restrict a search limit to 500.
         (c-just-after-func-arglist-p): Obviouly wrong `or' -> `and'.
 
@@ -77,7 +97,7 @@
 2012-03-16  Aaron S. Hawley  <Aaron.S.Hawley@gmail.com>
 
         * tar-mode.el (tar-mode): Fix saving by conditionally undoing
-        `special-mode' setting of `buffer-read-only'.  (Bug#11010)
+        `special-mode' setting of `buffer-read-only'.  (Bug#11010)
 
 2012-03-16  Glenn Morris  <rgm@gnu.org>
 
@@ -144,8 +164,7 @@
 
 2012-03-12  Leo Liu  <sdl.web@gmail.com>
 
-        * simple.el (kill-new): Use equal-including-properties for
-        comparison.
+        * simple.el (kill-new): Use equal-including-properties for comparison.
         (kill-do-not-save-duplicates): Doc fix.
 
 2012-03-12  Stefan Monnier  <monnier@iro.umontreal.ca>
@@ -227,8 +246,7 @@
 
         * net/mairix.el (mairix-replace-invalid-chars): Rename from
         mairix-replace-illegal-chars; all callers changed.  Don't remove
-        ^, ~, and = characters: they are meaningful in mairix search
-        specs.
+        ^, ~, and = characters: they are meaningful in mairix search specs.
         (mairix-widget-create-query): Add usage information about mairix
         search forms: negating words, searching for substrings, etc.
 
@@ -413,8 +431,7 @@
 
 2012-03-04  Chong Yidong  <cyd@gnu.org>
 
-        * cus-start.el: Make x-select-enable-clipboard-manager
-        customizable.
+        * cus-start.el: Make x-select-enable-clipboard-manager customizable.
 
 2012-03-04  Glenn Morris  <rgm@gnu.org>
 
@@ -545,7 +562,7 @@
         (font-lock-default-function): Move the check for a specification
         to font-lock-spec-present.
 
-        * font-lock.el (font-lock-initial-fontify): call ...
+        * font-lock.el (font-lock-initial-fontify): Call ...
         (font-lock-spec-present): New function.
 
 2012-02-26  Jim Blandy  <jimb@red-bean.com>
@@ -874,8 +891,7 @@
 
 2012-02-12  Teodor Zlatanov  <tzz@lifelogs.com>
 
-        * net/gnutls.el (gnutls-algorithm-priority): Add missing :group
-        tag.
+        * net/gnutls.el (gnutls-algorithm-priority): Add missing :group tag.
 
 2012-02-12  Alan Mackenzie  <acm@muc.de>
 
@@ -1048,8 +1064,8 @@
         * progmodes/cc-guess.el (c-guess-offset-threshold, c-guess-region-max):
         Add :version tags.
 
-        * progmodes/compile.el (compilation-first-column)
-        (compilation-error-screen-columns, compilation-filter-start): Doc fixes.
+        * progmodes/compile.el (compilation-error-screen-columns)
+        (compilation-first-column, compilation-filter-start): Doc fixes.
 
         * vc/log-view.el (log-view-toggle-entry-display):
         * vc/vc.el (vc-merge, vc-pull): Doc fixes.
diff --git a/lisp/emacs-lisp/tabulated-list.el b/lisp/emacs-lisp/tabulated-list.el
index 8fe514ab551..f17b12da6a0 100644
--- a/lisp/emacs-lisp/tabulated-list.el
+++ b/lisp/emacs-lisp/tabulated-list.el
@@ -278,11 +278,10 @@ of column descriptors."
              (width  (nth 1 format))
              (label  (if (stringp desc) desc (car desc)))
              (help-echo (concat (car format) ": " label)))
-        ;; Truncate labels if necessary.
-        (and (> width 6)
-             (> (length label) width)
-             (setq label (concat (substring label 0 (- width 3))
-                                 "...")))
+        ;; Truncate labels if necessary (except last column).
+        (and (< (1+ n) len)
+             (> (string-width label) width)
+             (setq label (truncate-string-to-width label width nil nil t)))
         (setq label (bidi-string-mark-left-to-right label))
         (if (stringp desc)
             (insert (propertize label 'help-echo help-echo))
diff --git a/lisp/face-remap.el b/lisp/face-remap.el
index 3af9e31a6f7..ca7a28328f9 100644
--- a/lisp/face-remap.el
+++ b/lisp/face-remap.el
@@ -106,21 +106,20 @@ The list structure of ENTRY may be destructively modified."
 ;;;###autoload
 (defun face-remap-add-relative (face &rest specs)
   "Add a face remapping entry of FACE to SPECS in the current buffer.
-
-Return a cookie which can be used to delete the remapping with
+Return a cookie which can be used to delete this remapping with
 `face-remap-remove-relative'.
 
-SPECS can be any value suitable for the `face' text property,
-including a face name, a list of face names, or a face-attribute
-property list.  The attributes given by SPECS will be merged with
-any other currently active face remappings of FACE, and with the
-global definition of FACE.  An attempt is made to sort multiple
-entries so that entries with relative face-attributes are applied
-after entries with absolute face-attributes.
-
-The base (lowest priority) remapping may be set to a specific
-value, instead of the default of the global face definition,
-using `face-remap-set-base'."
+The remaining arguments, SPECS, should be either a list of face
+names, or a property list of face attribute/value pairs.  The
+remapping specified by SPECS takes effect alongside the
+remappings from other calls to `face-remap-add-relative', as well
+as the normal definition of FACE (at lowest priority).  This
+function tries to sort multiple remappings for the same face, so
+that remappings specifying relative face attributes are applied
+after remappings specifying absolute face attributes.
+
+The base (lowest priority) remapping may be set to something
+other than the normal definition of FACE via `face-remap-set-base'."
   (while (and (consp specs) (null (cdr specs)))
     (setq specs (car specs)))
   (make-local-variable 'face-remapping-alist)
@@ -148,7 +147,9 @@ COOKIE should be the return value from that function."
 
 ;;;###autoload
 (defun face-remap-reset-base (face)
-  "Set the base remapping of FACE to inherit from FACE's global definition."
+  "Set the base remapping of FACE to the normal definition of FACE.
+This causes the remappings specified by `face-remap-add-relative'
+to apply on top of the normal definition of FACE."
   (let ((entry (assq face face-remapping-alist)))
     (when entry
       ;; If there's nothing except a base remapping, we simply remove
@@ -163,10 +164,15 @@ COOKIE should be the return value from that function."
 ;;;###autoload
 (defun face-remap-set-base (face &rest specs)
   "Set the base remapping of FACE in the current buffer to SPECS.
-If SPECS is empty, the default base remapping is restored, which
-inherits from the global definition of FACE; note that this is
-different from SPECS containing a single value `nil', which does
-not inherit from the global definition of FACE."
+This causes the remappings specified by `face-remap-add-relative'
+to apply on top of the face specification given by SPECS.  SPECS
+should be either a list of face names, or a property list of face
+attribute/value pairs.
+
+If SPECS is empty, call `face-remap-reset-base' to use the normal
+definition of FACE as the base remapping; note that this is
+different from SPECS containing a single value `nil', which means
+not to inherit from the global definition of FACE at all."
   (while (and (consp specs) (not (null (car specs))) (null (cdr specs)))
     (setq specs (car specs)))
   (if (or (null specs)
diff --git a/lisp/faces.el b/lisp/faces.el
index 34fad66ce27..0256f8d951a 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -122,15 +122,13 @@ REGISTRY, ALTERNATIVE1, ALTERNATIVE2, and etc."
   "Return a list of all defined faces."
   (mapcar #'car face-new-frame-defaults))
 
-
-;;; ### If not frame-local initialize by what X resources?
-
 (defun make-face (face &optional no-init-from-resources)
   "Define a new face with name FACE, a symbol.
-NO-INIT-FROM-RESOURCES non-nil means don't initialize frame-local
-variants of FACE from X resources.  (X resources recognized are found
-in the global variable `face-x-resources'.)  If FACE is already known
-as a face, leave it unmodified.  Value is FACE."
+Do not call this directly from Lisp code; use `defface' instead.
+
+If NO-INIT-FROM-RESOURCES is non-nil, don't initialize face
+attributes from X resources.  If FACE is already known as a face,
+leave it unmodified.  Return FACE."
   (interactive (list (read-from-minibuffer
                       "Make face: " nil nil t 'face-name-history)))
   (unless (facep face)
@@ -145,31 +143,30 @@ as a face, leave it unmodified.  Value is FACE."
       (make-face-x-resource-internal face)))
   face)
 
-
 (defun make-empty-face (face)
   "Define a new, empty face with name FACE.
-If the face already exists, it is left unmodified.  Value is FACE."
+Do not call this directly from Lisp code; use `defface' instead."
   (interactive (list (read-from-minibuffer
                       "Make empty face: " nil nil t 'face-name-history)))
   (make-face face 'no-init-from-resources))
 
-
 (defun copy-face (old-face new-face &optional frame new-frame)
-  "Define a face just like OLD-FACE, with name NEW-FACE.
-
-If NEW-FACE already exists as a face, it is modified to be like
-OLD-FACE.  If it doesn't already exist, it is created.
-
-If the optional argument FRAME is given as a frame, NEW-FACE is
-changed on FRAME only.
-If FRAME is t, the frame-independent default specification for OLD-FACE
-is copied to NEW-FACE.
-If FRAME is nil, copying is done for the frame-independent defaults
-and for each existing frame.
-
-If the optional fourth argument NEW-FRAME is given,
-copy the information from face OLD-FACE on frame FRAME
-to NEW-FACE on frame NEW-FRAME.  In this case, FRAME may not be nil."
+  "Define a face named NEW-FACE, which is a copy of OLD-FACE.
+This function does not copy face customization data, so NEW-FACE
+will not be made customizable.  Most Lisp code should not call
+this function; use `defface' with :inherit instead.
+
+If NEW-FACE already exists as a face, modify it to be like
+OLD-FACE.  If NEW-FACE doesn't already exist, create it.
+
+If the optional argument FRAME is a frame, change NEW-FACE on
+FRAME only.  If FRAME is t, copy the frame-independent default
+specification for OLD-FACE to NEW-FACE.  If FRAME is nil, copy
+the defaults as well as the faces on each existing frame.
+
+If the optional fourth argument NEW-FRAME is given, copy the
+information from face OLD-FACE on frame FRAME to NEW-FACE on
+frame NEW-FRAME.  In this case, FRAME must not be nil."
   (let ((inhibit-quit t))
     (if (null frame)
         (progn
diff --git a/lisp/gnus/ChangeLog b/lisp/gnus/ChangeLog
index d0d35407367..878b9b9eb6b 100644
--- a/lisp/gnus/ChangeLog
+++ b/lisp/gnus/ChangeLog
@@ -1,3 +1,8 @@
+2012-03-19  Lars Magne Ingebrigtsen  <larsi@gnus.org>
+
+        * shr.el (shr-insert): Update the text state properly to avoid
+        inserting spurious paragraph starts.
+
 2012-03-14  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
         * gnus-sum.el (gnus-update-marks): Don't propagate marks unless
diff --git a/lisp/gnus/shr.el b/lisp/gnus/shr.el
index 53c0063de2e..c2040a9b8cf 100644
--- a/lisp/gnus/shr.el
+++ b/lisp/gnus/shr.el
@@ -332,6 +332,7 @@ the URL of the image to the kill buffer instead."
       (unless shr-start
         (setq shr-start (point)))
       (insert elem)
+      (setq shr-state nil)
       (let (found)
         (while (and (> (current-column) shr-width)
                     (progn
diff --git a/lisp/textmodes/artist.el b/lisp/textmodes/artist.el
index fdfb1a51ba0..72ae44bb60d 100644
--- a/lisp/textmodes/artist.el
+++ b/lisp/textmodes/artist.el
@@ -535,7 +535,8 @@ This variable is initialized by the `artist-make-prev-next-op-alist' function.")
                   ("Text" artist-select-op-text-overwrite text-ovwrt)
                   ("Ellipse" artist-select-op-circle circle)
                   ("Poly-line" artist-select-op-straight-poly-line spolyline)
-                  ("Rectangle" artist-select-op-square square)
+                  ("Square" artist-select-op-square square)
+                  ("Rectangle" artist-select-op-rectangle rectangle)
                   ("Line" artist-select-op-straight-line s-line)
                   ("Pen" artist-select-op-pen-line pen-line)))
       (define-key map (vector (nth 2 op))
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 61bb4db558c..b6feecebde5 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -1141,12 +1141,6 @@ the field."
         (kill-region (point) end)
       (call-interactively 'kill-line))))
 
-(defcustom widget-complete-field (lookup-key global-map "\M-\t")
-  "Default function to call for completion inside fields."
-  :options '(ispell-complete-word complete-tag lisp-complete-symbol)
-  :type 'function
-  :group 'widgets)
-
 (defun widget-narrow-to-field ()
   "Narrow to field."
   (interactive)
@@ -1169,10 +1163,6 @@ When not inside a field, signal an error."
         (completion-in-region (nth 0 data) (nth 1 data) (nth 2 data)
                               (plist-get completion-extra-properties
                                          :predicate))))
-     ((widget-field-find (point))
-      ;; This defaulting used to be performed in widget-default-complete, but
-      ;; it seems more appropriate here than in widget-default-completions.
-      (call-interactively 'widget-complete-field))
      (t
       (error "Not in an editable field")))))
 ;; We may want to use widget completion in buffers where the major mode
diff --git a/src/ChangeLog b/src/ChangeLog
index 8b1221ab6d8..7a97859ba63 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,18 @@
+2012-03-21  Chong Yidong  <cyd@gnu.org>
+
+        * xfaces.c (Vface_remapping_alist): Doc fix.
+
+2012-03-20  Eli Zaretskii  <eliz@gnu.org>
+
+        * w32proc.c (Fw32_set_console_codepage)
+        (Fw32_set_console_output_codepage, Fw32_get_codepage_charset): Doc
+        fixes.
+
+2012-03-20  Chong Yidong  <cyd@gnu.org>
+
+        * dispnew.c (Fredisplay, Vredisplay_preemption_period): Update doc
+        to reflect default non-nil value of redisplay-dont-pause.
+
 2012-03-19  Kenichi Handa  <handa@m17n.org>
 
         * ftfont.c (ftfont_drive_otf): Mask bits of character code to make
diff --git a/src/dispnew.c b/src/dispnew.c
index d302e717ec2..02d6de53bbf 100644
--- a/src/dispnew.c
+++ b/src/dispnew.c
@@ -6068,10 +6068,14 @@ sit_for (Lisp_Object timeout, int reading, int do_display)
 
 
 DEFUN ("redisplay", Fredisplay, Sredisplay, 0, 1, 0,
-       doc: /* Perform redisplay if no input is available.
-If optional arg FORCE is non-nil or `redisplay-dont-pause' is non-nil,
-perform a full redisplay even if input is available.
-Return t if redisplay was performed, nil otherwise.  */)
+       doc: /* Perform redisplay.
+Optional arg FORCE, if non-nil, prevents redisplay from being
+preempted by arriving input, even if `redisplay-dont-pause' is nil.
+If `redisplay-dont-pause' is non-nil (the default), redisplay is never
+preempted by arriving input, so FORCE does nothing.
+
+Return t if redisplay was performed, nil if redisplay was preempted
+immediately by pending input.  */)
   (Lisp_Object force)
 {
   int count;
@@ -6521,21 +6525,21 @@ syms_of_display (void)
   DEFSYM (Qredisplay_dont_pause, "redisplay-dont-pause");
 
   DEFVAR_INT ("baud-rate", baud_rate,
-              doc: /* *The output baud rate of the terminal.
+              doc: /* The output baud rate of the terminal.
 On most systems, changing this value will affect the amount of padding
 and the other strategic decisions made during redisplay.  */);
 
   DEFVAR_BOOL ("inverse-video", inverse_video,
-               doc: /* *Non-nil means invert the entire frame display.
+               doc: /* Non-nil means invert the entire frame display.
 This means everything is in inverse video which otherwise would not be.  */);
 
   DEFVAR_BOOL ("visible-bell", visible_bell,
-               doc: /* *Non-nil means try to flash the frame to represent a bell.
+               doc: /* Non-nil means try to flash the frame to represent a bell.
 
 See also `ring-bell-function'.  */);
 
   DEFVAR_BOOL ("no-redraw-on-reenter", no_redraw_on_reenter,
-               doc: /* *Non-nil means no need to redraw entire frame after suspending.
+               doc: /* Non-nil means no need to redraw entire frame after suspending.
 A non-nil value is useful if the terminal can automatically preserve
 Emacs's frame display when you reenter Emacs.
 It is up to you to set this variable if your terminal can do that.  */);
@@ -6590,14 +6594,15 @@ See `buffer-display-table' for more information.  */);
   Vstandard_display_table = Qnil;
 
   DEFVAR_BOOL ("redisplay-dont-pause", redisplay_dont_pause,
-               doc: /* *Non-nil means display update isn't paused when input is detected.  */);
+               doc: /* Non-nil means display update isn't paused when input is detected.  */);
   redisplay_dont_pause = 1;
 
 #if PERIODIC_PREEMPTION_CHECKING
   DEFVAR_LISP ("redisplay-preemption-period", Vredisplay_preemption_period,
-               doc: /* *The period in seconds between checking for input during redisplay.
-If input is detected, redisplay is pre-empted, and the input is processed.
-If nil, never pre-empt redisplay.  */);
+               doc: /* Period in seconds between checking for input during redisplay.
+This has an effect only if `redisplay-dont-pause' is nil; in that
+case, arriving input preempts redisplay until the input is processed.
+If the value is nil, redisplay is never preempted.  */);
   Vredisplay_preemption_period = make_float (0.10);
 #endif
 
diff --git a/src/w32proc.c b/src/w32proc.c
index f7982f36913..28591f90128 100644
--- a/src/w32proc.c
+++ b/src/w32proc.c
@@ -2067,8 +2067,8 @@ DEFUN ("w32-get-console-codepage", Fw32_get_console_codepage,
 
 DEFUN ("w32-set-console-codepage", Fw32_set_console_codepage,
        Sw32_set_console_codepage, 1, 1, 0,
-       doc: /* Make Windows codepage CP be the current codepage setting for Emacs.
-The codepage setting affects keyboard input and display in tty mode.
+       doc: /* Make Windows codepage CP be the codepage for Emacs tty keyboard input.
+This codepage setting affects keyboard input in tty mode.
 If successful, the new CP is returned, otherwise nil.  */)
   (Lisp_Object cp)
 {
@@ -2095,8 +2095,8 @@ DEFUN ("w32-get-console-output-codepage", Fw32_get_console_output_codepage,
 
 DEFUN ("w32-set-console-output-codepage", Fw32_set_console_output_codepage,
        Sw32_set_console_output_codepage, 1, 1, 0,
-       doc: /* Make Windows codepage CP be the current codepage setting for Emacs.
-The codepage setting affects keyboard input and display in tty mode.
+       doc: /* Make Windows codepage CP be the codepage for Emacs console output.
+This codepage setting affects display in tty mode.
 If successful, the new CP is returned, otherwise nil.  */)
   (Lisp_Object cp)
 {
@@ -2114,7 +2114,7 @@ If successful, the new CP is returned, otherwise nil.  */)
 
 DEFUN ("w32-get-codepage-charset", Fw32_get_codepage_charset,
        Sw32_get_codepage_charset, 1, 1, 0,
-       doc: /* Return charset of codepage CP.
+       doc: /* Return charset ID corresponding to codepage CP.
 Returns nil if the codepage is not valid.  */)
   (Lisp_Object cp)
 {
diff --git a/src/xfaces.c b/src/xfaces.c
index bcb04188aeb..476fb1e0366 100644
--- a/src/xfaces.c
+++ b/src/xfaces.c
@@ -6599,20 +6599,22 @@ ignore.  */);
                doc: /* Alist of face remappings.
 Each element is of the form:
 
-   (FACE REPLACEMENT...),
+   (FACE . REPLACEMENT),
 
-which causes display of the face FACE to use REPLACEMENT... instead.
-REPLACEMENT... is interpreted the same way as the value of a `face'
-text property: it may be (1) A face name, (2) A list of face names,
-(3) A property-list of face attribute/value pairs, or (4) A list of
-face names or lists containing face attribute/value pairs.
+which causes display of the face FACE to use REPLACEMENT instead.
+REPLACEMENT is a face specification, i.e. one of the following:
 
-Multiple entries in REPLACEMENT... are merged together to form the final
-result, with faces or attributes earlier in the list taking precedence
-over those that are later.
+  (1) a face name
+  (2) a property list of attribute/value pairs, or
+  (3) a list in which each element has the form of (1) or (2).
 
-Face-name remapping cycles are suppressed; recursive references use the
-underlying face instead of the remapped face.  So a remapping of the form:
+List values for REPLACEMENT are merged to form the final face
+specification, with earlier entries taking precedence, in the same as
+as in the `face' text property.
+
+Face-name remapping cycles are suppressed; recursive references use
+the underlying face instead of the remapped face.  So a remapping of
+the form:
 
    (FACE EXTRA-FACE... FACE)
 
@@ -6620,13 +6622,13 @@ or:
 
    (FACE (FACE-ATTR VAL ...) FACE)
 
-will cause EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the
-existing definition of FACE.  Note that for the default face, this isn't
-necessary, as every face inherits from the default face.
+causes EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the
+existing definition of FACE.  Note that this isn't necessary for the
+default face, since every face inherits from the default face.
 
-Making this variable buffer-local is a good way to allow buffer-specific
-face definitions.  For instance, the mode my-mode could define a face
-`my-mode-default', and then in the mode setup function, do:
+If this variable is made buffer-local, the face remapping takes effect
+only in that buffer.  For instance, the mode my-mode could define a
+face `my-mode-default', and then in the mode setup function, do:
 
    (set (make-local-variable 'face-remapping-alist)
         '((default my-mode-default)))).