Add manual entry for treesit-primary-parser

* doc/lispref/parsing.texi (Multiple Languages): Add entry.
* etc/NEWS (Example): Add news.

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 3220a3f16e4..922721f143c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2872,6 +2872,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