X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/31ff037ab849a8d5d9b871a8927154ffb38a8694..a3151a28789f413af73b14fbba557b2a587fca53:/doc/lispref/modes.texi diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 8d7e29f9ee..d2eebb7ddb 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1,6 +1,6 @@ @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 @@ -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 -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 @@ -1943,11 +1944,11 @@ Its default value displays the buffer name, padded with spaces to at 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 @@ -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 -@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 @@ -2509,6 +2510,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 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 @@ -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 -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. @@ -2527,7 +2575,7 @@ If non-@code{nil}, the value should look like this: @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 @@ -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}. -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 @@ -2941,6 +2984,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 @@ -3124,26 +3183,6 @@ is @code{nil}, syntactic fontification uses the buffer's syntax table 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).