bug#64018: 29.0.91; Improve tree-sitter docs

bug#64018: 29.0.91; Improve tree-sitter docs

[Basil Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 316 bytes --]

Severity: minor
Tags: patch

While reading through the excellent tree-sitter documentation I
collected some potential improvements against emacs-29, either for
typos, to clarify wording, or fix up some probable errors like duplicate
instances of treesit-defun-type-regexp and parent-bol.

WDYT?

Thanks,

-- 
Basil


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-tree-sitter-docs.patch --]
[-- Type: text/x-diff, Size: 51689 bytes --]

From 64404942af8957cfa9e9044a3f62e9edadfbc252 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sun, 11 Jun 2023 15:19:28 +0100
Subject: [PATCH] Improve tree-sitter docs

* doc/lispref/positions.texi (List Motion): Incorporate more
accurate description of treesit-defun-type-regexp from '(elisp)
Tree-sitter Major Modes', replacing that duplicate entry.

* doc/lispref/parsing.texi (Parsing Program Source)
(Language Grammar, Using Parser, Retrieving Nodes)
(Accessing Node Information, Pattern Matching, Multiple Languages):
(Tree-sitter Major Modes):
* doc/lispref/modes.texi (Parser-based Font Lock): Improve wording,
grammar, punctuation, and markup.  Fix typos.
(Parser-based Indentation): Ditto.  Document indent rule presets
field-is, catch-all, nth-sibling, grand-parent, and
great-grand-parent.

* lisp/treesit.el (treesit-simple-indent-presets): Mention field-is,
catch-all, nth-sibling, grand-parent, great-grand-parent in
docstring.
(treesit-major-mode-setup, treesit-explore-mode): Improve
docstring/commentary grammar.
---
 doc/lispref/modes.texi     |  92 ++++++++----
 doc/lispref/parsing.texi   | 295 ++++++++++++++++++-------------------
 doc/lispref/positions.texi |  21 ++-
 lisp/treesit.el            |  56 ++++---
 4 files changed, 254 insertions(+), 210 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 444637fb31b..98da154b52a 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -4069,7 +4069,7 @@ Parser-based Font Lock
 
 Parser-based font lock and other font lock mechanisms are not mutually
 exclusive.  By default, if enabled, parser-based font lock runs first,
-replacing syntactic font lock, then the regexp-based font lock.
+replacing syntactic font lock, followed by regexp-based font lock.
 
 Although parser-based font lock doesn't share the same customization
 variables with regexp-based font lock, it uses similar customization
@@ -4102,7 +4102,7 @@ Parser-based Font Lock
 For more information about queries, patterns, and capture names, see
 @ref{Pattern Matching}.
 
-To setup tree-sitter fontification, a major mode should first set
+To set up tree-sitter fontification, a major mode should first set
 @code{treesit-font-lock-settings} with the output of
 @code{treesit-font-lock-rules}, then call
 @code{treesit-major-mode-setup}.
@@ -4161,11 +4161,11 @@ Parser-based Font Lock
 with that face.
 
 @findex treesit-fontify-with-override
-Capture names can also be function names, in which case the function
+A capture name can also be a function name, in which case the function
 is called with 4 arguments: @var{node} and @var{override}, @var{start}
 and @var{end}, where @var{node} is the node itself, @var{override} is
-the override property of the rule which captured this node, and
-@var{start} and @var{end} limits the region in which this function
+the @code{:override} property of the rule which captured this node,
+and @var{start} and @var{end} limit the region which this function
 should fontify.  (If this function wants to respect the @var{override}
 argument, it can use @code{treesit-fontify-with-override}.)
 
@@ -4201,9 +4201,9 @@ Parser-based Font Lock
 highlights whatever is being defined, e.g., the function name in a
 function definition, the struct name in a struct definition, the
 variable name in a variable definition; @code{assignment} highlights
-the whatever is being assigned to, e.g., the variable or field in an
+whatever is being assigned to, e.g., the variable or field in an
 assignment statement; @code{key} highlights keys in key-value pairs,
-e.g., keys in a JSON object, or a Python dictionary; @code{doc}
+e.g., keys in a JSON object or Python dictionary; @code{doc}
 highlights docstrings or doc-comments.
 
 For example, the value of this variable could be:
@@ -4977,7 +4977,7 @@ Parser-based Indentation
 to write a custom indentation function that queries the syntax tree
 and indents accordingly for each language, but that is a lot of work.
 It is more convenient to use the simple indentation engine described
-below: then the major mode needs only to write some indentation rules
+below: then the major mode needs only write some indentation rules,
 and the engine takes care of the rest.
 
 To enable the parser-based indentation engine, either set
@@ -4996,10 +4996,11 @@ Parser-based Indentation
 @cindex indentation rules, for parser-based indentation
 
 @defvar treesit-simple-indent-rules
-This local variable stores indentation rules for every language.  It is
-a list of the form: @w{@code{(@var{language} . @var{rules})}}, where
-@var{language} is a language symbol, and @var{rules} is a list of the
-form @w{@code{(@var{matcher} @var{anchor} @var{offset})}}.
+This local variable stores indentation rules for every language.  It
+is an alist with elements of the form @w{@code{(@var{language}
+. @var{rules})}}, where @var{language} is a language symbol, and
+@var{rules} is a list with elements of the form
+@w{@code{(@var{matcher} @var{anchor} @var{offset})}}.
 
 First, Emacs passes the smallest tree-sitter node at the beginning of
 the current line to @var{matcher}; if it returns non-@code{nil}, this
@@ -5033,14 +5034,14 @@ Parser-based Indentation
 
 @defvar treesit-simple-indent-presets
 This is a list of defaults for @var{matcher}s and @var{anchor}s in
-@code{treesit-simple-indent-rules}.  Each of them represents a function
-that takes 3 arguments: @var{node}, @var{parent} and @var{bol}.  The
-available default functions are:
+@code{treesit-simple-indent-rules}.  Each of them represents a
+function that takes 3 arguments: @var{node}, @var{parent}, and
+@var{bol}.  The available default functions are:
 
 @ftable @code
 @item no-node
 This matcher is a function that is called with 3 arguments:
-@var{node}, @var{parent}, and @var{bol}, and returns non-@code{nil},
+@var{node}, @var{parent}, and @var{bol}.  It returns non-@code{nil},
 indicating a match, if @var{node} is @code{nil}, i.e., there is no
 node that starts at @var{bol}.  This is the case when @var{bol} is on
 an empty line or inside a multi-line string, etc.
@@ -5057,6 +5058,12 @@ Parser-based Indentation
 and @var{bol}, and returns non-@code{nil} if @var{node}'s type matches
 regexp @var{type}.
 
+@item field-is
+This matcher is a function of one argument, @var{name}; it returns a
+function that is called with 3 arguments: @var{node}, @var{parent},
+and @var{bol}, and returns non-@code{nil} if @var{node}'s field name
+in @var{parent} matches regexp @var{name}.
+
 @item query
 This matcher is a function of one argument, @var{query}; it returns a
 function that is called with 3 arguments: @var{node}, @var{parent},
@@ -5097,27 +5104,50 @@ Parser-based Indentation
 @item comment-end
 This matcher is a function that is called with 3 arguments:
 @var{node}, @var{parent}, and @var{bol}, and returns non-@code{nil} if
-point is before a comment ending token.  Comment ending tokens are
-defined by regular expression @code{comment-end-skip}
+point is before a comment-ending token.  Comment-ending tokens are
+defined by regexp @code{comment-end-skip}.
+
+@item catch-all
+This matcher is a function that is called with 3 arguments:
+@var{node}, @var{parent}, and @var{bol}.  It always returns
+non-@code{nil}, indicating a match.
 
 @item first-sibling
 This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}, and returns the start of the first child
 of @var{parent}.
 
