bug#20436: 25.0.50; syntax-multiline not documented

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Lars Ingebrigtsen [2021-07-13 19:57:55] wrote:
> Tom Tromey <tom@tromey.com> writes:
>> I noticed some code in syntax.el for the syntax-multiline property.
>> This doesn't seem to be documented anywhere, but I think it should be.
>
> Looking at this:
>
> (defun syntax-propertize-multiline (beg end)
>   "Let `syntax-propertize' pay attention to the syntax-multiline property."
>   (when (and (> beg (point-min))
> 	     (get-text-property (1- beg) 'syntax-multiline))
>     (setq beg (or (previous-single-property-change beg 'syntax-multiline)
> 		  (point-min))))
>   ;;
>   (when (get-text-property end 'syntax-multiline)
>     (setq end (or (text-property-any end (point-max)
> 				     'syntax-multiline nil)
> 		  (point-max))))
>   (cons beg end))
>
> And some of the usage sites...  I'm still not quite sure what the
> semantics here are.  :-)  I've added Stefan M to the CCs; perhaps he can
> explain and I'll write something up for the manual?

Its semantics is implemented by `syntax-propertize-multiline` (whose
docstring speaks volumes ;-), so the property is only effective after
you've added `syntax-propertize-multiline` to
`syntax-propertize-extend-region-functions`.

What it does is cause `syntax-propertize` to treat the marked text such
that it will always be propertized in a single call rather than two or
more separate calls.

The most common use for it is when the syntax to use for "FOO" depends
on some *later* text "BAR": by placing this property over the whole of
"FOO...BAR" you make sure that any change of "BAR" will cause the
syntax of "FOO" to be recomputed.


        Stefan