Update docs for window dividers and `window-text-pixel-size'.

* xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
* elisp.texi (Top): Rename section "Width" to "Size of Displayed
Text".
* text.texi (Primitive Indent):
* strings.texi (String Basics):
* sequences.texi (Sequence Functions): Update references
accordingly.
* display.texi (Size of Displayed Text): Rename section from
"Width".  Add description for `window-text-pixel-size'.
(Window Dividers): Reword description of window dividers.
* frames.texi (Layout Parameters): Improve description of window
divider parameters.
* windows.texi (Window Sizes): Add descriptions of
`window-mode-line-height' and `window-header-line-height'.
(Coordinates and Windows): Mention window dividers.

8 files changed, 168 insertions, 44 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 88a20fd8a2..93153a1ecb 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,20 @@
+2014-03-09  Martin Rudalics  <[email protected]>
+
+	* elisp.texi (Top): Rename section "Width" to "Size of Displayed
+	Text".
+	* text.texi (Primitive Indent):
+	* strings.texi (String Basics):
+	* sequences.texi (Sequence Functions): Update references
+	accordingly.
+	* display.texi (Size of Displayed Text): Rename section from
+	"Width".  Add description for `window-text-pixel-size'.
+	(Window Dividers): Reword description of window dividers.
+	* frames.texi (Layout Parameters): Improve description of window
+	divider parameters.
+	* windows.texi (Window Sizes): Add descriptions of
+	`window-mode-line-height' and `window-header-line-height'.
+	(Coordinates and Windows): Mention window dividers.
+
 2014-03-07  Martin Rudalics  <[email protected]>
 
 	* buffers.texi (The Buffer List): Rename node to Buffer List.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 56dd718588..bffb840bfe 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -18,7 +18,7 @@ that Emacs presents to the user.
 * Selective Display::   Hiding part of the buffer text (the old way).
 * Temporary Displays::  Displays that go away automatically.
 * Overlays::            Use overlays to highlight parts of the buffer.
-* Width::               How wide a character or string is on the screen.
+* Size of Displayed Text::  How large displayed text is.
 * Line Height::         Controlling the height of lines.
 * Faces::               A face defines a graphics style for text characters:
                           font, colors, etc.
@@ -1765,8 +1765,8 @@ changes.
     (point)))
 @end smallexample
 
-@node Width
-@section Width
+@node Size of Displayed Text
+@section Size of Displayed Text
 
 Since not all characters have the same width, these functions let you
 check the width of a character.  @xref{Primitive Indent}, and
@@ -1823,6 +1823,54 @@ to or less than the display width of @var{ellipsis}.  If
 @end example
 @end defun
 
+The following function returns the size in pixels of text as if it were
+displayed in a given window.  This function is used by
+@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and
+@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window
+exactly as large as the text it contains.
+
+@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
+This function returns the size of the text of @var{window}'s buffer in
+pixels.  @var{window} must be a live window and defaults to the selected
+one.  The return value is a cons of the maximum pixel-width of any text
+line and the maximum pixel-height of all text lines.
+
+The optional argument @var{from}, if non-@code{nil}, specifies the first
+text position to consider and defaults to the minimum accessible
+position of the buffer.  If @var{from} is @code{t}, it uses the minimum
+accessible position that is not a newline character.  The optional
+argument @var{to}, if non-@code{nil}, specifies the last text position
+to consider and defaults to the maximum accessible position of the
+buffer.  If @var{to} is @code{t}, it uses the maximum accessible
+position that is not a newline character.
+
+The optional argument @var{x-limit}, if non-@code{nil}, specifies the
+maximum pixel-width that can be returned.  @var{x-limit} @code{nil} or
+omitted, means to use the pixel-width of @var{window}'s body
+(@pxref{Window Sizes}); this is useful when the caller does not intend
+to change the width of @var{window}.  Otherwise, the caller should
+specify here the maximum width @var{window}'s body may assume.  Text
+whose x-coordinate is beyond @var{x-limit} is ignored.  Since
+calculating the width of long lines can take some time, it's always a
+good idea to make this argument as small as needed; in particular, if
+the buffer might contain long lines that will be truncated anyway.
+
+The optional argument @var{y-limit}, if non-@code{nil}, specifies the
+maximum pixel-height that can be returned.  Text lines whose
+y-coordinate is beyond @var{y-limit} are ignored.  Since calculating the
+pixel-height of a large buffer can take some time, it makes sense to
+specify this argument; in particular, if the caller does not know the
+size of the buffer.
+
+The optional argument @var{mode-and-header-line} @code{nil} or omitted
+means to not include the height of the mode- or header-line of
+@var{window} in the return value.  If it is either the symbol
+@code{mode-line} or @code{header-line}, include only the height of that
+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
+
+
 @node Line Height
 @section Line Height
 @cindex line height
