[Emacs-diffs] /srv/bzr/emacs/trunk r106283: Fix documentation per bug #9949.

[Eli Zaretskii]

------------------------------------------------------------
revno: 106283
fixes bug(s): http://debbugs.gnu.org/9949
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Fri 2011-11-04 12:09:41 +0200
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/windows.texi
  lisp/ChangeLog
  lisp/window.el
  src/ChangeLog
  src/window.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-10-30 08:29:56 +0000
+++ b/doc/lispref/ChangeLog     2011-11-04 10:09:41 +0000
@@ -1,3 +1,9 @@
+2011-11-04  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * windows.texi (Windows and Frames): Remove "iso-" infix from

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2011-10-30 08:29:56 +0000
+++ b/doc/lispref/windows.texi  2011-11-04 10:09:41 +0000
@@ -563,8 +563,18 @@
 
 @cindex body size of a window
 @cindex window body size
-The following functions retrieve height and width of the body of a live
-window:
address@hidden 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.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-11-03 22:10:02 +0000
+++ b/lisp/ChangeLog    2011-11-04 10:09:41 +0000
@@ -1,3 +1,9 @@
+2011-11-04  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * progmodes/cc-langs.el (c-nonlabel-token-2-key): New variable for

=== modified file 'lisp/window.el'
--- a/lisp/window.el    2011-11-02 12:56:48 +0000
+++ b/lisp/window.el    2011-11-04 10:09:41 +0000
@@ -972,7 +972,14 @@
 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 @@
 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.

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2011-11-03 22:11:40 +0000
+++ b/src/ChangeLog     2011-11-04 10:09:41 +0000
@@ -1,3 +1,8 @@
+2011-11-04  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * xdisp.c (note_mouse_highlight): Initialize `area'.  (Bug#9947)

=== modified file 'src/window.c'
--- a/src/window.c      2011-11-01 16:21:41 +0000
+++ b/src/window.c      2011-11-04 10:09:41 +0000
@@ -653,16 +653,25 @@
 }
 
 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);