@table @code
@item :group @var{group}
Custom group name to use in all generated @code{defcustom} forms.
-Defaults to @var{mode} without the possible trailing @samp{-mode}. Be
-aware that this default may not be a valid customization group defined
-with @code{defgroup}. Please make sure it is.
+Defaults to @var{mode} without the possible trailing @samp{-mode}.
+@strong{Warning:} don't use this default group name unless you have
+written a @code{defgroup} to define that group properly. @xref{Group
+Definitions}.
@item :global @var{global}
If non-@code{nil} specifies that the minor mode should be global.
which contexts. This section explains how to customize Font Lock for a
particular major mode.
- Font Lock mode finds text to highlight in two ways: through syntactic
-parsing based on the syntax table, and through searching (usually for
-regular expressions). Syntactic fontification happens first; it finds
-comments and string constants, and highlights them using
-@code{font-lock-comment-face} and @code{font-lock-string-face}
-(@pxref{Faces for Font Lock}). Search-based fontification follows.
+ Font Lock mode finds text to highlight in two ways: through
+syntactic parsing based on the syntax table, and through searching
+(usually for regular expressions). Syntactic fontification happens
+first; it finds comments and string constants and highlights them.
+Search-based fontification happens second.
@menu
* Font Lock Basics:: Overview of customizing Font Lock.
* Precalculated Fontification:: How Lisp programs that produce the buffer
contents can also specify how to fontify it.
* Faces for Font Lock:: Special faces specifically for Font Lock.
-* Syntactic Font Lock:: Defining character syntax based on context
+* Syntactic Font Lock:: Fontification based on syntax tables.
+* Setting Syntax Properties:: Defining character syntax based on context
using the Font Lock mechanism.
@end menu
@defvar font-lock-defaults
This variable is set by major modes, as a buffer-local variable, to
-specify how to fontify text in that mode. The value should look like
-this:
+specify how to fontify text in that mode. It automatically becomes
+buffer-local when you set it. 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{keywords} [@var{keywords-only} [@var{case-fold}
+ [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
@end example
The first element, @var{keywords}, indirectly specifies the value of
-@code{font-lock-keywords}. It can be a symbol, a variable whose value
-is the list to use for @code{font-lock-keywords}. It can also be a list of
-several such symbols, one for each possible level of fontification. The
-first symbol specifies how to do level 1 fontification, the second
-symbol how to do level 2, and so on.
+@code{font-lock-keywords} which directs search-based fontification.
+It can be a symbol, a variable or a function whose value is the list
+to use for @code{font-lock-keywords}. It can also be a list of
+several such symbols, one for each possible level of fontification.
+The first symbol specifies how to do level 1 fontification, the second
+symbol how to do level 2, and so on. @xref{Levels of Font Lock}.
The second element, @var{keywords-only}, specifies the value of the
variable @code{font-lock-keywords-only}. If this is non-@code{nil},
syntactic fontification (of strings and comments) is not performed.
+@xref{Syntactic Font Lock}.
The third element, @var{case-fold}, specifies the value of
-@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, Font Lock
-mode ignores case when searching as directed by
+@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
+Font Lock mode ignores case when searching as directed by
@code{font-lock-keywords}.
-If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
-a list of cons cells of the form @code{(@var{char-or-string}
+If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
+should be a list of cons cells of the form @code{(@var{char-or-string}
. @var{string})}. These are used to set up a syntax table for
-fontification (@pxref{Syntax Table Functions}). The resulting syntax
-table is stored in @code{font-lock-syntax-table}.
+syntactic fontification (@pxref{Syntax Table Functions}). The
+resulting syntax table is stored in @code{font-lock-syntax-table}.
The fifth element, @var{syntax-begin}, specifies the value of
-@code{font-lock-beginning-of-syntax-function} (see below).
+@code{font-lock-beginning-of-syntax-function}.
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 @var{variable}
-buffer-local and then set it to @var{value}. You can use these
-@var{other-vars} to set other variables that affect fontification,
-aside from those you can control with the first five elements.
+@code{(@var{variable} . @var{value})}---which means, make
+@var{variable} buffer-local and then set it to @var{value}. You can
+use these @var{other-vars} to set other variables that affect
+fontification, aside from those you can control with the first five
+elements. @xref{Other Font Lock Variables}.
@end defvar
@node Search-based Fontification
The most important variable for customizing Font Lock mode is
@code{font-lock-keywords}. It specifies the search criteria for
-search-based fontification.
+search-based fontification. You should specify the value of this
+variable with @var{keywords} in @code{font-lock-defaults}.
@defvar font-lock-keywords
This variable's value is a list of the keywords to highlight. Be
@code{font-lock-extra-managed-props} so that the properties will also
be cleared out when they are no longer appropriate. Alternatively,
you can set the variable @code{font-lock-unfontify-region-function} to
-a function that clears these properties.
+a function that clears these properties. @xref{Other Font Lock
+Variables}.
@item (@var{matcher} . @var{subexp-highlighter})
In this kind of element, @var{subexp-highlighter} is a list
Its value should have one of the forms described in this table.
@end table
+@vindex font-lock-multiline
@strong{Warning:} Do not design an element of @code{font-lock-keywords}
to match text which spans lines; this does not work reliably. While
@code{font-lock-fontify-buffer} handles multi-line patterns correctly,
setting @code{font-lock-multiline} to @code{t}. But it still will not
work in all cases.
-@node Other Font Lock Variables
-@subsection Other Font Lock Variables
-
- This section describes additional variables that a major mode
-can set by means of @code{font-lock-defaults}.
-
-@defvar font-lock-keywords-only
-Non-@code{nil} means Font Lock should not fontify comments or strings
-syntactically; it should only fontify based on
-@code{font-lock-keywords}.
-@end defvar
-
-@ignore
-Other variables include those for buffer-specialized fontification functions,
-`font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
-`font-lock-fontify-region-function', `font-lock-unfontify-region-function',
-`font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
-@end ignore
+You can use @var{case-fold} in @code{font-lock-defaults} to specify
+the value of @code{font-lock-keywords-case-fold-search} which says
+whether search-based fontification should be case-insensitive.
@defvar font-lock-keywords-case-fold-search
Non-@code{nil} means that regular expression matching for the sake of
@code{font-lock-keywords} should be case-insensitive.
@end defvar
-@defvar font-lock-syntax-table
-This variable specifies the syntax table to use for fontification of
-comments and strings.
-@end defvar
+You can use @code{font-lock-add-keywords} to add additional
+search-based fontification rules to a major mode, and
+@code{font-lock-remove-keywords} to removes rules.
+
+@defun font-lock-add-keywords mode keywords &optional append
+This function adds highlighting @var{keywords} for @var{mode}. The
+argument @var{keywords} should be a list with the same format as the
+variable @code{font-lock-keywords}. @var{mode} should be a symbol,
+the major mode command name, such as @code{c-mode}. When Font Lock
+mode is turned on in @var{mode}, it adds @var{keywords} to
+@code{font-lock-keywords}. @var{mode} can also be @code{nil}; the
+highlighting @var{keywords} are immediately added to
+@code{font-lock-keywords} in the current buffer in that case.
+
+By default, @var{keywords} are added at the beginning of
+@code{font-lock-keywords}. If the optional argument @var{append} is
+@code{set}, they are used to replace the value of
+@code{font-lock-keywords}. If @var{append} is any other
+non-@code{nil} value, they are added at the end of
+@code{font-lock-keywords}.
-@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. Font Lock uses this when necessary
-to get the right results for syntactic fontification.
+For example:
-This 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} (i.e., 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 (i.e., the
-mode-dependent function is known to move outside a syntactic block).
+@smallexample
+(font-lock-add-keywords 'c-mode
+ '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
+ ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
+@end smallexample
-If the value is @code{nil}, the beginning of the buffer is used as a
-position outside of a syntactic block. This cannot be wrong, but it can
-be slow.
-@end defvar
+adds two fontification patterns for C mode: one to fontify the word
+@samp{FIXME}, even in comments, and another to fontify the words
+@samp{and}, @samp{or} and @samp{not} as keywords.
+
+Some modes have specialized support for additional patterns. See the
+variables @code{c-font-lock-extra-types},
+@code{c++-font-lock-extra-types}, @code{objc-font-lock-extra-types}
+and @code{java-font-lock-extra-types}, for example.
+@end defun
+
+@defun font-lock-remove-keywords mode keywords
+This function removes highlighting @var{keywords} for @var{mode}. As
+in @code{font-lock-add-keywords}, @var{mode} should be a major mode
+command name or @code{nil}. If @code{nil}, the highlighting
+@var{keywords} are immediately removed in the current buffer.
+@end defun
+
+@strong{Warning:} Only use a non-@code{nil} @var{mode} argument when
+you use @code{font-lock-add-keywords} or
+@code{font-lock-remove-keywords} in your @file{.emacs} file. When you
+use these functions from a Lisp program (such as a minor mode), we
+recommend that you use @code{nil} for @var{mode} (and place the call
+on a hook) to avoid subtle problems due to the details of the
+implementation.
+
+@node Other Font Lock Variables
+@subsection Other Font Lock Variables
+
+ This section describes additional variables that a major mode can
+set by means of @var{other-vars} in @code{font-lock-defaults}
+(@pxref{Font Lock Basics}).
@defvar font-lock-mark-block-function
If this variable is non-@code{nil}, it should be a function that is
@end defvar
@defvar font-lock-extra-managed-props
-Additional properties (other than @code{font-lock-face}) that are
-being managed by Font Lock mode. Font Lock mode normally manages only
-the @code{font-lock-face} property; if you want it to manage others as
-well, you must specify them in a @var{facespec} in
-@code{font-lock-keywords} as well as adding them to this list.
+This variable specifies additional properties (other than
+@code{font-lock-face}) that are being managed by Font Lock mode. It
+is used by @code{font-lock-default-unfontify-region}, which normally
+only manages the @code{font-lock-face} property. If you want Font
+Lock to manage other properties as well, you must specify them in a
+@var{facespec} in @code{font-lock-keywords} as well as add them to
+this list. @xref{Search-based Fontification}.
@end defvar
-@defvar font-lock-syntactic-face-function
-A function to determine which face to use for a given syntactic
-element (a string or a comment). The function is called with one
-argument, the parse state at point returned by
-@code{parse-partial-sexp}, and should return a face. The default
-value returns @code{font-lock-comment-face} for comments and
-@code{font-lock-string-face} for strings.
+@defvar font-lock-fontify-buffer-function
+Function to use for fontifying the buffer. The default value is
+@code{font-lock-default-fontify-buffer}.
+@end defvar
-This can be used to highlighting different kinds of strings or
-comments differently. It is also sometimes abused together with
-@code{font-lock-syntactic-keywords} to highlight elements that span
-multiple lines, but this is too obscure to document in this manual.
+@defvar font-lock-unfontify-buffer-function
+Function to use for unfontifying the buffer. This is used when
+turning off Font Lock mode. The default value is
+@code{font-lock-default-unfontify-buffer}.
+@end defvar
+
+@defvar font-lock-fontify-region-function
+Function to use for fontifying a region. It should take two
+arguments, the beginning and end of the region, and an optional third
+argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
+function should print status messages. The default value is
+@code{font-lock-default-fontify-region}.
+@end defvar
+
+@defvar font-lock-unfontify-region-function
+Function to use for unfontifying a region. It should take two
+arguments, the beginning and end of the region. The default value is
+@code{font-lock-default-unfontify-region}.
@end defvar
@defvar font-lock-lines-before
multi-line patterns.
@end defvar
+@ignore
+@defvar font-lock-inhibit-thing-lock
+List of Font Lock mode related modes that should not be turned on.
+Currently, valid mode names are @code{fast-lock-mode},
+@code{jit-lock-mode} and @code{lazy-lock-mode}.
+@end defvar
+@end ignore
+
@node Levels of Font Lock
@subsection Levels of Font Lock
@code{list-buffers} and @code{occur}.
If your mode does not use any of the other machinery of Font Lock
-(i.e. it only uses the @code{font-lock-face} property), you can tell
-Emacs not to load all of font-lock.el (unless it's already loaded), by
-setting the variable @code{font-lock-core-only} to non-@code{nil} as
-part of the @code{font-lock-defaults} settings. Here is the canonical
-way to do this:
-
-@example
-(set (make-local-variable 'font-lock-defaults)
- '(nil t nil nil nil (font-lock-core-only . t)))
-@end example
+(i.e. it only uses the @code{font-lock-face} property), it should not
+set the variable @code{font-lock-defaults}. That way, it will not
+cause loading of the @file{font-lock} library.
@node Faces for Font Lock
@subsection Faces for Font Lock
@vindex font-lock-comment-face
Used (typically) for comments.
+@item font-lock-comment-delimiter-face
+@vindex font-lock-comment-delimiter-face
+Used (typically) for comments delimiters.
+
@item font-lock-doc-face
@vindex font-lock-doc-face
Used (typically) for documentation strings in the code.
@node Syntactic Font Lock
@subsection Syntactic Font Lock
+Syntactic fontification uses the syntax table to find comments and
+string constants (@pxref{Syntax Tables}). It highlights them using
+@code{font-lock-comment-face} and @code{font-lock-string-face}
+(@pxref{Faces for Font Lock}). There are several variables that
+affect syntactic fontification; you should set them by means of
+@code{font-lock-defaults} (@pxref{Font Lock Basics}).
+
+@defvar font-lock-keywords-only
+Non-@code{nil} means Font Lock should not do syntactic fontification;
+it should only fontify based on @code{font-lock-keywords}. The normal
+way for a mode to set this variable to @code{t} is with
+@var{keywords-only} in @code{font-lock-defaults}.
+@end defvar
+
+@defvar font-lock-syntax-table
+This variable holds the syntax table to use for fontification of
+comments and strings. Specify it using @var{syntax-alist} in
+@code{font-lock-defaults}.
+@end defvar
+
+@c ???
+@c The docstring says that font-lock-syntax-table is semi-obsolete.
+@c How the alternative should be used is not clear. --lute
+
+@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. Font Lock uses this when necessary
+to get the right results for syntactic fontification.
+
+This 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.
+
+If the value is @code{nil}, the beginning of the buffer is used as a
+position outside of a syntactic block. This cannot be wrong, but it
+can be slow.
+
+Specify this variable using @var{syntax-begin} in
+@code{font-lock-defaults}.
+@end defvar
+
+@defvar font-lock-syntactic-face-function
+A function to determine which face to use for a given syntactic
+element (a string or a comment). The function is called with one
+argument, the parse state at point returned by
+@code{parse-partial-sexp}, and should return a face. The default
+value returns @code{font-lock-comment-face} for comments and
+@code{font-lock-string-face} for strings.
+
+This can be used to highlighting different kinds of strings or
+comments differently. It is also sometimes abused together with
+@code{font-lock-syntactic-keywords} to highlight elements that span
+multiple lines, but this is too obscure to document in this manual.
+
+Specify this variable using @var{other-vars} in
+@code{font-lock-defaults}.
+@end defvar
+
+@node Setting Syntax Properties
+@subsection Setting Syntax Properties
+
Font Lock mode can be used to update @code{syntax-table} properties
-automatically. This is useful in languages for which a single syntax
-table by itself is not sufficient.
+automatically (@pxref{Syntax Properties}). This is useful in
+languages for which a single syntax table by itself is not sufficient.
@defvar font-lock-syntactic-keywords
-This variable enables and controls syntactic Font Lock. It is
-normally set via @code{font-lock-defaults}. Its value should be a
-list of elements of this form:
+This variable enables and controls updating @code{syntax-table}
+properties by Font Lock. Its value should be a list of elements of
+this form:
@example
(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
sort of element of @code{font-lock-keywords},
@example
-(@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
+(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
@end example
-However, instead of specifying the value @var{facename} to use for the
+However, instead of specifying the value @var{facespec} to use for the
@code{face} property, it specifies the value @var{syntax} to use for
the @code{syntax-table} property. Here, @var{syntax} can be a string
(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
strings.
+Major modes normally set this variable with @var{other-vars} in
+@code{font-lock-defaults}.
@end defvar
@node Desktop Save Mode
projects / emacs.git / commitdiff