Merge from origin/emacs-29

db96b1282f9 * lisp/help.el: Use 'C-h C-q' to toggle 'help-quick' wind...
489865c21e4 ; Improve markup of long key sequences
d42c2668cf3 ; * etc/NEWS: Fix wording of a recently edited entry.
7a0eaee1980 * lisp/isearch.el: Small fixes.
b69bffeec05 * lisp/vc/diff-mode.el (diff-minor-mode-prefix): Replace ...
9263847ab76 ; * etc/NEWS: Move the paragraph with 'C-u RET' closer to...
62fb2dc37da * doc/emacs/display.texi (Text Scale): Improve section ab...
70480d3b6b7 * lisp/repeat.el (repeat-echo-function): Suggest 'add-fun...
fd48201ffe7 * lisp/tab-line.el (tab-line-cache-key-default): More cac...
b1646602602 * etc/package-keyring.gpg: Update with new key
c0be51389eb ; Yet another declare-function to avoid treesit-related w...
8676bec51de ; * lisp/treesit.el (treesit--simple-imenu-1): Doc fix; w...
2ddc480f441 Warn of absent networks module in ERC
19d00fab9aa Avoid "already compiled" warning in erc-compat
2d8f7b66bcc ; Fix one more treesit byte-compilation warning.
2d0a9214863 ; Avoid treesit-related byte-compiler warnings
8503b370be1 (python--treesit-settings): Remove duplicate matcher
b464e6c490b Make last change of w32 GUI dialogs conditional and rever...
eedc9d79aed Fix tree-sitter typos
248c13dcfe1 Update tree-sitter major modes to use the new Imenu facility
b39dc7ab27a Add tree-sitter helper functions for Imenu
ba1ddea9dab Fix treesit--things-around (bug#60355)
7512b9025a1 ; * lisp/treesit.el (treesit-traverse-parent): Remove alias.
5326b041982 Improve treesit-node-top-level and treesit-parent-until
637f5b164f2 ; Add "src" to the heuristic sub-directory heuristic
8ab6df0c9fd ; * lisp/epa-ks.el (epa-ks-do-key-to-fetch): Fix 'when' u...
2b55a48d3e3 * src/w32menu.c (simple_dialog_show): Use MB_YESNOCANCEL ...
8b8b7915679 ; Improve documentation of TAB/SPC indentation
624e3822110 ; Improve doc strings of some new faces
41f12e1019b ; * lisp/elide-head.el (elide-head): Doc fix to silence c...
e3b4cd0ac1d ; * lisp/htmlfontify.el (hfy-text-p): Fix whitespace.
1b4dc4691c1 Fix htmlfontify.el command injection vulnerability.
1fe4b98b4d5 Improve support for Scheme R6RS and R7RS libraries (bug#5...
2347f37f677 ; * test/src/treesit-tests.el: remove dead store (bytecom...
a6d961ae2fd Add a new tree-sitter query predicate 'pred'
835a80dcc48 ; Fix tree-sitter defun tests
a14821d6151 Improve gnutls-min-prime-bits docstring
b14bbd108e4 Improve handling of tab-bar height.
669160d47b2 ; * nt/INSTALL.W64: More fixes and updates.
26b2ec7cb8c Simplify last change (bug#60311)
082fc6e3088 Fix 'json-available-p' on MS-Windows
6c86faec29e loaddefs-gen: Group results by absolute file name
d90d7d15f2f ; Fix vindexes in parsing.texi
eb268728376 Fix imenu for c-ts-mode (bug#60296)
8f68b6497ee Clean up python-ts-mode font-lock features
28f26b11a1e Add comment indent and filling to other tree-sitter major...
c6b02826450 ; Remove unused function in c-ts-mode
6e52a9fcadc ; * doc/lispref/modes.texi (Parser-based Font Lock): Mino...
2bcd1e9a99d ; * doc/lispref/parsing.texi (Retrieving Nodes): Add notice.
7c7950fe006 Add maintainer stub for tree-sitter files
cf327766226 ; * doc/lispref/parsing.texi (Using Parser): Remove delet...

# Conflicts:
#	etc/NEWS
#	lisp/progmodes/c-ts-mode.el
#	lisp/progmodes/typescript-ts-mode.el
#	lisp/treesit.el

2 files changed, 66 insertions, 19 deletions

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 736c2d6841f..de17969566d 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2841,6 +2841,35 @@ function uses @code{imenu-generic-expression} instead.
 Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
+If built with tree-sitter, Emacs can automatically generate an Imenu
+index if the major mode sets relevant variables.
+
+@defvar treesit-simple-imenu-settings
+This variable instructs Emacs how to generate Imenu indexes.  It
+should be a list of @w{(@var{category} @var{regexp} @var{pred}
+@var{name-fn})}.
+
+@var{category} should be the name of a category, like "Function",
+"Class", etc.  @var{regexp} should be a regexp matching the type of
+nodes that belong to @var{category}.  @var{pred} should be either
+@code{nil} or a function that takes a node as the argument.  It should
+return non-@code{nil} if the node is a valid node for @var{category},
+or @code{nil} if not.
+
+@var{category} could also be @code{nil}.  In which case the entries
+matched by @var{regexp} and @var{pred} are not grouped under
+@var{category}.
+
+@var{name-fn} should be either @var{nil} or a function that takes a
+defun node and returns the name of that defun, e.g., the function name
+for a function definition.  If @var{name-fn} is @var{nil},
+@code{treesit-defun-name} (@pxref{Tree-sitter major modes}) is used
+instead.
+
+@code{treesit-major-mode-setup} (@pxref{Tree-sitter major modes})
+automatically sets up Imenu if this variable is non-@code{nil}.
+@end defvar
+
 @node Font Lock Mode
 @section Font Lock Mode
 @cindex Font Lock mode
@@ -4023,11 +4052,12 @@ This function takes a series of @var{query-spec}s, where each
 @var{:keyword}/@var{value} pairs.  Each @var{query} is a
 tree-sitter query in either the string, s-expression or compiled form.
 
+@c FIXME: Cross-ref treesit-font-lock-level to user manual.
 For each @var{query}, the @var{:keyword}/@var{value} pairs that
 precede it 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
+enabled with @code{treesit-font-lock-level} and
 @code{treesit-font-lock-feature-list} (described below).  These two
 keywords are mandatory.
 
@@ -4067,10 +4097,11 @@ priority.  If a capture name is neither a face nor a function, it is
 ignored.
 @end defun
 
+@c FIXME: Cross-ref treesit-font-lock-level to user manual.
 @defvar treesit-font-lock-feature-list
 This is a list of lists of feature symbols.  Each element of the list
 is a list that represents a decoration level.
-@code{font-lock-maximum-decoration} controls which levels are
+@code{treesit-font-lock-level} controls which levels are
 activated.
 
 Each element of the list is a list of the form @w{@code{(@var{feature}
diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 6baa253cfdf..b7199f071bc 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -393,12 +393,6 @@ tree-sitter can be activated.  Major modes should check this value
 when deciding whether to enable tree-sitter features.
 @end defvar
 
-@defun treesit-can-enable-p
-This function checks whether the current buffer is suitable for
-activating tree-sitter features.  It basically checks
-@code{treesit-available-p} and @code{treesit-max-buffer-size}.
-@end defun
-
 @cindex creating tree-sitter parsers
 @cindex tree-sitter parser, creating
 @defun treesit-parser-create language &optional buffer no-reuse
@@ -649,6 +643,10 @@ it, or query for information about this node.
 
 @defun treesit-node-parent node
 This function returns the immediate parent of @var{node}.
+
+If @var{node} is more than 1000 levels deep in a parse tree, the
+return value is undefined.  Currently it returns @var{nil}, but that
+could change in the future.
 @end defun
 
 @defun treesit-node-child node n &optional named
@@ -1268,10 +1266,11 @@ example, with the following pattern:
 @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 two predicates, @code{#equal} and @code{#match}.
+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}.
 
 @deffn Predicate equal arg1 arg2
 Matches if @var{arg1} equals to @var{arg2}.  Arguments can be either
@@ -1284,6 +1283,11 @@ Matches if the text that @var{capture-name}'s node spans in the buffer
 matches regular expression @var{regexp}.  Matching is case-sensitive.
 @end deffn
 
+@deffn Predicate pred fn &rest nodes
+Matches if function @var{fn} returns non-@code{nil} when passed each
+node in @var{nodes} as arguments.
+@end deffn
+
 Note that a predicate can only refer to capture names that appear in
 the same pattern.  Indeed, it makes little sense to refer to capture
 names in other patterns.
@@ -1717,17 +1721,14 @@ This function activates some tree-sitter features for a major mode.
 
 Currently, it sets up the following features:
 @itemize
-@vindex treesit-font-lock-settings
 @item
-If @code{treesit-font-lock-settings} is non-@code{nil}, it sets up
-fontification.
+If @code{treesit-font-lock-settings} (@pxref{Parser-based Font Lock})
+is non-@code{nil}, it sets up fontification.
 
-@vindex treesit-simple-indent-rules
 @item
-If @code{treesit-simple-indent-rules} is non-@code{nil}, it sets up
-indentation.
+If @code{treesit-simple-indent-rules} (@pxref{Parser-based Font Lock})
+is non-@code{nil}, it sets up indentation.
 
-@vindex treesit-defun-type-regexp
 @item
 If @code{treesit-defun-type-regexp} is non-@code{nil}, it sets up
 navigation functions for @code{beginning-of-defun} and
@@ -1736,6 +1737,10 @@ navigation functions for @code{beginning-of-defun} and
 @item
 If @code{treesit-defun-name-function} is non-@code{nil}, it sets up
 add-log functions used by @code{add-log-current-defun}.
+
+@item
+If @code{treesit-simple-imenu-settings} (@pxref{Imenu}) is
+non-@code{nil}, it sets up Imenu.
 @end itemize
 @end defun
 
@@ -1784,6 +1789,17 @@ 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