master 5fa9458511a 2/4: Merge from origin/emacs-29

[Eli Zaretskii]

branch: master
commit 5fa9458511a17ff79a822e5cf8cc00f7bfb89364
Merge: ff5caf68c93 8f62e7b85f6
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Merge from origin/emacs-29
    
    8f62e7b85f6 Describe primarily the Emacs s-exp dialect for treesit qu...
    eacd75df4e4 ; Improve documentation of overlay priorities
    b3f11e94fad Fix documentation of :predicate in 'define-globalized-min...
---
 doc/lispref/display.texi      |  55 ++++++++++--------
 doc/lispref/modes.texi        |  13 +++--
 doc/lispref/parsing.texi      | 132 +++++++++++++++++++++---------------------
 lisp/emacs-lisp/easy-mmode.el |   7 ++-
 4 files changed, 111 insertions(+), 96 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9b6e4f609bf..e229935170f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1792,34 +1792,43 @@ of them:
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}
-This property's value determines the priority of the overlay.
-If you want to specify a priority value, use either @code{nil}
-(or zero), or a positive integer.  Any other value has undefined behavior.
+This property's value determines the priority of the overlay.  If you
+want to specify a priority value, use either @code{nil} (or zero), or
+a positive integer, or a cons of two values.  Any other value triggers
+undefined behavior.
 
 The priority matters when two or more overlays cover the same
 character and both specify the same property with different values;
-the one whose @code{priority} value is larger overrides the other.
+the one whose @code{priority} value is higher overrides the other.
 (For the @code{face} property, the higher priority overlay's value
-does not completely override the other value; instead, its face
-attributes override the face attributes of the @code{face} property
-whose priority is lower.)  If two overlays have the same priority
-value, and one is nested in the other, then the inner one will prevail
-over the outer one.  If neither is nested in the other then you should
-not make assumptions about which overlay will prevail.
+does not completely override the other value; instead, its individual
+face attributes override the corresponding face attributes of the
+@code{face} property whose priority is lower.)  If two overlays have
+the same priority value, and one is ``nested'' in the other (i.e.,
+covers fewer buffer or string positions), then the inner one will
+prevail over the outer one.  If neither is nested in the other then
+you should not make assumptions about which overlay will prevail.
+
+When a Lisp program puts overlays with defined priorities on text that
+might have overlays without priorities, this could cause undesirable
+results, because any overlay with a positive priority value will
+override all the overlays without a priority.  Since most Emacs
+features that use overlays don't specify priorities for their
+overlays, integer priorities should be used with care.  Instead of
+using integer priorities and risk overriding other overlays, you can
+use priority values of the form @w{@code{(@var{primary} . @var{secondary})}},
+where the @var{primary} value is used as described above, and
+@var{secondary} is the fallback value used when @var{primary} and the
+nesting considerations fail to resolve the precedence between
+overlays.  In particular, priority value @w{@code{(nil . @var{n})}},
+with @var{n} a positive integer, allows to have the overlays ordered
+by priority when necessary without completely overriding other
+overlays.
 
 Currently, all overlays take priority over text properties.
 
-Note that Emacs sometimes uses non-numeric priority values for some of
-its internal overlays, so do not try to do arithmetic on the priority
-of an overlay (unless it is one that you created).  In particular, the
-overlay used for showing the region uses a priority value of the form
-@w{@code{(@var{primary} . @var{secondary})}}, where the @var{primary}
-value is used as described above, and @var{secondary} is the fallback
-value used when @var{primary} and the nesting considerations fail to
-resolve the precedence between overlays.  However, you are advised not
-to design Lisp programs based on this implementation detail; if you
-need to put overlays in priority order, use the @var{sorted} argument
-of @code{overlays-at}.  @xref{Finding Overlays}.
+If you need to put overlays in priority order, use the @var{sorted}
+argument of @code{overlays-at}.  @xref{Finding Overlays}.
 
 @item window
 @kindex window @r{(overlay property)}
@@ -3329,8 +3338,8 @@ enough to the overlay, Emacs applies the face or face 
attributes
 specified by the @code{mouse-face} property instead.  @xref{Overlay
 Properties}.
 
-When multiple overlays cover one character, an overlay with higher
-priority overrides those with lower priority.  @xref{Overlays}.
+When multiple overlays cover the same character, an overlay with
+higher priority overrides those with lower priority.  @xref{Overlays}.
 
 @item
 If the text contains a @code{face} or @code{mouse-face} property,
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index cdbda5503b7..8ca0afe1bca 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1888,11 +1888,14 @@ user option called the same as the global mode 
variable, but with
 @code{-modes} instead of @code{-mode} at the end, i.e.@:
 @code{@var{global-mode}s}.  This variable will be used in a predicate
 function that determines whether the minor mode should be activated in