+@item nth-sibling
+This anchor is a function of two arguments: @var{n}, and an optional
+argument @var{named}.  It returns a function that is called with 3
+arguments: @var{node}, @var{parent}, and @var{bol}, and returns the
+start of the @var{n}th child of @var{parent}.  If @var{named} is
+non-@code{nil}, only named children are counted (@pxref{tree-sitter
+named node, named node}).
+
 @item parent
 This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}, and returns the start of @var{parent}.
 
+@item grand-parent
+This anchor is a function that is called with 3 arguments: @var{node},
+@var{parent}, and @var{bol}, and returns the start of @var{parent}'s
+parent.
+
+@item great-grand-parent
+This anchor is a function that is called with 3 arguments: @var{node},
+@var{parent}, and @var{bol}, and returns the start of @var{parent}'s
+parent's parent.
+
 @item parent-bol
 This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}, and returns the first non-space character
 on the line which @var{parent}'s start is on.
 
-@item parent-bol
+@item standalone-parent
 This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}.  It finds the first ancestor node
-(parent, grandparent, etc) of @var{node} that starts on its own line,
+(parent, grandparent, etc.) of @var{node} that starts on its own line,
 and return the start of that node.  ``Starting on its own line'' means
 there is only whitespace character before the node on the line which
 the node's start is on.
@@ -5150,14 +5180,14 @@ Parser-based Indentation
 
 @item prev-adaptive-prefix
 This anchor is a function that is called with 3 arguments: @var{node},
-@var{parent}, and @var{bol}.  It tries to go to the beginning of the
-previous non-empty line, and matches @code{adaptive-fill-regexp}.  If
-there is a match, this function returns the end of the match,
-otherwise it returns @code{nil}.  However, if the current line begins
-with a prefix (e.g., ``-''), return the beginning of the prefix of the
-previous line instead, so that the two prefixes align.  This anchor is
-useful for an @code{indent-relative}-like indent behavior for block
-comments.
+@var{parent}, and @var{bol}.  It tries to match
+@code{adaptive-fill-regexp} to the text at the beginning of the
+previous non-empty line.  If there is a match, this function returns
+the end of the match, otherwise it returns @code{nil}.  However, if
+the current line begins with a prefix (e.g., @samp{-}), return the
+beginning of the prefix of the previous line instead, so that the two
+prefixes align.  This anchor is useful for an
+@code{indent-relative}-like indent behavior for block comments.
 
 @end ftable
 @end defvar
@@ -5168,14 +5198,14 @@ Parser-based Indentation
 Here are some utility functions that can help writing parser-based
 indentation rules.
 
-@defun treesit-check-indent mode
-This function checks the current buffer's indentation against major
+@deffn Command treesit-check-indent mode
+This command checks the current buffer's indentation against major
 mode @var{mode}.  It indents the current buffer according to
 @var{mode} and compares the results with the current indentation.
 Then it pops up a buffer showing the differences.  Correct
 indentation (target) is shown in green color, current indentation is
 shown in red color.  @c Are colors customizable? faces?
-@end defun
+@end deffn
 
 It is also helpful to use @code{treesit-inspect-mode} (@pxref{Language
 Grammar}) when writing indentation rules.
diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 7e77af0a5cf..bd6e0572ca1 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -9,7 +9,7 @@ Parsing Program Source
 Emacs provides various ways to parse program source text and produce a
 @dfn{syntax tree}.  In a syntax tree, text is no longer considered a
 one-dimensional stream of characters, but a structured tree of nodes,
-where each node representing a piece of text.  Thus, a syntax tree can
+where each node represents a piece of text.  Thus, a syntax tree can
 enable interesting features like precise fontification, indentation,
 navigation, structured editing, etc.
 
@@ -19,8 +19,8 @@ Parsing Program Source
 
 In addition to those, Emacs also provides integration with
 @uref{https://tree-sitter.github.io/tree-sitter, the tree-sitter
-library}) if support for it was compiled in.  The tree-sitter library
-implements an incremental parser and has support from a wide range of
+library} if support for it was compiled in.  The tree-sitter library
+implements an incremental parser and has support for a wide range of
 programming languages.
 
 @defun treesit-available-p
@@ -65,10 +65,10 @@ Language Grammar
 
 @vindex treesit-extra-load-path
 @vindex treesit-load-language-error
-Tree-sitter language grammar are distributed as dynamic libraries.
+Tree-sitter language grammars are distributed as dynamic libraries.
 In order to use a language grammar in Emacs, you need to make sure
 that the dynamic library is installed on the system.  Emacs looks for
-language grammar in several places, in the following order:
+language grammars in several places, in the following order:
 
 @itemize @bullet
 @item
@@ -95,8 +95,8 @@ Language Grammar
 This means that Emacs could not find in the library the expected function
 that every language grammar library should export.
 @item (version-mismatch @var{error-msg})
-This means that the version of language grammar library is incompatible
-with that of the tree-sitter library.
+This means that the version of the language grammar library is
+incompatible with that of the tree-sitter library.
 @end table
 
 @noindent
@@ -105,7 +105,7 @@ Language Grammar
 
 @defun treesit-language-available-p language &optional detail
 This function returns non-@code{nil} if the language grammar for
-@var{language} exist and can be loaded.
+@var{language} exists and can be loaded.
 
 If @var{detail} is non-@code{nil}, return @code{(t . nil)} when
 @var{language} is available, and @code{(nil . @var{data})} when it's
@@ -126,7 +126,7 @@ Language Grammar
 @end example
 
 to the list in the variable @code{treesit-load-name-override-list}, where
-@var{library-base-name} is the basename of the dynamic library's file name,
+@var{library-base-name} is the basename of the dynamic library's file name
 (usually, @file{libtree-sitter-@var{language}}), and
 @var{function-name} is the function provided by the library
 (usually, @code{tree_sitter_@var{language}}).  For example,
@@ -146,7 +146,7 @@ Language Grammar
 tree-sitter library.  By default, it returns the latest ABI version
 supported by the library, but if @var{min-compatible} is
 non-@code{nil}, it returns the oldest ABI version which the library
-still can support.  language grammar libraries must be built for
+still can support.  Language grammar libraries must be built for
 ABI versions between the oldest and the latest versions supported by
 the tree-sitter library, otherwise the library will be unable to load
 them.
@@ -232,11 +232,11 @@ Language Grammar
 @cindex explore tree-sitter syntax tree
 @cindex inspection of tree-sitter parse tree nodes
 
-To aid in understanding the syntax of a language and in debugging of
-Lisp program that use the syntax tree, Emacs provides an ``explore''
-mode, which displays the syntax tree of the source in the current
-buffer in real time.  Emacs also comes with an ``inspect mode'', which
-displays information of the nodes at point in the mode-line.
+To aid in understanding the syntax of a language and in debugging Lisp
+programs that use the syntax tree, Emacs provides an ``explore'' mode,
+which displays the syntax tree of the source in the current buffer in
+real time.  Emacs also comes with an ``inspect mode'', which displays
+information of the nodes at point in the mode-line.
 
 @deffn Command treesit-explore-mode
 This mode pops up a window displaying the syntax tree of the source in
@@ -271,7 +271,7 @@ Language Grammar
 @heading Reading the grammar definition
 @cindex reading grammar definition, tree-sitter
 
-Authors of language grammar define the @dfn{grammar} of a
+Authors of language grammars define the @dfn{grammar} of a
 programming language, which determines how a parser constructs a
 concrete syntax tree out of the program text.  In order to use the
 syntax tree effectively, you need to consult the @dfn{grammar file}.
@@ -283,7 +283,7 @@ Language Grammar
 homepage}.
 
 The grammar definition is written in JavaScript.  For example, the
-rule matching a @code{function_definition} node looks like
+rule matching a @code{function_definition} node may look like
 
 @example
 @group
