bug#20436: 25.0.50; syntax-multiline not documented

bug#20436: 25.0.50; syntax-multiline not documented

[Tom Tromey]

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.




In GNU Emacs 25.0.50.2 (x86_64-unknown-linux-gnu, GTK+ Version 3.14.12)
 of 2015-04-19 on bapiya
Repository revision: 61f67da4e4b1a4aa3409d4b6758fe046037fbe88
Windowing system distributor `Fedora Project', version 11.0.11603000
Configured using:
 `configure --prefix=/home/tromey/Emacs/install'

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND GPM DBUS GCONF GSETTINGS
NOTIFY LIBSELINUX GNUTLS LIBXML2 FREETYPE M17N_FLT LIBOTF XFT ZLIB

Important settings:
  value of $LANG: en_US.utf8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Emacs-Lisp

Minor modes in effect:
  diff-auto-refine-mode: t
  flyspell-mode: t
  which-function-mode: t
  global-auto-revert-mode: t
  desktop-save-mode: t
  erc-services-mode: t
  erc-list-mode: t
  erc-menu-mode: t
  erc-autojoin-mode: t
  erc-ring-mode: t
  erc-networks-mode: t
  erc-pcomplete-mode: t
  erc-track-mode: t
  erc-match-mode: t
  erc-netsplit-mode: t
  erc-hl-nicks-mode: t
  erc-button-mode: t
  erc-fill-mode: t
  erc-stamp-mode: t
  erc-irccontrols-mode: t
  erc-noncommands-mode: t
  erc-move-to-prompt-mode: t
  erc-readonly-mode: t
  savehist-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  auto-fill-function: do-auto-fill

Recent messages:
Saving file /home/tromey/Emacs/Multi/PLAN...
Wrote /home/tromey/Emacs/Multi/PLAN
Saving file /home/tromey/Emacs/Multi/PLAN...
Wrote /home/tromey/Emacs/Multi/PLAN
Saving file /home/tromey/Emacs/Multi/PLAN...
Wrote /home/tromey/Emacs/Multi/PLAN
Type C-x 1 to delete the help window, C-M-v to scroll help.
Mark saved where search started [2 times]
Mark set
Mark saved where search started
Quit

Load-path shadows:
/home/tromey/.emacs.d/elpa/bubbles-0.5/bubbles hides /home/tromey/Emacs/install/share/emacs/25.0.50/lisp/play/bubbles

