Merge branch 'master' into scratch/org-mode-merge

13 files changed, 668 insertions, 190 deletions

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 22b0fcd4676..28cb51d88bb 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -875,27 +875,33 @@ treat it specially.
 
 @item
 Otherwise, if the command string contains @samp{?} surrounded by
-whitespace, Emacs runs the shell command once @emph{for each file},
-substituting the current file name for @samp{?} each time.  You can
-use @samp{?} more than once in the command; the same file name
-replaces each occurrence.
+whitespace or @samp{`?`}, Emacs runs the shell command once
+@emph{for each file}, substituting the current file name for @samp{?}
+and @samp{`?`} each time.  You can use both @samp{?} or @samp{`?`} more
+than once in the command; the same file name replaces each occurrence.
+If you mix them with @samp{*} the command signals an error.
 
 @item
-If the command string contains neither @samp{*} nor @samp{?}, Emacs
-runs the shell command once for each file, adding the file name at the
+If the command string contains neither @samp{*} nor @samp{?} nor @samp{`?`},
+Emacs runs the shell command once for each file, adding the file name at the
 end.  For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on
 each file.
 @end itemize
 
-  To iterate over the file names in a more complicated fashion, use an
-explicit shell loop.  For example, here is how to uuencode each file,
-making the output file name by appending @samp{.uu} to the input file
-name:
+  To iterate over the file names in a more complicated fashion, you might
+prefer to use an explicit shell loop.  For example, here is how to uuencode
+each file, making the output file name by appending @samp{.uu} to the input
+file name:
 
 @example
 for file in * ; do uuencode "$file" "$file" >"$file".uu; done
 @end example
 
+The same example with @samp{`?`} notation:
+@example
+uuencode ? ? > `?`.uu
+@end example
+
   The @kbd{!} and @kbd{&} commands do not attempt to update the Dired
 buffer to show new or modified files, because they don't know what
 files will be changed.  Use the @kbd{g} command to update the Dired
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 548ca6a1b48..fd6df1c7e53 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -203,9 +203,10 @@ string}, which describes exactly what the command does.
 describes the command corresponding to @var{key}.
 
   @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key
-sequences, including function keys, menus, and mouse events.  For
-instance, after @kbd{C-h k} you can select a menu item from the menu
-bar, to view the documentation string of the command it runs.
+sequences, including function keys, menus, and mouse events (except
+that @kbd{C-h c} ignores mouse movement events).  For instance, after
+@kbd{C-h k} you can select a menu item from the menu bar, to view the
+documentation string of the command it runs.
 
 @kindex C-h w
 @findex where-is
diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi
index 47de0531292..0b5efd04a18 100644
--- a/doc/emacs/killing.texi
+++ b/doc/emacs/killing.texi
@@ -519,6 +519,10 @@ when exiting Emacs; if you wish to prevent Emacs from transferring
 data to the clipboard manager, change the variable
 @code{x-select-enable-clipboard-manager} to @code{nil}.
 
+  Since strings containing NUL bytes are usually truncated when passed
+through the clipboard, Emacs replaces such characters with ``\0''
+before transfering them to the system's clipboard.
+
 @vindex select-enable-primary
 @findex clipboard-kill-region
 @findex clipboard-kill-ring-save
diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index 13407f6f07b..8edf2640cfe 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -1795,8 +1795,12 @@ of the first character you read precedes that of the next character.
 Reordering of bidirectional text into the @dfn{visual} order happens
 at display time.  As result, character positions no longer increase
 monotonically with their positions on display.  Emacs implements the
-Unicode Bidirectional Algorithm described in the Unicode Standard
-Annex #9, for reordering of bidirectional text for display.
+Unicode Bidirectional Algorithm (UBA) described in the Unicode
+Standard Annex #9, for reordering of bidirectional text for display.
+It deviates from the UBA only in how continuation lines are displayed
+when text direction is opposite to the base paragraph direction,
+e.g. when a long line of English text appears in a right-to-left
+paragraph.
 
 @vindex bidi-display-reordering
   The buffer-local variable @code{bidi-display-reordering} controls
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 4de55fd3fb2..2ebe872c362 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1974,6 +1974,71 @@ line, if present, in the return value.  If it is @code{t}, include the
 height of both, if present, in the return value.
 @end defun
 
+@code{window-text-pixel-size} treats the text displayed in a window as a
+whole and does not care about the size of individual lines.  The
+following function does.
+
+@defun window-lines-pixel-dimensions &optional window first last body inverse
+This function calculates the pixel dimensions of each line displayed in
+the specified @var{window}.  It does so by walking @var{window}'s
+current glyph matrix---a matrix storing the glyph (@pxref{Glyphs}) of
+each buffer character currently displayed in @var{window}.  If
+successful, it returns a list of cons pairs representing the x- and
+y-coordinates of the lower right corner of the last character of each
+line.  Coordinates are measured in pixels from an origin (0, 0) at the
+top-left corner of @var{window}.  @var{window} must be a live window and
+defaults to the selected one.
+
+If the optional argument @var{first} is an integer, it denotes the index
+(starting with 0) of the first line of @var{window}'s glyph matrix to be
+returned.  Note that if @var{window} has a header line, the line with
+index 0 is that header line.  If @var{first} is nil, the first line to
+be considered is determined by the value of the optional argument
+@var{body}: If @var{body} is non-@code{nil}, this means to start with
+the first line of @var{window}'s body, skipping any header line, if
+present.  Otherwise, this function will start with the first line of
+@var{window}'s glyph matrix, possibly the header line.
+
+If the optional argument @var{last} is an integer, it denotes the index
+of the last line of @var{window}'s glyph matrix that shall be returned.
+If @var{last} is nil, the last line to be considered is determined by
+the value of @var{body}: If @var{body} is non-@code{nil}, this means to
+use the last line of @var{window}'s body, omitting @var{window}'s mode
+line, if present.  Otherwise, this means to use the last line of
+@var{window} which may be the mode line.
+
+The optional argument @var{inverse}, if @code{nil}, means that the
+y-pixel value returned for any line specifies the distance in pixels
+from the left edge (body edge if @var{body} is non-@code{nil}) of
+@var{window} to the right edge of the last glyph of that line.
+@var{inverse} non-@code{nil} means that the y-pixel value returned for
+any line specifies the distance in pixels from the right edge of the
+last glyph of that line to the right edge (body edge if @var{body} is
+non-@code{nil}) of @var{window}.  This is useful for determining the
+amount of slack space at the end of each line.
+
+The optional argument @var{left}, if non-@code{nil} means to return the
+x- and y-coordinates of the lower left corner of the leftmost character
+on each line.  This is the value that should be used for windows that
+mostly display text from right to left.
+
+If @var{left} is non-@code{nil} and @var{inverse} is @code{nil}, this
+means that the y-pixel value returned for any line specifies the
+distance in pixels from the left edge of the last (leftmost) glyph of
+that line to the right edge (body edge if @var{body} is non-@code{nil})
+of @var{window}.  If @var{left} and @var{inverse} are both
+non-@code{nil}, the y-pixel value returned for any line specifies the
+distance in pixels from the left edge (body edge if @var{body} is
+non-@code{nil}) of @var{window} to the left edge of the last (leftmost)
+glyph of that line.
+
+This function returns @code{nil} if the current glyph matrix of
+@var{window} is not up-to-date which usually happens when Emacs is busy,
+for example, when processing a command.  The value should be retrievable
+though when this function is run from an idle timer with a delay of zero
+seconds.
+@end defun
+
 @defun line-pixel-height
 This function returns the height in pixels of the line at point in the
 selected window.  The value includes the line spacing of the line