@@ -331,13 +331,13 @@ Language Grammar
 @item choice(@var{rule1}, @var{rule2}, @dots{})
 matches one of the rules in its arguments.
 @item repeat(@var{rule})
-matches @var{rule} for @emph{zero or more} times.
+matches @var{rule} @emph{zero or more} times.
 This is like the @samp{*} operator in regular expressions.
 @item repeat1(@var{rule})
-matches @var{rule} for @emph{one or more} times.
+matches @var{rule} @emph{one or more} times.
 This is like the @samp{+} operator in regular expressions.
 @item optional(@var{rule})
-matches @var{rule} for @emph{zero or one} time.
+matches @var{rule} @emph{zero or one} times.
 This is like the @samp{?} operator in regular expressions.
 @item field(@var{name}, @var{rule})
 assigns field name @var{name} to the child node matched by @var{rule}.
@@ -366,7 +366,7 @@ Language Grammar
 @item token.immediate(@var{rule})
 Normally, grammar rules ignore preceding whitespace; this
 changes @var{rule} to match only when there is no preceding
-whitespaces.
+whitespace.
 @item prec(@var{n}, @var{rule})
 gives @var{rule} the level-@var{n} precedence.
 @item prec.left([@var{n},] @var{rule})
@@ -412,7 +412,7 @@ Using Parser
 If that buffer is an indirect buffer, its base buffer is used instead.
 That is, indirect buffers use their base buffer's parsers.  If the
 base buffer is narrowed, an indirect buffer might not be able to
-retrieve information of the portion of the buffer text that are
+retrieve information of the portion of the buffer text that is
 invisible in the base buffer.  Lisp programs should widen as necessary
 should they want to use a parser in an indirect buffer.
 @end defun
@@ -441,7 +441,7 @@ Using Parser
 
 @vindex treesit-buffer-too-large
 When a parser does parse, it checks for the size of the buffer.
-Tree-sitter can only handle buffer no larger than about 4GB.  If the
+Tree-sitter can only handle buffers no larger than about 4GB@.  If the
 size exceeds that, Emacs signals the @code{treesit-buffer-too-large}
 error with signal data being the buffer size.
 
@@ -500,13 +500,12 @@ Using Parser
 though the text is not directly edited, it is deemed to be ``changed''
 nevertheless.
 
-Emacs lets a Lisp program to register callback functions
-(a.k.a.@: @dfn{notifiers}) for this kind of changes.  A notifier
-function takes two arguments: @var{ranges} and @var{parser}.
-@var{ranges} is a list of cons cells of the form @w{@code{(@var{start}
-. @var{end})}}, where @var{start} and @var{end} mark the start and the
-end positions of a range.  @var{parser} is the parser issuing the
-notification.
+Emacs lets a Lisp program register callback functions (a.k.a.@:
+@dfn{notifiers}) for these kinds of changes.  A notifier function
+takes two arguments: @var{ranges} and @var{parser}.  @var{ranges} is a
+list of cons cells of the form @w{@code{(@var{start} . @var{end})}},
+where @var{start} and @var{end} mark the start and the end positions
+of a range.  @var{parser} is the parser issuing the notification.
 
 Every time a parser reparses a buffer, it compares the old and new
 parse-tree, computes the ranges in which nodes have changed, and
@@ -537,7 +536,7 @@ Retrieving Nodes
 @cindex get node, tree-sitter
 
 @cindex terminology, for tree-sitter functions
-Here's some terminology and conventions we use when documenting
+Here are some terms and conventions we use when documenting
 tree-sitter functions.
 
 A node in a syntax tree spans some portion of the program text in the
@@ -571,8 +570,8 @@ Retrieving Nodes
 A leaf node is a node that doesn't have any child nodes.
 
 This function tries to return a node whose span covers @var{pos}: the
-node's beginning position is less or equal to @var{pos}, and the
-node's end position is greater or equal to @var{pos}.
+node's beginning position is less than or equal to @var{pos}, and the
+node's end position is greater than or equal to @var{pos}.
 
 If no leaf node's span covers @var{pos} (e.g., @var{pos} is in the
 whitespace between two leaf nodes), this function returns the first
@@ -612,7 +611,7 @@ Retrieving Nodes
 is at or after @var{end}.
 
 @emph{Beware:} calling this function on an empty line that is not
-inside any top-level construct (function definition, etc.) most
+inside any top-level construct (function definition, etc.@:) most
 probably will give you the root node, because the root node is the
 smallest node that covers that empty line.  Most of the time, you want
 to use @code{treesit-node-at} instead.
@@ -672,7 +671,7 @@ Retrieving Nodes
 is the string text.
 
 This function returns @code{nil} if there is no @var{n}'th child.
-@var{n} could be negative, e.g., @code{-1} represents the last child.
+@var{n} could be negative, e.g., @minus{}1 represents the last child.
 @end defun
 
 @defun treesit-node-children node &optional named
@@ -694,7 +693,7 @@ Retrieving Nodes
 @cindex nodes, by field name
 @cindex syntax tree nodes, by field name
 
-To make the syntax tree easier to analyze, many language grammar
+To make the syntax tree easier to analyze, many language grammars
 assign @dfn{field names} to child nodes (@pxref{tree-sitter node field
 name, field name}).  For example, a @code{function_definition} node
 could have a @code{declarator} node and a @code{body} node.
@@ -729,7 +728,7 @@ Retrieving Nodes
 This function finds the @emph{smallest} descendant node of @var{node}
 that spans the region of text between positions @var{beg} and
 @var{end}.  It is similar to @code{treesit-node-at}.  If @var{named}
-is non-@code{nil}, it looks for smallest named child.
+is non-@code{nil}, it looks for the smallest named child.
 @end defun
 
 @heading Searching for node
@@ -755,8 +754,8 @@ Retrieving Nodes
 Like @code{treesit-search-subtree}, this function also traverses the
 parse tree and matches each node with @var{predicate} (except for
 @var{start}), where @var{predicate} can be a regexp or a function.
-For a tree like the below where @var{start} is marked S, this function
-traverses as numbered from 1 to 12:
+For a tree like the one below where @var{start} is marked @samp{S},
+this function traverses as numbered from 1 to 12:
 
 @example
 @group
@@ -773,7 +772,7 @@ Retrieving Nodes
 @end example
 
 Note that this function doesn't traverse the subtree of @var{start},
-and it always traverse leaf nodes first, then upwards.
+and it always traverses leaf nodes first, before moving upwards.
 
 Like @code{treesit-search-subtree}, this function only searches for
 named nodes by default, but if @var{all} is non-@code{nil}, it
@@ -786,10 +785,10 @@ Retrieving Nodes
 start positions greater than the end position of @var{start}.
 
 In the tree shown above, @code{treesit-search-subtree} traverses node
-S (@var{start}) and nodes marked with @code{o}, where this function
-traverses the nodes marked with numbers.  This function is useful for
-answering questions like ``what is the first node after @var{start} in
-the buffer that satisfies some condition?''
+@samp{S} (@var{start}) and nodes marked with @code{o}, where this
+function traverses the nodes marked with numbers.  This function is
+useful for answering questions like ``what is the first node after
+@var{start} in the buffer that satisfies some condition?''
 @end defun
 
 @defun treesit-search-forward-goto node predicate &optional start backward all
@@ -801,7 +800,7 @@ Retrieving Nodes
 progress in terms of buffer position: the start/end position of the
 returned node is always greater than that of @var{node}.
 
-Arguments @var{predicate}, @var{backward} and @var{all} are the same
+Arguments @var{predicate}, @var{backward}, and @var{all} are the same
 as in @code{treesit-search-forward}.
 @end defun
 
@@ -811,12 +810,12 @@ Retrieving Nodes
 It takes the subtree under @var{root}, and combs it so only the nodes
 that match @var{predicate} are left.  Like previous functions, the
 @var{predicate} can be a regexp string that matches against each
