@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 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
@defun run-hook-with-args-until-failure hook &rest args
This function runs an abnormal hook by calling each hook function in
-turn, stopping if one of them ``fails'' by returning @code{nil}. Each
+turn, stopping if one of them fails by returning @code{nil}. Each
hook function is passed the arguments @var{args}. If this function
stops because one of the hook functions fails, it returns @code{nil};
otherwise it returns a non-@code{nil} value.
@defun run-hook-with-args-until-success hook &rest args
This function runs an abnormal hook by calling each hook function,
-stopping if one of them ``succeeds'' by returning a non-@code{nil}
+stopping if one of them succeeds by returning a non-@code{nil}
value. Each hook function is passed the arguments @var{args}. If this
function stops because one of the hook functions returns a
non-@code{nil} value, it returns that value; otherwise it returns
A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
-be some kind of ``moving forward and backward'', but this does not
+be some kind of moving forward and backward, but this does not
necessarily mean cursor motion.
It is legitimate for a major mode to rebind a standard key sequence if
-it provides a command that does ``the same job'' in a way better
+it provides a command that does the same job in a way better
suited to the text this mode is used for. For example, a major mode
for editing a programming language might redefine @kbd{C-M-a} to
-``move to the beginning of a function'' in a way that works better for
+move to the beginning of a function in a way that works better for
that language.
It is also legitimate for a major mode to rebind a standard key
@item
The new mode has its own mode hook, @code{@var{variant}-hook}. It
runs this hook, after running the hooks of its ancestor modes, with
-@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
+@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
@end itemize
In addition, you can specify how to override other aspects of
way, specifying @code{tabulated-list-mode} as the second argument
(@pxref{Derived Modes}). The body of the @code{define-derived-mode}
form should specify the format of the tabulated data, by assigning
-values to the variables documented below; then, it should call the
-function @code{tabulated-list-init-header} to initialize the header
-line.
+values to the variables documented below; optionally, it can then call
+the function @code{tabulated-list-init-header}, which will populate a
+header with the names of the columns.
The derived mode should also define a @dfn{listing command}. This,
not the mode command, is what the user calls (e.g., @kbd{M-x
@itemize
@item
@var{id} is either @code{nil}, or a Lisp object that identifies the
-entry. If the latter, the cursor stays on the ``same'' entry when
+entry. If the latter, the cursor stays on the same entry when
re-sorting entries. Comparison is done with @code{equal}.
@item
@code{tabulated-list-format}).
@end defun
-@defun tabulated-list-print &optional remember-pos
+@defun tabulated-list-print &optional remember-pos update
This function populates the current buffer with entries. It should be
called by the listing command. It erases the buffer, sorts the entries
specified by @code{tabulated-list-entries} according to
If the optional argument @var{remember-pos} is non-@code{nil}, this
function looks for the @var{id} element on the current line, if any, and
tries to move to that entry after all the entries are (re)inserted.
+
+If the optional argument @var{update} is non-@code{nil}, this function
+will only erase or add entries that have changed since the last print.
+This is several times faster if most entries haven't changed since the
+last time this function was called. The only difference in outcome is
+that tags placed via @code{tabulated-list-put-tag} will not be removed
+from entries that haven't changed (normally all tags are removed).
@end defun
@node Generic Modes
The argument @var{comment-list} is a list in which each element is
either a character, a string of one or two characters, or a cons cell.
A character or a string is set up in the mode's syntax table as a
-``comment starter''. If the entry is a cons cell, the @sc{car} is set
-up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''.
+comment starter. If the entry is a cons cell, the @sc{car} is set
+up as a comment starter and the @sc{cdr} as a comment ender.
(Use @code{nil} for the latter if you want comments to end at the end
of the line.) Note that the syntax table mechanism has limitations
about what comment starters and enders are actually possible.
(let ((st (make-syntax-table)))
(modify-syntax-entry ?\" ". " st)
(modify-syntax-entry ?\\ ". " st)
- ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
+ ;; Add 'p' so M-c on 'hello' leads to 'Hello', not 'hello'.
(modify-syntax-entry ?' "w p" st)
st)
"Syntax table used while in `text-mode'.")
disables it. From Lisp, an argument of @code{toggle} toggles the mode,
whereas an omitted or @code{nil} argument enables the mode.
This makes it easy to enable the minor mode in a major mode hook, for example.
-If @var{doc} is nil, the macro supplies a default documentation string
+If @var{doc} is @code{nil}, the macro supplies a default documentation string
explaining the above.
By default, it also defines a variable named @var{mode}, which is set to
There is one exception: if the value of @var{symbol} is a string, it is
displayed verbatim: the @code{%}-constructs are not recognized.
-Unless @var{symbol} is marked as ``risky'' (i.e., it has a
+Unless @var{symbol} is marked as risky (i.e., it has a
non-@code{nil} @code{risky-local-variable} property), all text
properties specified in @var{symbol}'s value are ignored. This includes
the text properties of strings in @var{symbol}'s value, as well as all
@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
@defvar imenu-prev-index-position-function
If this variable is non-@code{nil}, its value should be a function that
-finds the next ``definition'' to put in the buffer index, scanning
+finds the next definition to put in the buffer index, scanning
backward in the buffer from point. It should return @code{nil} if it
-doesn't find another ``definition'' before point. Otherwise it should
-leave point at the place it finds a ``definition'' and return any
+doesn't find another definition before point. Otherwise it should
+leave point at the place it finds a definition and return any
non-@code{nil} value.
Setting this variable makes it buffer-local in the current buffer.
@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
@code{font-lock-comment-face} is @code{font-lock-comment-face}.
The faces are listed with descriptions of their typical usage, and in
-order of greater to lesser ``prominence''. If a mode's syntactic
+order of greater to lesser prominence. If a mode's syntactic
categories do not fit well with the usage descriptions, the faces can be
assigned using the ordering as a guide.
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).
incorrect code.
Good maintainable indentation functions usually fall into two categories:
-either parsing forward from some ``safe'' starting point until the
+either parsing forward from some safe starting point until the
position of interest, or parsing backward from the position of interest.
Neither of the two is a clearly better choice than the other: parsing
backward is often more difficult than parsing forward because
programming languages are designed to be parsed forward, but for the
purpose of indentation it has the advantage of not needing to
-guess a ``safe'' starting point, and it generally enjoys the property
+guess a safe starting point, and it generally enjoys the property
that only a minimum of text will be analyzed to decide the indentation
of a line, so indentation will tend to be less affected by syntax errors in
some earlier unrelated piece of code. Parsing forward on the other hand
@cindex SMIE
SMIE is a package that provides a generic navigation and indentation
-engine. Based on a very simple parser using an ``operator precedence
-grammar'', it lets major modes extend the sexp-based navigation of Lisp
+engine. Based on a very simple parser using an operator precedence
+grammar, it lets major modes extend the sexp-based navigation of Lisp
to non-Lisp languages as well as provide a simple to use but reliable
auto-indentation.
transpose the two arguments of a @code{+} operator, taking into account
the precedence rules of the language.
-Calling `smie-setup' is also sufficient to make TAB indentation work in
+Calling @code{smie-setup} is also sufficient to make TAB indentation work in
the expected way, extends @code{blink-matching-paren} to apply to
elements like @code{begin...end}, and provides some commands that you
can bind in the major mode keymap.
Notice how those lexers return the empty string when in front of
parentheses. This is because SMIE automatically takes care of the
parentheses defined in the syntax table. More specifically if the lexer
-returns nil or an empty string, SMIE tries to handle the corresponding
+returns @code{nil} or an empty string, SMIE tries to handle the corresponding
text as a sexp according to syntax tables.
@node SMIE Tricks
block).
@var{method} should be the method name that was passed to
-`smie-rules-function'.
+@code{smie-rules-function}.
@end defun
@node SMIE Indentation Example