From fd1fe1e1ecb6c68bbdea4bf071166779388174d0 Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Sat, 19 Sep 2020 16:50:27 +0000 Subject: [PATCH] Add doc to syntax-propertize-function saying it must do a 100% job and cannot be combined with other ways of applying syntax-table text properties. * lisp/emacs-lisp/syntax.el (syntax-propertize-function): Amend doc string. * doc/lispref/syntax.texi (Syntax Properties): Amend the description of the variable. --- doc/lispref/syntax.texi | 9 +++++++++ lisp/emacs-lisp/syntax.el | 7 ++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 9eb99a0ac92..b3c77665bae 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -575,6 +575,15 @@ position before @var{end}. However, it should not call @code{syntax-ppss-flush-cache}; so, it is not allowed to call @code{syntax-ppss} on some position and later modify the buffer at an earlier position. + +@strong{Caution:} When this variable is non-@code{nil}, Emacs removes +@code{syntax-table} text properties arbitrarily and relies on +@code{syntax-propertize-function} to reapply them. Thus if this +facility is used at all, the function must apply @strong{all} +@code{syntax-table} text properties used by the major mode. In +particular, Modes derived from a CC Mode mode must not use this +variable, since CC Mode uses other means to apply and remove these +text properties. @end defvar @defvar syntax-propertize-extend-region-functions diff --git a/lisp/emacs-lisp/syntax.el b/lisp/emacs-lisp/syntax.el index 11cc1988b1f..f4f077264be 100644 --- a/lisp/emacs-lisp/syntax.el +++ b/lisp/emacs-lisp/syntax.el @@ -65,7 +65,12 @@ cannot be handled just by the buffer's syntax-table. The specified function may call `syntax-ppss' on any position before END, but it should not call `syntax-ppss-flush-cache', which means that it should not call `syntax-ppss' on some -position and later modify the buffer on some earlier position.") +position and later modify the buffer on some earlier position. + +Note: When this variable is a function, it must apply _all_ the +`syntax-table' properties needed in the given text interval. +Using both this function and other means to apply these +properties won't work properly.") (defvar syntax-propertize-chunk-size 500) -- 2.39.5