@@ -7297,7 +7362,11 @@ follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}),
 which is described in Annex #9 of the Unicode standard
 (@url{http://www.unicode.org/reports/tr9/}).  Emacs provides a ``Full
 Bidirectionality'' class implementation of the @acronym{UBA},
-consistent with the requirements of the Unicode Standard v8.0.
+consistent with the requirements of the Unicode Standard v9.0.  Note,
+however, that the way Emacs displays continuation lines when text
+direction is opposite to the base paragraph direction deviates from
+the UBA, which requires to perform line wrapping before reordering
+text for display.
 
 @defvar bidi-display-reordering
 If the value of this buffer-local variable is non-@code{nil} (the
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 7cc91a8f7e3..4bedea3bdd1 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1130,6 +1130,8 @@ Window Frame Parameters
 * Buffer Parameters::       Which buffers have been or should be shown.
 * Frame Interaction Parameters::  Parameters for interacting with other
                               frames.
+* Mouse Dragging Parameters::  Parameters for resizing and moving
+                              frames with the mouse.
 * Management Parameters::   Communicating with the window manager.
 * Cursor Parameters::       Controlling the cursor appearance.
 * Font and Color Parameters:: Fonts and colors for the frame text.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 50467d1dfd5..b430f7c6fad 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -974,14 +974,7 @@ Parameters}).  The text size of the initial frame can be also set with
 the help of an X-style geometry specification.  @xref{Emacs Invocation,,
 Command Line Arguments for Emacs Invocation, emacs, The GNU Emacs
 Manual}.  Below we list some functions to access and set the size of an
-existing, visible frame.
-
-@defun frame-text-height &optional frame
-@defunx frame-text-width &optional frame
-These functions return the height and width of the text area of
-@var{frame} (@pxref{Frame Layout}), measured in pixels.  For a text
-terminal, the results are in characters rather than pixels.
-@end defun
+existing, visible frame, by default the selected one.
 
 @defun frame-height &optional frame
 @defunx frame-width &optional frame
@@ -997,11 +990,33 @@ rounded down to the number of characters of the default font that fully
 fit into the text area.
 @end defun
 
-@defun frame-pixel-height &optional frame
-@defunx frame-pixel-width &optional frame
-These functions return the native width and height, see @ref{Frame
-Layout}) of @var{frame} in pixels.  For a text terminal, the results are
-in characters rather than pixels.
+The functions following next return the pixel widths and heights of the
+native, outer and inner frame and the text area (@pxref{Frame Layout})
+of a given frame.  For a text terminal, the results are in characters
+rather than pixels.
+
+@defun frame-outer-width &optional frame
+@defunx frame-outer-height &optional frame
+These functions return the outer width and height of @var{frame} in
+pixels.
+@end defun
+
+@defun frame-native-height &optional frame
+@defunx frame-native-width &optional frame
+These functions return the native width and height of @var{frame} in
+pixels.
+@end defun
+
+@defun frame-inner-width &optional frame
+@defunx frame-inner-height &optional frame
+These functions return the inner width and height of @var{frame} in
+pixels.
+@end defun
+
+@defun frame-text-width &optional frame
+@defunx frame-text-height &optional frame
+These functions return the width and height of the text area of
+@var{frame} in pixels.
 @end defun
 
 On window systems that support it, Emacs tries by default to make the
@@ -1345,6 +1360,8 @@ text terminals.
 * Buffer Parameters::           Which buffers have been or should be shown.
 * Frame Interaction Parameters::  Parameters for interacting with other
                                   frames.
+* Mouse Dragging Parameters::   Parameters for resizing and moving
+                                  frames with the mouse.
 * Management Parameters::       Communicating with the window manager.
 * Cursor Parameters::           Controlling the cursor appearance.
 * Font and Color Parameters::   Fonts and colors for the frame text.
@@ -1404,18 +1421,19 @@ named, this parameter will be @code{nil}.
 @cindex frame position
 
 Parameters describing the X- and Y-offsets of a frame are always
-measured in pixels.  For normal, non-child frames they specify the
-frame's absolute outer position (@pxref{Frame Geometry}) with respect to
-its display's origin.  For a child frame (@pxref{Child Frames}) they
-specify the frame's outer position relative to the native position of
-the frame's parent frame.  (Note that none of these parameters is
-meaningful on TTY frames.)
+measured in pixels.  For a normal, non-child frame they specify the
+frame's outer position (@pxref{Frame Geometry}) relative to its
+display's origin.  For a child frame (@pxref{Child Frames}) they specify
+the frame's outer position relative to the native position of the
+frame's parent frame.  (Note that none of these parameters is meaningful
+on TTY frames.)
 
 @table @code
 @vindex left, a frame parameter
 @item left
 The position, in pixels, of the left outer edge of the frame with
-respect to the left edge of the frame's display or parent frame.
+respect to the left edge of the frame's display or parent frame.  It can
+be specified in one of the following ways.
 
 @table @asis
 @item an integer
@@ -1436,6 +1454,30 @@ right edge of the display or parent frame.  The integer @var{pos} may be
 positive or negative; a negative value specifies a position outside the
 screen or parent frame or on a monitor other than the primary one (for
 multi-monitor displays).
+
+@cindex left position ratio
+@cindex top position ratio
+@item a floating-point value
+A floating-point value in the range 0.0 to 1.0 specifies the left edge's
+offset via the @dfn{left position ratio} of the frame---the ratio of the
+left edge of its outer frame to the width of the frame's workarea
+(@pxref{Multiple Terminals}) or its parent's native frame (@pxref{Child
+Frames}) minus the width of the outer frame.  Thus, a left position
+ratio of 0.0 flushes a frame to the left, a ratio of 0.5 centers it and
+a ratio of 1.0 flushes it to the right of its display or parent frame.
+Similarly, the @dfn{top position ratio} of a frame is the ratio of the
+frame's top position to the height of its workarea or parent frame minus
+the height of the frame.
+
+Emacs will try to keep the position ratios of a child frame unaltered if
+that frame has a non-@code{nil} @code{keep-ratio} parameter
+(@pxref{Frame Interaction Parameters}) and its parent frame is resized.
+
+Since the outer size of a frame (@pxref{Frame Geometry}) is usually
+unavailable before a frame has been made visible, it is generally not
+advisable to use floating-point values when creating decorated frames.
+Floating-point values are more suited for ensuring that an (undecorated)
+child frame is positioned nicely within the area of its parent frame.
 @end table
 
 Some window managers ignore program-specified positions.  If you want to
@@ -1448,17 +1490,19 @@ following example:
   nil '((user-position . t) (left . (+ -4))))
 @end example
 
-In general, it is not a good idea to specify negative offsets to
-position a frame relative to the right or bottom edge of its display.
-Positioning the initial or a new frame is either not accurate (because
-the size of the outer frame is not yet fully known before the frame has
-been made visible) or will cause additional flicker (if the frame is
-repositioned after becoming visible).
+In general, it is not a good idea to position a frame relative to the
+right or bottom edge of its display.  Positioning the initial or a new
+frame is either not accurate (because the size of the outer frame is not
+yet fully known before the frame has been made visible) or will cause
+additional flicker (if the frame has to be repositioned after becoming
+visible).
 
-  Note also, that negative offsets are not stored internally and are not
-returned by the function @code{frame-parameters}.  This means that the
-desktop saving routines will restore the frame from the positive offsets
-obtained by that function.
+  Note also, that positions specified relative to the right/bottom edge
+of a display, workarea or parent frame as well as floating-point offsets
+are stored internally as integer offsets relative to the left/top edge
+of the display, workarea or parent frame edge.  They are also returned
+as such by functions like @code{frame-parameters} and restored as such
+by the desktop saving routines.
 
 @vindex top, a frame parameter
 @item top