-a particular major mode.  Valid values of @code{:predicate} include
-@code{t} (use in all major modes), @code{nil} (don't use in any major
-modes), or a list of mode names, optionally preceded with @code{not}
-(as in @w{@code{(not @var{mode-name} @dots{})}}).  These elements can
-be mixed, as shown in the following examples.
+a particular major mode, and users can customize the value of the
+variable to control the modes in which the minor mode will be switched
+on.  Valid values of @code{:predicate} (and thus valid values of the
+user option it creates) include @code{t} (use in all major modes),
+@code{nil} (don't use in any major modes), or a list of mode names,
+optionally preceded with @code{not} (as in @w{@code{(not
+@var{mode-name} @dots{})}}).  These elements can be mixed, as shown in
+the following examples.
 
 @example
 (c-mode (not mail-mode message-mode) text-mode)
diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 1ec985f6d70..3bb5071f02f 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -1131,9 +1131,9 @@ 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, an s-expression, or a
-compiled query object.  For now, we focus on the string syntax;
-s-expression syntax and compiled queries are described at the end of
+argument @var{query} can be either an s-expression, a string, or a
+compiled query object.  For now, we focus on the s-expression syntax;
+string 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
@@ -1165,8 +1165,8 @@ For example, suppose @var{node}'s text is @code{1 + 2}, 
and
 @example
 @group
 (setq query
-      "(binary_expression
-        (number_literal) @@number-in-exp) @@biexp")
+      '((binary_expression
+         (number_literal) @@number-in-exp) @@biexp)
 @end group
 @end example
 
@@ -1187,8 +1187,8 @@ For example, it could have two top-level patterns:
 @example
 @group
 (setq query
-      "(binary_expression) @@biexp
-       (number_literal)  @@number @@biexp")
+      '((binary_expression) @@biexp
+        (number_literal) @@number @@biexp)
 @end group
 @end example
 
@@ -1246,23 +1246,23 @@ field, say, a @code{function_definition} without a 
@code{body} field:
 @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:
-@samp{*} matches the preceding pattern zero or more times, @samp{+}
-matches one or more times, and @samp{?} matches zero or one times.
+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 times.
 
 For example, the following pattern matches @code{type_declaration}
 nodes that have @emph{zero or more} @code{long} keywords.
 
 @example
-(type_declaration "long"*) @@long-type
+(type_declaration "long" :*) @@long-type
 @end example
 
 The following pattern matches a type declaration that may or may not
 have a @code{long} keyword:
 
 @example
-(type_declaration "long"?) @@long-type
+(type_declaration "long" :?) @@long-type
 @end example
 
 @subheading Grouping
@@ -1272,15 +1272,14 @@ groups and apply quantification operators to them.  For 
example, to
 express a comma-separated list of identifiers, one could write
 
 @example
-(identifier) ("," (identifier))*
+(identifier) ("," (identifier)) :*
 @end example
 
 @subheading Alternation
 
 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
+of these patterns'' in a pattern.  The syntax is a vector of patterns.
+For example, to capture some keywords in C, the pattern would be
 
 @example
 @group
@@ -1295,7 +1294,7 @@ C, the pattern would be
 
 @subheading Anchor
 
-The anchor operator @samp{.} can be used to enforce juxtaposition,
+The anchor operator @code{:anchor} can be used to enforce juxtaposition,
 i.e., to enforce two things to be directly next to each other.  The
 two ``things'' can be two nodes, or a child and the end of its parent.
 For example, to capture the first child, the last child, or two
@@ -1304,19 +1303,19 @@ adjacent children:
 @example
 @group
 ;; Anchor the child with the end of its parent.
-(compound_expression (_) @@last-child .)
+(compound_expression (_) @@last-child :anchor)
 @end group
 
 @group
 ;; Anchor the child with the beginning of its parent.
-(compound_expression . (_) @@first-child)
+(compound_expression :anchor (_) @@first-child)
 @end group
 
 @group
 ;; Anchor two adjacent children.
 (compound_expression
  (_) @@prev-child
- .
+ :anchor
  (_) @@next-child)
 @end group
 @end example
@@ -1332,8 +1331,8 @@ example, with the following pattern:
 @example
 @group
 (
- (array . (_) @@first (_) @@last .)
- (#equal @@first @@last)
+ (array :anchor (_) @@first (_) @@last :anchor)
+ (:equal @@first @@last)
 )
 @end group
 @end example
@@ -1341,22 +1340,22 @@ example, with the following pattern:
 @noindent
 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}.
+group them together.  Currently there are three predicates:
+@code{:equal}, @code{:match}, and @code{:pred}.
 
-@deffn Predicate equal arg1 arg2
+@deffn Predicate :equal arg1 arg2
 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
 
-@deffn Predicate match regexp capture-name
+@deffn Predicate :match regexp capture-name
 Matches if the text that @var{capture-name}'s node spans in the buffer
-matches regular expression @var{regexp}.  Matching is case-sensitive.
+matches regular expression @var{regexp}, given as a string literal.
+Matching is case-sensitive.
 @end deffn
 
-@deffn Predicate pred fn &rest nodes
+@deffn Predicate :pred fn &rest nodes
 Matches if function @var{fn} returns non-@code{nil} when passed each
 node in @var{nodes} as arguments.  The function runs with the current
 buffer set to the buffer of node being queried.
@@ -1366,23 +1365,23 @@ 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.
 
