# HG changeset patch
# User Richard M. Stallman <rms@gnu.org>
# Date 1242576562 0
# Node ID 074577abd4d1c262eee803ea1642a9e53535e7f7
# Parent  0c05518365a6a2868f85381586b7ac24a4ea46b2
* modes.texi (Precalculated Fontification): Clarify text.

diff -r 0c05518365a6 -r 074577abd4d1 doc/lispref/ChangeLog
--- a/doc/lispref/ChangeLog	Sun May 17 12:11:18 2009 +0000
+++ b/doc/lispref/ChangeLog	Sun May 17 16:09:22 2009 +0000
@@ -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 -r 0c05518365a6 -r 074577abd4d1 doc/lispref/modes.texi
--- a/doc/lispref/modes.texi	Sun May 17 12:11:18 2009 +0000
+++ b/doc/lispref/modes.texi	Sun May 17 16:09:22 2009 +0000
@@ -2864,18 +2864,21 @@
 @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