@@ -1523,24 +1567,61 @@ function @code{frame-restack} (@pxref{Raising and Lowering}).
 @subsubsection Size Parameters
 @cindex window size on display
 
-  Frame parameters specify frame sizes in character units.  On
-graphical displays, the @code{default} face determines the actual
-pixel sizes of these character units (@pxref{Face Attributes}).
+Frame parameters usually specify frame sizes in character units.  On
+graphical displays, the @code{default} face determines the actual pixel
+sizes of these character units (@pxref{Face Attributes}).
 
 @table @code
 @vindex width, a frame parameter
 @item width
-The width of the frame's text area (@pxref{Frame Geometry}), in
-characters.  The value can be also a cons cell of the symbol
-@code{text-pixels} and an integer denoting the width of the text area in
-pixels.
+This parameter specifies the width of the frame.  It can be specified as
+in the following ways:
+
+@table @asis
+@item an integer
+A positive integer specifies the width of the frame's text area
+(@pxref{Frame Geometry}) in characters.
+
+@item a cons cell
+If this is a cons cell with the symbol @code{text-pixels} in its
+@sc{car}, the @sc{cdr} of that cell specifies the width of the frame's
+text area in pixels.
+
+@cindex frame width ratio
+@cindex frame height ratio
+@item a floating-point value
+A floating-point number between 0.0 and 1.0 can be used to specify the
+width of a frame via its @dfn{width ratio}---the ratio of its outer
+width (@pxref{Frame Geometry}) to the width of the frame's workarea
+(@pxref{Multiple Terminals}) or its parent frame's (@pxref{Child
+Frames}) native frame.  Thus, a value of 0.5 makes the frame occupy half
+of the width of its workarea or parent frame, a value of 1.0 the full
+width.  Similarly, the @dfn{height ratio} of a frame is the ratio of its
+outer height to the height of its workarea or its parent's native frame.
+
+Emacs will try to keep the width and height ratio of a child frame
+unaltered if that frame has a non-@code{nil} @code{keep-ratio} parameter
+(@pxref{Frame Interaction Parameters}) and its parent frame is resized.
+
+Since the outer size of a frame is usually unavailable before a frame
+has been made visible, it is generally not advisable to use
+floating-point values when creating decorated frames.  Floating-point
+values are more suited to ensure that a child frame always fits within
+the area of its parent frame as, for example, when customizing
+@code{display-buffer-alist} (@pxref{Choosing Window}) via
+@code{display-buffer-in-child-frame}.
+@end table
+
+Regardless of how this parameter was specified, functions reporting the
+value of this parameter like @code{frame-parameters} always report the
+width of the frame's text area in characters as an integer rounded, if
+necessary, to a multiple of the frame's default character width.  That
+value is also used by the desktop saving routines.
 
 @vindex height, a frame parameter
 @item height
-The height of the frame's text area (@pxref{Frame Geometry}), in
-characters.  The value can be also a cons cell of the symbol
-@code{text-pixels} and an integer denoting the height of the text area
-in pixels.
+This parameter specifies the height of the frame.  It works just like
+@code{width}, except vertically instead of horizontally.
 
 @vindex user-size, a frame parameter
 @item user-size
@@ -1551,25 +1632,25 @@ user-position}) does for the position parameters @code{top} and
 
 @vindex min-width, a frame parameter
 @item min-width
-This parameter specifies the minimum native width of the frame
-(@pxref{Frame Geometry}), in characters.  Normally, the functions that
+This parameter specifies the minimum native width (@pxref{Frame
+Geometry}) of the frame, in characters.  Normally, the functions that
 establish a frame's initial width or resize a frame horizontally make
 sure that all the frame's windows, vertical scroll bars, fringes,
 margins and vertical dividers can be displayed.  This parameter, if
 non-@code{nil} allows to make a frame narrower than that with the
-consequence that any components that do not fit on the frame will be
-clipped by the window manager.
+consequence that any components that do not fit will be clipped by the
+window manager.
 
 @vindex min-height, a frame parameter
 @item min-height
-This parameter specifies the minimum height of the native (@pxref{Frame
-Geometry}), in characters.  Normally, the functions that establish a
-frame's initial size or resize a frame make sure that all the frame's
-windows, horizontal scroll bars and dividers, mode and header lines, the
-echo area and the internal menu and tool bar can be displayed.  This
-parameter, if non-@code{nil} allows to make a frame smaller than that
-with the consequence that any components that do not fit on the frame
-will be clipped by the window-system or window manager.
+This parameter specifies the minimum native height (@pxref{Frame
+Geometry}) of the frame, in characters.  Normally, the functions that
+establish a frame's initial size or resize a frame make sure that all
+the frame's windows, horizontal scroll bars and dividers, mode and
+header lines, the echo area and the internal menu and tool bar can be
+displayed.  This parameter, if non-@code{nil} allows to make a frame
+smaller than that with the consequence that any components that do not
+fit will be clipped by the window manager.
 
 @cindex fullboth frames
 @cindex fullheight frames
@@ -1623,6 +1704,20 @@ file as, for example
 
 This will give a new frame full height after typing in it @key{F11} for
 the first time.
+
+@vindex fit-frame-to-buffer-margins, a frame parameter
+@item fit-frame-to-buffer-margins
+This parameter allows to override the value of the option
+@code{fit-frame-to-buffer-margins} when fitting this frame to the buffer
+of its root window with @code{fit-frame-to-buffer} (@pxref{Resizing
+Windows}).
+
+@vindex fit-frame-to-buffer-sizes, a frame parameter
+@item fit-frame-to-buffer-sizes
+This parameter allows to override the value of the option
+@code{fit-frame-to-buffer-sizes} when fitting this frame to the buffer
+of its root window with @code{fit-frame-to-buffer} (@pxref{Resizing
+Windows}).
 @end table
 
 
@@ -1646,9 +1741,9 @@ Geometry}).
 
 @vindex vertical-scroll-bars, a frame parameter
 @item vertical-scroll-bars
