Make tree-sitter font-lock support decoration levels

* admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html:
Update.
* admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html:
Update.
* doc/lispref/modes.texi: Mention the new :level option.
* lisp/treesit.el (treesit-font-lock-settings): Update docstring.
(treesit-font-lock-rules): Support :level.  Relayout the let form.
(treesit-font-lock-fontify-region): Support :level.

2 files changed, 13 insertions, 0 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 246ebf05193..c91152edc0e 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
@@ -117,8 +117,17 @@ every query must specify the language.  Other keywords are optional:
 <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>
+<tr><td width="15%"></td><td width="15%">nil</td><td width="60%">Always enable this query.</td></tr>
+<tr><td width="15%"><code>:level</code></td><td width="15%"><var>integer</var></td><td width="60%">If non-nil, its value should be the decoration level for this query.
+Decoration level is controlled by <code>font-lock-maximum-decoration</code>.</td></tr>
+<tr><td width="15%"></td><td width="15%">nil</td><td width="60%">Always enable this query.</td></tr>
 </table>
 
+<p>Note that a query is applied only when both <code>:toggle</code> and
+<code>:level</code> permit it.  <code>:level</code> is used for global,
+coarse-grained control, whereas <code>:toggle</code> is for local,
+fine-grained control.
+</p>
 <p>Capture names in <var>query</var> should be face names like
 <code>font-lock-keyword-face</code>.  The captured node will be fontified
 with that face.  Capture names can also be function names, in which
diff --git a/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html b/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html
index 7b6e51468a6..81b42f7f526 100644
--- a/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html
+++ b/admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html
@@ -94,6 +94,10 @@ for this Emacs instance.
 see <a href="Parser_002dbased-Font-Lock.html">Parser-based Font Lock</a>, <a href="Parser_002dbased-Indentation.html">Parser-based Indentation</a>, and
 <a href="List-Motion.html">Moving over Balanced Expressions</a>.
 </p>
+<p>About naming convention: use &ldquo;tree-sitter&rdquo; when referring to it as a
+noun, like <code>python-use-tree-sitter</code>, but use &ldquo;treesit&rdquo; for
+prefixes, like <code>python-treesit-indent-function</code>.
+</p>
 <p>To access the syntax tree of the text in a buffer, we need to first
 load a language definition and create a parser with it.  Next, we can
 query the parser for specific nodes in the syntax tree.  Then, we can