feature/tree-sitter 29418f954e: ; Improve tree-sitter documentation

[Yuan Fu]

branch: feature/tree-sitter
commit 29418f954eb114bf3c108b6e03569036f854ae45
Author: Yuan Fu <casouri@gmail.com>
Commit: Yuan Fu <casouri@gmail.com>

    ; Improve tree-sitter documentation
    
    * doc/lispref/modes.texi (Parser-based Font Lock)
    * doc/lispref/parsing.texi (Multiple Languages)
    * lisp/treesit.el (treesit-range-rules)
    (treesit-font-lock-rules): Improve phrasing around queries and keyword
    and values.
---
 doc/lispref/modes.texi   | 22 +++++++++++-----------
 doc/lispref/parsing.texi | 12 ++++++------
 lisp/treesit.el          | 15 +++++++++------
 3 files changed, 26 insertions(+), 23 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 8a0b5a12a1..da190b0b02 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3950,16 +3950,16 @@ example:
 @end group
 @end example
 
-This function takes a series of @var{query-spec}s, which are triplets
-@w{@code{@var{:keyword} @var{value} @dots{} @var{query}}}.  Each
-@var{query} is a tree-sitter query in either the string, s-expression
-or compiled form.
-
-The @var{:keyword} and @var{value} pairs configure the query which
-follows them in the argument list.  The @code{:lang} keyword sets the
-query's language.  The @code{:feature} keyword sets the feature name
-of the query.  Users can control which features are enabled with
-@code{font-lock-maximum-decoration} and
+This function takes a series of @var{query-spec}s, where each
+@var{query-spec} is a @var{query} preceded by multiple pairs of
+@var{:keyword} and @var{value}.  Each @var{query} is a tree-sitter
+query in either the string, s-expression or compiled form.
+
+For each @var{query}, the @var{:keyword} and @var{value} pairs add
+meta information to it.  The @code{:lang} keyword declares
+@var{query}'s language.  The @code{:feature} keyword sets the feature
+name of @var{query}.  Users can control which features are enabled
+with @code{font-lock-maximum-decoration} and
 @code{treesit-font-lock-feature-list} (described below).  These two
 keywords are mandated.
 
@@ -3975,7 +3975,7 @@ Other keywords are optional:
 @item @tab @code{keep} @tab Fill-in regions without an existing face
 @end multitable
 
-Lisp programs mark patterns in the query with capture names (names
+Lisp programs mark patterns in @var{query} with capture names (names
 that starts with @code{@@}), and tree-sitter will return matched nodes
 tagged with those same capture names.  For the purpose of
 fontification, capture names in @var{query} should be face names like
diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index a22b088111..cae83f8d5c 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -1537,14 +1537,14 @@ takes care of compiling queries and other 
post-processing, and outputs
 a value that @var{treesit-range-settings} can have.
 
 It takes a series of @var{query-spec}s, where each @var{query-spec} is
-a triplet of arguments @w{@code{@var{:keyword} @var{value} @dots{}
-@var{query}}}.  Each @var{query} is a tree-sitter query in either the
+a @var{query} preceded by zero or more pairs of @var{keyword} and
+@var{value}.  Each @var{query} is a tree-sitter query in either the
 string, s-expression or compiled form, or a function.
 
-If @var{query} is a tree-sitter query, it should be used with the pair
-@var{:keyword} and @var{value}, where the @code{:embed}
-keyword specifies the embedded language, and the @code{:host}
-keyword specified the host language.
+If @var{query} is a tree-sitter query, it should be preceeded by two
+@var{:keyword} @var{value} pairs, where the @code{:embed} keyword
+specifies the embedded language, and the @code{:host} keyword
+specified the host language.
 
 @code{treesit-update-ranges} uses @var{query} to figure out how to set
 the ranges for parsers for the embedded language.  It queries
diff --git a/lisp/treesit.el b/lisp/treesit.el
index 61bca49d8c..c2a15835b3 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -374,15 +374,17 @@ to change.  Use `treesit-range-rules' to set this 
variable.")
 (defun treesit-range-rules (&rest query-specs)
   "Produce settings for `treesit-range-settings'.
 
-QUERY-SPECS are a series of QUERY-SPEC triplets of the form
+QUERY-SPECS are a series of QUERY-SPECs, where each QUERY-SPEC is
+a QUERY preceeded by zero or more pairs of :KEYWORD and VALUE,
+like this:
 
     :KEYWORD VALUE... QUERY
 
 Each QUERY is a tree-sitter query in either the string,
 s-expression or compiled form.
 
-Each QUERY should be preceded by :KEYWORD VALUE pairs that
-configures this query.  For example,
+For each QUERY, :KEYWORD and VALUE pairs add meta information to
+it.  For example,
 
     (treesit-range-rules
      :embed \\='javascript
@@ -562,7 +564,8 @@ t, nil, append, prepend, keep.  See more in
 (defun treesit-font-lock-rules (&rest query-specs)
   "Return a value suitable for `treesit-font-lock-settings'.
 
-QUERY-SPECS is a series of 3 arguments:
+QUERY-SPECS is a series of QUERY-SPECs.  Each QUERY-SPEC is a
+QUERY preceded by multiple pairs of :KEYWORD and VALUE:
 
    :KEYWORD VALUE... QUERY
 
@@ -570,8 +573,8 @@ QUERY is a tree-sitter query in either the string, 
s-expression
 or compiled form.  For each query, captured nodes are highlighted
 with the capture name as its face.
 
-Before each QUERY there could be :KEYWORD and VALUE pairs that
-configure the query (and only that query).  For example,
+:KEYWORD and VALUE pairs preceeding a QUERY add meta information
+to QUERY.  For example,
 
     (treesit-font-lock-rules
      :language \\='javascript