Merged from emacs@sv.gnu.org

Patches applied:

 * emacs@sv.gnu.org/emacs--devo--0--patch-234
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-235
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-236
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-237
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-238
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-239
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-240
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-241
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-242
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-243
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-244
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-245
   (Ffield_beginning, find_field): Undo change of 2006-04-23.

 * emacs@sv.gnu.org/emacs--devo--0--patch-246
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-247
   Rcirc patch from Ryan Yeske

 * emacs@sv.gnu.org/emacs--devo--0--patch-248
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-249
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-250
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-251
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-87
   Merge from emacs--devo--0

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-88
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-89
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-90
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-91
   Merge from emacs--devo--0

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-92
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-93
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-94
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-95
   Update from CVS

git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-553

3 files changed, 95 insertions, 42 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 48205488ef8..ac6bd07a175 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2006-04-26  Richard Stallman  <rms@gnu.org>
+
+        * syntax.texi (Parsing Expressions): Minor cleanup.
+
 2006-04-18  Richard Stallman  <rms@gnu.org>
 
         * tips.texi (Coding Conventions): Explain when the package's
diff --git a/lispref/modes.texi b/lispref/modes.texi
index b33424a58be..3f56179231c 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -2336,8 +2336,6 @@ Search-based fontification happens second.
 * 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.
@@ -2347,6 +2345,8 @@ Search-based fontification happens second.
 * Syntactic Font Lock::         Fontification based on syntax tables.
 * Setting Syntax Properties::   Defining character syntax based on context
                                   using the Font Lock mechanism.
+* Multi line Font Lock Elements:: How to coerce Font Lock into properly
+                                  highlighting multiline elements.
 @end menu
 
 @node Font Lock Basics
@@ -2623,16 +2623,9 @@ this value of @code{font-lock-keywords} is used in a buffer.
 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{Multi line Font Lock Elements}.
 
 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
@@ -2718,36 +2711,6 @@ C mode @emph{and} all modes derived from it, do this instead:
       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-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
 
@@ -3052,6 +3015,90 @@ Major modes normally set this variable with @var{other-vars} in
 @code{font-lock-defaults}.
 @end defvar
 
+@node Multi line Font Lock Elements
+@subsection Multi line Font Lock Elements
+@cindex multi line font lock
+
+Normally, Font Lock elements specified via @code{font-lock-keywords}
+should not match across multiple lines.  If they do, Font Lock may
+fail to highlight them properly.  This is fundamentally due to the
+fact that Font Lock does not always look at the whole buffer at
+a time, for obvious performance reasons, and instead only looks
+at a small chunk at a time.  In order for the highlight to be correct,
+a chunk should not straddle an element matched by
+@code{font-lock-keywords}.  The default heuristic used for this is to
+start and end chunks at the beginning resp. end of a line.
+
+To work around this limitations, a few tools are provided.
+
+@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
+
+In order to make it possible to properly highlight elements that span
+multiple lines, Font Lock obeys a special text property
+@code{font-lock-multiline} which if non-@code{nil} indicates that this
+piece of text is part of a multiline construct.  So when Font Lock is
+asked to highlight a region, it first verifies the two boundaries and
+extends them as needed so they do not fall in the middle of a piece of
+text marked with the @code{font-lock-multiline} property.
+Immediately after that, it also erases all @code{font-lock-multiline}
+properties from the region it is about to highlight, so it is the
+responsability of the highlighting specification (mostly
+@code{font-lock-keywords}) to make sure that this property is re-added
+where needed so as to inform the next round of Font Locking of the
+presence of a multiline construct.
+
+It is important to understand that the @code{font-lock-multiline}
+property should preferably only be used on Font Lock elements of
+moderate size: every time that text is modified within the multiline
+elements (or nearby), the whole multiline element will be completely
+re-highlighted, so if its size is large, the time to font-lock may
+render editing painfully slow.
+
+@defvar font-lock-multiline
+If the @code{font-lock-multiline} variable is set to @code{t}, Font
+Lock will try to automatically add the @code{font-lock-multiline}
+property on the keywords that span several lines.  This is no silver
+bullet however since it slows down Font Lock somewhat, and still does
+not always find all multiline constructs, especially when used with
+Jit Lock, which is enabled by default.
+@end defvar
+
+@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 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 @c either of
+the following variables:
+
+@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 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
diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index 7297f6b9104..1575ebeb850 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -672,7 +672,9 @@ the parse:
 
 @enumerate 0
 @item
-The depth in parentheses, counting from 0.
+The depth in parentheses, counting from 0.  @strong{Warning:} this can
+be negative if there are more close parens than open parens between
+the start of the defun and point.
 
 @item
 @cindex innermost containing parentheses