-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.
+Whether the frame has scroll bars (@pxref{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.
 
 @vindex horizontal-scroll-bars, a frame parameter
 @item horizontal-scroll-bars
@@ -1692,30 +1787,40 @@ to not draw bottom dividers.
 
 @vindex menu-bar-lines frame parameter
 @item menu-bar-lines
-The number of lines to allocate at the top of the frame for a menu bar.
-The default is one if Menu Bar mode is enabled and zero otherwise.
-@xref{Menu Bars,,,emacs, The GNU Emacs Manual}.  For an external menu
-bar, this value remains unchanged even when the menu bar wraps to two or
-more lines.  In that case, the @code{menu-bar-size} value returned by
-@code{frame-geometry} (@pxref{Frame Geometry}) allows to derive whether
-the menu bar actually occupies one or more lines.
+The number of lines to allocate at the top of the frame for a menu bar
+(@pxref{Menu Bar}).  The default is one if Menu Bar mode is enabled and
+zero otherwise.  @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.  For an
+external menu bar (@pxref{Frame Layout}), this value remains unchanged
+even when the menu bar wraps to two or more lines.  In that case, the
+@code{menu-bar-size} value returned by @code{frame-geometry}
+(@pxref{Frame Geometry}) allows to derive whether the menu bar actually
+occupies one or more lines.
 
 @vindex tool-bar-lines frame parameter
 @item tool-bar-lines
-The number of lines to use for the tool bar.  The default is one if Tool
-Bar mode is enabled and zero otherwise.  @xref{Tool Bars,,,emacs, The
-GNU Emacs Manual}.  This value may change whenever the tool bar wraps.
+The number of lines to use for the tool bar (@pxref{Tool Bar}).  The
+default is one if Tool Bar mode is enabled and zero otherwise.
+@xref{Tool Bars,,,emacs, The GNU Emacs Manual}.  This value may change
+whenever the tool bar wraps (@pxref{Frame Layout}).
 
 @vindex tool-bar-position frame parameter
 @item tool-bar-position
-The position of the tool bar.  Currently only for the GTK tool bar.
-Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
-The default is @code{top}.
+The position of the tool bar when Emacs was built with GTK+.  Its value
+can be one of @code{top}, @code{bottom} @code{left}, @code{right}.  The
+default is @code{top}.
 
 @vindex line-spacing, a frame parameter
 @item line-spacing
 Additional space to leave below each text line, in pixels (a positive
 integer).  @xref{Line Height}, for more information.
+
+@vindex no-special-glyphs, a frame parameter
+@item no-special-glyphs
+If this is non-@code{nil}, it suppresses the display of any truncation
+and continuation glyphs (@pxref{Truncation}) for all buffers displayed
+by this frame.  This is useful to eliminate such glyphs when fitting a
+frame to its buffer via @code{fit-frame-to-buffer} (@pxref{Resizing
+Windows}).
 @end table
 
 
@@ -1781,15 +1886,115 @@ Frames}.
 @item mouse-wheel-frame
 If non-@code{nil}, this parameter specifies the frame whose windows will
 be scrolled whenever the mouse wheel is scrolled with the mouse pointer
-hovering over this frame (@pxref{Mouse Commands,,, emacs, The GNU Emacs
-Manual}).
+hovering over this frame, see @ref{Mouse Commands,,, emacs, The GNU
+Emacs Manual}.
 
 @vindex no-other-frame, a frame parameter
 @item no-other-frame
 If this is non-@code{nil}, then this frame is not eligible as candidate
 for the functions @code{next-frame}, @code{previous-frame}
-(@pxref{Finding All Frames}) and @code{other-frame} (@pxref{Frame
-Commands,,, emacs, The GNU Emacs Manual}).
+(@pxref{Finding All Frames}) and @code{other-frame}, see @ref{Frame
+Commands,,, emacs, The GNU Emacs Manual}.
+
+@vindex auto-hide-function, a frame parameter
+@item auto-hide-function
+When this parameter specifies a function, that function will be called
+instead of the function specified by the variable
+@code{frame-auto-hide-function} when quitting the frame's only window
+(@pxref{Quitting Windows}) and there are other frames left.
+
+@vindex minibuffer-exit, a frame parameter
+@item minibuffer-exit
+When this parameter is non-@code{nil}, Emacs will by default make this
+frame invisible whenever the minibuffer (@pxref{Minibuffers}) is exited.
+Alternatively, it can specify the functions @code{iconify-frame} and
+@code{delete-frame}.  This parameter is useful to make a child frame
+disappear automatically (similar to how Emacs deals with a window) when
+exiting the minibuffer.
+
+@vindex keep-ratio, a frame parameter
+@item keep-ratio
+This parameter is currently meaningful for child frames (@pxref{Child
+Frames}) only.  If it is non-@code{nil}, then Emacs will try to keep the
+frame's size (width and height) ratios (@pxref{Size Parameters}) as well
+as its left and right position ratios (@pxref{Position Parameters})
+unaltered whenever its parent frame is resized.
+
+If the value of this parameter is @code{nil}, the frame's position and
+size remain unaltered when the parent frame is resized, so the position
+and size ratios may change.  If the value of this parameter is @code{t},
+Emacs will try to preserve the frame's size and position ratios, hence
+the frame's size and position relative to its parent frame may change.
+
+More individual control is possible by using a cons cell: In that case
+the frame's width ratio is preserved if the @sc{car} of the cell is
+either @code{t} or @code{width-only}.  The height ratio is preserved if
+the @sc{car} of the cell is either @code{t} or @code{height-only}.  The
+left position ratio is preserved if the @sc{cdr} of the cell is either
+@code{t} or @code{left-only}.  The top position ratio is preserved if
+the @sc{cdr} of the cell is either @code{t} or @code{top-only}.
+@end table
+
+
+@node Mouse Dragging Parameters
+@subsubsection Mouse Dragging Parameters
+@cindex mouse dragging parameters
+@cindex parameters for resizing frames with the mouse
+@cindex parameters for moving frames with the mouse
+
+The parameters described below provide support for resizing a frame by
+dragging its internal borders with the mouse.  They also allow moving a
+frame with the mouse by dragging the header line of its topmost or the
+mode line of its bottommost window.
+
+These parameters are mostly useful for child frames (@pxref{Child
+Frames}) that come without window manager decorations.  If necessary,
+they can be used for undecorated top-level frames as well.
+
+@table @code
+@vindex drag-internal-border, a frame parameter
+@item drag-internal-border
+If non-@code{nil}, the frame can be resized by dragging its internal
+borders, if present, with the mouse.
+
+@vindex drag-with-header-line, a frame parameter
+@item drag-with-header-line
+If non-@code{nil}, the frame can be moved with the mouse by dragging the
+header line of its topmost window.
+
+@vindex drag-with-mode-line, a frame parameter
+@item drag-with-mode-line
+If non-@code{nil}, the frame can be moved with the mouse by dragging the
+mode line of its bottommost window.  Note that such a frame is not
+allowed to have its own minibuffer window.
+
+@vindex snap-width, a frame parameter
+@item snap-width
+A frame that is moved with the mouse will ``snap'' at the border(s) of
+the display or its parent frame whenever it is dragged as near to such
+an edge as the number of pixels specified by this parameter.
+
+@vindex top-visible, a frame parameter
+@item top-visible
+If this parameter is a number, the top edge of the frame never appears
+above the top edge of its display or parent frame.  Moreover, as many
+pixels of the frame as specified by that number will remain visible when
+the frame is moved against any of the remaining edges of its display or
+parent frame.  Setting this parameter is useful to guard against
+dragging a child frame with a non-@code{nil}
+@code{drag-with-header-line} parameter completely out of the area
+of its parent frame.
+
+@vindex bottom-visible, a frame parameter
+@item bottom-visible
+If this parameter is a number, the bottom edge of the frame never
+appears below the bottom edge of its display or parent frame.  Moreover,
+as many pixels of the frame as specified by that number will remain
+visible when the frame is moved against any of the remaining edges of
+its display or parent frame.  Setting this parameter is useful to guard
+against dragging a child frame with a non-@code{nil}
+@code{drag-with-mode-line} parameter completely out of the area of
+its parent frame.
 @end table
 
 
@@ -1797,9 +2002,9 @@ Commands,,, emacs, The GNU Emacs Manual}).
 @subsubsection Window Management Parameters
 @cindex window manager interaction, and frame parameters
 
-  The following frame parameters control various aspects of the
-frame's interaction with the window manager.  They have no effect on
-text terminals.
+  The following frame parameters control various aspects of the frame's
+interaction with the window manager or window system.  They have no
+effect on text terminals.
 
 @table @code
 @vindex visibility, a frame parameter
@@ -1908,7 +2113,8 @@ If non-@code{nil}, this means that this is an @dfn{override redirect}
 frame---a frame not handled by window managers under X.  Override
 redirect frames have no window manager decorations, can be positioned
 and resized only via Emacs' positioning and resizing functions and are
