master 7433e74 1/2: Improve documentation of pixel-fill

[Eli Zaretskii]

branch: master
commit 7433e7457118841b4820cd865fb60b247ba97ef0
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of pixel-fill
    
    * doc/lispref/text.texi (Filling): Describe the arguments of
    'pixel-fill-region'.  Add index entry.
    
    * lisp/textmodes/pixel-fill.el (pixel-fill-region): Doc fix.
---
 doc/lispref/text.texi        | 18 +++++++++++++-----
 lisp/textmodes/pixel-fill.el |  5 +++--
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index ff42cea..7154074 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1656,9 +1656,15 @@ Most Emacs buffers use monospaced text, so all the 
filling functions
 (like @code{fill-region}) work based on the number of characters and
 @code{char-width}.  However, Emacs can render other types of things,
 like text that contains images and using proportional fonts, and the
-@code{pixel-fill-region} exists to handle that.  For instance, this
-Lisp snippet will insert text using a proportional font, and then fill
-this to be no wider than 300 pixels:
+@code{pixel-fill-region} exists to handle that.  It fills the region
+of text between @var{start} and @var{end} at pixel granularity, so
+text using variable-pitch fonts or several different fonts looks
+filled regardless of different character sizes.  The argument
+@var{pixel-width} specifies the maximum pixel width a line is allowed
+to have aftder filling; it is the pixel-resolution equivalent of the
+@code{fill-column} in @code{fill-region}.  For instance, this Lisp
+snippet will insert text using a proportional font, and then fill this
+to be no wider than 300 pixels:
 
 @lisp
 (insert (propertize
@@ -1667,9 +1673,11 @@ this to be no wider than 300 pixels:
 (pixel-fill-region (point) (point-max) 300)
 @end lisp
 
-If @var{start} isn't at the start of a line, that pixel position will
-be used as the indentation prefix on subsequent lines.
+If @var{start} isn't at the start of a line, the horizontal position
+of @var{start}, converted to pixel units, will be used as the
+indentation prefix on subsequent lines.
 
+@findex pixel-fill-width
 The @code{pixel-fill-width} helper function can be used to compute the
 pixel width to use.  If given no arguments, it'll return a value
 slightly less than the width of the current window.  The first
diff --git a/lisp/textmodes/pixel-fill.el b/lisp/textmodes/pixel-fill.el
index a66f07e..53aeb0a 100644
--- a/lisp/textmodes/pixel-fill.el
+++ b/lisp/textmodes/pixel-fill.el
@@ -70,8 +70,9 @@ If WINDOW is nil, this defaults to the current window."
 This will attempt to reformat the text in the region to have no
 lines that are visually wider than PIXEL-WIDTH.
 
-If START isn't at the start of a line, that pixel position will
-be used as the indentation prefix on subsequent lines."
+If START isn't at the start of a line, the horizontal position of
+START, converted to pixel units, will be used as the indentation
+prefix on subsequent lines."
   (save-excursion
     (goto-char start)
     (let ((indentation