-node's type, or a function that takes a node and return non-@code{nil}
-if it matches.
+node's type, or a function that takes a node and returns
+non-@code{nil} if it matches.
 
-For example, for a subtree on the left that consist of both numbers
-and letters, if @var{predicate} is ``letter only'', the returned tree
-is the one on the right.
+For example, given the subtree on the left that consists of both
+numbers and letters, if @var{predicate} is ``letter only'', the
+returned tree is the one on the right.
 
 @example
 @group
@@ -836,9 +835,9 @@ Retrieving Nodes
 
 If @var{process-fn} is non-@code{nil}, instead of returning the
 matched nodes, this function passes each node to @var{process-fn} and
-uses the returned value instead.  If non-@code{nil}, @var{depth} is
-the number of levels to go down from @var{root}.  If @var{depth} is
-@code{nil}, it defaults to 1000.
+uses the returned value instead.  If non-@code{nil}, @var{depth}
+limits the number of levels to go down from @var{root}.  If
+@var{depth} is @code{nil}, it defaults to 1000.
 
 Each node in the returned tree looks like
 @w{@code{(@var{tree-sitter-node} . (@var{child} @dots{}))}}.  The
@@ -853,17 +852,17 @@ Retrieving Nodes
 This function finds immediate children of @var{node} that satisfy
 @var{predicate}.
 
-The @var{predicate} function takes a node as the argument and should
+The @var{predicate} function takes a node as argument and should
 return non-@code{nil} to indicate that the node should be kept.  If
-@var{named} is non-@code{nil}, this function only examines the named
+@var{named} is non-@code{nil}, this function only examines named
 nodes.
 @end defun
 
 @defun treesit-parent-until node predicate &optional include-node
 This function repeatedly finds the parents of @var{node}, and returns
 the parent that satisfies @var{pred}, a function that takes a node as
-the argument and returns a boolean that indicates a match.  If no
-parent satisfies @var{pred}, this function returns @code{nil}.
+argument and returns a boolean that indicates a match.  If no parent
+satisfies @var{pred}, this function returns @code{nil}.
 
 Normally this function only looks at the parents of @var{node} but not
 @var{node} itself.  But if @var{include-node} is non-@code{nil}, this
@@ -873,10 +872,10 @@ Retrieving Nodes
 @defun treesit-parent-while node pred
 This function goes up the tree starting from @var{node}, and keeps
 doing so as long as the nodes satisfy @var{pred}, a function that
-takes a node as the argument.  That is, this function returns the
-highest parent of @var{node} that still satisfies @var{pred}.  Note
-that if @var{node} satisfies @var{pred} but its immediate parent
-doesn't, @var{node} itself is returned.
+takes a node as argument.  That is, this function returns the highest
+parent of @var{node} that still satisfies @var{pred}.  Note that if
+@var{node} satisfies @var{pred} but its immediate parent doesn't,
+@var{node} itself is returned.
 @end defun
 
 @defun treesit-node-top-level node &optional type
@@ -979,7 +978,7 @@ Accessing Node Information
 @cindex tree-sitter, live parsing node
 @cindex live node, tree-sitter
 A node is considered @dfn{live} if its parser is not deleted, and the
-buffer to which it belongs to is a live buffer (@pxref{Killing Buffers}).
+buffer to which it belongs is a live buffer (@pxref{Killing Buffers}).
 
 @defun treesit-node-check node property
 This function returns non-@code{nil} if @var{node} has the specified
@@ -1016,12 +1015,12 @@ Accessing Node Information
 @var{node}.  It returns @code{nil} if there is no @var{n}'th child, or
 the @var{n}'th child doesn't have a field name.
 
-Note that @var{n} counts both named and anonymous child.  And @var{n}
-could be negative, e.g., @code{-1} represents the last child.
+Note that @var{n} counts both named and anonymous children, and
+@var{n} can be negative, e.g., @minus{}1 represents the last child.
 @end defun
 
 @defun treesit-node-child-count node &optional named
-This function finds the number of children of @var{node}.  If
+This function returns the number of children of @var{node}.  If
 @var{named} is non-@code{nil}, it only counts named children
 (@pxref{tree-sitter named node, named node}).
 @end defun
@@ -1048,7 +1047,7 @@ Pattern Matching
 @cindex query, tree-sitter
 A @dfn{query} consists of multiple @dfn{patterns}.  Each pattern is an
 s-expression that matches a certain node in the syntax node.  A
-pattern has the form @w{@code{(@var{type} (@var{child}@dots{}))}}
+pattern has the form @w{@code{(@var{type} (@var{child}@dots{}))}}.
 
 For example, a pattern that matches a @code{binary_expression} node that
 contains @code{number_literal} child nodes would look like
@@ -1084,30 +1083,31 @@ Pattern Matching
 Now we can introduce the @dfn{query functions}.
 
 @defun treesit-query-capture node query &optional beg end node-only
-This function matches patterns in @var{query} within @var{node}.
-The argument @var{query} can be either a string, a s-expression, or a
+This function matches patterns in @var{query} within @var{node}.  The
+argument @var{query} can be either a string, an s-expression, or a
 compiled query object.  For now, we focus on the string syntax;
-s-expression syntax and compiled query are described at the end of the
-section.
+s-expression syntax and compiled queries are described at the end of
+the section.
 
 The argument @var{node} can also be a parser or a language symbol.  A
-parser means using its root node, a language symbol means find or
-create a parser for that language in the current buffer, and use the
-root node.
+parser means use its root node, a language symbol means find or create
+a parser for that language in the current buffer, and use the root
+node.
 
-The function returns all the captured nodes in a list of the form
-@w{@code{(@var{capture_name} . @var{node})}}.  If @var{node-only} is
-non-@code{nil}, it returns the list of nodes instead.  By default the
-entire text of @var{node} is searched, but if @var{beg} and @var{end}
-are both non-@code{nil}, they specify the region of buffer text where
-this function should match nodes.  Any matching node whose span
-overlaps with the region between @var{beg} and @var{end} are captured,
-it doesn't have to be completely in the region.
+The function returns all the captured nodes in an alist with elements
+of the form @w{@code{(@var{capture_name} . @var{node})}}.  If
+@var{node-only} is non-@code{nil}, it returns the list of @var{node}s
+instead.  By default the entire text of @var{node} is searched, but if
+@var{beg} and @var{end} are both non-@code{nil}, they specify the
+region of buffer text where this function should match nodes.  Any
+matching node whose span overlaps with the region between @var{beg}
+and @var{end} is captured; it doesn't have to be completely contained
+in the region.
 
 @vindex treesit-query-error
 @findex treesit-query-validate
 This function raises the @code{treesit-query-error} error if
-@var{query} is malformed.  The signal data contains a description of
+@var{query} is malformed.  The signal data contain a description of
 the specific error.  You can use @code{treesit-query-validate} to
 validate and debug the query.
 @end defun
@@ -1146,13 +1146,13 @@ Pattern Matching
 @end example
 
 @defun treesit-query-string string query language
-This function parses @var{string} with @var{language}, matches its
-root node with @var{query}, and returns the result.
+This function parses @var{string} as @var{language}, matches its root
+node with @var{query}, and returns the result.
 @end defun
 
 @heading More query syntax
 
-Besides node type and capture, tree-sitter's pattern syntax can
+Besides node type and capture name, tree-sitter's pattern syntax can
 express anonymous node, field name, wildcard, quantification,
 grouping, alternation, anchor, and predicate.
 
@@ -1168,11 +1168,11 @@ Pattern Matching
 @subheading Wild card
 
 In a pattern, @samp{(_)} matches any named node, and @samp{_} matches
-any named and anonymous node.  For example, to capture any named child
+any named or anonymous node.  For example, to capture any named child
 of a @code{binary_expression} node, the pattern would be
 
 @example
