changeset 69469:cc34fffac608

* modes.texi: New node, "Region to Fontify" (for Font Lock). This describes font-lock-extend-region-function. ("Other Font Lock Variables"): move "font-lock-lines-before" to the new node "Region to Fontify".

--- a/lispref/modes.texi	Tue Mar 14 18:23:47 2006 +0000
+++ b/lispref/modes.texi	Tue Mar 14 18:30:48 2006 +0000
@@ -2337,6 +2337,8 @@
 * Font Lock Basics::            Overview of customizing Font Lock.
 * Search-based Fontification::  Fontification based on regexps.
 * Customizing Keywords::        Customizing search-based fontification.
+* Region to Fontify::           Controlling which region gets refontified
+                                  after a buffer change.
 * Other Font Lock Variables::   Additional customization facilities.
 * Levels of Font Lock::         Each mode can define alternative levels
                                   so that the user can select more or less.
@@ -2717,6 +2719,46 @@
       font-lock-keyword-face)))))
 @end smallexample
 
+@node Region to Fontify
+@subsection Region to Fontify after a Buffer Change
+
+  When a buffer is changed, the region that Font Lock refontifies is by
+default the smallest sequence of whole lines that spans the change.
+While this works well most of the time, sometimes it doesn't---for
+example, when a buffer change has changed the syntactic meaning of text
+on an earlier line.
+
+You can enlarge (or even reduce) the region to fontify by setting either
+of the following variables:
+
+@defvar font-lock-lines-before
+This variable specifies the number of extra lines to consider when
+refontifying the buffer after each text change.  Font lock begins
+refontifying from that number of lines before the changed region.  The
+default is 0, but using a larger value can be useful for coping with
+multi-line patterns.  This variable is ignored whenever
+@code{font-lock-extend-region-function} is set and returns a
+non-@code{nil} value.
+@end defvar
+
+@defvar font-lock-extend-region-function
+This buffer-local variable is either @code{nil} or is a function that
+determines the region to fontify, which Emacs then calls after each
+buffer change.
+
+The function is given three parameters, the standard @var{beg},
+@var{end}, and @var{old-len} from after-change-functions (@pxref{Change
+Hooks}).  It should return either a cons of the beginning and end buffer
+positions (in that order) of the region to fontify, or @code{nil} (which
+directs the caller to fontify the default region).  This function need
+not preserve point or the match-data, but must preserve the current
+restriction.  The region it returns may start or end in the middle of a
+line.
+
+Since this function is called after every buffer change, it should be
+reasonably fast.
+@end defvar
+
 @node Other Font Lock Variables
 @subsection Other Font Lock Variables
 
@@ -2772,14 +2814,6 @@
 @code{font-lock-default-unfontify-region}.
 @end defvar
 
-@defvar font-lock-lines-before
-This variable specifies the number of extra lines to consider when
-refontifying the buffer after each text change.  Font lock begins
-refontifying from that number of lines before the changed region.  The
-default is 0, but using a larger value can be useful for coping with
-multi-line patterns.
-@end defvar
-
 @ignore
 @defvar font-lock-inhibit-thing-lock
 List of Font Lock mode related modes that should not be turned on.