@@ -3904,28 +3952,28 @@ to use the value specified by the frame.
 @cindex bottom dividers
 
 Window dividers are bars drawn between a frame's windows.  A ``right''
-divider is drawn between a window and its sibling(s) on the right.  Its
-width is specified by the frame parameter @code{right-divider-width}.  A
-``bottom'' divider is drawn between a window and its sibling(s) on the
-bottom or the echo area.  Its width is specified by the frame parameter
-@code{bottom-divider-width}.  In either case, specifying a width of zero
-means to not draw such dividers.  @xref{Layout Parameters}.
+divider is drawn between a window and any adjacent windows on the right.
+Its width (thickness) is specified by the frame parameter
+@code{right-divider-width}.  A ``bottom'' divider is drawn between a
+window and adjacent windows on the bottom or the echo area.  Its width
+is specified by the frame parameter @code{bottom-divider-width}.  In
+either case, specifying a width of zero means to not draw such dividers.
+@xref{Layout Parameters}.
 
    Technically, a right divider ``belongs'' to the window on its left,
-which means that its width is part of the total width of that window.  A
-bottom divider ``belongs'' to the window above it, which means that its
-height is part of the total height of that window.  @xref{Window Sizes}.
-When a window has both, a right and a bottom divider, the bottom divider
-``prevails''.  This means that the width of the bottom divider equals
-the total width of the window while the height of the right divider
-equals the total height of the window minus the height of the bottom
-divider.
+which means that its width contributes to the total width of that
+window.  A bottom divider ``belongs'' to the window above it, which
+means that its width contributes to the total height of that window.
+@xref{Window Sizes}.  When a window has both, a right and a bottom
+divider, the bottom divider ``prevails''.  This means that a bottom
+divider is drawn over the full total width of its window while the right
+divider ends above the bottom divider.
 
    Dividers can be dragged with the mouse and are therefore useful for
 adjusting the sizes of adjacent windows with the mouse.  They also serve
-to set windows visually apart from their siblings when no scroll bars or
-mode lines are present.  The following three faces allow to customize
-the appearance of dividers:
+to visually set apart adjacent windows when no scroll bars or mode lines
+are present.  The following three faces allow to customize the
+appearance of dividers:
 
 @table @code
 @item window-divider
@@ -3944,6 +3992,23 @@ least three pixels wide.  To obtain a solid appearance, set this to the
 same value used for the @code{window-divider} face.
 @end table
 
+You can get the sizes of the dividers of a specific window with the
+following two functions.
+
+@defun window-right-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s right divider.
+@var{window} must be a live window and defaults to the selected one.
+The return value is always zero for a rightmost window.
+@end defun
+
+@defun window-bottom-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s bottom divider.
+@var{window} must be a live window and defaults to the selected one.
+The return value is zero for the minibuffer window or a bottommost
+window on a minibuffer-less frame.
+@end defun
+
+
 @node Display Property
 @section The @code{display} Property
 @cindex display specification
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index f0a5596837..c0040d748c 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1338,7 +1338,7 @@ Emacs Display
 * Selective Display::       Hiding part of the buffer text (the old way).
 * Temporary Displays::      Displays that go away automatically.
 * Overlays::                Use overlays to highlight parts of the buffer.
-* Width::                   How wide a character or string is on the screen.
+* Size of Displayed Text::  How large displayed text is.
 * Line Height::             Controlling the height of lines.
 * Faces::                   A face defines a graphics style
                               for text characters: font, colors, etc.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 166ec6d8de..206f14e751 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -747,15 +747,15 @@ widths are negative, only the left fringe gets the specified width.
 
 @vindex right-divider-width, a frame parameter
 @item right-divider-width
-The width of the right divider (@pxref{Window Dividers}) of any window
-on the frame, in pixels.  A value of zero means to not draw right
-dividers.
+The width (thickness) reserved for the right divider (@pxref{Window
+Dividers}) of any window on the frame, in pixels.  A value of zero means
+to not draw right dividers.
 
 @vindex bottom-divider-width, a frame parameter
 @item bottom-divider-width
-The width of the bottom divider (@pxref{Window Dividers}) of any window
-on the frame, in pixels.  A value of zero means to not draw bottom
-dividers.
+The width (thickness) reserved for the bottom divider (@pxref{Window
+Dividers}) of any window on the frame, in pixels.  A value of zero means
+to not draw bottom dividers.
 
 @vindex menu-bar-lines frame parameter
 @item menu-bar-lines
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 52a1cf5e32..01de4ccb0c 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -107,9 +107,9 @@ Emacs character code.
 @noindent
 See also @code{string-bytes}, in @ref{Text Representations}.
 
