Add a :toggle option for tree-sitter font-lock

* admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html:
Update html manual.
* admin/notes/tree-sitter/html-manual/build-manual.sh: Fix manual
path.
* admin/notes/tree-sitter/starter-guide: Mention :toggle.
* doc/lispref/modes.texi: Mention :toggle.
* lisp/treesit.el (treesit-font-lock-settings): Update docstring.
(treesit-font-lock-rules): Handle :toggle.  Also change
some wrong-type-argument signal to treesit-font-lock-error which is
easier to understand.
(treesit-font-lock-fontify-region): Handle :toggle.

3 files changed, 13 insertions, 11 deletions

diff --git a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html b/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html
index ec89b7749c8..246ebf05193 100644
--- a/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html
+++ b/admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html
@@ -115,6 +115,8 @@ every query must specify the language.  Other keywords are optional:
 <tr><td width="15%"></td><td width="15%"><code>append</code></td><td width="60%">Append the new face to existing ones</td></tr>
 <tr><td width="15%"></td><td width="15%"><code>prepend</code></td><td width="60%">Prepend the new face to existing ones</td></tr>
 <tr><td width="15%"></td><td width="15%"><code>keep</code></td><td width="60%">Fill-in regions without an existing face</td></tr>
+<tr><td width="15%"><code>:toggle</code></td><td width="15%"><var>symbol</var></td><td width="60%">If non-nil, its value should be a variable name.  The variable&rsquo;s value
+(nil/non-nil) disables/enables the query during fontification.</td></tr>
 </table>
 
 <p>Capture names in <var>query</var> should be face names like
diff --git a/admin/notes/tree-sitter/html-manual/build-manual.sh b/admin/notes/tree-sitter/html-manual/build-manual.sh
index adde3f2a2af..8d931b143b2 100755
--- a/admin/notes/tree-sitter/html-manual/build-manual.sh
+++ b/admin/notes/tree-sitter/html-manual/build-manual.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-MANUAL_DIR="../../../doc/lispref"
+MANUAL_DIR="../../../../doc/lispref"
 THIS_DIR=$(pwd)
 
 echo "Build manual"
diff --git a/admin/notes/tree-sitter/starter-guide b/admin/notes/tree-sitter/starter-guide
index 6cf8cf8a236..129f9ee5fa4 100644
--- a/admin/notes/tree-sitter/starter-guide
+++ b/admin/notes/tree-sitter/starter-guide
@@ -238,22 +238,22 @@ You’ll notice that tree-sitter’s font-lock doesn’t respect
 ‘font-lock-maximum-decoration’, major modes are free to set
 ‘treesit-font-lock-settings’ based on the value of
 ‘font-lock-maximum-decoration’, or provide more fine-grained control
-through other mode-specific means.
+through other mode-specific means. (Towards that end, the :toggle option in treesit-font-lock-rules is very useful.)
 
 * Indent
 
-Indent works like this: We have a bunch of rules that look like this:
+Indent works like this: We have a bunch of rules that look like
 
    (MATCHER ANCHOR OFFSET)
 
-At the beginning point is at the BOL of a line, we want to know which
-column to indent this line to. Let NODE be the node at point, we pass
-this node to the MATCHER of each rule, one of them will match the node
-("this node is a closing bracket!"). Then we pass the node to the
-ANCHOR, which returns a point, eg, the BOL of the previous line. We
-find the column number of that point (eg, 4), add OFFSET to it (eg,
-0), and that is the column we want to indent the current line to (4 +
-0 = 4).
+When the indentation process starts, point is at the BOL of a line, we
+want to know which column to indent this line to. Let NODE be the node
+at point, we pass this node to the MATCHER of each rule, one of them
+will match the node (eg, "this node is a closing bracket!"). Then we pass
+the node to the ANCHOR, which returns a point, eg, the BOL of the
+previous line. We find the column number of that point (eg, 4), add
+OFFSET to it (eg, 0), and that is the column we want to indent the
+current line to (4 + 0 = 4).
 
 For MATHCER we have