From 22af16c2fbc8bec8999d86d75867b800dd6bfb56 Mon Sep 17 00:00:00 2001 From: Yuan Fu Date: Tue, 4 Jun 2024 21:32:19 -0700 Subject: [PATCH] Add manual entry for treesit-primary-parser * doc/lispref/parsing.texi (Multiple Languages): Add entry. * etc/NEWS (Example): Add news. (cherry picked from commit 636461686f1d36388d4523cbb10eb7ec3bbbd63e) --- doc/lispref/parsing.texi | 22 ++++++++++++++++++++-- etc/NEWS | 6 ++++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index 645aad94a63..c8c2fe80c03 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -1683,16 +1683,34 @@ instead to specify regions of buffer text (i.e., ranges) in which a parser will operate. This section describes functions for setting and getting ranges for a parser. +@cindex primary parser +Generally when there are multiple languages at play, there is a +``primary'', or ``host'' language. The parser for this language---the +@dfn{primary parser}, parses the entire buffer. Parsers for other +languages are ``embedded'' or ``guest'' parsers, which only work on part +of the buffer. The parse tree of the primary parser is usually used to +determine the ranges in which the embedded parsers operate. + +@vindex treesit-primary-parser +Major modes should set @var{treesit-primary-parser} to the primary +parser before calling @code{treesit-major-mode-setup}, so that Emacs can +configure the primary parser correctly for font-lock and other features. + Lisp programs should call @code{treesit-update-ranges} to make sure the ranges for each parser are correct before using parsers in a buffer, and call @code{treesit-language-at} to figure out the language responsible for the text at some position. These two functions don't work by themselves, they need major modes to set -@code{treesit-range-settings} and -@code{treesit-language-at-point-function}, which do the actual work. +@var{treesit-range-settings} and +@var{treesit-language-at-point-function}, which do the actual work. These functions and variables are explained in more detail towards the end of the section. +@b{In short}, multi-language major modes should set +@var{treesit-primary-parser}, @var{treesit-range-settings}, and +@var{treesit-language-at-point-function} before calling +@code{treesit-major-mode-setup}. + @heading Getting and setting ranges @defun treesit-parser-set-included-ranges parser ranges diff --git a/etc/NEWS b/etc/NEWS index ee458038270..3c65d51eab1 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -3006,6 +3006,12 @@ only return parsers for that language. If TAG is given, only return parsers with that tag. Note that passing nil as tag doesn't mean return all parsers, but rather "all parsers with no tags". ++++ +*** New variable 'treesit-primary-parser'. +This variable should be set by multi-langauge major modes before calling +'treesit-major-mode-setup', in order for tree-sitter integration +functionalities to operate correctly. + * Changes in Emacs 30.1 on Non-Free Operating Systems -- 2.39.2