Fix documentation per bug #9949.

 src/window.c (Fwindow_body_size): Mention in the doc string that the
 return value is in frame's canonical units.
 lisp/window.el (window-body-height, window-body-width): Mention in
 the doc string that the return values are in frame's canonical
 units.
 doc/lispref/windows.texi (Window Sizes): Mention in the doc string that the
 return values of `window-body-height' and `window-body-width' are
 in frame's canonical units.

6 files changed, 64 insertions, 14 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 1e86e07998c..2da562bdcfb 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2011-11-04  Eli Zaretskii  <eliz@gnu.org>
+
+        * windows.texi (Window Sizes): Mention in the doc string that the
+        return values of `window-body-height' and `window-body-width' are
+        in frame's canonical units.  (Bug#9949)
+
 2011-10-30  Martin Rudalics  <rudalics@gmx.at>
 
         * windows.texi (Windows and Frames): Remove "iso-" infix from
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 37679aa4a0b..bd20f5d8f44 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -563,8 +563,18 @@ window's body width.
 
 @cindex body size of a window
 @cindex window body size
-The following functions retrieve height and width of the body of a live
-window:
+@cindex canonical units of window/frame size
+The following functions retrieve height and width of the body of a
+live window.  Note that the values these functions return are measured
+in @dfn{canonical units}, i.e.@: for the default frame's face.  If the
+window shows some characters with non-default face, e.g., if the font
+of some characters is larger or smaller than the default font, the
+values returned by these functions will not match the actual number of
+lines or characters per line shown in the window.  To get the actual
+number of columns and lines, move to the last character in the line
+(e.g., with @code{end-of-visual-line}) or to the last line of the
+window (e.g., with @code{window-end}), and use @code{posn-at-point} to
+find the line or column there.
 
 @defun window-body-size &optional window horizontal
 This function returns the number of lines of @var{window}'s text area.
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 6352a65e4fc..eb276721dbc 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2011-11-04  Eli Zaretskii  <eliz@gnu.org>
+
+        * window.el (window-body-height, window-body-width): Mention in
+        the doc string that the return values are in frame's canonical
+        units.  (Bug#9949)
+
 2011-11-03  Alan Mackenzie  <acm@muc.de>
 
         * progmodes/cc-langs.el (c-nonlabel-token-2-key): New variable for
diff --git a/lisp/window.el b/lisp/window.el
index 9b12c204d48..d6ab5e0e6cc 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -972,7 +972,14 @@ The return value does not include WINDOW's mode line and header
 line, if any.  If a line at the bottom of the window is only
 partially visible, that line is included in the return value.  If
 you do not want to include a partially visible bottom line in the
-return value, use `window-text-height' instead."
+return value, use `window-text-height' instead.
+
+Note that the return value is measured in canonical units, i.e. for
+the default frame's face.  If the window shows some characters with
+non-default face, e.g., if the font of some characters is larger or
+smaller than the default font, the value returned by this function
+will not match the actual number of lines shown in the window.  To
+get the actual number of lines, use `posn-at-point'."
   (window-body-size window))
 
 (defsubst window-body-width (&optional window)
@@ -982,7 +989,14 @@ WINDOW must be a live window and defaults to the selected one.
 The return value does not include any vertical dividers or scroll
 bars owned by WINDOW.  On a window-system the return value does
 not include the number of columns used for WINDOW's fringes or
-display margins either."
+display margins either.
+
+Note that the return value is measured in canonical units, i.e. for
+the default frame's face.  If the window shows some characters with
+non-default face, e.g., if the font of some characters is larger or
+smaller than the default font, the value returned by this function
+will not match the actual number of characters per line shown in the
+window.  To get the actual number of columns, use `posn-at-point'."
   (window-body-size window t))
 
 ;; Eventually we should make `window-height' obsolete.
diff --git a/src/ChangeLog b/src/ChangeLog
index f198f37d0c1..ccfcb48daf0 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,8 @@
+2011-11-04  Eli Zaretskii  <eliz@gnu.org>
+
+        * window.c (Fwindow_body_size): Mention in the doc string that the
+        return value is in frame's canonical units.  (Bug#9949)
+
 2011-11-03  Eli Zaretskii  <eliz@gnu.org>
 
         * xdisp.c (note_mouse_highlight): Initialize `area'.  (Bug#9947)
diff --git a/src/window.c b/src/window.c
index 422073b1bd3..6b3b7f2a471 100644
--- a/src/window.c
+++ b/src/window.c
@@ -653,16 +653,25 @@ window_body_cols (struct window *w)
 }
 
 DEFUN ("window-body-size", Fwindow_body_size, Swindow_body_size, 0, 2, 0,
-       doc: /* Return the number of lines of WINDOW's body.
-WINDOW must be a live window and defaults to the selected one.  The
-return value does not include WINDOW's mode line and header line, if
-any.
-
-Optional argument HORIZONTAL non-nil means return the number of columns
-of WINDOW's body.  In this case, the return value does not include any
-vertical dividers or scroll bars owned by WINDOW.  On a window-system
-the return value does not include the number of columns used for
-WINDOW's fringes or display margins either.  */)
+       doc: /* Return the number of lines or columns of WINDOW's body.
+WINDOW must be a live window and defaults to the selected one.
+
+If the optional argument HORIZONTAL is omitted or nil, the function
+returns the number of WINDOW's lines, excluding the mode line and
+header line, if any.
+
+If HORIZONTAL is non-nil, the function returns the number of columns
+excluding any vertical dividers or scroll bars owned by WINDOW.  On a
+window-system the return value also excludes the number of columns
+used for WINDOW's fringes or display margins.
+
+Note that the return value is measured in canonical units, i.e. for
+the default frame's face.  If the window shows some characters with
+non-default face, e.g., if the font of some characters is larger or
+smaller than the default font, the value returned by this function
+will not match the actual number of lines or characters per line
+shown in the window.  To get the actual number of columns and lines,
+use `posn-at-point'.  */)
   (Lisp_Object window, Lisp_Object horizontal)
 {
   struct window *w = decode_any_window (window);