@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002,
-@c 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@node Modes, Documentation, Keymaps, Top
@end defmac
The initial value must be @code{nil} except in cases where (1) the
-mode is preloaded in Emacs, or (2) it is painless to for loading to
+mode is preloaded in Emacs, or (2) it is painless for loading to
enable the mode even though the user did not request it. For
instance, if the mode has no effect unless something else is enabled,
and will always be loaded by that time, enabling it by default is
@menu
* Base: Mode Line Basics. Basic ideas of mode line control.
* Data: Mode Line Data. The data structure that controls the mode line.
-* Top: Mode LIne Top. The top level variable, mode-line-format.
+* Top: Mode Line Top. The top level variable, mode-line-format.
* Mode Line Variables:: Variables used in that data structure.
* %-Constructs:: Putting information into a mode line.
* Properties in Mode:: Using text properties in the mode line.
@item %c
The current column number of point.
+@item %e
+When Emacs is nearly out of memory for Lisp objects, a brief message
+saying so. Otherwise, this is empty.
+
@item %f
The visited file name, obtained with the @code{buffer-file-name}
function. @xref{Buffer File Name}.
meaningful distinction only on certain operating systems (@pxref{MS-DOS
File Types}).
+@item %z
+The mnemonics of buffer, terminal, and keyboard coding systems.
+
+@item %Z
+Like @samp{%z}, but including the end-of-line format.
+
@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
The value of @code{mode-name}.
@item %M
-The value of @code{global-mode-string}. Currently, only
-@code{display-time} modifies the value of @code{global-mode-string}.
+The value of @code{global-mode-string}.
@end table
@node Properties in Mode
(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
@end example
-Like in the previous case, each match for this element creates an
-index item. However, if this index item is selected by the user, it
-calls @var{function} with arguments consisting of the item name, the
-buffer position, and @var{arguments}.
+Each match for this element creates an index item, and when the index
+item is selected by the user, it calls @var{function} with arguments
+consisting of the item name, the buffer position, and @var{arguments}.
For Emacs Lisp mode, @code{imenu-generic-expression} could look like
this:
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
+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.
* Syntactic Font Lock:: Fontification based on syntax tables.
* Setting Syntax Properties:: Defining character syntax based on context
using the Font Lock mechanism.
+* Multiline Font Lock:: How to coerce Font Lock into properly
+ highlighting multiline constructs.
@end menu
@node Font Lock Basics
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,
-updating when you edit the buffer does not, since it considers text one
-line at a time. If you have patterns that typically only span one
-line but can occasionally span two or three, such as
-@samp{<title>...</title>}, you can ask Font Lock to be more careful by
-setting @code{font-lock-multiline} to @code{t}. But it still will not
-work in all cases.
+to match text which spans lines; this does not work reliably.
+For details, see @xref{Multiline Font Lock}.
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
@code{font-lock-default-unfontify-region}.
@end defvar
-@defvar font-lock-lines-before
-This variable specifies the number of extra lines to consider when
-refontifying the buffer after each text change. Font lock begins
-refontifying from that number of lines before the changed region. The
-default is 0, but using a larger value can be useful for coping with
-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.
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.
+@code{font-lock-syntactic-keywords} to highlight constructs that span
+multiple lines, but this is too esoteric to document here.
Specify this variable using @var{other-vars} in
@code{font-lock-defaults}.
@code{font-lock-defaults}.
@end defvar
+@node Multiline Font Lock
+@subsection Multiline Font Lock Constructs
+@cindex multiline font lock
+
+ Normally, elements of @code{font-lock-keywords} should not match
+across multiple lines; that doesn't work reliably, because Font Lock
+usually scans just part of the buffer, and it can miss a multi-line
+construct that crosses the line boundary where the scan starts. (The
+scan normally starts at the beginning of a line.)
+
+ Making elements that match multiline constructs work properly has
+two aspects: correct @emph{identification} and correct
+@emph{rehighlighting}. The first means that Font Lock finds all
+multiline constructs. The second means that Font Lock will correctly
+rehighlight all the relevant text when a multiline construct is
+changed---for example, if some of the text that was previously part of
+a multiline construct ceases to be part of it. The two aspects are
+closely related, and often getting one of them to work will appear to
+make the other also work. However, for reliable results you must
+attend explicitly to both aspects.
+
+ There are two ways to ensure correct identification of multiline
+constructs:
+
+@itemize
+@item
+Place a @code{font-lock-multiline} or @code{jit-lock-defer-multiline}
+property on the construct when it is added to the buffer.
+@item
+Use @code{font-lock-fontify-region-function} hook to extend the scan
+so that the scanned text never starts or ends in the middle of a
+multiline construct.
+@end itemize
+
+ There are three ways to do rehighlighting of multiline constructs:
+
+@itemize
+@item
+Place a @code{font-lock-multiline} property on the construct. This
+will rehighlight the whole construct if any part of it is changed. In
+some cases you can do this automatically by setting the
+@code{font-lock-multiline} variable.
+@item
+Use @code{jit-lock-contextually}. This will only rehighlight the part
+of the construct that follows the actual change, and will do it after
+a short delay. This only works if the highlighting of the various
+parts of your multiline construct never depends on text in subsequent
+lines. Since @code{jit-lock-contextually} is activated by default,
+this can be an attractive solution.
+@item
+Place a @code{jit-lock-defer-multiline} property on the construct.
+This works only if @code{jit-lock-contextually} is used, but it can
+handle the case where highlighting depends on subsequent lines.
+@item
+@end itemize
+
+@menu
+* Font Lock Multiline:: Marking multiline chunks with a text property
+* Region to Fontify:: Controlling which region gets refontified
+ after a buffer change.
+@end menu
+
+@node Font Lock Multiline
+@subsubsection Font Lock Multiline
+
+ One way to ensure reliable rehighlighting of multiline Font Lock
+constructs is to put on the text property @code{font-lock-multiline}.
+It should be present and non-@code{nil} for text that is part of a
+multiline construct.
+
+ When Font Lock is about to highlight a range of text, it first
+extends the boundaries of the range as necessary so that they do not
+fall within text marked with the @code{font-lock-multiline} property.
+Then it removes any @code{font-lock-multiline} properties from the
+range, and highlights it. The highlighting specification (mostly
+@code{font-lock-keywords}) must reinstall this property each time,
+whenever it is appropriate.
+
+ @strong{Warning:} don't use the @code{font-lock-multiline} property
+on large ranges of text, because that will make rehighlighting slow.
+
+@defvar font-lock-multiline
+If the @code{font-lock-multiline} variable is set to @code{t}, Font
+Lock will try to add the @code{font-lock-multiline} property
+automatically on multiline constructs. This is not a universal
+solution, however, since it slows down Font Lock somewhat. It can
+miss some multiline constructs, or make the property larger or smaller
+than necessary.
+
+For elements whose @var{matcher} is a function, the function should
+ensure that submatch 0 covers the whole relevant multiline construct,
+even if only a small subpart will be highlighted. It is often just as
+easy to add the @code{font-lock-multiline} property by hand.
+@end defvar
+
+ The @code{font-lock-multiline} property is meant to ensure proper
+refontification; it does not automatically identify new multiline
+constructs. Identifying the requires that Font-Lock operate on large
+enough chunks at a time. This will happen by accident on many cases,
+which may give the impression that multiline constructs magically work.
+If you set the @code{font-lock-multiline} variable non-@code{nil},
+this impression will be even stronger, since the highlighting of those
+constructs which are found will be properly updated from then on.
+But that does not work reliably.
+
+ To find multiline constructs reliably, you must either manually
+place the @code{font-lock-multiline} property on the text before
+Font-Lock looks at it, or use
+@code{font-lock-fontify-region-function}.
+
+@node Region to Fontify
+@subsubsection Region to Fontify after a Buffer Change
+
+ When a buffer is changed, the region that Font Lock refontifies is
+by default the smallest sequence of whole lines that spans the change.
+While this works well most of the time, sometimes it doesn't---for
+example, when a change alters the syntactic meaning of text on an
+earlier line.
+
+ You can enlarge (or even reduce) the region to fontify by setting
+one the following variables:
+
+@defvar font-lock-extend-region-function
+This buffer-local variable is either @code{nil} or a function for
+Font-Lock to call to determine the region to scan and fontify.
+
+The function is given three parameters, the standard @var{beg},
+@var{end}, and @var{old-len} from after-change-functions
+(@pxref{Change Hooks}). It should return either a cons of the
+beginning and end buffer positions (in that order) of the region to
+fontify, or @code{nil} (which means choose the region in the standard
+way). This function needs to preserve point, the match-data, and the
+current restriction. The region it returns may start or end in the
+middle of a line.
+
+Since this function is called after every buffer change, it should be
+reasonably fast.
+@end defvar
+
@node Desktop Save Mode
@section Desktop Save Mode
@cindex desktop save mode