-@heading S-expression patterns
+@heading String patterns
 
-@cindex tree-sitter patterns as sexps
-@cindex patterns, tree-sitter, in sexp form
-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
+@cindex tree-sitter patterns as strings
+@cindex patterns, tree-sitter, in string form
+Besides s-expressions, Emacs allows the tree-sitter's native query
+syntax to be used by writing them as strings.  It largely resembles
+the s-expression syntax.  For example, the following query
 
 @example
 @group
 (treesit-query-capture
- node "(addition_expression
-        left: (_) @@left
-        \"+\" @@plus-sign
-        right: (_) @@right) @@addition
+ node '((addition_expression
+         left: (_) @@left
+         "+" @@plus-sign
+         right: (_) @@right) @@addition
 
-        [\"return\" \"break\"] @@keyword")
+         ["return" "break"] @@keyword))
 @end group
 @end example
 
@@ -1392,52 +1391,53 @@ is equivalent to
 @example
 @group
 (treesit-query-capture
- node '((addition_expression
-         left: (_) @@left
-         "+" @@plus-sign
-         right: (_) @@right) @@addition
+ node "(addition_expression
+        left: (_) @@left
+        \"+\" @@plus-sign
+        right: (_) @@right) @@addition
 
-         ["return" "break"] @@keyword))
+        [\"return\" \"break\"] @@keyword")
 @end group
 @end example
 
-Most patterns can be written directly as strange but nevertheless
-valid s-expressions.  Only a few of them need modification:
+Most patterns can be written directly as s-expressions inside a string.
+Only a few of them need modification:
 
 @itemize
 @item
-Anchor @samp{.} is written as @code{:anchor}.
+Anchor @code{:anchor} is written as @samp{.}.
 @item
-@samp{?} is written as @samp{:?}.
+@samp{:?} is written as @samp{?}.
 @item
-@samp{*} is written as @samp{:*}.
+@samp{:*} is written as @samp{*}.
 @item
-@samp{+} is written as @samp{:+}.
+@samp{:+} is written as @samp{+}.
 @item
-@code{#equal} is written as @code{:equal}.  In general, predicates
-change their @samp{#} to @samp{:}.
+@code{:equal}, @code{:match} and @code{:pred} are written as
+@code{#equal}, @code{#match} and @code{#pred}, respectively.
+In general, predicates change their @samp{:} to @samp{#}.
 @end itemize
 
 For example,
 
 @example
 @group
-"(
-  (compound_expression . (_) @@first (_)* @@rest)
-  (#match \"love\" @@first)
-  )"
+'((
+   (compound_expression :anchor (_) @@first (_) :* @@rest)
+   (:match "love" @@first)
+   ))
 @end group
 @end example
 
 @noindent
-is written in s-expression syntax as
+is written in string form as
 
 @example
 @group
-'((
-   (compound_expression :anchor (_) @@first (_) :* @@rest)
-   (:match "love" @@first)
-   ))
+"(
+  (compound_expression . (_) @@first (_)* @@rest)
+  (#match \"love\" @@first)
+  )"
 @end group
 @end example
 
@@ -1461,7 +1461,7 @@ validate and debug the query.
 @end defun
 
 @defun treesit-query-language query
-This function return the language of @var{query}.
+This function returns the language of @var{query}.
 @end defun
 
 @defun treesit-query-expand query
@@ -1653,7 +1653,7 @@ ranges for @acronym{CSS} and JavaScript parsers:
 (setq css-range
       (treesit-query-range
        'html
-       "(style_element (raw_text) @@capture)"))
+       '((style_element (raw_text) @@capture))))
 (treesit-parser-set-included-ranges css css-range)
 @end group
 
@@ -1662,7 +1662,7 @@ ranges for @acronym{CSS} and JavaScript parsers:
 (setq js-range
       (treesit-query-range
        'html
-       "(script_element (raw_text) @@capture)"))
+       '((script_element (raw_text) @@capture))))
 (treesit-parser-set-included-ranges js js-range)
 @end group
 @end example
diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 3c6a215c9dc..20681374ee3 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -453,14 +453,17 @@ TURN-ON is a function that will be called with no args in 
every buffer
 and that should try to turn MODE on if applicable for that buffer.
 
 Each of KEY VALUE is a pair of CL-style keyword arguments.
-The :predicate argument specifies in which major modes should the
+The :predicate key specifies in which major modes should the
 globalized minor mode be switched on.  The value should be t (meaning
 switch on the minor mode in all major modes), nil (meaning don't
 switch on in any major mode), a list of modes (meaning switch on only
 in those modes and their descendants), or a list (not MODES...),
 meaning switch on in any major mode except MODES.  The value can also
 mix all of these forms, see the info node `Defining Minor Modes' for
-details.
+details.  The :predicate key causes the macro to create a user option
+named the same as MODE, but ending with \"-modes\" instead of \"-mode\".
+That user option can then be used to customize in which modes this
+globalized minor mode will be switched on.
 As the minor mode defined by this function is always global, any
 :global keyword is ignored.
 Other keywords have the same meaning as in `define-minor-mode',