[Emacs-diffs] Changes to emacs/lispref/modes.texi

[Lute Kamstra]

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