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.

2 files changed, 22 insertions, 2 deletions

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.