-(binary_expression (_) @@in_biexp)
+(binary_expression (_) @@in-biexp)
 @end example
 
 @subheading Field name
@@ -1190,7 +1190,7 @@ Pattern Matching
 @end example
 
 It is also possible to capture a node that doesn't have a certain
-field, say, a @code{function_definition} without a @code{body} field.
+field, say, a @code{function_definition} without a @code{body} field:
 
 @example
 (function_definition !body) @@func-no-body
@@ -1199,20 +1199,20 @@ Pattern Matching
 @subheading Quantify node
 
 @cindex quantify node, tree-sitter
-Tree-sitter recognizes quantification operators @samp{*}, @samp{+} and
-@samp{?}.  Their meanings are the same as in regular expressions:
+Tree-sitter recognizes quantification operators @samp{*}, @samp{+},
+and @samp{?}.  Their meanings are the same as in regular expressions:
 @samp{*} matches the preceding pattern zero or more times, @samp{+}
-matches one or more times, and @samp{?} matches zero or one time.
+matches one or more times, and @samp{?} matches zero or one times.
 
 For example, the following pattern matches @code{type_declaration}
-nodes that has @emph{zero or more} @code{long} keyword.
+nodes that have @emph{zero or more} @code{long} keywords.
 
 @example
 (type_declaration "long"*) @@long-type
 @end example
 
-The following pattern matches a type declaration that has zero or one
-@code{long} keyword:
+The following pattern matches a type declaration that may or may not
+have a @code{long} keyword:
 
 @example
 (type_declaration "long"?) @@long-type
@@ -1220,9 +1220,9 @@ Pattern Matching
 
 @subheading Grouping
 
-Similar to groups in regular expression, we can bundle patterns into
+Similar to groups in regular expressions, we can bundle patterns into
 groups and apply quantification operators to them.  For example, to
-express a comma separated list of identifiers, one could write
+express a comma-separated list of identifiers, one could write
 
 @example
 (identifier) ("," (identifier))*
@@ -1230,10 +1230,10 @@ Pattern Matching
 
 @subheading Alternation
 
-Again, similar to regular expressions, we can express ``match anyone
-from this group of patterns'' in a pattern.  The syntax is a list of
-patterns enclosed in square brackets.  For example, to capture some
-keywords in C, the pattern would be
+Again, similar to regular expressions, we can express ``match any one
+of these patterns'' in a pattern.  The syntax is a list of patterns
+enclosed in square brackets.  For example, to capture some keywords in
+C, the pattern would be
 
 @example
 @group
@@ -1292,14 +1292,14 @@ Pattern Matching
 @end example
 
 @noindent