-usually drawn on top of all other frames.
+usually drawn on top of all other frames.  Setting this parameter has
+no effect on MS-Windows.
 
 @ignore
 @vindex parent-id, a frame parameter
@@ -2080,6 +2286,9 @@ The @code{alpha} frame parameter can also be a cons cell
 @code{(@var{active} . @var{inactive})}, where @var{active} is the
 opacity of the frame when it is selected, and @var{inactive} is the
 opacity when it is not selected.
+
+Some window systems do not support the @code{alpha} parameter for child
+frames (@pxref{Child Frames}).
 @end table
 
 The following frame parameters are semi-obsolete in that they are
@@ -2824,57 +3033,78 @@ unwanted frames are iconified instead.
 @cindex child frames
 @cindex parent frames
 
-On some window-systems the @code{parent-frame} parameter (@pxref{Frame
-Interaction Parameters}) can be used to make a frame a child of the
-frame specified by that parameter.  The frame specified by that
-parameter will then be the frame's parent frame as long as the parameter
-is not changed or reset.  Technically, this makes the child frame's
-window-system window a child window of the parent frame's window-system
-window.
+Child frames are objects halfway between windows (@pxref{Windows}) and
+``normal'' frames.  Like windows, they are attached to an owning frame.
+Unlike windows, they may overlap each other---changing the size or
+position of one child frame does not change the size or position of any
+of its sibling child frames.
+
+  By design, operations to make or modify child frames are implemented
+with the help of frame parameters (@pxref{Frame Parameters}) without any
+specialized functions or customizable variables.  Note that child frames
+are meaningful on graphical terminals only.
+
+  To create a new child frame or to convert a normal frame into a child
+frame, set that frame's @code{parent-frame} parameter (@pxref{Frame
+Interaction Parameters}) to that of an already existing frame.  The
+frame specified by that parameter will then be the frame's parent frame
+as long as the parameter is not changed or reset.  Technically, this
+makes the child frame's window-system window a child window of the
+parent frame's window-system window.
 
+@cindex top-level frame
+@cindex reparent frame
+@cindex nest frame
   The @code{parent-frame} parameter can be changed at any time.  Setting
-it to another frame ``reparents'' the child frame.  Setting it to
-another child frame makes the frame a ``nested'' child frame.  Setting
-it to @code{nil} restores the frame's status as a top-level frame---one
-whose window-system window is a child of its display's root window.
+it to another frame @dfn{reparents} the child frame.  Setting it to
+another child frame makes the frame a @dfn{nested} child frame.  Setting
+it to @code{nil} restores the frame's status as a @dfn{top-level
+frame}---a frame whose window-system window is a child of its display's
+root window.
 
   Since child frames can be arbitrarily nested, a frame can be both a
 child and a parent frame.  Also, the relative roles of child and parent
 frame may be reversed at any time (though it's usually a good idea to
-keep the size of child frames sufficiently smaller than that of their
+keep the size of a child frame sufficiently smaller than that of its
 parent).  An error will be signaled for the attempt to make a frame an
 ancestor of itself.
 
-  A child frame is clipped at the native edges (@pxref{Frame Geometry})
-of its parent frame---everything outside these edges is invisible.  Its
-@code{left} and @code{top} parameters specify positions relative to the
-top-left corner of its parent's native frame.  When either of the frames
-is resized, the relative position of the child frame remains unaltered.
-Hence, resizing either of these frames can hide or reveal parts of the
-child frame.
+   Most window-systems clip a child frame at the native edges
+(@pxref{Frame Geometry}) of its parent frame---everything outside these
+edges is usually invisible.  A child frame's @code{left} and @code{top}
+parameters specify a position relative to the top-left corner of its
+parent's native frame.  When the parent frame is resized, this position
+remains conceptually unaltered.
 
   NS builds do not clip child frames at the parent frame's edges,
-allowing them to be positioned so they do not obscure the parent
-frame while still being visible themselves.
+allowing them to be positioned so they do not obscure the parent frame
+while still being visible themselves.
 
   Usually, moving a parent frame moves along all its child frames and
 their descendants as well, keeping their relative positions unaltered.
-The hook @code{move-frame-functions} (@pxref{Frame Position}) is run for
-a child frame only when the position of the child frame relative to its
-parent frame changes.  When a parent frame is resized, the child frame
-retains its position respective to the left and upper native edges of
-its parent.  In this case, the position respective to the lower or right
-native edge of the parent frame is usually lost.
+Note that the hook @code{move-frame-functions} (@pxref{Frame Position})
+is run for a child frame only when the position of the child frame
+relative to its parent frame changes.  It is not run for a child frame
+when the position of the parent frame changes.
+
+  When a parent frame is resized, its child frames conceptually retain
+their previous sizes and their positions relative to the left upper
+corner of the parent.  This means that a child frame may become
+(partially) invisible when its parent frame shrinks.  The parameter
+@code{keep-ratio} (@pxref{Frame Interaction Parameters}) can be used to
+resize and reposition a child frame proportionally whenever its parent
+frame is resized.  This may avoid obscuring parts of a frame when its
+parent frame is shrunk.
 
   A visible child frame always appears on top of its parent frame thus
 obscuring parts of it, except on NS builds where it may be positioned
-beneath the parent.  This is comparable to the window-system window of
-a top-level frame which also always appears on top of its parent
-window---the desktop's root window.  When a parent frame is iconified
-or made invisible (@pxref{Visibility of Frames}), its child frames are
-made invisible.  When a parent frame is deiconified or made visible,
-its child frames are made visible.  When a parent frame is about to be
-deleted, (@pxref{Deleting Frames}) its child frames are recursively
+beneath the parent.  This is comparable to the window-system window of a
+top-level frame which also always appears on top of its parent
+window---the desktop's root window.  When a parent frame is iconified or
+made invisible (@pxref{Visibility of Frames}), its child frames are made
+invisible.  When a parent frame is deiconified or made visible, its
+child frames are made visible.  When a parent frame is about to be
+deleted (@pxref{Deleting Frames}), its child frames are recursively
 deleted before it.
 
   Whether a child frame can have a menu or tool bar is window-system or
@@ -2892,7 +3122,55 @@ outer border can be used.  On MS-Windows, specifying a non-zero outer
 border width will show a one-pixel wide external border.  Under all
 window-systems, the internal border can be used.  In either case, it's
 advisable to disable a child frame's window manager decorations with the
