Update docs for window dividers and `window-text-pixel-size'.

* xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
* elisp.texi (Top): Rename section "Width" to "Size of Displayed
Text".
* text.texi (Primitive Indent):
* strings.texi (String Basics):
* sequences.texi (Sequence Functions): Update references
accordingly.
* display.texi (Size of Displayed Text): Rename section from
"Width".  Add description for `window-text-pixel-size'.
(Window Dividers): Reword description of window dividers.
* frames.texi (Layout Parameters): Improve description of window
divider parameters.
* windows.texi (Window Sizes): Add descriptions of
`window-mode-line-height' and `window-header-line-height'.
(Coordinates and Windows): Mention window dividers.

2 files changed, 16 insertions, 8 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index 5b75161f91c..af8cd0e492b 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,9 +1,13 @@
+2014-03-09  Martin Rudalics  <rudalics@gmx.at>
+
+        * xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
+
 2014-03-08  Jan Djärv  <jan.h.d@swipnet.se>
 
         * nsterm.h (MAC_OS_X_VERSION_10_9): Add.
 
-        * nsterm.m (constrainFrameRect:toScreen:): Constrain normally when frame
-        is only on one screen (Bug#14713).
+        * nsterm.m (constrainFrameRect:toScreen:): Constrain normally
+        when frame is only on one screen (Bug#14713).
 
 2014-03-08  Eli Zaretskii  <eliz@gnu.org>
 
diff --git a/src/xdisp.c b/src/xdisp.c
index 0216aaea116..b7821eb5048 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -9600,19 +9600,23 @@ character.  TO, if non-nil, specifies the last text position and
 defaults to the maximum accessible position of the buffer.  If TO is t,
 use the maximum accessible position that is not a newline character.
 
-The optional argument X_LIMIT, if non-nil, specifies the maximum text
-width that can be returned.  X_LIMIT nil or omitted, means to use the
+The optional argument X-LIMIT, if non-nil, specifies the maximum text
+width that can be returned.  X-LIMIT nil or omitted, means to use the
 pixel-width of WINDOW's body; use this if you do not intend to change
 the width of WINDOW.  Use the maximum width WINDOW may assume if you
-intend to change WINDOW's width.
+intend to change WINDOW's width.  In any case, text whose x-coordinate
+is beyond X-LIMIT is ignored.  Since calculating the width of long lines
+can take some time, it's always a good idea to make this argument as
+small as possible; in particular, if the buffer contains long lines that
+shall be truncated anyway.
 
-The optional argument Y_LIMIT, if non-nil, specifies the maximum text
+The optional argument Y-LIMIT, if non-nil, specifies the maximum text
 height that can be returned.  Text lines whose y-coordinate is beyond
-Y_LIMIT are ignored.  Since calculating the text height of a large
+Y-LIMIT are ignored.  Since calculating the text height of a large
 buffer can take some time, it makes sense to specify this argument if
 the size of the buffer is unknown.
 
-Optional argument MODE_AND_HEADER_LINE nil or omitted means do not
+Optional argument MODE-AND-HEADER-LINE nil or omitted means do not
 include the height of the mode- or header-line of WINDOW in the return
 value.  If it is either the symbol `mode-line' or `header-line', include
 only the height of that line, if present, in the return value.  If t,