Re: doc for multi-line font-lock

[Stefan Monnier]

>     Setting font-lock-multiline to t should allow font-lock-keywords that
>     typically span a single line but sometimes a bit more (things like
>     <title>blabla</title>) to work correctly most of the time.
> can you doc that?
>     Documenting its behavior is not something I'm looking forward to.
>     I'm responsible for introducing `font-lock-syntactic-face-function' as
>     well as for all of the code that uses it in Emacs (AFAIK), but I think
>     it's just a hack that's screaming for a replacement based on
>     a significant improvement to font-lock rather than a quick hack.
> how about if we mention it in the manual and say 3 lines abt what it
> can do, and say we decided not to doc it fully since it is so obscure
> and unfinished.

I've installed the patch below,


        Stefan


--- modes.texi.~1.70.~  2003-10-20 16:31:29.000000000 -0400
+++ modes.texi  2003-10-30 17:14:37.000000000 -0500
@@ -2161,7 +2161,11 @@
 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.
+line at a time.  If you have patterns that typically only span one
+line but can occasionally span two or three, such as
address@hidden<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.
 
 @node Other Font Lock Variables
 @subsection Other Font Lock Variables
@@ -2231,6 +2235,20 @@
 @code{font-lock-keywords} as well as adding them to this list.
 @end defvar
 
address@hidden 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
address@hidden, and should return a face.  The default
+value returns @code{font-lock-comment-face} for comments and
address@hidden for strings.
+
+This can be used to highlighting different kinds of strings or
+comments differently.  It is also sometimes abused together with
address@hidden to highlight elements that span
+multiple lines, but this is too obscure to document in this manual.
address@hidden defvar
+
 @node Levels of Font Lock
 @subsection Levels of Font Lock