Commit 277d7efd authored by Eli Zaretskii's avatar Eli Zaretskii

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.
parent d30c30b0
......@@ -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
......
......@@ -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'.
......
......@@ -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))))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment