doc for multi-line font-lock

[Dave Love]

The Lisp manual tells you not to use multi-line font-lock matchers,
but NEWS talks about `font-lock-multiline'.  I'm rather unclear what
the current situation is with font-lock, especially if I want to make
things work in Emacs 21.3.

I find the doc rather hard to follow, though I'm not sure how to
improve it.

A concrete example is that I wanted to do something that's probably a
job for `font-lock-syntactic-face-function'.  I didn't know about that
function and only found it by grovelling a mode I thought must be
doing what I wanted.