]> code.delx.au - gnu-emacs/blobdiff - doc/lispref/modes.texi
Add a cross ref to Optional Mode Line
[gnu-emacs] / doc / lispref / modes.texi
index 8d7e29f9eef4a4a598576c16a350a1157537fba0..d2eebb7ddb442087a9093989343335005e0d7b73 100644 (file)
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @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
 @c Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @node Modes
@@ -1912,7 +1912,8 @@ could have the same effects on the mode line if the value of
 @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
 @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
 
 @defvar mode-line-mule-info
 This variable holds the value of the mode line construct that displays
@@ -1943,11 +1944,11 @@ Its default value displays the buffer name, padded with spaces to at
 least 12 columns.
 @end defvar
 
 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.
 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
 
 @defvar vc-mode
 The variable @code{vc-mode}, buffer-local in each buffer, records
@@ -1956,11 +1957,11 @@ and, if so, which kind.  Its value is a string that appears in the mode
 line, or @code{nil} for no version control.
 @end defvar
 
 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.
 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
 
 @defvar mode-line-remote
 This variable is used to show whether @code{default-directory} for the
@@ -2509,6 +2510,53 @@ Search-based fontification happens second.
 @node Font Lock Basics
 @subsection Font Lock Basics
 
 @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
   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
@@ -2516,10 +2564,10 @@ variable.  The value assigned to this variable is used, if and when Font
 Lock mode is enabled, to set all the other variables.
 
 @defvar font-lock-defaults
 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.
 
 Properties} in the menu bar) to assign faces explicitly to text in the
 buffer.
 
@@ -2527,7 +2575,7 @@ If non-@code{nil}, the value should look like this:
 
 @example
 (@var{keywords} [@var{keywords-only} [@var{case-fold}
 
 @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
 @end example
 
 The first element, @var{keywords}, indirectly specifies the value of
@@ -2559,11 +2607,6 @@ fontification; the resulting syntax table is stored in
 @code{nil}, syntactic fontification uses the syntax table returned by
 the @code{syntax-table} function.  @xref{Syntax Table Functions}.
 
 @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
 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
@@ -2941,6 +2984,22 @@ arguments, the beginning and end of the region.  The default value is
 @code{font-lock-default-unfontify-region}.
 @end defvar
 
 @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
 @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
@@ -3124,26 +3183,6 @@ is @code{nil}, syntactic fontification uses the buffer's syntax table
 Table Functions}).
 @end defvar
 
 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).
 @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).