Improve recently installed documentation

* doc/lispref/display.texi (Size of Displayed Text): Move to
description of 'buffer-text-pixel-size' to preserve previous text;
mention the importance of WINDOW.

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 23418831290d62e0c34ad837b09801c086075518..6b1c52b4859c7a23f8b21a8f2ab2e0add9d5e36c 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2140,21 +2140,6 @@ height of all of these lines, if present, in the return value.
 whole and does not care about the size of individual lines.  The
 following function does.
 
-@defun buffer-text-pixel-size &optional buffer-or-name window from to x-limit y-limit
-This is much like @code{window-text-pixel-size}, but can be used when
-the buffer isn't shown in a window.  (@code{window-text-pixel-size} is
-faster when it is, so this function shouldn't be used in that case.)
-
-@var{buffer-or-name} must specify a live buffer or the name of a live
-buffer and defaults to the current buffer.  @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 pixel-height
-of all the text lines of the buffer specified by @var{buffer-or-name}.
-
-The optional arguments @var{x-limit} and @var{y-limit} have the same
-meaning as with @code{window-text-pixel-size}.
-@end defun
-
 @defun window-lines-pixel-dimensions &optional window first last body inverse left
 This function calculates the pixel dimensions of each line displayed in
 the specified @var{window}.  It does so by walking @var{window}'s
@@ -2216,6 +2201,23 @@ though when this function is run from an idle timer with a delay of zero
 seconds.
 @end defun
 
+@defun buffer-text-pixel-size &optional buffer-or-name window from to x-limit y-limit
+This is much like @code{window-text-pixel-size}, but can be used when
+the buffer isn't shown in a window.  (@code{window-text-pixel-size} is
+faster when it is, so this function shouldn't be used in that case.)
+
+@var{buffer-or-name} must specify a live buffer or the name of a live
+buffer and defaults to the current buffer.  @var{window} must be a
+live window and defaults to the selected one; the function will
+compute the text dimensions as if @var{buffer} is displayed in
+@var{window}.  The return value is a cons of the maximum pixel-width
+of any text line and the pixel-height of all the text lines of the
+buffer specified by @var{buffer-or-name}.
+
+The optional arguments @var{x-limit} and @var{y-limit} have the same
+meaning as with @code{window-text-pixel-size}.
+@end defun
+
 @defun string-pixel-width string
 This is a convenience function that uses @code{window-text-pixel-size}
 to compute the width of @var{string} (in pixels).