@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.
@example
(@var{keywords} [@var{keywords-only} [@var{case-fold}
- [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
+ [@var{syntax-alist} @var{other-vars}@dots{}]]])
@end example
The first element, @var{keywords}, indirectly specifies the value of
@code{nil}, syntactic fontification uses the syntax table returned by
the @code{syntax-table} function. @xref{Syntax Table Functions}.
-The fifth element, @var{syntax-begin}, specifies the value of
-@code{font-lock-beginning-of-syntax-function}. We recommend setting
-this variable to @code{nil} and using @code{syntax-begin-function}
-instead.
-
All the remaining elements (if any) are collectively called
@var{other-vars}. Each of these elements should have the form
@code{(@var{variable} . @var{value})}---which means, make
@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
Table Functions}).
@end defvar
-@defvar font-lock-beginning-of-syntax-function
-If this variable is non-@code{nil}, it should be a function to move
-point back to a position that is syntactically at top level and
-outside of strings or comments. The value is normally set through an
-@var{other-vars} element in @code{font-lock-defaults}. If it is
-@code{nil}, Font Lock uses @code{syntax-begin-function} to move back
-outside of any comment, string, or sexp (@pxref{Position Parse}).
-
-This variable is semi-obsolete; we usually recommend setting
-@code{syntax-begin-function} instead. One of its uses is to tune the
-behavior of syntactic fontification, e.g., to ensure that different
-kinds of strings or comments are highlighted differently.
-
-The specified function is called with no arguments. It should leave
-point at the beginning of any enclosing syntactic block. Typical values
-are @code{beginning-of-line} (used when the start of the line is known
-to be outside a syntactic block), or @code{beginning-of-defun} for
-programming modes, or @code{backward-paragraph} for textual modes.
-@end defvar
-
@defvar font-lock-syntactic-face-function
If this variable is non-@code{nil}, it should be a function to determine
which face to use for a given syntactic element (a string or a comment).