* modes.texi (Precalculated Fontification): Clarify text.

2 files changed, 19 insertions, 12 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 43ee966a463..9bcd9511f78 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2009-05-17  Richard M Stallman  <rms@gnu.org>
+
+	* modes.texi (Precalculated Fontification): Clarify text.
+
 2009-05-17  Martin Rudalics  <rudalics@gmx.at>
 
 	* windows.texi (Selecting Windows): Clarify descriptions of
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index f166877b45c..af20bed18b5 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2864,18 +2864,21 @@ wherever they appear.
 @node Precalculated Fontification
 @subsection Precalculated Fontification
 
-  In addition to using @code{font-lock-defaults} for search-based
-fontification, you may use the special character property
-@code{font-lock-face} (@pxref{Special Properties}).  This property
-acts just like the explicit @code{face} property, but its activation
-is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
-@code{font-lock-face} is especially convenient for special modes
-which construct their text programmatically, such as
-@code{list-buffers} and @code{occur}.
-
-If your mode does not use any of the other machinery of Font Lock
-(i.e. it only uses the @code{font-lock-face} property), it should not
-set the variable @code{font-lock-defaults}.
+  Some major modes such as @code{list-buffers} and @code{occur}
+construct the buffer text programmatically.  The easiest way for them
+to support Font Lock mode is to specify the faces of text when they
+insert the text in the buffer.
+
+  The way to do this is to specify the faces in the text with the
+special text property @code{font-lock-face} (@pxref{Special
+Properties}).  When Font Lock mode is enabled, this property controls
+the display, just like the @code{face} property.  When Font Lock mode
+is disabled, @code{font-lock-face} has no effect on the display.
+
+  It is ok for a mode to use @code{font-lock-face} for some text and
+also use the normal Font Lock machinery.  But if the mode does not use
+the normal Font Lock machinery, it should not set the variable
+@code{font-lock-defaults}.
 
 @node Faces for Font Lock
 @subsection Faces for Font Lock