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, 24 insertions, 10 deletions

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);