Merge from trunk and resolve conflicts.

18 files changed, 734 insertions, 312 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 151fb0005a0..b8f17c0fae5 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,126 @@
+2014-10-13  Glenn Morris  <rgm@gnu.org>
+
+        * Makefile.in (dist): Update for new output variables.
+
+2014-10-12  Glenn Morris  <rgm@gnu.org>
+
+        * elisp.texi (DATE): Bump to October 2014.
+
+2014-10-09  Glenn Morris  <rgm@gnu.org>
+
+        * frames.texi (Multiple Terminals): Copyedits.
+
+2014-10-09  Eli Zaretskii  <eliz@gnu.org>
+
+        * frames.texi (Multiple Terminals): Improve the description of X
+        display names.  Add index entries.
+        (Basic Parameters): Add a cross-reference to where X display names
+        are described.
+        (Position Parameters): Mention that positional parameters of the
+        form (+ POS) can be negative if they are on a non-primary monitor
+        of a multi-monitor display.  (Bug#18636)
+        (Creating Frames): Mention that on multi-monitor displays the
+        frame might be positioned differently than specified by the frame
+        parameters alist.
+
+2014-10-08  Leo Liu  <sdl.web@gmail.com>
+
+        * streams.texi (Output Functions): Document new argument ENSURE to
+        terpri.  (Bug#18652)
+
+2014-10-04  Martin Rudalics  <rudalics@gmx.at>
+
+        * display.texi (Scroll Bars): Add description of horizontal scroll
+        bars and associated functions.
+        * frames.texi (Layout Parameters): Add horizontal scroll bar
+        entries.  Remove paragraph on "combined fringe widths".
+        * windows.texi (Window Sizes): Describe affects of horizontal
+        scroll bars on window layout and sizes.  Fix description of
+        window-full-height-p.
+        (Resizing Windows): Mention horizontal scroll bar.
+
+2014-10-04  Glenn Morris  <rgm@gnu.org>
+
+        * commands.texi (Generic Commands): Copyedits.
+
+        * display.texi (Scroll Bars):
+        * modes.texi (Header Lines): Copyedits.
+
+        * buffers.texi (Buffer List):
+        * display.texi (Image Descriptors, Defining Images):
+        * functions.texi (Core Advising Primitives): Small fixes re @var usage.
+
+        * windows.texi (Window Sizes, Resizing Windows): Copyedits.
+
+        * frames.texi (Multiple Terminals): Copyedits re multiple monitors.
+
+2014-10-03  Martin Rudalics  <rudalics@gmx.at>
+
+        * frames.texi (Size Parameters, Size and Position): Mention that
+        with some window managers you have to set `frame-resize-pixelwise'
+        in order make a frame truly fullscreen or maximized.
+
+2014-10-01  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Improve doc for use of 'int', and discuss 'ssize_t'.
+        * internals.texi (C Integer Types): Mention 'int' for other
+        randomish values that lie in 'int' range.  Mention 'ssize_t'.  See:
+        http://lists.gnu.org/archive/html/emacs-devel/2014-10/msg00019.html
+
+        Use AUTO_CONS instead of SCOPED_CONS, etc.
+        * internals.texi (Stack-allocated Objects):
+        Adjust to match the revised, less error-prone macros.
+
+2014-09-30  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * internals.texi (Stack-allocated Objects): Further improvements.
+        Give an example of misuse.
+
+2014-09-30  Eli Zaretskii  <eliz@gnu.org>
+
+        * internals.texi (Stack-allocated Objects): Minor improvements of
+        the wording and the indexing.
+
+2014-09-30  Dmitry Antipov  <dmantipov@yandex.ru>
+
+        * internals.texi (Stack-allocated Objects): Describe this feature.
+
+2014-09-15  Daniel Colascione  <dancol@dancol.org>
+
+        * text.texi (Registers): Make `insert-register' documentation
+        reflect interface change.
+
+2014-09-08  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * functions.texi (Core Advising Primitives): Add a note about the
+        confusing treatment of `interactive' for :filter-args (bug#18399).
+
+2014-09-07  Michael Albinus  <michael.albinus@gmx.de>
+
+        * strings.texi (Text Comparison): Describe `string-collate-equalp'
+        and `string-collate-lessp'.
+
+2014-09-06  Leo Liu  <sdl.web@gmail.com>
+
+        * control.texi (Pattern matching case statement): Document vector
+        qpattern.  (Bug#18327)
+
+2014-08-29  Dmitry Antipov  <dmantipov@yandex.ru>
+
+        * lists.texi (Functions that Rearrange Lists): Remove
+        description of sort ...
+        * sequences.texi (Sequence Functions): ... and generalize
+        it for sequences.  Add an example.
+
+2014-08-28  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Bidirectional Display): Update the Emacs's class
+        of bidirectional conformance.
+
+2014-08-27  Dmitry Antipov  <dmantipov@yandex.ru>
+
+        * eval.texi (Eval): Mention possible recovery from stack overflow.
+
 2014-10-13  Eli Zaretskii  <eliz@gnu.org>
 
         * display.texi (Bidirectional Display): Update the version of the
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 2919d97b3a3..22955fb9bae 100644
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -192,6 +192,21 @@ dist:
           -e 's/^\(clean:.*\)/\1 infoclean/' \
           -e "s/@ver[s]ion@/${version}/" \
           -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \
+          -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \
+          -e 's|@SH[E]LL@|/bin/bash|' \
+          -e 's|@[p]refix@|/usr/local|' \
+          -e 's|@[d]atarootdir@|$${prefix}/share|' \
+          -e 's|@[d]atadir@|$${datarootdir}|' \
+          -e 's|@[P]ACKAGE_TARNAME@|emacs|' \
+          -e 's|@[d]ocdir@|$${datarootdir}/doc/$${PACKAGE_TARNAME}|' \
+          -e 's|@[d]vidir@|$${docdir}|' \
+          -e 's|@[h]tmldir@|$${docdir}|' \
+          -e 's|@[p]dfdir@|$${docdir}|' \
+          -e 's|@[p]sdir@|$${docdir}|' \
+          -e 's|@[G]ZIP_PROG@|gzip|' \
+          -e 's|@IN[S]TALL@|install -c|' \
+          -e 's|@IN[S]TALL_DATA@|$${INSTALL} -m 644|' \
+          -e '/@[c]onfigure_input@/d' \
           ${srcdir}/Makefile.in > emacs-lispref-${version}/Makefile
         @if grep '@[a-zA-Z_]*@' emacs-lispref-${version}/Makefile; then \
           echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1293a03082c..5ac2d6786e8 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -863,7 +863,7 @@ If no suitable buffer exists, the buffer @file{*scratch*} is returned
 
 @defun last-buffer &optional buffer visible-ok frame
 This function returns the last buffer in @var{frame}'s buffer list other
-than @var{BUFFER}.  If @var{frame} is omitted or @code{nil}, it uses the
+than @var{buffer}.  If @var{frame} is omitted or @code{nil}, it uses the
 selected frame's buffer list.
 
 The argument @var{visible-ok} is handled as with @code{other-buffer},
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 58e903918bf..e5db4d87539 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -589,31 +589,26 @@ Put them into three windows, selecting the last one."
 @cindex alternatives, defining
 
 The macro @code{define-alternatives} can be used to define
-@dfn{generic commands}.  Generic commands are interactive functions
-whose implementation can be selected among several alternatives, as a
-matter of user preference.
+@dfn{generic commands}.  These are interactive functions whose
+implementation can be selected from several alternatives, as a matter
+of user preference.
 
 @defmac define-alternatives command &rest customizations
-Define the new command `COMMAND'.
+Define the new command @var{command}, a symbol.
 
-The argument `COMMAND' should be a symbol.
+When a user runs @kbd{M-x @var{command} @key{RET}} for the first time,
+Emacs prompts for which real form of the command to use, and records
+the selection by way of a custom variable.  Using a prefix argument
+repeats this process of choosing an alternative.
 
-When a user runs @kbd{M-x COMMAND @key{RET}} for the first time, Emacs
-will prompt for which alternative to use and record the selected
-command as a custom variable.
+The variable @code{@var{command}-alternatives} should contain an alist
+with alternative implementations of @var{command}.
+Until this variable is set, @code{define-alternatives} has no effect.
 
-Running @kbd{C-u M-x COMMAND @key{RET}} prompts again for an
-alternative and overwrites the previous choice.
-
-The variable @code{COMMAND-alternatives} contains an alist
-(@pxref{Association Lists}) with alternative implementations of
-`COMMAND'.  @code{define-alternatives} does not have any effect until
-this variable is set.
-
-If @var{customizations} is non-@var{nil}, it should be composed of
-alternating @code{defcustom} keywords and values to add to the
-declaration of @code{COMMAND-alternatives} (typically :group and
-:version).
+If @var{customizations} is non-@code{nil}, it should consist of
+alternating @code{defcustom} keywords (typically @code{:group} and
+@code{:version}) and values to add to the declaration of
+@code{@var{command}-alternatives}.
 @end defmac
 
 @node Interactive Call
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index edf60dd5cc8..5cf6368db52 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -328,13 +328,13 @@ lexical binding):
 @example
 (defun evaluate (exp env)
   (pcase exp
-    (`(add ,x ,y)         (+ (evaluate x env) (evaluate y env)))
-    (`(call ,fun ,arg)    (funcall (evaluate fun env) (evaluate arg env)))
-    (`(fn ,arg ,body)     (lambda (val)
-                            (evaluate body (cons (cons arg val) env))))
-    ((pred numberp)       exp)
-    ((pred symbolp)       (cdr (assq exp env)))
-    (_                    (error "Unknown expression %S" exp))))
+    (`(add ,x ,y)       (+ (evaluate x env) (evaluate y env)))
+    (`(call ,fun ,arg)  (funcall (evaluate fun env) (evaluate arg env)))
+    (`(fn ,arg ,body)   (lambda (val)
+                          (evaluate body (cons (cons arg val) env))))
+    ((pred numberp)     exp)
+    ((pred symbolp)     (cdr (assq exp env)))
+    (_                  (error "Unknown expression %S" exp))))
 @end example
 
 Where @code{`(add ,x ,y)} is a pattern that checks that @code{exp} is a three
@@ -370,6 +370,10 @@ More specifically, a Q-pattern can take the following forms:
 @item (@var{qpattern1} . @var{qpattern2})
 This pattern matches any cons cell whose @code{car} matches @var{QPATTERN1} and
 whose @code{cdr} matches @var{PATTERN2}.
+@item [@var{qpattern1 qpattern2..qpatternm}]
+This pattern matches a vector of length @code{M} whose 0..(M-1)th
+elements match @var{QPATTERN1}, @var{QPATTERN2}..@var{QPATTERNm},
+respectively.
 @item @var{atom}
 This pattern matches any atom @code{equal} to @var{atom}.
 @item ,@var{upattern}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index fd4a7d7058e..4cb06dd188f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -23,7 +23,7 @@ that Emacs presents to the user.
 * Faces::               A face defines a graphics style for text characters:
                           font, colors, etc.
 * Fringes::             Controlling window fringes.
-* Scroll Bars::         Controlling vertical scroll bars.
+* Scroll Bars::         Controlling scroll bars.
 * Window Dividers::     Separating windows visually.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
@@ -3866,102 +3866,164 @@ arrow position.  If either property is not set, the default
 @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
 is used.
 
+
 @node Scroll Bars
 @section Scroll Bars
 @cindex scroll bars
 
 Normally the frame parameter @code{vertical-scroll-bars} controls
-whether the windows in the frame have vertical scroll bars, and
-whether they are on the left or right.  The frame parameter
-@code{scroll-bar-width} specifies how wide they are (@code{nil}
-meaning the default).  @xref{Layout Parameters}.
+whether the windows in the frame have vertical scroll bars, and whether
+they are on the left or right.  The frame parameter
+@code{scroll-bar-width} specifies how wide they are (@code{nil} meaning
+the default).
+
+   The frame parameter @code{horizontal-scroll-bars} controls whether
+the windows in the frame have horizontal scroll bars.  The frame
+parameter @code{scroll-bar-height} specifies how high they are
+(@code{nil} meaning the default).  @xref{Layout Parameters}.
+
+@vindex horizontal-scroll-bars-available-p
+   Horizontal scroll bars are not available on all platforms.  The
+function @code{horizontal-scroll-bars-available-p} which takes no
+argument returns non-@code{nil} if they are available on your system.
+
+   The following three functions take as argument a live frame which
+defaults to the selected one.
 
 @defun frame-current-scroll-bars &optional frame
-This function reports the scroll bar type settings for frame
-@var{frame}.  The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
-@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
-(which means no scroll bar.)  @var{horizontal-type} is meant to
-specify the horizontal scroll bar type, but since they are not
-implemented, it is always @code{nil}.
-@end defun
-
-@vindex vertical-scroll-bar
-  You can enable or disable scroll bars for a particular buffer,
-by setting the variable @code{vertical-scroll-bar}.  This variable
-automatically becomes buffer-local when set.  The possible values are
-@code{left}, @code{right}, @code{t}, which means to use the
-frame's default, and @code{nil} for no scroll bar.
+This function reports the scroll bar types for frame @var{frame}.  The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}, where @var{vertical-type} is either
+@code{left}, @code{right}, or @code{nil} (which means no vertical scroll
+bar.)  @var{horizontal-type} is either @code{bottom} or @code{nil}
+(which means no horizontal scroll bar).
+@end defun
 
-  You can also control this for individual windows.  Call the function
-@code{set-window-scroll-bars} to specify what to do for a specific window:
+@defun frame-scroll-bar-width &optional Lisp_Object &optional frame
+This function returns the width of vertical scroll bars of @var{frame}
+in pixels.
+@end defun
 
-@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
-This function sets the width and type of scroll bars for window
-@var{window}.
+@defun frame-scroll-bar-height &optional Lisp_Object &optional frame
+This function returns the height of horizontal scroll bars of
+@var{frame} in pixels.
+@end defun
 
-@var{width} specifies the scroll bar width in pixels (@code{nil} means
-use the width specified for the frame).  @var{vertical-type} specifies
-whether to have a vertical scroll bar and, if so, where.  The possible
-values are @code{left}, @code{right} and @code{nil}, just like the
-values of the @code{vertical-scroll-bars} frame parameter.
+You can override the frame specific settings for individual windows by
+using the following function:
 
-The argument @var{horizontal-type} is meant to specify whether and
-where to have horizontal scroll bars, but since they are not
-implemented, it has no effect.  If @var{window} is @code{nil}, the
-selected window is used.
+@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type
+This function sets the width and/or height and the types of scroll bars
+for window @var{window}.
+
+@var{width} specifies the width of the vertical scroll bar in pixels
+(@code{nil} means use the width specified for the frame).
+@var{vertical-type} specifies whether to have a vertical scroll bar and,
+if so, where.  The possible values are @code{left}, @code{right},
+@code{t}, which means to use the frame's default, and @code{nil} for no
+vertical scroll bar.
+
+@var{height} specifies the height of the horizontal scroll bar in pixels
+(@code{nil} means use the height specified for the frame).
+@var{horizontal-type} specifies whether to have a horizontal scroll bar.
+The possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no horizontal scroll bar.
+
+If @var{window} is @code{nil}, the selected window is used.
 @end defun
 
+The following four functions take as argument a live window which
+defaults to the selected one.
+
 @defun window-scroll-bars &optional window
-Report the width and type of scroll bars specified for @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a list of the form @code{(@var{width}
-@var{cols} @var{vertical-type} @var{horizontal-type})}.  The value
-@var{width} is the value that was specified for the width (which may
-be @code{nil}); @var{cols} is the number of columns that the scroll
-bar actually occupies.
+This function returns a list of the form @code{(@var{width}
+@var{columns} @var{vertical-type} @var{height} @var{lines}
+@var{horizontal-type})}.
 
-@var{horizontal-type} is not actually meaningful.
+The value @var{width} is the value that was specified for the width of
+the vertical scroll bar (which may be @code{nil}); @var{columns} is the
+(possibly rounded) number of columns that the vertical scroll bar
+actually occupies.
+
+The value @var{height} is the value that was specified for the height of
+the horizontal scroll bar (which may be @code{nil}); @var{lines} is the
+(possibly rounded) number of lines that the horizontally scroll bar
+actually occupies.
+@end defun
+
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}.  The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}.  Unlike @code{window-scroll-bars}, this reports
+the scroll bar type actually used, once frame defaults and
+@code{scroll-bar-mode} are taken into account.
 @end defun
 
 @defun window-scroll-bar-width &optional window
-This function returns the width of @var{window}'s vertical scrollbar,
-in pixels.  @var{window} must be a live window.  If @var{window} is
-@code{nil} or omitted, it will be the selected window.
+This function returns the width in pixels of @var{window}'s vertical
+scrollbar.
+@end defun
+
+@defun window-scroll-bar-height &optional window
+This function returns the height in pixels of @var{window}'s horizontal
+scrollbar.
 @end defun
 
 If you don't specify these values for a window with
 @code{set-window-scroll-bars}, the buffer-local variables
-@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
-displayed control the window's vertical scroll bars.  The function
+@code{vertical-scroll-bar}, @code{horizontal-scroll-bar},
+@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being
+displayed control the window's scroll bars.  The function
 @code{set-window-buffer} examines these variables.  If you change them
-in a buffer that is already visible in a window, you can make the
-window take note of the new values by calling @code{set-window-buffer}
+in a buffer that is already visible in a window, you can make the window
+take note of the new values by calling @code{set-window-buffer}
 specifying the same buffer that is already displayed.
 
-@defopt scroll-bar-mode
-This variable, always local in all buffers, controls whether and where
-to put scroll bars in windows displaying the buffer.  The possible values
-are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
-the left, and @code{right} to put a scroll bar on the right.
-@end defopt
+You can control the appearance of scroll bars for a particular buffer by
+setting the following variables which automatically become buffer-local
+when set.
 
-@defun window-current-scroll-bars &optional window
-This function reports the scroll bar type for window @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}.  Unlike
-@code{window-scroll-bars}, this reports the scroll bar type actually
-used, once frame defaults and @code{scroll-bar-mode} are taken into
-account.
-@end defun
+@defvar vertical-scroll-bar
+This variable specifies the location of the vertical scroll bar.  The
+possible values are @code{left}, @code{right}, @code{t}, which means to
+use the frame's default, and @code{nil} for no scroll bar.
+@end defvar
+
+@defvar horizontal-scroll-bar
+This variable specifies the location of the horizontal scroll bar.  The
+possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+@end defvar
 
 @defvar scroll-bar-width
-This variable, always local in all buffers, specifies the width of the
-buffer's scroll bars, measured in pixels.  A value of @code{nil} means
-to use the value specified by the frame.
+This variable specifies the width of the buffer's vertical scroll bars,
+measured in pixels.  A value of @code{nil} means to use the value
+specified by the frame.
 @end defvar
 
+@defvar scroll-bar-height
+This variable specifies the height of the buffer's horizontal scroll
+bar, measured in pixels.  A value of @code{nil} means to use the value
+specified by the frame.
+@end defvar
+
+Finally you can toggle the display of scroll bars on all frames by
+customizing the variables @code{scroll-bar-mode} and
+@code{horizontal-scroll-bar-mode}.
+
+@defopt scroll-bar-mode
+This variable controls whether and where to put vertical scroll bars in
+all frames.  The possible values are @code{nil} for no scroll bars,
+@code{left} to put scroll bars on the left and @code{right} to put
+scroll bars on the right.
+@end defopt
+
+@defopt horizontal-scroll-bar-mode
+This variable controls whether to display horizontal scroll bars on all
+frames.
+@end defopt
+
+
 @node Window Dividers
 @section Window Dividers
 @cindex window dividers
@@ -4503,7 +4565,7 @@ functions to insert images into buffers.
 
   Each image descriptor has the form @code{(image . @var{props})},
 where @var{props} is a property list of alternating keyword symbols
-and values, including at least the pair @code{:type @var{TYPE}} which
+and values, including at least the pair @code{:type @var{type}} that
 specifies the image type.
 
   The following is a list of properties that are meaningful for all
@@ -4995,7 +5057,7 @@ of a list of image specifications @var{specs}.
 Each specification in @var{specs} is a property list with contents
 depending on image type.  All specifications must at least contain the
 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
-or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
+or @w{@code{:data @var{data}}}, where @var{type} is a symbol specifying
 the image type, e.g., @code{xbm}, @var{file} is the file to load the
 image from, and @var{data} is a string containing the actual image data.
 The first specification in the list whose @var{type} is supported, and
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index bb2e4638396..fa665da34a4 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -56,7 +56,7 @@
 @c (See comments for EDITION in emacs.texi)
 @set VERSION  3.1
 @include emacsver.texi
-@set DATE January 2013
+@set DATE October 2014
 
 @c in general, keep the following line commented out, unless doing a
 @c copy of this manual that will be published.  The manual should go
@@ -1343,7 +1343,7 @@ Emacs Display
 * Faces::                   A face defines a graphics style
                               for text characters: font, colors, etc.
 * Fringes::                 Controlling window fringes.
-* Scroll Bars::             Controlling vertical scroll bars.
+* Scroll Bars::             Controlling scroll bars.
 * Window Dividers::         Separating windows visually.
 * Display Property::        Enabling special display features.
 * Images::                  Displaying images in Emacs buffers.
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 05250233b00..6ffc7db8abf 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -805,7 +805,12 @@ message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
 This limit, with the associated error when it is exceeded, is one way
 Emacs Lisp avoids infinite recursion on an ill-defined function.  If
 you increase the value of @code{max-lisp-eval-depth} too much, such
-code can cause stack overflow instead.
+code can cause stack overflow instead.  On some systems, this overflow
+can be handled.  In that case, normal Lisp evaluation is interrupted
+and control is transferred back to the top level command loop
+(@code{top-level}).  Note that there is no way to enter Emacs Lisp
+debugger in this situation.  @xref{Error Debugging}.
+
 @cindex Lisp nesting error
 
 The depth limit counts internal uses of @code{eval}, @code{apply}, and
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index b95a5ccdb92..a14702a7ce1 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -131,6 +131,13 @@ applies any parameters listed in @code{frame-inherited-parameters}
 (see below) and not present in the argument, taking the values from
 the frame that was selected when @code{make-frame} was called.
 
+Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
+window manager might position the frame differently than specified by
+the positional parameters in @var{alist} (@pxref{Position
+Parameters}).  For example, some window managers have a policy of
+displaying the frame on the monitor that contains the largest part of
+the window (a.k.a.@: the @dfn{dominating} monitor).
+
 This function itself does not make the new frame the selected frame.
 @xref{Input Focus}.  The previously selected frame remains selected.
 On graphical terminals, however, the windowing system may select the
@@ -258,13 +265,27 @@ of those frames is ``@emph{the} selected frame'' at any given moment
 terminals, by interacting with the @command{emacsclient} program.
 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
 
+@cindex X display names
+@cindex display name on X
   A single X server can handle more than one display.  Each X display
-has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
-The first two parts, @var{host} and @var{server}, identify the X
-server; the third part, @var{screen}, identifies a screen number on
-that X server.  When you use two or more screens belonging to one
-server, Emacs knows by the similarity in their names that they share a
-single keyboard.
+has a three-part name,
+@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}.  The
+first part, @var{hostname}, specifies the name of the machine to which
+the display is physically connected.  The second part,
+@var{displaynumber}, is a zero-based number that identifies one or
+more monitors connected to that machine that share a common keyboard
+and pointing device (mouse, tablet, etc.).  The third part,
+@var{screennumber}, identifies a zero-based screen number (a separate
+monitor) that is part of a single monitor collection on that X server.
+When you use two or more screens belonging to one server, Emacs knows
+by the similarity in their names that they share a single keyboard.
+
+  Systems that don't use the X window system, such as MS-Windows,
+don't support the notion of X displays, and have only one display on
+each host.  The display name on these systems doesn't follow the above
+3-part format; for example, the display name on MS-Windows systems is
+a constant string @samp{w32}, and exists for compatibility, so that
+you could pass it to functions that expect a display name.
 
 @deffn Command make-frame-on-display display &optional parameters
 This function creates and returns a new frame on @var{display}, taking
@@ -314,57 +335,84 @@ on that display (@pxref{Deleting Frames}).
 
 @cindex multi-monitor
   On some ``multi-monitor'' setups, a single X display outputs to more
-than one physical monitor.  @code{display-monitor-attributes-list} and
-@code{frame-monitor-attributes} can be used to obtain information
-about each physical monitor on multi-monitor setups.
+than one physical monitor.  You can use the functions
+@code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
+to obtain information about such setups.
 
 @defun display-monitor-attributes-list &optional display
 This function returns a list of physical monitor attributes on
-@var{display}.  Each element of the list is an association list,
-representing the attributes of each physical monitor.  The first
-element corresponds to the primary monitor.
-
-Attributes for a physical monitor are:
+@var{display}, which can be a display name (a string), a terminal, or
+a frame; if omitted or @code{nil}, it defaults to the selected frame's
+display.  Each element of the list is an association list,
+representing the attributes of a physical monitor.  The first element
+corresponds to the primary monitor.  The attribute keys and values
+are:
 
 @table @samp
 @item geometry
-Position and size in pixels in the form of @samp{(X Y WIDTH HEIGHT)}
+Position of the top-left corner of the monitor's screen and its size,
+in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}.  Note
+that, if the monitor is not the primary monitor, some of the
+coordinates might be negative.
 
 @item workarea
-Position and size of the workarea in pixels in the form of @samp{(X Y
-WIDTH HEIGHT)}
+Position of the top-left corner and size of the work area (``usable''
+space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
+This may be different from @samp{geometry} in that space occupied by
+various window manager features (docks, taskbars, etc.) may be
+excluded from the work area.  Whether or not such features actually
+subtract from the work area depends on the platform and environment.
+Again, if the monitor is not the primary monitor, some of the
+coordinates might be negative.
 
 @item mm-size
-Width and height in millimeters in the form of @samp{(WIDTH HEIGHT)}
+Width and height in millimeters as @samp{(@var{width} @var{height})}
 
 @item frames
-List of frames dominated by the physical monitor
+List of frames that this physical monitor dominates (see below).
 
 @item name
-Name of the physical monitor as a string
-@end table
+Name of the physical monitor as @var{string}.
 
-where X, Y, WIDTH, and HEIGHT are integers.  @samp{name} is optional.
+@item source
+Source of the multi-monitor information as @var{string};
+e.g., @samp{XRandr} or @samp{Xinerama}.
+@end table
 
-A frame is dominated by a physical monitor when either the
-largest area of the frame resides in the monitor, or the monitor
-is the closest to the frame if the frame does not intersect any
-physical monitors.  Every non-tip frame (including invisible one)
-in a graphical display is dominated by exactly one physical
-monitor at a time, though it can span multiple (or no) physical
-monitors.
+@var{x}, @var{y}, @var{width}, and @var{height} are integers.
+@samp{name} and @samp{source} may be absent.
+
+A frame is @dfn{dominated} by a physical monitor when either the
+largest area of the frame resides in that monitor, or (if the frame
+does not intersect any physical monitors) that monitor is the closest
+to the frame.  Every (non-tooltip) frame (whether visible or not) in a
+graphical display is dominated by exactly one physical monitor at a
+time, though the frame can span multiple (or no) physical monitors.
+
+Here's an example of the data produced by this function on a 2-monitor
+display:
+
+@lisp
+  (display-monitor-attributes-list)
+  @result{}
+  (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor}
+    (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height}
+    (mm-size 677 381)
+    (name . "DISPLAY1")
+    (frames #<frame emacs@@host *Messages* 0x11578c0>
+            #<frame emacs@@host *scratch* 0x114b838>))
+   ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor}
+    (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used}
+    (mm-size 593 370)
+    (name . "DISPLAY2")
+    (frames)))
+@end lisp
 
-@var{display} defaults to the selected frame's display.
 @end defun
 
 @defun frame-monitor-attributes &optional frame
 This function returns the attributes of the physical monitor
-dominating @var{frame}, which defaults to the selected frame.
-
-A frame is dominated by a physical monitor when either the
-largest area of the frame resides in the monitor, or the monitor
-is the closest to the frame if the frame does not intersect any
-physical monitors.
+dominating (see above) @var{frame}, which defaults to the selected frame.
 @end defun
 
 @node Frame Parameters
@@ -536,8 +584,9 @@ frame.  @code{title} and @code{name} are meaningful on all terminals.
 @vindex display, a frame parameter
 @item display
 The display on which to open this frame.  It should be a string of the
-form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
-@env{DISPLAY} environment variable.
+form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the
+@env{DISPLAY} environment variable.  @xref{Multiple Terminals}, for
+more details about display names.
 
 @vindex display-type, a frame parameter
 @item display-type
@@ -593,12 +642,14 @@ right screen edge.
 @item @code{(+ @var{pos})}
 This specifies the position of the left frame edge relative to the left
 screen edge.  The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen.
+negative value specifies a position outside the screen or on a monitor
+other than the primary one (for multi-monitor displays).
 
 @item @code{(- @var{pos})}
 This specifies the position of the right frame edge relative to the right
 screen edge.  The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen.
+negative value specifies a position outside the screen or on a monitor
+other than the primary one (for multi-monitor displays).
 @end table
 
 Some window managers ignore program-specified positions.  If you want to
@@ -686,6 +737,11 @@ difference between @code{maximized} and @code{fullboth} is that the
 former can still be resized by dragging window manager decorations
 with the mouse, while the latter really covers the whole screen and
 does not allow resizing by mouse dragging.
+
+With some window managers you may have to customize the variable
+@code{frame-resize-pixelwise} to a non-@code{nil} value in order to make
+a frame appear ``maximized'' or ``fullscreen''.
+
 @end table
 
 @node Layout Parameters
@@ -711,19 +767,21 @@ Whether the frame has scroll bars for vertical scrolling, and which side
 of the frame they should be on.  The possible values are @code{left},
 @code{right}, and @code{nil} for no scroll bars.
 
-@ignore
 @vindex horizontal-scroll-bars, a frame parameter
 @item horizontal-scroll-bars
-Whether the frame has scroll bars for horizontal scrolling
-(non-@code{nil} means yes).  Horizontal scroll bars are not currently
-implemented.
-@end ignore
+Whether the frame has scroll bars for horizontal scrolling (@code{t} and
+@code{bottom} mean yes, @code{nil} means no).
 
 @vindex scroll-bar-width, a frame parameter
 @item scroll-bar-width
 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
 use the default width.
 
+@vindex scroll-bar-height, a frame parameter
+@item scroll-bar-height
+The height of horizontal scroll bars, in pixels, or @code{nil} meaning
+to use the default height.
+
 @vindex left-fringe, a frame parameter
 @vindex right-fringe, a frame parameter
 @item left-fringe
@@ -737,14 +795,6 @@ these two frame parameters, the return value is always an integer.
 When using @code{set-frame-parameter}, passing a @code{nil} value
 imposes an actual default value of 8 pixels.
 
-The combined fringe widths must add up to an integral number of
-columns, so the actual default fringe widths for the frame, as
-reported by @code{frame-parameter}, may be larger than what you
-specify.  Any extra width is distributed evenly between the left and
-right fringe.  However, you can force one fringe or the other to a
-precise width by specifying that width as a negative integer.  If both
-widths are negative, only the left fringe gets the specified width.
-
 @vindex right-divider-width, a frame parameter
 @item right-divider-width
 The width (thickness) reserved for the right divider (@pxref{Window
@@ -966,7 +1016,7 @@ variable do not take effect immediately, only when you specify the
 A list of symbols, specifying the @dfn{font backends} to use for
 drawing fonts in the frame, in order of priority.  On X, there are
 currently two available font backends: @code{x} (the X core font
-driver) and @code{xft} (the Xft font driver).  On Windows, there are
+driver) and @code{xft} (the Xft font driver).  On MS-Windows, there are
 currently two available font backends: @code{gdi} and
 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
 Manual}).  On other systems, there is only one available font backend,
@@ -1158,12 +1208,15 @@ size hints to the window manager.  This means that this variable should
 be set only in a user's initial file; applications should never bind it
 temporarily.
 
-The precise semantics of a value of @code{nil} for this option depends
-on the toolkit used: Dragging the frame border with the mouse is usually
-always done character-wise.  Calling @code{set-frame-size} (see below)
+The precise meaning of a value of @code{nil} for this option depends
+on the toolkit used.  Dragging the frame border with the mouse is usually
+done character-wise.  Calling @code{set-frame-size} (see below)
 with arguments that do not specify the frame size as an integer multiple
-of its character size may be, however, either ignored or cause a
-rounding (GTK+, Windows) or get accepted (Lucid, Motif).
+of its character size, however, may: be ignored, cause a
+rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).
+
+With some window managers you may have to set this to non-@code{nil} in
+order to make a frame appear truly ``maximized'' or ``fullscreen''.
 @end defopt
 
 @defun set-frame-size frame width height pixelwise
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 91fdcc63cbe..023175e3632 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1220,15 +1220,6 @@ ways to do it.  The added function is also called an @emph{advice}.
 This macro is the handy way to add the advice @var{function} to the function
 stored in @var{place} (@pxref{Generalized Variables}).
 
-If @var{function} is not interactive, then the combined function will inherit
-the interactive spec, if any, of the original function.  Else, the combined
-function will be interactive and will use the interactive spec of
-@var{function}.  One exception: if the interactive spec of @var{function}
-is a function (rather than an expression or a string), then the interactive
-spec of the combined function will be a call to that function with as sole
-argument the interactive spec of the original function.  To interpret the spec
-received as argument, use @code{advice-eval-interactive-spec}.
-
 @var{where} determines how @var{function} is composed with the
 existing function, e.g. whether @var{function} should be called before, or
 after the original function.  @xref{Advice combinators}, for the list of
@@ -1241,7 +1232,7 @@ global value of @var{place}.  Whereas if @var{place} is of the form
 @code{(local @var{symbol})}, where @var{symbol} is an expression which returns
 the variable name, then @var{function} will only be added in the
 current buffer.  Finally, if you want to modify a lexical variable, you will
-have to use @code{(var @var{VARIABLE})}.
+have to use @code{(var @var{variable})}.
 
 Every function added with @code{add-function} can be accompanied by an
 association list of properties @var{props}.  Currently only two of those
@@ -1271,6 +1262,21 @@ original function and other advices will apply to it, whereas an outermost
 @code{:override} advice will override not only the original function but all
 other advices applied to it as well.
 @end table
+
+If @var{function} is not interactive, then the combined function will inherit
+the interactive spec, if any, of the original function.  Else, the combined
+function will be interactive and will use the interactive spec of
+@var{function}.  One exception: if the interactive spec of @var{function}
+is a function (rather than an expression or a string), then the interactive
+spec of the combined function will be a call to that function with as sole
+argument the interactive spec of the original function.  To interpret the spec
+received as argument, use @code{advice-eval-interactive-spec}.
+
+Note: The interactive spec of @var{function} will apply to the combined
+function and should hence obey the calling convention of the combined function
+rather than that of @var{function}.  In many cases, it makes no difference
+since they are identical, but it does matter for @code{:around},
+@code{:filter-args}, and @code{filter-return}, where @var{function}.
 @end defmac
 
 @defmac remove-function place function
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 3d85b474d4b..db6ed41268c 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -14,6 +14,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
 * Building Emacs::      How the dumped Emacs is made.
 * Pure Storage::        Kludge to make preloaded Lisp functions shareable.
 * Garbage Collection::  Reclaiming space for Lisp objects no longer used.
+* Stack-allocated Objects::    Temporary conses and strings on C stack.
 * Memory Usage::        Info about total size of Lisp objects made so far.
 * C Dialect::           What C variant Emacs is written in.
 * Writing Emacs Primitives::   Writing C code for Emacs.
@@ -529,6 +530,35 @@ during garbage collection so far in this Emacs session, as a
 floating-point number.
 @end defvar
 
+@node Stack-allocated Objects
+@section Stack-allocated Objects
+
+@cindex stack allocated Lisp objects
+@cindex Lisp objects, stack-allocated
+  The garbage collector described above is used to manage data visible
+from Lisp programs, as well as most of the data internally used by the
+Lisp interpreter.  Sometimes it may be useful to allocate temporary
+internal objects using the C stack of the interpreter.  This can help
+performance, as stack allocation is typically faster than using heap
+memory to allocate and the garbage collector to free.  The downside is
+that using such objects after they are freed results in undefined
+behavior, so uses should be well thought out and carefully debugged by
+using the @code{GC_CHECK_MARKED_OBJECTS} feature (see
+@file{src/alloc.c}).  In particular, stack-allocated objects should
+never be made visible to user Lisp code.
+
+  Currently, cons cells and strings can be allocated this way.  This
+is implemented by C macros like @code{AUTO_CONS} and
+@code{AUTO_STRING} that define a named @code{Lisp_Object} with block
+lifetime.  These objects are not freed by the garbage collector;
+instead, they have automatic storage duration, i.e., they are
+allocated like local variables and are automatically freed at the end
+of execution of the C block that defined the object.
+
+  For performance reasons, stack-allocated strings are limited to
+@acronym{ASCII} characters, and many of these strings are immutable,
+i.e., calling @code{ASET} on them produces undefined behavior.
+
 @node Memory Usage
 @section Memory Usage
 @cindex memory usage
@@ -1595,6 +1625,8 @@ of @code{intptr_t}).
 
 @item
 Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF.
+More generally, prefer @code{int} for integers known to be in
+@code{int} range, e.g., screen column counts.
 
 @item
 Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the
@@ -1606,6 +1638,17 @@ anyway since they would break pointer subtraction, so this does not
 impose an arbitrary limit.
 
 @item
+Avoid @code{ssize_t} except when communicating to low-level APIs that
+have @code{ssize_t}-related limitations.  Although it's equivalent to
+@code{ptrdiff_t} on typical platforms, @code{ssize_t} is occasionally
+narrower, so using it for size-related calculations could overflow.
+Also, @code{ptrdiff_t} is more ubiquitous and better-standardized, has
+standard @code{printf} formats, and is the basis for Emacs's internal
+size-overflow checking.  When using @code{ssize_t}, please note that
+POSIX requires support only for values in the range @minus{}1 ..@:
+@code{SSIZE_MAX}.
+
+@item
 Prefer @code{intptr_t} for internal representations of pointers, or
 for integers bounded only by the number of objects that can exist at
 any given time or by the total number of bytes that can be allocated.
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index f724d5bd902..21be5cca4fc 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1124,74 +1124,6 @@ each time you run it!  Here is what happens:
 @end smallexample
 @end defun
 
-@defun sort list predicate
-@cindex stable sort
-@cindex sorting lists
-This function sorts @var{list} stably, though destructively, and
-returns the sorted list.  It compares elements using @var{predicate}.  A
-stable sort is one in which elements with equal sort keys maintain their
-relative order before and after the sort.  Stability is important when
-successive sorts are used to order elements according to different
-criteria.
-
-The argument @var{predicate} must be a function that accepts two
-arguments.  It is called with two elements of @var{list}.  To get an
-increasing order sort, the @var{predicate} should return non-@code{nil} if the
-first element is ``less than'' the second, or @code{nil} if not.
-
-The comparison function @var{predicate} must give reliable results for
-any given pair of arguments, at least within a single call to
-@code{sort}.  It must be @dfn{antisymmetric}; that is, if @var{a} is
-less than @var{b}, @var{b} must not be less than @var{a}.  It must be
-@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
-is less than @var{c}, then @var{a} must be less than @var{c}.  If you
-use a comparison function which does not meet these requirements, the
-result of @code{sort} is unpredictable.
-
-The destructive aspect of @code{sort} is that it rearranges the cons
-cells forming @var{list} by changing @sc{cdr}s.  A nondestructive sort
-function would create new cons cells to store the elements in their
-sorted order.  If you wish to make a sorted copy without destroying the
-original, copy it first with @code{copy-sequence} and then sort.
-
-Sorting does not change the @sc{car}s of the cons cells in @var{list};
-the cons cell that originally contained the element @code{a} in
-@var{list} still has @code{a} in its @sc{car} after sorting, but it now
-appears in a different position in the list due to the change of
-@sc{cdr}s.  For example:
-
-@example
-@group
-(setq nums '(1 3 2 6 5 4 0))
-     @result{} (1 3 2 6 5 4 0)
-@end group
-@group
-(sort nums '<)
-     @result{} (0 1 2 3 4 5 6)
-@end group
-@group
-nums
-     @result{} (1 2 3 4 5 6)
-@end group
-@end example
-
-@noindent
-@strong{Warning}: Note that the list in @code{nums} no longer contains
-0; this is the same cons cell that it was before, but it is no longer
-the first one in the list.  Don't assume a variable that formerly held
-the argument now holds the entire sorted list!  Instead, save the result
-of @code{sort} and use that.  Most often we store the result back into
-the variable that held the original list:
-
-@example
-(setq nums (sort nums '<))
-@end example
-
-@xref{Sorting}, for more functions that perform sorting.
-See @code{documentation} in @ref{Accessing Documentation}, for a
-useful example of @code{sort}.
-@end defun
-
 @node Sets And Lists
 @section Using Lists as Sets
 @cindex lists as sets
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index e23e2685a7c..d67bac63b15 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2221,13 +2221,10 @@ is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
 It is normally @code{nil}, so that ordinary buffers have no header line.
 @end defvar
 
-The function @code{window-header-line-height} returns the height of
-the header line:
-
 @defun window-header-line-height &optional window
-Return the height of @var{window}'s header line, in pixels.
-@var{window} must be a live window.  If @var{window} is @code{nil} or
-omitted, it will be the selected window.
+This function returns the height in pixels of @var{window}'s header
+line.  @var{window} must be a live window, and defaults to the
+selected window.
 @end defun
 
   A window that is just one line tall never displays a header line.  A
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 8f17862d427..d3a6792c1ba 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -327,6 +327,98 @@ encouraged to treat strings as immutable.
 
 @end defun
 
+@defun sort sequence predicate
+@cindex stable sort
+@cindex sorting lists
+@cindex sorting vectors
+This function sorts @var{sequence} stably.  Note that this function doesn't work
+for all sequences; it may be used only for lists and vectors.  If @var{sequence}
+is a list, it is modified destructively.  This functions returns the sorted
+@var{sequence} and compares elements using @var{predicate}.  A stable sort is
+one in which elements with equal sort keys maintain their relative order before
+and after the sort.  Stability is important when successive sorts are used to
+order elements according to different criteria.
+
+The argument @var{predicate} must be a function that accepts two
+arguments.  It is called with two elements of @var{sequence}.  To get an
+increasing order sort, the @var{predicate} should return non-@code{nil} if the
+first element is ``less than'' the second, or @code{nil} if not.
+
+The comparison function @var{predicate} must give reliable results for
+any given pair of arguments, at least within a single call to
+@code{sort}.  It must be @dfn{antisymmetric}; that is, if @var{a} is
+less than @var{b}, @var{b} must not be less than @var{a}.  It must be
+@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
+is less than @var{c}, then @var{a} must be less than @var{c}.  If you
+use a comparison function which does not meet these requirements, the
+result of @code{sort} is unpredictable.
+
+The destructive aspect of @code{sort} for lists is that it rearranges the
+cons cells forming @var{sequence} by changing @sc{cdr}s.  A nondestructive
+sort function would create new cons cells to store the elements in their
+sorted order.  If you wish to make a sorted copy without destroying the
+original, copy it first with @code{copy-sequence} and then sort.
+
+Sorting does not change the @sc{car}s of the cons cells in @var{sequence};
+the cons cell that originally contained the element @code{a} in
+@var{sequence} still has @code{a} in its @sc{car} after sorting, but it now
+appears in a different position in the list due to the change of
+@sc{cdr}s.  For example:
+
+@example
+@group
+(setq nums '(1 3 2 6 5 4 0))
+     @result{} (1 3 2 6 5 4 0)
+@end group
+@group
+(sort nums '<)
+     @result{} (0 1 2 3 4 5 6)
+@end group
+@group
+nums
+     @result{} (1 2 3 4 5 6)
+@end group
+@end example
+
+@noindent
+@strong{Warning}: Note that the list in @code{nums} no longer contains
+0; this is the same cons cell that it was before, but it is no longer
+the first one in the list.  Don't assume a variable that formerly held
+the argument now holds the entire sorted list!  Instead, save the result
+of @code{sort} and use that.  Most often we store the result back into
+the variable that held the original list:
+
+@example
+(setq nums (sort nums '<))
+@end example
+
+For the better understanding of what stable sort is, consider the following
+vector example.  After sorting, all items whose @code{car} is 8 are grouped
+at the beginning of @code{vector}, but their relative order is preserved.
+All items whose @code{car} is 9 are grouped at the end of @code{vector},
+but their relative order is also preserved:
+
+@example
+@group
+(setq
+  vector
+  (vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz")
+          '(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff")))
+     @result{} [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz")
+         (9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")]
+@end group
+@group
+(sort vector (lambda (x y) (< (car x) (car y))))
+     @result{} [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee")
+         (9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")]
+@end group
+@end example
+                
+@xref{Sorting}, for more functions that perform sorting.
+See @code{documentation} in @ref{Accessing Documentation}, for a
+useful example of @code{sort}.
+@end defun
+
 @node Arrays
 @section Arrays
 @cindex array
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index 1d549ae8916..c287b617713 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -615,10 +615,13 @@ spacing between calls.
 @end example
 @end defun
 
-@defun terpri &optional stream
+@defun terpri &optional stream ensure
 @cindex newline in print
-This function outputs a newline to @var{stream}.  The name stands
-for ``terminate print''.
+This function outputs a newline to @var{stream}.  The name stands for
+``terminate print''.  If @var{ensure} is non-nil no newline is printed
+if @var{stream} is already at the beginning of a line.  Note in this
+case @var{stream} can not be a function and an error is signalled if
+it is.  This function returns @code{t} if a newline is printed.
 @end defun
 
 @defun write-char character &optional stream
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index e6b00f06f79..5e0148b75a9 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -458,6 +458,59 @@ Representations}.
 @code{string-equal} is another name for @code{string=}.
 @end defun
 
+@defun string-collate-equalp string1 string2 &optional locale ignore-case
+This function returns @code{t} if @var{string1} and @var{string2} are
+equal with respect to collation rules.  A collation rule is not only
+determined by the lexicographic order of the characters contained in
+@var{string1} and @var{string2}, but also further rules about
+relations between these characters.  Usually, it is defined by the
+@var{locale} environment Emacs is running with.
+
+For example, characters with different coding points but
+the same meaning might be considered as equal, like different grave
+accent Unicode characters:
+
+@example
+@group
+(string-collate-equalp (string ?\uFF40) (string ?\u1FEF))
+     @result{} t
+@end group
+@end example
+
+The optional argument @var{locale}, a string, overrides the setting of
+your current locale identifier for collation.  The value is system
+dependent; a @var{locale} "en_US.UTF-8" is applicable on POSIX
+systems, while it would be, e.g., "enu_USA.1252" on MS-Windows
+systems.
+
+If @var{IGNORE-CASE} is non-nil, characters are converted to lower-case
+before comparing them.
+
+To emulate Unicode-compliant collation on MS-Windows systems,
+bind @code{w32-collate-ignore-punctuation} to a non-nil value, since
+the codeset part of the locale cannot be "UTF-8" on MS-Windows.
+
+If your system does not support a locale environment, this function
+behaves like @code{string-equal}.
+
+Do NOT use this function to compare file names for equality, only
+for sorting them.
+@end defun
+
+@defun string-prefix-p string1 string2 &optional ignore-case
+This function returns non-@code{nil} if @var{string1} is a prefix of
+@var{string2}; i.e., if @var{string2} starts with @var{string1}.  If
+the optional argument @var{ignore-case} is non-@code{nil}, the
+comparison ignores case differences.
+@end defun
+
+@defun string-suffix-p suffix string &optional ignore-case
+This function returns non-@code{nil} if @var{suffix} is a suffix of
+@var{string}; i.e., if @var{string} ends with @var{suffix}.  If the
+optional argument @var{ignore-case} is non-@code{nil}, the comparison
+ignores case differences.
+@end defun
+
 @cindex lexical comparison
 @defun string< string1 string2
 @c (findex string< causes problems for permuted index!!)
@@ -516,6 +569,50 @@ are used.
 @code{string-lessp} is another name for @code{string<}.
 @end defun
 
+@defun string-collate-lessp string1 string2 &optional locale ignore-case
+This function returns @code{t} if @var{string1} is less than
+@var{string2} in collation order.  A collation order is not only
+determined by the lexicographic order of the characters contained in
+@var{string1} and @var{string2}, but also further rules about
+relations between these characters.  Usually, it is defined by the
+@var{locale} environment Emacs is running with.
+
+For example, punctuation and whitespace characters might be considered
+less significant for @ref{Sorting,,sorting}.
+
+@example
+@group
+(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp)
+     @result{} ("11" "1 1" "1.1" "12" "1 2" "1.2")
+@end group
+@end example
+
+The optional argument @var{locale}, a string, overrides the setting of
+your current locale identifier for collation.  The value is system
+dependent; a @var{locale} "en_US.UTF-8" is applicable on POSIX
+systems, while it would be, e.g., "enu_USA.1252" on MS-Windows
+systems.  The @var{locale} "POSIX" lets @code{string-collate-lessp}
+behave like @code{string-lessp}:
+
+@example
+@group
+(sort '("11" "12" "1 1" "1 2" "1.1" "1.2")
+      (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX")))
+     @result{} ("1 1" "1 2" "1.1" "1.2" "11" "12")
+@end group
+@end example
+
+If @var{IGNORE-CASE} is non-nil, characters are converted to lower-case
+before comparing them.
+
+To emulate Unicode-compliant collation on MS-Windows systems,
+bind @code{w32-collate-ignore-punctuation} to a non-nil value, since
+the codeset part of the locale cannot be "UTF-8" on MS-Windows.
+
+If your system does not support a locale environment, this function
+behaves like @code{string-lessp}.
+@end defun
+
 @defun string-prefix-p string1 string2 &optional ignore-case
 This function returns non-@code{nil} if @var{string1} is a prefix of
 @var{string2}; i.e., if @var{string2} starts with @var{string1}.  If
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6665cc3e673..f21d2b76656 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4114,8 +4114,9 @@ buffer.
 Normally, this command puts point before the inserted text, and the
 mark after it.  However, if the optional second argument @var{beforep}
 is non-@code{nil}, it puts the mark before and point after.
-You can pass a non-@code{nil} second argument @var{beforep} to this
-function interactively by supplying any prefix argument.
+
+When called interactively, the command defaults to putting point after
+text, and a prefix argument inverts this behavior.
 
 If the register contains a rectangle, then the rectangle is inserted
 with its upper left corner at point.  This means that text is inserted
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index f2fe5c85a93..5060fef804f 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -394,13 +394,14 @@ internal window).  The @var{edges} element is a list @code{(@var{left}
 @group
         ____________________________________________
        |______________ Header Line ______________|RD| ^
-     ^ |LS|LF|LM|                       |RM|RF|RS|  | |
+     ^ |LS|LM|LF|                       |RF|RM|RS|  | |
      | |  |  |  |                       |  |  |  |  | |
 Window |  |  |  |       Text Area       |  |  |  |  | Window
 Body | |  |  |  |     (Window Body)     |  |  |  |  | Total
 Height |  |  |  |                       |  |  |  |  | Height
      | |  |  |  |<- Window Body Width ->|  |  |  |  | |
      v |__|__|__|_______________________|__|__|__|  | |
+       |_________ Horizontal Scroll Bar _________|  | |
        |_______________ Mode Line _______________|__| |
        |_____________ Bottom Divider _______________| v
         <---------- Window Total Width ------------>
@@ -414,15 +415,15 @@ Height |  |  |  |                       |  |  |  |  | Height
   At the center of the window is the @dfn{text area}, or @dfn{body},
 where the buffer text is displayed.  The text area can be surrounded by
 a series of optional areas.  On the left and right, from innermost to
-outermost, these are the left and right margins, denoted by LM and RM in
-the schematic (@pxref{Display Margins}); the left and right fringes,
-denoted by LF and RF (@pxref{Fringes}); the left or right scroll bar,
-only one of which is present at any time, denoted by LS and RS
-(@pxref{Scroll Bars}); and the right divider, denoted by RD
+outermost, these are the left and right fringes, denoted by LF and RF
+(@pxref{Fringes}); the left and right margins, denoted by LM and RM in
+the schematic (@pxref{Display Margins}); the left or right vertical
+scroll bar, only one of which is present at any time, denoted by LS and
+RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
 (@pxref{Window Dividers}).  At the top of the window is the header line
-(@pxref{Header Lines}); at the bottom of the window is the mode line
-(@pxref{Mode Line Format}) followed by the bottom divider (@pxref{Window
-Dividers}).
+(@pxref{Header Lines}).  At the bottom of the window are the horizontal
+scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
+Format}); and the bottom divider (@pxref{Window Dividers}).
 
   Emacs provides miscellaneous functions for finding the height and
 width of a window.  The return value of many of these functions can be
@@ -439,11 +440,8 @@ displayed within it.
 @cindex height of a window
 @cindex total height of a window
   The @dfn{total height} of a window is the number of lines comprising
-the window's body, the header line, the mode line and the bottom divider
-(if any).  Note that the height of a frame is not the same as the height
-of its root window (@pxref{Windows and Frames}), since a frame may also
-contain an echo area, a menu bar, and a tool bar (@pxref{Size and
-Position}).
+the window's body, the header line, the horizontal scroll bar, the mode
+line and the bottom divider (if any).
 
 @defun window-total-height &optional window round
 This function returns the total height, in lines, of the window
@@ -451,24 +449,23 @@ This function returns the total height, in lines, of the window
 the selected window.  If @var{window} is an internal window, the return
 value is the total height occupied by its descendant windows.
 
-   If a window's pixel height is not an integral multiple of its frame's
+  If a window's pixel height is not an integral multiple of its frame's
 default character height, the number of lines occupied by the window is
 rounded internally.  This is done in a way such that, if the window is a
 parent window, the sum of the total heights of all its child windows
 internally equals the total height of their parent.  This means that
 although two windows have the same pixel height, their internal total
-heights may differ by one line.  This means also, that if this window is
-vertically combined and has a right sibling, the topmost row of that
+heights may differ by one line.  This means also, that if window is
+vertically combined and has a next sibling, the topmost row of that
 sibling can be calculated as the sum of this window's topmost row and
 total height (@pxref{Coordinates and Windows})
 
-   If the optional argument @var{round} equals @code{ceiling}, this
+  If the optional argument @var{round} is @code{ceiling}, this
 function returns the smallest integer larger than @var{window}'s pixel
-height divided by the character height of @var{window}'s frame; if it is
-@code{floor}, it returns the largest integer smaller than @var{window}'s
-pixel height divided by the character height of @var{window}'s frame.
-Any other value of @var{round} means to return the internal value of the
-total height of @var{window}.
+height divided by the character height of its frame; if it is
+@code{floor}, it returns the largest integer smaller than said value;
+with any other @var{round} it returns the internal value of
+@var{windows}'s total height.
 @end defun
 
 @cindex window width
@@ -484,24 +481,17 @@ This function returns the total width, in columns, of the window
 the selected window.  If @var{window} is internal, the return value is
 the total width occupied by its descendant windows.
 
-   If a window's pixel width is not an integral multiple of its frame's
+  If a window's pixel width is not an integral multiple of its frame's
 character width, the number of lines occupied by the window is rounded
 internally.  This is done in a way such that, if the window is a parent
 window, the sum of the total widths of all its children internally
 equals the total width of their parent.  This means that although two
 windows have the same pixel width, their internal total widths may
 differ by one column.  This means also, that if this window is
-horizontally combined and has a right sibling, the leftmost column of
+horizontally combined and has a next sibling, the leftmost column of
 that sibling can be calculated as the sum of this window's leftmost
-column and total width (@pxref{Coordinates and Windows}).
-
-If the optional argument @var{round} is @code{ceiling}, this function
-will return the smallest integer larger than @var{window}'s pixel width
-divided by the character width of @var{window}'s frame; if it is
-@code{floor}, it returns the largest integer smaller than @var{window}'s
-pixel width divided by the character width of @var{window}'s frame.  Any
-other value of @var{round} means to return the internal total width of
-@var{window}.
+column and total width (@pxref{Coordinates and Windows}).  The optional
+argument @var{round} behaves as it does for @code{window-total-height}.
 @end defun
 
 @defun window-total-size &optional window horizontal round
@@ -510,8 +500,7 @@ width in columns of the window @var{window}.  If @var{horizontal} is
 omitted or @code{nil}, this is equivalent to calling
 @code{window-total-height} for @var{window}; otherwise it is equivalent
 to calling @code{window-total-width} for @var{window}.  The optional
-argument @code{ROUND} is handled as for @code{window-total-height} and
-@code{window-total-width}.
+argument @var{round} behaves as it does for @code{window-total-height}.
 @end defun
 
 The following two functions can be used to return the total size of a
@@ -525,9 +514,10 @@ window in units of pixels.
 This function returns the total height of window @var{window} in pixels.
 @var{window} must be a valid window and defaults to the selected one.
 
-The return value includes mode and header line and a bottom divider, if
-any.  If @var{window} is an internal window, its pixel height is the
-pixel height of the screen areas spanned by its children.
+The return value includes mode and header line, a horizontal scroll bar
+and a bottom divider, if any.  If @var{window} is an internal window,
+its pixel height is the pixel height of the screen areas spanned by its
+children.
 @end defun
 
 @cindex window pixel height
@@ -550,10 +540,12 @@ the screen areas spanned by its children.
 window has any adjacent windows.
 
 @defun window-full-height-p &optional window
-This function returns non-@code{nil} if @var{window} has no other
-window above or below it in its frame, i.e., its total height equals
-the total height of the root window on that frame.  If @var{window} is
-omitted or @code{nil}, it defaults to the selected window.
+This function returns non-@code{nil} if @var{window} has no other window
+above or below it in its frame.  More precisely, this means that the
+total height of @var{window} equals the total height of the root window
+on that frame.  The minibuffer window does not count in this regard.  If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window.
 @end defun
 
 @defun window-full-width-p &optional window
@@ -567,7 +559,8 @@ that of the root window on that frame.  If @var{window} is omitted or
 @cindex body height of a window
 @cindex window body width
 The @dfn{body height} of a window is the height of its text area, which
-does not include a mode or header line or a bottom divider.
+does not include a mode or header line, a horizontal scroll bar, or a
+bottom divider.
 
 @defun window-body-height &optional window pixelwise
 This function returns the height, in lines, of the body of window
@@ -654,7 +647,8 @@ size:
 @defopt window-min-height
 This option specifies the minimum total height, in lines, of any window.
 Its value has to accommodate at least one text line as well as a mode
-and header line and a bottom divider, if present.
+and header line, a horizontal scroll bar and a bottom divider, if
+present.
 @end defopt
 
 @defopt window-min-width
@@ -693,10 +687,11 @@ of @var{window}'s lines.
 
 The return value makes sure that all components of @var{window} remain
 fully visible if @var{window}'s size were actually set to it.  With
-@var{horizontal} @code{nil} it includes the mode and header line and the
-bottom divider.  With @var{horizontal} non-@code{nil} it includes the
-fringes, a scroll bar, and a right divider, if present.  It does not,
-however, include the space reserved for the margins.
+@var{horizontal} @code{nil} it includes the mode and header line, the
+horizontal scroll bar and the bottom divider.  With @var{horizontal}
+non-@code{nil} it includes the fringes, a scroll bar, and a right
+divider, if present.  It does not, however, include the space reserved
+for the margins.
 
 The optional argument @var{ignore}, if non-@code{nil}, means ignore
 restrictions imposed by fixed size windows, @code{window-min-height} or
@@ -748,14 +743,14 @@ Normally, the variables @code{window-min-height} and
 (@pxref{Window Sizes}).  However, if the optional argument @var{ignore}
 is non-@code{nil}, this function ignores @code{window-min-height} and
 @code{window-min-width}, as well as @code{window-size-fixed}.  Instead,
-it considers the minimum-height window to be one consisting of a header,
-a mode line and a bottom divider (if any), plus a text area one line
-tall; and a minimum-width window as one consisting of fringes, margins,
-a scroll bar and a right divider (if any), plus a text area two columns
-wide.
+it considers the minimum-height window to be one consisting of a header
+and a mode line, a horizontal scrollbar and a bottom divider (if any),
+plus a text area one line tall; and a minimum-width window as one
+consisting of fringes, margins, a scroll bar and a right divider (if
+any), plus a text area two columns wide.
 
-If the optional argument @code{pixelwise} is non-@code{nil},
-@var{delta} will be interpreted as pixels.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
 @end defun
 
 @defun window-resize window delta &optional horizontal ignore pixelwise
@@ -779,7 +774,7 @@ values of the option @code{window-combination-resize} and the
 combination limits of the involved windows; in some cases, it may alter
 both edges.  @xref{Recombining Windows}.  To resize by moving only the
 bottom or right edge of a window, use the function
-@code{adjust-window-trailing-edge}, below.
+@code{adjust-window-trailing-edge}.
 @end defun
 
 @c The commands enlarge-window, enlarge-window-horizontally,
@@ -792,8 +787,8 @@ If optional argument @var{horizontal} is non-@code{nil}, it instead
 moves the right edge by @var{delta} columns.  If @var{window} is
 @code{nil}, it defaults to the selected window.
 
-If the optional argument @code{pixelwise} is non-@code{nil},
-@var{delta} will be interpreted as pixels.
+If the optional argument @var{pixelwise} is non-@code{nil},
+@var{delta} is interpreted as pixels.
 
 A positive @var{delta} moves the edge downwards or to the right; a
 negative @var{delta} moves it upwards or to the left.  If the edge
@@ -807,17 +802,16 @@ window is fixed-size), it may resize other windows.
 
 @cindex pixelwise, resizing windows
 @defopt window-resize-pixelwise
-If the value of this option is non-@code{nil}, windows are resized in
+If the value of this option is non-@code{nil}, Emacs resizes windows in
 units of pixels.  This currently affects functions like
 @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
 @code{minimize-window}, @code{fit-window-to-buffer},
 @code{shrink-window-if-larger-than-buffer} (all listed below) and
 @code{fit-frame-to-buffer} (@pxref{Size and Position}).
 
-Note that when a frame's pixel size is not a multiple of the frame's
-character size, at least one window may get resized pixelwise even if
-this option is @code{nil}.  The default value of this option is
-@code{nil}.
+Note that when a frame's pixel size is not a multiple of its character
+size, at least one window may get resized pixelwise even if this
+option is @code{nil}.  The default value is @code{nil}.
 @end defopt
 
   The following commands resize windows in more specific ways.  When