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.

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index ff42ceaf9c661402b9f69354e68f2a28350b368b..71540742bac25acb0d816663fddf84114c697e83 100644 (file)
--- 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 a66f07e1a99ba83131a0ee06fbcd2312431d37d1..53aeb0a2d6d0d82e69ad98a824addeb8540a8915 100644 (file)
--- 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