@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Modes
@code{mode-line-format} is changed to use them. However, various parts
of Emacs set these variables on the understanding that they will control
parts of the mode line; therefore, practically speaking, it is essential
-for the mode line to use them.
+for the mode line to use them. Also see
+@ref{Optional Mode Line,,, emacs, The GNU Emacs Manual}.
@defvar mode-line-mule-info
This variable holds the value of the mode line construct that displays
least 12 columns.
@end defvar
-@defopt mode-line-position
+@defvar mode-line-position
This variable indicates the position in the buffer. Its default value
displays the buffer percentage and, optionally, the buffer size, the
line number and the column number.
-@end defopt
+@end defvar
@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
line, or @code{nil} for no version control.
@end defvar
-@defopt mode-line-modes
+@defvar mode-line-modes
This variable displays the buffer's major and minor modes. Its
default value also displays the recursive editing level, information
on the process status, and whether narrowing is in effect.
-@end defopt
+@end defvar
@defvar mode-line-remote
This variable is used to show whether @code{default-directory} for the
@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 and minor 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 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
Lock mode is enabled, to set all the other variables.
@defvar font-lock-defaults
-This variable is set by major modes to specify how to fontify text in
-that mode. It automatically becomes buffer-local when set. If its
-value is @code{nil}, Font Lock mode does no highlighting, and you can
-use the @samp{Faces} menu (under @samp{Edit} and then @samp{Text
+This variable is set by modes to specify how to fontify text in that
+mode. It automatically becomes buffer-local when set. If its value
+is @code{nil}, Font Lock mode does no highlighting, and you can use
+the @samp{Faces} menu (under @samp{Edit} and then @samp{Text
Properties} in the menu bar) to assign faces explicitly to text in the
buffer.
@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