-@code{undecorated} frame parameter @pxref{Management Parameters}).
+@code{undecorated} frame parameter (@pxref{Management Parameters}).
+
+  To resize or move an undecorated child frame with the mouse, special
+frame parameters (@pxref{Mouse Dragging Parameters}) have to be used.
+The internal border of a child frame, if present, can be used to resize
+the frame with the mouse, provided that frame has a non-@code{nil}
+@code{drag-internal-border} parameter.  If set, the @code{snap-width}
+parameter indicates the number of pixels where the frame @dfn{snaps} at
+the respective edge or corner of its parent frame.
+
+  There are two ways to drag an entire child frame with the mouse: The
+@code{drag-with-mode-line} parameter, if non-@code{nil}, allows to drag
+a frame without minibuffer window (@pxref{Minibuffer Windows}) via the
+mode line area of its bottommost window.  The
+@code{drag-with-header-line} parameter, if non-@code{nil}, allows to
+drag the frame via the header line area of its topmost window.
+
+  In order to give a child frame a draggable header or mode line, the
+window parameters @code{mode-line-format} and @code{header-line-format}
+are handy (@pxref{Window Parameters}).  These allow to remove an
+unwanted mode line (when @code{drag-with-header-line} is chosen) and to
+remove mouse-sensitive areas which might interfere with frame dragging.
+
+  To avoid that dragging moves a frame completely out of its parent's
+native frame, something which might happen when the mouse cursor
+overshoots and makes the frame difficult to retrieve once the mouse
+button has been released, it is advisable to set the frame's
+@code{top-visible} or @code{bottom-visible} parameter correspondingly.
+
+  The @code{top-visible} parameter specifies the number of pixels at the
+top of the frame that always remain visible within the parent's native
+frame during dragging and should be set when specifying a non-@code{nil}
+@code{drag-with-header-line} parameter.  The @code{bottom-visible}
+parameter specifies the number of pixels at the bottom of the frame that
+always remain visible within the parent's native frame during dragging
+and should be preferred when specifying a non-@code{nil}
+@code{drag-with-mode-line} parameter.
+
+  When a child frame is used for displaying a buffer via
+@code{display-buffer-in-child-frame} (@pxref{Display Action Functions}),
+the frame's @code{auto-hide-function} parameter (@pxref{Frame
+Interaction Parameters}) can be set to a function, in order to
+appropriately deal with the frame when the window displaying the buffer
+shall be quit.
+
+  When a child frame is used during minibuffer interaction, for example,
+to display completions in a separate window, the @code{minibuffer-exit}
+parameter (@pxref{Frame Interaction Parameters}) is useful in order to
+deal with the frame when the minibuffer is exited.
 
   The behavior of child frames deviates from that of top-level frames in
 a number of other ways as well.  Here we sketch a few of them:
@@ -2930,7 +3208,7 @@ work on all window-systems.  Some will drop the object on the parent
 frame or on some ancestor instead.
 @end itemize
 
-  The following two functions may be useful when working with child and
+  The following two functions can be useful when working with child and
 parent frames:
 
 @defun frame-parent &optional frame
@@ -2951,6 +3229,12 @@ of @var{descendant}'s parent frame.  Both, @var{ancestor} and
 frame.
 @end defun
 
+Note also the function @code{window-largest-empty-rectangle}
+(@pxref{Coordinates and Windows}) which can be used to inscribe a child
+frame in the largest empty area of an existing window.  This can be
+useful to avoid that a child frame obscures any text shown in that
+window.
+
 
 @node Mouse Tracking
 @section Mouse Tracking
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 0e476b47a31..f7013da9433 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1737,7 +1737,9 @@ holds a @dfn{mode line construct}: a template that controls what is
 displayed on the buffer's mode line.  The value of
 @code{header-line-format} specifies the buffer's header line in the same
 way.  All windows for the same buffer use the same
-@code{mode-line-format} and @code{header-line-format}.
+@code{mode-line-format} and @code{header-line-format} unless a
+@code{mode-line-format} or @code{header-line-format} parameter has been
+specified for that window (@pxref{Window Parameters}).
 
   For efficiency, Emacs does not continuously recompute each window's
 mode line and header line.  It does so when circumstances appear to call
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 1f4c378df18..daa397175c3 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -283,11 +283,11 @@ character @kbd{a}.
 ?Q @result{} 81     ?q @result{} 113
 @end example
 