-tree-sitter only matches arrays where the first element equals to the
-last element.  To attach a predicate to a pattern, we need to group
-them together.  A predicate always starts with a @samp{#}.  Currently
-there are three predicates, @code{#equal}, @code{#match}, and
-@code{#pred}.
+tree-sitter only matches arrays where the first element is equal to
+the last element.  To attach a predicate to a pattern, we need to
+group them together.  A predicate always starts with a @samp{#}.
+Currently there are three predicates: @code{#equal}, @code{#match},
+and @code{#pred}.
 
 @deffn Predicate equal arg1 arg2
-Matches if @var{arg1} equals to @var{arg2}.  Arguments can be either
+Matches if @var{arg1} is equal to @var{arg2}.  Arguments can be either
 strings or capture names.  Capture names represent the text that the
 captured node spans in the buffer.
 @end deffn
@@ -1322,7 +1322,7 @@ Pattern Matching
 
 @cindex tree-sitter patterns as sexps
 @cindex patterns, tree-sitter, in sexp form
-Besides strings, Emacs provides a s-expression based syntax for
+Besides strings, Emacs provides an s-expression based syntax for
 tree-sitter patterns.  It largely resembles the string-based syntax.
 For example, the following query
 
@@ -1354,7 +1354,7 @@ Pattern Matching
 @end example
 
 Most patterns can be written directly as strange but nevertheless
-valid s-expressions.  Only a few of them needs modification:
+valid s-expressions.  Only a few of them need modification:
 
 @itemize
 @item
@@ -1382,7 +1382,7 @@ Pattern Matching
 @end example
 
 @noindent
-is written in s-expression as
+is written in s-expression syntax as
 
 @example
 @group
@@ -1407,7 +1407,7 @@ Pattern Matching
 query object and returns it.
 
 This function raises the @code{treesit-query-error} error if
-@var{query} is malformed.  The signal data contains a description of
+@var{query} is malformed.  The signal data contain a description of
 the specific error.  You can use @code{treesit-query-validate} to
 validate and debug the query.
 @end defun
@@ -1440,8 +1440,8 @@ Multiple Languages
 need to be assigned different parsers.  Traditionally, this is
 achieved by using narrowing.  While tree-sitter works with narrowing
 (@pxref{tree-sitter narrowing, narrowing}), the recommended way is
-instead to set regions of buffer text (i.e., ranges) in which a parser
-will operate.  This section describes functions for setting and
+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.
 
 Lisp programs should call @code{treesit-update-ranges} to make sure
@@ -1459,7 +1459,7 @@ Multiple Languages
 @defun treesit-parser-set-included-ranges parser ranges
 This function sets up @var{parser} to operate on @var{ranges}.  The
 @var{parser} will only read the text of the specified ranges.  Each
-range in @var{ranges} is a list of the form @w{@code{(@var{beg}
+range in @var{ranges} is a pair of the form @w{@code{(@var{beg}
 . @var{end})}}.
 
 The ranges in @var{ranges} must come in order and must not overlap.
@@ -1478,7 +1478,7 @@ Multiple Languages
 @vindex treesit-range-invalid
 If @var{ranges} violates this constraint, or something else went
 wrong, this function signals the @code{treesit-range-invalid} error.
-The signal data contains a specific error message and the ranges we
+The signal data contain a specific error message and the ranges we
 are trying to set.
 
 This function can also be used for disabling ranges.  If @var{ranges}
@@ -1533,7 +1533,7 @@ Multiple Languages
 @heading Supporting multiple languages in Lisp programs
 
 It should suffice for general Lisp programs to call the following two
-functions in order to support program sources that mixes multiple
+functions in order to support program sources that mix multiple
 languages.
 
 @defun treesit-update-ranges &optional beg end
@@ -1569,13 +1569,13 @@ Multiple Languages
 embedded languages with that information, and then parses the embedded
 languages.
 
-Take a buffer containing @acronym{HTML}, @acronym{CSS} and JavaScript
+Take a buffer containing @acronym{HTML}, @acronym{CSS}, and JavaScript
 as an example.  A Lisp program will first parse the whole buffer with
 an @acronym{HTML} parser, then query the parser for
-@code{style_element} and @code{script_element} nodes, which
-correspond to @acronym{CSS} and JavaScript text, respectively.  Then
-it sets the range of the @acronym{CSS} and JavaScript parser to the
-ranges in which their corresponding nodes span.
+@code{style_element} and @code{script_element} nodes, which correspond
+to @acronym{CSS} and JavaScript text, respectively.  Then it sets the
+range of the @acronym{CSS} and JavaScript parsers to the range which
+their corresponding nodes span.
 
 Given a simple @acronym{HTML} document:
 
@@ -1629,17 +1629,17 @@ Multiple Languages
 
 @example
 @group
-(setq-local treesit-range-settings
-            (treesit-range-rules
-             :embed 'javascript
-             :host 'html
-             '((script_element (raw_text) @@capture))
+(setq treesit-range-settings
+      (treesit-range-rules
+       :embed 'javascript
+       :host 'html
+       '((script_element (raw_text) @@capture))
 @end group
 
 @group
-             :embed 'css
-             :host 'html
-             '((style_element (raw_text) @@capture))))
+       :embed 'css
+       :host 'html
+       '((style_element (raw_text) @@capture))))
 @end group
 @end example
 
@@ -1649,20 +1649,20 @@ Multiple Languages
 value that @code{treesit-range-settings} can have.
 
 It takes a series of @var{query-spec}s, where each @var{query-spec} is
-a @var{query} preceded by zero or more @var{keyword}/@var{value}
+a @var{query} preceded by zero or more @var{:keyword}/@var{value}
 pairs.  Each @var{query} is a tree-sitter query in either the
-string, s-expression or compiled form, or a function.
+string, s-expression, or compiled form, or a function.
 
 If @var{query} is a tree-sitter query, it should be preceded 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.
+specifies 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
-@var{query} in a host language parser, computes the ranges in which
-the captured nodes span, and applies these ranges to embedded
-language parsers.
+@var{query} in a host language parser, computes the ranges which the
+captured nodes span, and applies these ranges to embedded language
+parsers.
 
 If @var{query} is a function, it doesn't need any @var{:keyword} and
 @var{value} pair.  It should be a function that takes 2 arguments,
@@ -1717,8 +1717,8 @@ Tree-sitter Major Modes
 @code{treesit-ready-p} automatically emits a warning if conditions for
 enabling tree-sitter aren't met.
 
-If a tree-sitter major mode shares setup with their ``native''
-counterpart, they can create a ``base mode'' that contains the common
+If a tree-sitter major mode shares setup with its ``native''
+counterpart, one can create a ``base mode'' that contains the common
 setup, like this:
 
 @example
@@ -1749,9 +1749,9 @@ Tree-sitter Major Modes
 @defun treesit-ready-p language &optional quiet
 This function checks for conditions for activating tree-sitter.  It
 checks whether Emacs was built with tree-sitter, whether the buffer's
-size is not too large for tree-sitter to handle it, and whether the
-language grammar for @var{language} is available on the system
-(@pxref{Language Grammar}).
+size is not too large for tree-sitter to handle, and whether the
+grammar for @var{language} is available on the system (@pxref{Language
+Grammar}).
 
 This function emits a warning if tree-sitter cannot be activated.  If
 @var{quiet} is @code{message}, the warning is turned into a message;
@@ -1789,7 +1789,7 @@ Tree-sitter Major Modes
 @end itemize
 @end defun
 
-For more information of these built-in tree-sitter features,
+For more information on these built-in tree-sitter features,
 @pxref{Parser-based Font Lock}, @pxref{Parser-based Indentation}, and
 @pxref{List Motion}.
 
@@ -1828,28 +1828,17 @@ Tree-sitter Major Modes
 @defvar treesit-defun-name-function
 If non-@code{nil}, this variable's value should be a function that is
 called with a node as its argument, and returns the defun name of the
-node.  The function should have the same semantic as
+node.  The function should have the same semantics as
 @code{treesit-defun-name}: if the node is not a defun node, or the
 node is a defun node but doesn't have a name, or the node is
 @code{nil}, it should return @code{nil}.
 @end defvar
 
-@defvar treesit-defun-type-regexp
-This variable determines which nodes are considered defuns by Emacs.
-It can be a regexp that matches the type of defun nodes.
-
-Sometimes not all nodes matched by the regexp are valid defuns.
-Therefore, this variable can also be a cons cell of the form
-@w{(@var{regexp} . @var{pred})}, where @var{pred} should be a function
-that takes a node as its argument, and returns @code{t} if the node is
-valid defun, or @code{nil} if it is not valid.
-@end defvar
-
 @node Tree-sitter C API
 @section Tree-sitter C API Correspondence
 
 Emacs' tree-sitter integration doesn't expose every feature
-provided by tree-sitter's C API.  Missing features include:
+provided by tree-sitter's C API@.  Missing features include:
 
 @itemize
 @item
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index e09fd4e7ca5..d98e425b972 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -844,18 +844,25 @@ List Motion
 @code{treesit-beginning-of-defun} and @code{treesit-end-of-defun}.
 
 @defvar treesit-defun-type-regexp
-The value of this variable is a regexp matching the node type of defun
-nodes.  (For ``node'' and ``node type'', @pxref{Parsing Program Source}.)
+This variable determines which nodes are considered defuns by Emacs.
+It can be a regexp that matches the type of defun nodes.  (For
+``node'' and ``node type'', @pxref{Parsing Program Source}.)
 
 For example, @code{python-mode} sets this variable to a regexp that
-matches either @code{"function_definition"} or @code{"class_definition"}.
+matches either @code{function_definition} or @code{class_definition}.
+
+Sometimes not all nodes matched by the regexp are valid defuns.
+Therefore, this variable can also be a cons cell of the form
+@w{(@var{regexp} . @var{pred})}, where @var{pred} should be a function
+that takes a node as its argument, and returns non-@code{nil} if the
+node is a valid defun, or @code{nil} if it is not valid.
 @end defvar
 
 @defvar treesit-defun-tactic
-This variable determines how Emacs treats nested defuns.  If the
-value is @code{top-level}, navigation functions only move across
-top-level defuns, if the value is @code{nested}, navigation functions
-recognize nested defuns.
+This variable determines how Emacs treats nested defuns.  If the value
+is @code{top-level}, navigation functions only move across top-level
+defuns.  If the value is @code{nested}, navigation functions recognize
+nested defuns.
 @end defvar
 
 @node Skipping Characters
diff --git a/lisp/treesit.el b/lisp/treesit.el
index 3ec4fbc5c91..0e1d7931d49 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -1168,7 +1168,6 @@ treesit-simple-indent-presets
                              (save-excursion
                                (goto-char bol)
                                (looking-at-p comment-end-skip))))
-        ;; TODO: Document.
         (cons 'catch-all (lambda (&rest _) t))
 
         (cons 'query (lambda (pattern)
@@ -1182,7 +1181,6 @@ treesit-simple-indent-presets
         (cons 'first-sibling (lambda (_n parent &rest _)
                                (treesit-node-start
                                 (treesit-node-child parent 0))))
-        ;; TODO: Document.
         (cons 'nth-sibling (lambda (n &optional named)
                              (lambda (_n parent &rest _)
                                (treesit-node-start
@@ -1224,7 +1222,6 @@ treesit-simple-indent-presets
                          (or (and this-line-has-prefix
                                   (match-beginning 1))
                              (match-end 0)))))))
-        ;; TODO: Document.
         (cons 'grand-parent
               (lambda (_n parent &rest _)
                 (treesit-node-start (treesit-node-parent parent))))
@@ -1295,10 +1292,10 @@ treesit-simple-indent-presets
                         (mapcar (lambda (fn)
                                   (funcall fn node parent bol))
                                 fns)))))
-  "A list of presets.
-These presets that can be used as MATHER and ANCHOR in
-`treesit-simple-indent-rules'.  MACHTERs and ANCHORs are
-functions that take 3 arguments: NODE, PARENT and BOL.
+  "A list of indent rule presets.
+These presets can be used as MATCHER and ANCHOR values in
+`treesit-simple-indent-rules'.  MATCHERs and ANCHORs are
+functions that take 3 arguments: NODE, PARENT, and BOL.
 
 MATCHER:
 
@@ -1329,6 +1326,10 @@ treesit-simple-indent-presets
 
     Checks that NODE's type matches regexp TYPE.
 
+\(field-is NAME)
+
+    Checks that NODE's field name in PARENT matches regexp NAME.
+
 \(n-p-gp NODE-TYPE PARENT-TYPE GRANDPARENT-TYPE)
 
     Checks for NODE's, its parent's, and its grandparent's type.
@@ -1342,16 +1343,33 @@ treesit-simple-indent-presets
 
     Matches if text after point matches `treesit-comment-end'.
 
+catch-all
+
+    Always matches.
+
 ANCHOR:
 
 first-sibling
 
     Returns the start of the first child of PARENT.
 
+\(nth-sibling N &optional NAMED)
+
+    Returns the start of the Nth child of PARENT.
+    NAMED non-nil means count only named nodes.
+
 parent
 
     Returns the start of PARENT.
 
+grand-parent
+
+    Returns the start of PARENT's parent.
+
+great-grand-parent
+
+    Returns the start of PARENT's parent's parent.
+
 parent-bol
 
     Returns the beginning of non-space characters on the line where
@@ -1359,8 +1377,8 @@ treesit-simple-indent-presets
 
 standalone-parent
 
-    Finds the first ancestor node (parent, grandparent, etc) that
-    starts on its own line, and return the start of that node.
+    Finds the first ancestor node (parent, grandparent, etc.) that
+    starts on its own line, and returns the start of that node.
 
 prev-sibling
 
@@ -1391,7 +1409,7 @@ treesit-simple-indent-presets
     end of the match, otherwise return nil.  However, if the
     current line begins with a prefix, return the beginning of
     the prefix of the previous line instead, so that the two
-    prefixes aligns.  This is useful for a `indent-relative'-like
+    prefixes aligns.  This is useful for an `indent-relative'-like
     indent behavior for block comments.")
 
 (defun treesit--simple-indent-eval (exp)
@@ -2332,24 +2350,24 @@ treesit-ready-p
 (defun treesit-major-mode-setup ()
   "Activate tree-sitter to power major-mode features.
 
-If `treesit-font-lock-settings' is non-nil, setup fontification and
-enable `font-lock-mode'.
+If `treesit-font-lock-settings' is non-nil, set up fontification
+and enable `font-lock-mode'.
 
-If `treesit-simple-indent-rules' is non-nil, setup indentation.
+If `treesit-simple-indent-rules' is non-nil, set up indentation.
 
-If `treesit-defun-type-regexp' is non-nil, setup
-`beginning/end-of-defun' functions.
+If `treesit-defun-type-regexp' is non-nil, set up
+`beginning-of-defun-function' and `end-of-defun-function'.
 
-If `treesit-defun-name-function' is non-nil, setup
+If `treesit-defun-name-function' is non-nil, set up
 `add-log-current-defun'.
 
-If `treesit-simple-imenu-settings' is non-nil, setup Imenu.
+If `treesit-simple-imenu-settings' is non-nil, set up Imenu.
 
 Make sure necessary parsers are created for the current buffer
 before calling this function."
   ;; Font-lock.
   (when treesit-font-lock-settings
-    ;; `font-lock-mode' wouldn't setup properly if
+    ;; `font-lock-mode' wouldn't set up properly if
     ;; `font-lock-defaults' is nil, see `font-lock-specified-p'.
     (setq-local font-lock-defaults
                 '( nil nil nil nil
@@ -2803,7 +2821,7 @@ treesit-explore-mode
           (display-buffer treesit--explorer-buffer
                           (cons nil '((inhibit-same-window . t))))
           (treesit--explorer-refresh)
-          ;; Setup variables and hooks.
+          ;; Set up variables and hooks.
           (add-hook 'post-command-hook
                     #'treesit--explorer-post-command 0 t)
           (add-hook 'kill-buffer-hook
-- 
2.34.1


[-- Attachment #3: Type: text/plain, Size: 3258 bytes --]


In GNU Emacs 29.0.91 (build 1, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.16.0, Xaw3d scroll bars) of 2023-06-12 built on blc
Repository revision: bdb0bc2b4e44a7d40369e10e3de825d58fe46825
Repository branch: wt/emacs-29
Windowing system distributor 'The X.Org Foundation', version 11.0.12101004
System Description: Ubuntu 22.04.2 LTS

Configured using:
 'configure CC=gcc-12 'CFLAGS=-Og -ggdb3' --prefix=/home/bic/.local
 --with-program-suffix=-29 --with-file-notification=yes --with-x
 --with-x-toolkit=lucid'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
JSON LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NOTIFY
INOTIFY PDUMPER PNG RSVG SECCOMP SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP X11 XAW3D XDBE XIM XINPUT2 XPM
LUCID ZLIB

Important settings:
  value of $LC_MONETARY: en_IE.UTF-8
  value of $LC_NUMERIC: en_IE.UTF-8
  value of $LC_TIME: en_IE.UTF-8
  value of $LANG: en_GB.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message mailcap yank-media puny dired
dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg rfc6068
epg-config gnus-util text-property-search time-date subr-x mm-decode
mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader
cl-loaddefs cl-lib sendmail rfc2047 rfc2045 ietf-drums mm-util
mail-prsvr mail-utils rmc iso-transl tooltip cconv eldoc paren electric
uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel
term/x-win x-win term/common-win x-dnd tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode lisp-mode
prog-mode register page tab-bar menu-bar rfn-eshadow isearch easymenu
timer select scroll-bar mouse jit-lock font-lock syntax font-core
term/tty-colors frame minibuffer nadvice seq simple cl-generic
indonesian philippine cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs
theme-loaddefs faces cus-face macroexp files window text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget keymap
hashtable-print-readable backquote threads dbusbind inotify lcms2
dynamic-setting system-font-setting font-render-setting cairo x-toolkit
xinput2 x multi-tty make-network-process emacs)

Memory information:
((conses 16 36709 7363)
 (symbols 48 5149 0)
 (strings 32 13887 1551)
 (string-bytes 1 379631)
 (vectors 16 9301)
 (vector-slots 8 148632 9511)
 (floats 8 23 25)
 (intervals 56 248 0)
 (buffers 984 10))

bug#64018: 29.0.91; Improve tree-sitter docs

[Eli Zaretskii]

> Cc: Yuan Fu <casouri@gmail.com>
> Date: Mon, 12 Jun 2023 15:15:41 +0100
> From:  Basil Contovounesios via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> While reading through the excellent tree-sitter documentation I
> collected some potential improvements against emacs-29, either for
> typos, to clarify wording, or fix up some probable errors like duplicate
> instances of treesit-defun-type-regexp and parent-bol.
> 
> WDYT?

Thanks for this proofreading.  Everything LGTM, with a couple of minor
exceptions:

>  This function raises the @code{treesit-query-error} error if
> -@var{query} is malformed.  The signal data contains a description of
> +@var{query} is malformed.  The signal data contain a description of

I think "data contains" looks better.  In general, "data" is used as
singular in this and other similar cases.  (There are other such
changes in the patch, which I'd rather drop.)

>  It takes a series of @var{query-spec}s, where each @var{query-spec} is
> -a @var{query} preceded by zero or more @var{keyword}/@var{value}
> +a @var{query} preceded by zero or more @var{:keyword}/@var{value}
                                          ^^^^^^^^^^^^^^
This should be @code{:@var{keyword}} instead.  That is, the colon is
not part of the meta-syntactic variable, it is a literal character.

>  For example, @code{python-mode} sets this variable to a regexp that
> -matches either @code{"function_definition"} or @code{"class_definition"}.
> +matches either @code{function_definition} or @code{class_definition}.

It is better to use @samp here, not @code.  That way, you get the
quotes in the printed output.

bug#64018: 29.0.91; Improve tree-sitter docs

[Yuan Fu]

> On Jun 12, 2023, at 8:09 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Cc: Yuan Fu <casouri@gmail.com>
>> Date: Mon, 12 Jun 2023 15:15:41 +0100
>> From:  Basil Contovounesios via "Bug reports for GNU Emacs,
>> the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> While reading through the excellent tree-sitter documentation I
>> collected some potential improvements against emacs-29, either for
>> typos, to clarify wording, or fix up some probable errors like duplicate
>> instances of treesit-defun-type-regexp and parent-bol.
>> 
>> WDYT?
> 
> Thanks for this proofreading.  Everything LGTM, with a couple of minor
> exceptions:
> 
>> This function raises the @code{treesit-query-error} error if
>> -@var{query} is malformed.  The signal data contains a description of
>> +@var{query} is malformed.  The signal data contain a description of
> 
> I think "data contains" looks better.  In general, "data" is used as
> singular in this and other similar cases.  (There are other such
> changes in the patch, which I'd rather drop.)
> 
>> It takes a series of @var{query-spec}s, where each @var{query-spec} is
>> -a @var{query} preceded by zero or more @var{keyword}/@var{value}
>> +a @var{query} preceded by zero or more @var{:keyword}/@var{value}
>                                          ^^^^^^^^^^^^^^
> This should be @code{:@var{keyword}} instead.  That is, the colon is
> not part of the meta-syntactic variable, it is a literal character.
> 
>> For example, @code{python-mode} sets this variable to a regexp that
>> -matches either @code{"function_definition"} or @code{"class_definition"}.
>> +matches either @code{function_definition} or @code{class_definition}.
> 
> It is better to use @samp here, not @code.  That way, you get the
> quotes in the printed output.

Thanks a bunch! I don’t have anything to add.

Yuan

bug#64018: 29.0.91; Improve tree-sitter docs

[Basil Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1143 bytes --]

Eli Zaretskii [2023-06-12 11:09 -0400] wrote:

>> Cc: Yuan Fu <casouri@gmail.com>
>> Date: Mon, 12 Jun 2023 15:15:41 +0100
>> From:  Basil Contovounesios via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>>  This function raises the @code{treesit-query-error} error if
>> -@var{query} is malformed.  The signal data contains a description of
>> +@var{query} is malformed.  The signal data contain a description of
>
> I think "data contains" looks better.  In general, "data" is used as
> singular in this and other similar cases.  (There are other such
> changes in the patch, which I'd rather drop.)

Done.

>>  It takes a series of @var{query-spec}s, where each @var{query-spec} is
>> -a @var{query} preceded by zero or more @var{keyword}/@var{value}
>> +a @var{query} preceded by zero or more @var{:keyword}/@var{value}
>                                           ^^^^^^^^^^^^^^
> This should be @code{:@var{keyword}} instead.  That is, the colon is
> not part of the meta-syntactic variable, it is a literal character.

I can agree with that, but the result looks a bit jarring to me:


[-- Attachment #2: kv.png --]
[-- Type: image/png, Size: 8194 bytes --]

[-- Attachment #3: Type: text/plain, Size: 560 bytes --]


Particularly when juxtaposed with the associated @var{value} which gets
a different font.  Should I make the change regardless?

FWIW, there are several existing places that use @var{:keyword} or
similar.

>>  For example, @code{python-mode} sets this variable to a regexp that
>> -matches either @code{"function_definition"} or @code{"class_definition"}.
>> +matches either @code{function_definition} or @code{class_definition}.
>
> It is better to use @samp here, not @code.  That way, you get the
> quotes in the printed output.

Done.

Thanks,

-- 
Basil

bug#64018: 29.0.91; Improve tree-sitter docs

[Eli Zaretskii]

> From: Basil Contovounesios <contovob@tcd.ie>
> Cc: 64018@debbugs.gnu.org,  casouri@gmail.com
> Date: Tue, 13 Jun 2023 13:32:36 +0100
> 
> > This should be @code{:@var{keyword}} instead.  That is, the colon is
> > not part of the meta-syntactic variable, it is a literal character.
> 
> I can agree with that, but the result looks a bit jarring to me:

I don't see anything jarring there, FWIW.

But on second thought: why do you need the colon at all?  What does it
signifiy?  If you must say that KEYWORD begins with a colon, just say
that (although it's pretty clear), or maybe show an example.

bug#64018: 29.0.91; Improve tree-sitter docs

[Basil Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii [2023-06-13 09:31 -0400] wrote:

> But on second thought: why do you need the colon at all?  What does it
> signifiy?  If you must say that KEYWORD begins with a colon, just say
> that (although it's pretty clear), or maybe show an example.

I added a colon in this single instance for consistency with subsequent
paragraphs of the same function definition:

     It takes a series of QUERY-SPECs, where each QUERY-SPEC is a QUERY
     preceded by zero or more KEYWORD/VALUE pairs.  Each QUERY is a
                              ^^^^^^^
     tree-sitter query in either the string, s-expression or compiled
     form, or a function.

     If QUERY is a tree-sitter query, it should be preceded by two
     :KEYWORD/VALUE pairs, where the ‘:embed’ keyword specifies the
     ^^^^^^^^
     embedded language, and the ‘:host’ keyword specified the host
     language.

     [...]

     If QUERY is a function, it doesn’t need any :KEYWORD and VALUE
                                                 ^^^^^^^^
     pair.  It should be a function that takes 2 arguments, START and
     END, and sets the ranges for parsers in the current buffer in the
     region between START and END.  It is fine for this function to set
     ranges in a larger region that encompasses the region between START
     and END.

The same @var{:keyword}/@var{value} pattern also appears a couple of
times in the related '(elisp) Parser-based Font Lock'.

I don't mind what we go with, so long as it's used consistently across
paragraphs of the same definition.  Which markup/wording do you prefer?

Thanks,

-- 
Basil

bug#64018: 29.0.91; Improve tree-sitter docs

[Eli Zaretskii]

> From: Basil Contovounesios <contovob@tcd.ie>
> Cc: 64018@debbugs.gnu.org,  casouri@gmail.com
> Date: Tue, 13 Jun 2023 15:45:03 +0100
> 
> Eli Zaretskii [2023-06-13 09:31 -0400] wrote:
> 
> > But on second thought: why do you need the colon at all?  What does it
> > signifiy?  If you must say that KEYWORD begins with a colon, just say
> > that (although it's pretty clear), or maybe show an example.
> 
> I added a colon in this single instance for consistency with subsequent
> paragraphs of the same function definition:
> 
>      It takes a series of QUERY-SPECs, where each QUERY-SPEC is a QUERY
>      preceded by zero or more KEYWORD/VALUE pairs.  Each QUERY is a
>                               ^^^^^^^
>      tree-sitter query in either the string, s-expression or compiled
>      form, or a function.
> 
>      If QUERY is a tree-sitter query, it should be preceded by two
>      :KEYWORD/VALUE pairs, where the ‘:embed’ keyword specifies the
>      ^^^^^^^^
>      embedded language, and the ‘:host’ keyword specified the host
>      language.
> 
>      [...]
> 
>      If QUERY is a function, it doesn’t need any :KEYWORD and VALUE
>                                                  ^^^^^^^^
>      pair.  It should be a function that takes 2 arguments, START and
>      END, and sets the ranges for parsers in the current buffer in the
>      region between START and END.  It is fine for this function to set
>      ranges in a larger region that encompasses the region between START
>      and END.
> 
> The same @var{:keyword}/@var{value} pattern also appears a couple of
> times in the related '(elisp) Parser-based Font Lock'.
> 
> I don't mind what we go with, so long as it's used consistently across
> paragraphs of the same definition.  Which markup/wording do you prefer?

I think the colons should removed.

bug#64018: 29.0.91; Improve tree-sitter docs

[Basil Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

close 64018 29.1
quit

Eli Zaretskii [2023-06-13 11:52 -0400] wrote:

>> From: Basil Contovounesios <contovob@tcd.ie>
>> Cc: 64018@debbugs.gnu.org,  casouri@gmail.com
>> Date: Tue, 13 Jun 2023 15:45:03 +0100
>> 
>> The same @var{:keyword}/@var{value} pattern also appears a couple of
>> times in the related '(elisp) Parser-based Font Lock'.
>> 
>> I don't mind what we go with, so long as it's used consistently across
>> paragraphs of the same definition.  Which markup/wording do you prefer?
>
> I think the colons should removed.

Done, pushed, and closing.

Improve tree-sitter docs
28478574961 2023-06-13 17:22:16 +0100
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=28478574961

Thanks,

-- 
Basil