[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/modes.texi
From: |
Lute Kamstra |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/modes.texi |
Date: |
Thu, 28 Apr 2005 07:32:56 -0400 |
Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.97 emacs/lispref/modes.texi:1.98
*** emacs/lispref/modes.texi:1.97 Tue Apr 26 10:57:21 2005
--- emacs/lispref/modes.texi Thu Apr 28 11:32:54 2005
***************
*** 1134,1142 ****
@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.
@item :global @var{global}
If address@hidden specifies that the minor mode should be global.
--- 1134,1143 ----
@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}.
! @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 address@hidden specifies that the minor mode should be global.
***************
*** 2025,2036 ****
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.
@menu
* Font Lock Basics:: Overview of customizing Font Lock.
--- 2026,2036 ----
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.
! Search-based fontification happens second.
@menu
* Font Lock Basics:: Overview of customizing Font Lock.
***************
*** 2041,2047 ****
* 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
using the Font Lock mechanism.
@end menu
--- 2041,2048 ----
* 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:: Fontification based on syntax tables.
! * Setting Syntax Properties:: Defining character syntax based on context
using the Font Lock mechanism.
@end menu
***************
*** 2056,2100 ****
@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:
@example
! (@var{keywords} @var{keywords-only} @var{case-fold}
! @var{syntax-alist} @var{syntax-begin} @address@hidden)
@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.
The second element, @var{keywords-only}, specifies the value of the
variable @code{font-lock-keywords-only}. If this is address@hidden,
syntactic fontification (of strings and comments) is not performed.
The third element, @var{case-fold}, specifies the value of
! @code{font-lock-keywords-case-fold-search}. If it is address@hidden, Font
Lock
! mode ignores case when searching as directed by
@code{font-lock-keywords}.
! If the fourth element, @var{syntax-alist}, is address@hidden, 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}.
The fifth element, @var{syntax-begin}, specifies the value of
! @code{font-lock-beginning-of-syntax-function} (see below).
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.
@end defvar
@node Search-based Fontification
--- 2057,2104 ----
@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. It automatically becomes
! buffer-local when you set it. The value should look like this:
@example
! (@var{keywords} address@hidden address@hidden
! address@hidden address@hidden @address@hidden)
@end example
The first element, @var{keywords}, indirectly specifies the value of
! @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 address@hidden,
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 address@hidden,
! Font Lock mode ignores case when searching as directed by
@code{font-lock-keywords}.
! If the fourth element, @var{syntax-alist}, is address@hidden, 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
! 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}.
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. @xref{Other Font Lock Variables}.
@end defvar
@node Search-based Fontification
***************
*** 2102,2108 ****
The most important variable for customizing Font Lock mode is
@code{font-lock-keywords}. It specifies the search criteria for
! search-based fontification.
@defvar font-lock-keywords
This variable's value is a list of the keywords to highlight. Be
--- 2106,2113 ----
The most important variable for customizing Font Lock mode is
@code{font-lock-keywords}. It specifies the search criteria for
! 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,2198 ****
@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.
@item (@var{matcher} . @var{subexp-highlighter})
In this kind of element, @var{subexp-highlighter} is a list
--- 2197,2204 ----
@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. @xref{Other Font Lock
! Variables}.
@item (@var{matcher} . @var{subexp-highlighter})
In this kind of element, @var{subexp-highlighter} is a list
***************
*** 2312,2317 ****
--- 2318,2324 ----
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,2373 ****
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
! address@hidden 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
@defvar font-lock-keywords-case-fold-search
address@hidden 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 address@hidden, 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
@defvar font-lock-mark-block-function
If this variable is address@hidden, it should be a function that is
--- 2329,2403 ----
setting @code{font-lock-multiline} to @code{t}. But it still will not
work in all cases.
! 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
address@hidden means that regular expression matching for the sake of
@code{font-lock-keywords} should be case-insensitive.
@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
! address@hidden 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 address@hidden @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 address@hidden, it should be a function that is
***************
*** 2383,2407 ****
@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.
! @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.
@end defvar
@defvar font-lock-lines-before
--- 2413,2450 ----
@end defvar
@defvar font-lock-extra-managed-props
! 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-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 address@hidden, 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,2417 ****
--- 2455,2468 ----
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,2471 ****
@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 address@hidden 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
@node Faces for Font Lock
@subsection Faces for Font Lock
--- 2507,2515 ----
@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), 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,2488 ****
--- 2527,2536 ----
@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,2547 ****
@node Syntactic Font Lock
@subsection Syntactic Font Lock
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.
@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:
@example
(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
--- 2582,2659 ----
@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
+ address@hidden 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 address@hidden, 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 (@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 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,2560 ****
sort of element of @code{font-lock-keywords},
@example
! (@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
@end example
! However, instead of specifying the value @var{facename} 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
--- 2663,2672 ----
sort of element of @code{font-lock-keywords},
@example
! (@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
@end example
! 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,2596 ****
--- 2703,2710 ----
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