-  You can use the same syntax for punctuation characters, but it is
-often a good idea to add a @samp{\} so that the Emacs commands for
-editing Lisp code don't get confused.  For example, @samp{?\(} is the
-way to write the open-paren character.  If the character is @samp{\},
-you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
+  You can use the same syntax for punctuation characters.  However, if
+the punctuation character has a special syntactic meaning in Lisp, you
+must quote it with a @samp{\}.  For example, @samp{?\(} is the way to
+write the open-paren character.  Likewise, if the character is
+@samp{\}, you must use a second @samp{\} to quote it: @samp{?\\}.
 
 @cindex whitespace
 @cindex bell character
@@ -336,18 +336,19 @@ escape character; this has nothing to do with the
 character @key{ESC}.  @samp{\s} is meant for use in character
 constants; in string constants, just write the space.
 
-  A backslash is allowed, and harmless, preceding any character without
-a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
-There is no reason to add a backslash before most characters.  However,
-you should add a backslash before any of the characters
-@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
-Lisp code.  You can also add a backslash before whitespace characters such as
-space, tab, newline and formfeed.  However, it is cleaner to use one of
-the easily readable escape sequences, such as @samp{\t} or @samp{\s},
-instead of an actual whitespace character such as a tab or a space.
-(If you do write backslash followed by a space, you should write
-an extra space after the character constant to separate it from the
-following text.)
+  A backslash is allowed, and harmless, preceding any character
+without a special escape meaning; thus, @samp{?\+} is equivalent to
+@samp{?+}.  There is no reason to add a backslash before most
+characters.  However, you must add a backslash before any of the
+characters @samp{()[]\;"}, and you should add a backslash before any
+of the characters @samp{|'`#.,} to avoid confusing the Emacs commands
+for editing Lisp code.  You can also add a backslash before whitespace
+characters such as space, tab, newline and formfeed.  However, it is
+cleaner to use one of the easily readable escape sequences, such as
+@samp{\t} or @samp{\s}, instead of an actual whitespace character such
+as a tab or a space.  (If you do write backslash followed by a space,
+you should write an extra space after the character constant to
+separate it from the following text.)
 
 @node General Escape Syntax
 @subsubsection General Escape Syntax
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index d9b4b743a3b..eb5c2fc46be 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -752,6 +752,7 @@ The optional argument @var{pixelwise} non-@code{nil} means to return the
 minimum size of @var{window} counted in pixels.
 @end defun
 
+
 @node Resizing Windows
 @section Resizing Windows
 @cindex window resizing
@@ -943,7 +944,8 @@ help of the two options listed next.
 @defopt fit-frame-to-buffer-margins
 This option can be used to specify margins around frames to be fit by
 @code{fit-frame-to-buffer}.  Such margins can be useful to avoid, for
-example, that such frames overlap the taskbar.
+example, that the resized frame overlaps the taskbar or parts of its
+parent frame.
 
 It specifies the numbers of pixels to be left free on the left, above,
 the right, and below a frame that shall be fit.  The default specifies
@@ -2484,6 +2486,25 @@ the function specified in @code{pop-up-frame-function}
 is added to the newly created frame's parameters.
 @end defun
 
+@defun display-buffer-in-child-frame buffer alist
+This function tries to display @var{buffer} in a child frame
+(@pxref{Child Frames}) of the selected frame, either reusing an existing
+child frame or by making a new one.  If @var{alist} has a non-@code{nil}
+@code{child-frame-parameters} entry, the corresponding value is an alist
+of frame parameters to give the new frame.  A @code{parent-frame}
+parameter specifying the selected frame is provided by default.  If the
+child frame should be or become the child of another frame, a
+corresponding entry must be added to @var{alist}.
+
+The appearance of child frames is largely dependent on the parameters
+provided via @var{alist}.  It is advisable to use at least ratios to
+specify the size (@pxref{Size Parameters}) and the position
+(@pxref{Position Parameters}) of the child frame and to add the
+@code{keep-ratio} in order to make sure that the child frame remains
+visible.  For other parameters that should be considered see @ref{Child
+Frames}.
+@end defun
+
 @defun display-buffer-use-some-frame buffer alist
 This function tries to display @var{buffer} by trying to find a
 frame that meets a predicate (by default any frame other than the
@@ -3124,12 +3145,17 @@ killed.
 The default is to call @code{iconify-frame} (@pxref{Visibility of
 Frames}).  Alternatively, you may specify either @code{delete-frame}
 (@pxref{Deleting Frames}) to remove the frame from its display,
-@code{ignore} to leave the frame unchanged, or any other function that
-can take a frame as its sole argument.
+@code{make-frame-invisible} to make the frame invisible, @code{ignore}
+to leave the frame unchanged, or any other function that can take a
+frame as its sole argument.
 
 Note that the function specified by this option is called only if the
 specified frame contains just one live window and there is at least one
 other frame on the same terminal.
+
+For a particular frame, the value specified here may be overridden by
+that frame's @code{auto-hide-function} frame parameter (@pxref{Frame
+Interaction Parameters}).
 @end defopt
 
 
@@ -4364,13 +4390,12 @@ is off the screen due to horizontal scrolling:
 @cindex coordinate, relative to frame
 @cindex window position
 
-This section describes functions that report the position of a window.
-Most of these functions report positions relative to an origin at the
-native position of the window's frame (@pxref{Frame Geometry}).  Some
-functions report positions relative to the origin of the display of the
-window's frame.  In any case, the origin has the coordinates (0, 0) and
-X and Y coordinates increase rightward and downward
-respectively.
+This section describes functions that report positions of and within a
+window.  Most of these functions report positions relative to an origin
+at the native position of the window's frame (@pxref{Frame Geometry}).
+Some functions report positions relative to the origin of the display of
+the window's frame.  In any case, the origin has the coordinates (0, 0)
+and X and Y coordinates increase rightward and downward respectively.
 
   For the following functions, X and Y coordinates are reported in
 integer character units, i.e., numbers of lines and columns
@@ -4608,6 +4633,49 @@ point in the selected window, it's sufficient to write:
 @end example
 @end defun
 
+The following function returns the largest rectangle that can be
+inscribed in a window without covering text displayed in that window.
+
+@defun window-largest-empty-rectangle &optional window count min-width min-height positions left
+This function calculates the dimensions of the largest empty rectangle
+that can be inscribed in the specified @var{window}'s text area.
+@var{window} must be a live window and defaults to the selected one.
+
+The return value is a triple of the width and the start and end
+y-coordinates of the largest rectangle that can be inscribed into the
+empty space (space not displaying any text) of the text area of
+@var{window}.  No x-coordinates are returned by this function---any such
+rectangle is assumed to end at the right edge of @var{window}'s text
+area.  If no empty space can be found, the return value is @code{nil}.
+
+The optional argument @var{count}, if non-@code{nil}, specifies a
+maximum number of rectangles to return.  This means that the return
+value is a list of triples specifying rectangles with the largest
+rectangle first.  @var{count} can be also a cons cell whose car
+specifies the number of rectangles to return and whose @sc{cdr}, if
+non-@code{nil}, states that all rectangles returned must be disjoint.
+
+The optional arguments @var{min-width} and @var{min-height}, if
+non-@code{nil}, specify the minimum width and height of any rectangle
+returned.
+
+The optional argument @var{positions}, if non-@code{nil}, is a cons cell
+whose @sc{car} specifies the uppermost and whose @sc{cdr} specifies the
+lowermost pixel position that must be covered by any rectangle returned.
+These positions measure from the start of the text area of @var{window}.
+
+The optional argument @var{left}, if non-@code{nil}, means to return
+values suitable for buffers displaying right to left text.  In that
+case, any rectangle returned is assumed to start at the left edge of
+@var{window}'s text area.
+
+Note that this function has to retrieve the dimensions of each line of
+@var{window}'s glyph matrix via @code{window-lines-pixel-dimensions}
+(@pxref{Size of Displayed Text}).  Hence, this function may also return
+@code{nil} when the current glyph matrix of @var{window} is not
+up-to-date.
+@end defun
+
 
 @node Mouse Window Auto-selection
 @section Mouse Window Auto-selection
@@ -4911,37 +4979,45 @@ windows when exiting that function.
 The following parameters are currently used by the window management
 code:
 
-@table @asis
-@item @code{delete-window}
+@table @code
+@item delete-window
+@vindex delete-window, a window parameter
 This parameter affects the execution of @code{delete-window}
 (@pxref{Deleting Windows}).
 
-@item @code{delete-other-windows}
+@item delete-other-windows
+@vindex delete-other-windows, a window parameter
 This parameter affects the execution of @code{delete-other-windows}
 (@pxref{Deleting Windows}).
 
-@item @code{no-delete-other-window}
+@item no-delete-other-window
+@vindex no-delete-other-window, a window parameter
 This parameter marks the window as not deletable by
 @code{delete-other-windows} (@pxref{Deleting Windows}).
 
-@item @code{split-window}
+@item split-window
+@vindex split-window, a window parameter
 This parameter affects the execution of @code{split-window}
 (@pxref{Splitting Windows}).
 
-@item @code{other-window}
+@item other-window
+@vindex other-window, a window parameter
 This parameter affects the execution of @code{other-window}
 (@pxref{Cyclic Window Ordering}).
 
-@item @code{no-other-window}
+@item no-other-window
+@vindex no-other-window, a window parameter
 This parameter marks the window as not selectable by @code{other-window}
 (@pxref{Cyclic Window Ordering}).
 
-@item @code{clone-of}
+@item clone-of
+@vindex clone-of, a window parameter
 This parameter specifies the window that this one has been cloned
 from.  It is installed by @code{window-state-get} (@pxref{Window
 Configurations}).
 
-@item @code{preserved-size}
+@item preserved-size
+@vindex preserved-size, a window parameter
 This parameter specifies a buffer, a direction where @code{nil} means
 vertical and @code{t} horizontal, and a size in pixels.  If this window
 displays the specified buffer and its size in the indicated direction
@@ -4950,7 +5026,8 @@ preserve the size of this window in the indicated direction.  This
 parameter is installed and updated by the function
 @code{window-preserve-size} (@pxref{Preserving Window Sizes}).
 
-@item @code{quit-restore}
+@item quit-restore
+@vindex quit-restore, a window parameter
 This parameter is installed by the buffer display functions
 (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
 (@pxref{Quitting Windows}).  It contains four elements:
@@ -4981,15 +5058,37 @@ only if it still shows that buffer.
 See the description of @code{quit-restore-window} in @ref{Quitting
 Windows} for details.
 
-@item @code{window-side} @code{window-slot}
+@item window-side window-slot
+@vindex window-side, a window parameter
+@vindex window-slot, a window parameter
 These parameters are used for implementing side windows (@pxref{Side
 Windows}).
 
-@item @code{window-atom}
+@item window-atom
+@vindex window-atom, a window parameter
 This parameter is used for implementing atomic windows, see @ref{Atomic
 Windows}.
 
-@item @code{min-margins}
+@item mode-line-format
+@vindex mode-line-format, a window parameter
+This parameter replaces the value of the buffer-local variable
+@code{mode-line-format} (@pxref{Mode Line Basics}) of this window's
+buffer whenever this window is displayed.  The symbol @code{none} means
+to suppress display of a mode line for this window.  Display and
+contents of the mode line on other windows showing this buffer are not
+affected.
+
+@item header-line-format
+@vindex header-line-format, a window parameter
+This parameter replaces the value of the buffer-local variable
+@code{header-line-format} (@pxref{Mode Line Basics}) of this window's
+buffer whenever this window is displayed.  The symbol @code{none} means
+to suppress display of a header line for this window.  Display and
+contents of the header line on other windows showing this buffer are not
+affected.
+
+@item min-margins
+@vindex min-margins, a window parameter
 The value of this parameter is a cons cell whose @sc{car} and @sc{cdr},
 if non-@code{nil}, specify the minimum values (in columns) for the left
 and right margin of this window.  When present, Emacs will use these
diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index b0cfbc9d3c0..069d6b3389b 100644
--- a/doc/misc/emacs-mime.texi
+++ b/doc/misc/emacs-mime.texi
@@ -405,7 +405,7 @@ variable will cause @samp{text/html} parts to be treated as attachments.
 @item mm-text-html-renderer
 @vindex mm-text-html-renderer
 This selects the function used to render @acronym{HTML}.  The predefined
-renderers are selected by the symbols @code{gnus-article-html},
+renderers are selected by the symbols @code{shr}, @code{gnus-w3m},
 @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
 information about emacs-w3m}, @code{links}, @code{lynx},
 @code{w3m-standalone} or @code{html2text}.  If @code{nil} use an
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index a42dc6ed3c0..6209e02ebc5 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -72,21 +72,21 @@ local and the remote host, whereas @value{tramp} uses a combination of
 @command{ssh}/@command{scp}.
 
 You can find the latest version of this document on the web at
-@uref{http://www.gnu.org/software/tramp/}.
+@uref{https://www.gnu.org/software/tramp/}.
 
 @ifhtml
 The latest release of @value{tramp} is available for
-@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
+@uref{https://ftp.gnu.org/gnu/tramp/, download}, or you may see
 @ref{Obtaining Tramp} for more details, including the Git server
 details.
 
-@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
+@value{tramp} also has a @uref{https://savannah.gnu.org/projects/tramp/,
 Savannah Project Page}.
 @end ifhtml
 
 There is a mailing list for @value{tramp}, available at
 @email{tramp-devel@@gnu.org}, and archived at
-@uref{http://lists.gnu.org/archive/html/tramp-devel/, the
+@uref{https://lists.gnu.org/archive/html/tramp-devel/, the
 @value{tramp} Mail Archive}.
 
 @page
@@ -321,7 +321,7 @@ behind the scenes when you open a file with @value{tramp}.
 @value{tramp} is included as part of Emacs (since Emacs version 22.1).
 
 @value{tramp} is also freely packaged for download on the Internet at
-@uref{ftp://ftp.gnu.org/gnu/tramp/}.
+@uref{https://ftp.gnu.org/gnu/tramp/}.
 
 @value{tramp} development versions are available on Git servers.
 Development versions contain new and incomplete features.
@@ -331,7 +331,7 @@ page at the following URL and then clicking on the Git link in the
 navigation bar at the top.
 
 @noindent
-@uref{http://savannah.gnu.org/projects/tramp/}
+@uref{https://savannah.gnu.org/projects/tramp/}
 
 @noindent
 Another way is to follow the terminal session below:
@@ -349,7 +349,7 @@ From behind a firewall:
 @example
 @group
 ] @strong{git config --global http.proxy http://user:pwd@@proxy.server.com:8080}
-] @strong{git clone http://git.savannah.gnu.org/r/tramp.git}
+] @strong{git clone https://git.savannah.gnu.org/r/tramp.git}
 @end group
 @end example
 
@@ -917,7 +917,7 @@ numbers are not applicable to Android devices connected through USB@.
 @cindex dbus
 
 GVFS is the virtual file system for the Gnome Desktop,
-@uref{http://en.wikipedia.org/wiki/GVFS}.  Remote files on GVFS are
+@uref{https://en.wikipedia.org/wiki/GVFS}.  Remote files on GVFS are
 mounted locally through FUSE and @value{tramp} uses this locally
 mounted directory internally.
 
@@ -1896,12 +1896,16 @@ where @samp{192.168.0.1} is the remote host IP address
 @value{tramp} uses the @option{adb} method to access Android devices.
 Android devices provide a restricted shell access through an USB
 connection.  The local host must have the @command{adb} program
-installed.
+installed.  Usually, it is sufficient to open the file
+@file{@trampfn{adb,,/}}.  Then you can navigate in the filesystem via
+@code{dired}.
 
-Applications such as @code{SSHDroid} that run @command{sshd} process
-on the Android device can accept any @option{ssh}-based methods
-provided these settings are adjusted:
+Alternatively, applications such as @code{SSHDroid} that run
+@command{sshd} process on the Android device can accept any
+@option{ssh}-based methods provided these settings are adjusted:
 
+@itemize
+@item
 @command{sh} must be specified for remote shell since Android devices
 do not provide @command{/bin/sh}.  @command{sh} will then invoke
 whatever shell is installed on the device with this setting:
@@ -1917,6 +1921,7 @@ whatever shell is installed on the device with this setting:
 where @samp{192.168.0.26} is the Android device's IP address.
 (@pxref{Predefined connection information}).
 
+@item
 @value{tramp} requires preserving @env{PATH} environment variable from
 user settings.  Android devices prefer @file{/system/xbin} path over
 @file{/system/bin}.  Both of these are set as follows:
@@ -1928,7 +1933,7 @@ user settings.  Android devices prefer @file{/system/xbin} path over
 @end group
 @end lisp
 
-@noindent
+@item
 When the Android device is not @samp{rooted}, specify a writable
 directory for temporary files:
 
@@ -1936,7 +1941,7 @@ directory for temporary files:
 (add-to-list 'tramp-remote-process-environment "TMPDIR=$HOME")
 @end lisp
 
-@noindent
+@item
 Open a remote connection with the command @kbd{C-x C-f
 @trampfn{ssh,192.168.0.26#2222,}}, where @command{sshd} is listening
 on port @samp{2222}.
@@ -1967,6 +1972,7 @@ the previous example, fix the connection properties as follows:
 @noindent
 Open a remote connection with a more concise command @kbd{C-x C-f
 @trampfn{ssh,android,}}.
+@end itemize
 
 
 @node Auto-save and Backup
@@ -2083,7 +2089,7 @@ Pseudo-terminal will not be allocated because stdin is not a terminal.
 
 Some older versions of Cygwin's @command{ssh} work with the
 @option{sshx} access method.  Consult Cygwin's FAQ at
-@uref{http://cygwin.com/faq/} for details.
+@uref{https://cygwin.com/faq/} for details.
 
 @cindex Cygwin and fakecygpty
 @cindex fakecygpty and Cygwin
@@ -2797,7 +2803,7 @@ this address go to all the subscribers.  This is @emph{not} the
 address to send subscription requests to.
 
 To subscribe to the mailing list, visit:
-@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, the
+@uref{https://lists.gnu.org/mailman/listinfo/tramp-devel/, the
 @value{tramp} Mail Subscription Page}.
 
 @ifset installchapter
@@ -2849,13 +2855,13 @@ Where is the latest @value{tramp}?
 @value{tramp} is available at the GNU URL:
 
 @noindent
-@uref{ftp://ftp.gnu.org/gnu/tramp/}
+@uref{https://ftp.gnu.org/gnu/tramp/}
 
 @noindent
 @value{tramp}'s GNU project page is located here:
 
 @noindent
-@uref{http://savannah.gnu.org/projects/tramp/}
+@uref{https://savannah.gnu.org/projects/tramp/}
 
 
 @item
diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi
index f1cb60b9d25..05b577da005 100644
--- a/doc/misc/trampver.texi
+++ b/doc/misc/trampver.texi
@@ -8,7 +8,7 @@
 @c In the Tramp GIT, the version number is auto-frobbed from
 @c configure.ac, so you should edit that file and run
 @c "autoconf && ./configure" to change the version number.
-@set trampver 2.3.2-pre
+@set trampver 2.3.2
 
 @c Other flags from configuration
 @set instprefix /usr/local