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)

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 645aad94a639beccdb2ddc9adf34b42fbbe8c07f..c8c2fe80c03b2db5c74c513f6ff53ad13191b5fa 100644 (file)
--- 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 ee458038270e0d4cf1a351566432476cdaf9f827..3c65d51eab190695164736fea966d3c0ea6c5bef 100644 (file)
--- 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.
+
 \f
 * Changes in Emacs 30.1 on Non-Free Operating Systems