-If you need to compute the width of a string on display, you should
-use @code{string-width} (@pxref{Width}), not @code{length}, since
-@code{length} only counts the number of characters, but does not
+If you need to compute the width of a string on display, you should use
+@code{string-width} (@pxref{Size of Displayed Text}), not @code{length},
+since @code{length} only counts the number of characters, but does not
 account for the display width of each character.
 
 @defun elt sequence index
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 5c814b22b2..04e11fec61 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -48,13 +48,13 @@ Vectors}).  Unlike in C, Emacs Lisp strings are @emph{not} terminated
 by a distinguished character code.
 
   Since strings are arrays, and therefore sequences as well, you can
-operate on them with the general array and sequence functions
-documented in @ref{Sequences Arrays Vectors}.  For example, you can
-access or change individual characters in a string using the functions
-@code{aref} and @code{aset} (@pxref{Array Functions}).  However, note
-that @code{length} should @emph{not} be used for computing the width
-of a string on display; use @code{string-width} (@pxref{Width})
-instead.
+operate on them with the general array and sequence functions documented
+in @ref{Sequences Arrays Vectors}.  For example, you can access or
+change individual characters in a string using the functions @code{aref}
+and @code{aset} (@pxref{Array Functions}).  However, note that
+@code{length} should @emph{not} be used for computing the width of a
+string on display; use @code{string-width} (@pxref{Size of Displayed
+Text}) instead.
 
   There are two text representations for non-@acronym{ASCII}
 characters in Emacs strings (and in buffers): unibyte and multibyte.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 5a38ce1e0d..d93f937bd8 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2202,7 +2202,7 @@ count from zero at the left margin.
 
   This section describes the primitive functions used to count and
 insert indentation.  The functions in the following sections use these
-primitives.  @xref{Width}, for related functions.
+primitives.  @xref{Size of Displayed Text}, for related functions.
 
 @defun current-indentation
 @comment !!Type Primitive Function
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index fb022de546..3e1cd40c45 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -618,6 +618,29 @@ argument @var{pixelwise} is passed to the function called.
 @code{window-width} is an alias for @code{window-body-width}.  These
 aliases are considered obsolete and will be removed in the future.
 
+   The pixel heights of a window's mode and header line can be retrieved
+with the functions given below.  Their return value is usually accurate
+unless the window has not been displayed before: In that case, the
+return value is based on an estimate of the font used for the window's
+frame.
+
+@defun window-mode-line-height &optional window
+This function returns the height in pixels of @var{window}'s mode line.
+@var{window} must be a live window and defaults to the selected one.  If
+@var{window} has no mode line, the return value is zero.
+@end defun
+
+@defun window-header-line-height &optional 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
+one.  If @var{window} has no header line, the return value is zero.
+@end defun
+
+Functions for retrieving the height and/or width of window dividers
+(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
+(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
+described in the corresponding sections.
+
 @cindex fixed-size window
 @vindex window-min-height
 @vindex window-min-width
@@ -3476,18 +3499,18 @@ coordinate of the topmost row, the X coordinate one column to the
 right of the rightmost column, and the Y coordinate one row down from
 the bottommost row.
 
-Note that these are the actual outer edges of the window, including
-any header line, mode line, scroll bar, fringes, and display margins.
-On a text terminal, if the window has a neighbor on its right, its
-right edge includes the separator line between the window and its
+Note that these are the actual outer edges of the window, including any
+header line, mode line, scroll bar, fringes, window divider and display
+margins.  On a text terminal, if the window has a neighbor on its right,
+its right edge includes the separator line between the window and its
 neighbor.
 @end defun
 
 @defun window-inside-edges &optional window
 This function is similar to @code{window-edges}, but the returned edge
 values are for the text area of the window.  They exclude any header
-line, mode line, scroll bar, fringes, display margins, and vertical
-separator.
+line, mode line, scroll bar, fringes, window divider, display margins,
+and vertical separator.
 @end defun
 
 @defun window-top-line &optional window
@@ -3536,6 +3559,14 @@ The coordinates are in the mode line of @var{window}.
 @item header-line
 The coordinates are in the header line of @var{window}.
 
+@item right-divider
+The coordinates are in the divider separating @var{window} from a
+window on the right.
+
+@item right-divider
+The coordinates are in the divider separating @var{window} from a
+window beneath.
+
 @item vertical-line
 The coordinates are in the vertical line between @var{window} and its
 neighbor to the right.  This value occurs only if the window doesn't
@@ -3597,6 +3628,17 @@ returns the edge pixel coordinates relative to the top left corner of
 the display screen.  @var{window} must specify a live window.
 @end defun
 
+@defun window-pixel-left &optional window
+This function returns the left pixel edge of window @var{window}.
+@var{window} must be a valid window and defaults to the selected one.
+@end defun
+
+@defun window-pixel-top &optional window
+This function returns the top pixel edge of window @var{window}.
+@var{window} must be a valid window and defaults to the selected one.
+@end defun
+
+
 @node Window Configurations
 @section Window Configurations
 @cindex window configurations