Document new features of Font Lock

* doc/lispref/modes.texi (Other Font Lock Variables): Document
'font-lock-flush-function' and 'font-lock-ensure-function'.
(Font Lock Basics): Document the basic fontification functions
referenced in "Other Font Lock Variables".

* lisp/font-lock.el (font-lock-flush, font-lock-ensure): Doc fix.

3 files changed, 71 insertions, 4 deletions

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index a1747707d1..3b8550e13b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2509,6 +2509,53 @@ Search-based fontification happens second.
 @node Font Lock Basics
 @subsection Font Lock Basics
 
+  The Font Lock functionality is based on several basic functions.
+Each of these calls the function specified by the corresponding
+variable.  This indirection allows major modes to modify the way
+fontification works in the buffers of that mode, and even use the Font
+Lock mechanisms for features that have nothing to do with
+fontification.  (This is why the description below says ``should''
+when it describes what the functions do: the major mode can customize
+the values of the corresponding variables to do something entirely
+different.)  The variables mentioned below are described in @ref{Other
+Font Lock Variables}.
+
+@ftable @code
+@item font-lock-fontify-buffer
+This function should fontify the current buffer's accessible portion,
+by calling the function specified by
+@code{font-lock-fontify-buffer-function}.
+
+@item font-lock-unfontify-buffer
+Used when turning Font Lock off to remove the fontification.  Calls
+the function specified by @code{font-lock-unfontify-buffer-function}.
+
+@item font-lock-fontify-region beg end &optional loudly
+Should fontify the region between @var{beg} and @var{end}.  If
+@var{loudly} is non-@code{nil}, should display status messages while
+fontifying.  Calls the function specified by
+@code{font-lock-fontify-region-function}.
+
+@item font-lock-unfontify-region beg end
+Should remove fontification from the region between @var{beg} and
+@var{end}.  Calls the function specified by
+@code{font-lock-unfontify-region-function}.
+
+@item font-lock-flush &optional beg end
+This function should mark the fontification of the region between
+@var{beg} and @var{end} as outdated.  If not specified or @code{nil},
+@var{beg} and @var{end} default to the beginning and end of the
+buffer's accessible portion.  Calls the function specified by
+@code{font-lock-flush-function}.
+
+@item font-lock-ensure &optional beg end
+This function should make sure the region between @var{beg} and
+@var{end} has been fontified.  The optional arguments @var{beg} and
+@var{end} default to the beginning and the end of the buffer's
+accessible portion.  Calls the function specified by
+@code{font-lock-ensure-function}.
+@end ftable
+
   There are several variables that control how Font Lock mode highlights
 text.  But major modes should not set any of these variables directly.
 Instead, they should set @code{font-lock-defaults} as a buffer-local
@@ -2936,6 +2983,22 @@ arguments, the beginning and end of the region.  The default value is
 @code{font-lock-default-unfontify-region}.
 @end defvar
 
+@defvar font-lock-flush-function
+Function to use for declaring that a region's fontification is out of
+date.  It takes two arguments, the beginning and end of the region.
+The default value of this variable is
+@code{font-lock-after-change-function}.
+@end defvar
+
+@defvar font-lock-ensure-function
+Function to use for making sure a region of the current buffer has
+been fontified.  It is called with two arguments, the beginning and
+end of the region.  The default value of this variable is a function
+that calls @code{font-lock-default-fontify-buffer} if the buffer is
+not fontified; the effect is to make sure the entire accessible
+portion of the buffer is fontified.
+@end defvar
+
 @defun jit-lock-register function &optional contextual
 This function tells Font Lock mode to run the Lisp function
 @var{function} any time it has to fontify or refontify part of the
diff --git a/etc/NEWS b/etc/NEWS
index 3a219851ff..5f19c40972 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -642,8 +642,10 @@ respectively, `show-paren-when-point-inside-paren' or
 *** C-x C-x in rectangle-mark-mode now cycles through the four corners.
 *** `string-rectangle' provides on-the-fly preview of the result.
 
-** New font-lock functions font-lock-ensure and font-lock-flush, which
-should be used instead of font-lock-fontify-buffer when called from Elisp.
++++
+** New font-lock functions `font-lock-ensure' and `font-lock-flush'.
+These should be used in preference to `font-lock-fontify-buffer' when
+called from Lisp.
 
 ** Macro `minibuffer-with-setup-hook' takes (:append FUN) to mean
 appending FUN to `minibuffer-setup-hook'.
diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 762720d5ba..93d677c67e 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -1065,7 +1065,8 @@ Called with two arguments BEG and END.")
 
 (defun font-lock-flush (&optional beg end)
   "Declare the region BEG...END's fontification as out-of-date.
-If the region is not specified, it defaults to the whole buffer."
+If the region is not specified, it defaults to the entire
+accessible portion of the current buffer."
   (and font-lock-mode
        font-lock-fontified
        (funcall font-lock-flush-function
@@ -1079,7 +1080,8 @@ Called with two arguments BEG and END.")
 
 (defun font-lock-ensure (&optional beg end)
   "Make sure the region BEG...END has been fontified.
-If the region is not specified, it defaults to the whole buffer."
+If the region is not specified, it defaults to the entire accessible
+portion of the buffer."
   (font-lock-set-defaults)
   (funcall font-lock-ensure-function
            (or beg (point-min)) (or end (point-max))))