Features:
(shadow bbdb-message mailalias mail-hist emacsbug debug log-view
whitespace shr-color epg tabify man nndoc url-handlers debbugs-gnu
debbugs soap-client url-http url-auth url-gw log-edit pcvs-util dabbrev
copyright eieio-opt help-mode gnus-fun flow-fill shr dom subr-x
mm-archive gnus-html browse-url xml url-cache mm-url url url-proxy
url-privacy url-expand url-methods url-history url-cookie url-domsuf
url-util url-parse url-vars sort smiley gnus-cite mail-extr qp
gnus-async gnus-bcklg gnus-ml disp-table gnus-topic nndraft nnmh
nnfolder utf-7 bbdb-gnus bbdb-mua bbdb-com crm gnutls network-stream nsm
starttls gnus-agent gnus-srvr gnus-score score-mode nnvirtual gnus-msg
nntp gnus-cache gnus-registry registry eieio-compat eieio-base gnus-art
mm-uu mml2015 mm-view mml-smime smime dig mailcap gnus-sum gnus-group
gnus-undo smtpmail sendmail gnus-start gnus-cloud nnimap nnmail
mail-source tls utf7 netrc nnoo parse-time gnus-spec gnus-int gnus-range
gnus-win gnus gnus-ems nnheader misearch multi-isearch message rfc822
mml mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047
rfc2045 ietf-drums mailabbrev mail-utils gmm-utils mailheader goto-addr
sh-script executable arc-mode archive-mode texinfo python systemtap-mode
derived cc-langs cc-awk php-mode speedbar sb-image ezimage dframe etags
xref flymake css-mode smie sgml-mode js json make-mode smerge-mode
bug-reference tar-mode markdown-mode org-element org-rmail org-mhe
org-irc org-info org-gnus org-docview doc-view jka-compr image-mode
dired org-bibtex bibtex org-bbdb org-w3m org org-macro org-footnote
org-pcomplete org-list org-faces org-entities noutline outline
org-version ob-emacs-lisp ob ob-tangle ob-ref ob-lob ob-table ob-exp
org-src ob-keys ob-comint ob-core ob-eval org-compat org-macs
org-loaddefs vc-mtn vc-hg vc-bzr vc-src vc-sccs vc-svn vc-cvs vc-rcs
vc-git diff-mode easy-mmode cc-mode cc-fonts cc-guess cc-menus cc-cmds
add-log flyspell ispell diminish edmacro kmacro projectile ibuf-ext
ibuffer pkg-info find-func lisp-mnt epl grep compile dash s appt
diary-lib diary-loaddefs cal-menu calendar cal-loaddefs which-func imenu
minimap autorevert filenotify desktop frameset cus-start cus-load status
erc-services erc-list erc-menu erc-join erc-ring erc-networks
erc-pcomplete pcomplete erc-track erc-match erc-netsplit erc-hl-nicks
color erc-button erc-fill erc-stamp wid-edit erc-goodies erc erc-backend
erc-compat format-spec auth-source eieio gnus-util mm-util mail-prsvr
password-cache thingatpt pp warnings advice vc-dir ewoc vc vc-dispatcher
cc-styles cc-align cc-engine cc-vars cc-defs bbdb bbdb-site timezone
ange-ftp comint ansi-color ring server savehist finder-inf
dwarf-mode-autoloads gdb-shell-autoloads eieio-core cl-generic byte-opt
bytecomp byte-compile cl-extra seq cconv lisppaste-autoloads
pydoc-info-autoloads info-look info easymenu help-fns cl-macs cl gv
cl-loaddefs pcase cl-lib weblogger-autoloads package epg-config
bbdb-loaddefs mule-util time-date tooltip eldoc electric uniquify
ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar dnd
fontset image regexp-opt fringe tabulated-list newcomment elisp-mode
lisp-mode prog-mode register page menu-bar rfn-eshadow timer select
scroll-bar mouse jit-lock font-lock syntax facemenu font-core frame cham
georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese hebrew greek romanian slovak czech european ethiopic
indian cyrillic chinese case-table epa-hook jka-cmpr-hook help simple
abbrev minibuffer cl-preloaded nadvice loaddefs button faces cus-face
macroexp files text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget hashtable-print-readable backquote
make-network-process dbusbind gfilenotify dynamic-setting
system-font-setting font-render-setting move-toolbar gtk x-toolkit x
multi-tty emacs)

Memory information:
((conses 16 1886374 102577)
 (symbols 48 123934 0)
 (miscs 40 33584 42)
 (strings 32 469971 49248)
 (string-bytes 1 11979959)
 (vectors 16 111010)
 (vector-slots 8 2312396 8980)
 (floats 8 3337 1446)
 (intervals 56 170204 9355)
 (buffers 976 323)
 (heap 1024 331141 126832))

Tom

bug#20436: 25.0.50; syntax-multiline not documented

[Lars Ingebrigtsen]

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.

I guess it should...  I grepped through the tree and there doesn't
really seem to be any comments about how it's used, either.  Could
somebody who knows add something...  somewhere?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20436: 25.0.50; syntax-multiline not documented

[Lars Ingebrigtsen]

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?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20436: 25.0.50; syntax-multiline not documented

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

bug#20436: 25.0.50; syntax-multiline not documented

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> 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.

Excellent; I've now basically added that kinda verbatim to the
"Multiline Font Lock" section in the lispref manual.  Feel free to tweak
further.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no