Mercurial > emacs

--- a/lispref/modes.texi	Thu Apr 28 09:20:45 2005 +0000
+++ b/lispref/modes.texi	Thu Apr 28 11:32:54 2005 +0000
@@ -1134,9 +1134,10 @@
 @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.
@@ -2025,12 +2026,11 @@
 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.
@@ -2041,7 +2041,8 @@
 * 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

@@ -2056,45 +2057,48 @@

 @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
@@ -2102,7 +2106,8 @@

   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
@@ -2192,7 +2197,8 @@
 @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
@@ -2312,6 +2318,7 @@
 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,
@@ -2322,52 +2329,75 @@
 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
-
-@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} (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).
-
-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
+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}.
+
+For example:
+
+@smallexample
+(font-lock-add-keywords 'c-mode
+ '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
+   ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
+@end smallexample
+
+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
@@ -2383,25 +2413,38 @@
 @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-fontify-buffer-function
+Function to use for fontifying the buffer.  The default value is
+@code{font-lock-default-fontify-buffer}.
 @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.
+@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
@@ -2412,6 +2455,14 @@
 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

@@ -2456,16 +2507,9 @@
 @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
@@ -2483,6 +2527,10 @@
 @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.
@@ -2534,14 +2582,78 @@
 @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})
@@ -2551,10 +2663,10 @@
 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
@@ -2591,6 +2703,8 @@
 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