@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}); @*
(@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:
* Font Lock Basics:: Overview of customizing Font Lock.
* Search-based Fontification:: Fontification based on regexps.
* Customizing Keywords:: Customizing search-based fontification.
-* Region to Fontify:: Controlling which region gets refontified
- after a buffer change.
* Other Font Lock Variables:: Additional customization facilities.
* Levels of Font Lock:: Each mode can define alternative levels
so that the user can select more or less.
* 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
font-lock-keyword-face)))))
@end smallexample
-@node Region to Fontify
-@subsection 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 buffer change has changed the syntactic meaning of text
-on an earlier line.
-
-You can enlarge (or even reduce) the region to fontify by setting either
-of the following variables:
-
-@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. This variable is ignored whenever
-@code{font-lock-extend-region-function} is set and returns a
-non-@code{nil} value.
-@end defvar
-
-@defvar font-lock-extend-region-function
-This buffer-local variable is either @code{nil} or is a function that
-determines the region to fontify, which Emacs then calls after each
-buffer change.
-
-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
-directs the caller to fontify the default region). This function need
-not preserve point or the match-data, but must preserve 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 Other Font Lock Variables
@subsection Other Font Lock Variables
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