bug#60894: 30.0.50; [PATCH] Add treesit-forward-sexp

[Eli Zaretskii]

> Cc: Mickey Petersen <mickey@masteringemacs.org>,
>  Stefan Monnier <monnier@iro.umontreal.ca>, Juri Linkov <juri@linkov.net>
> Date: Wed, 18 Jan 2023 06:35:36 +0100
> From:  Theodor Thornhill via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
> index 8d95ecee7a..8b7431096f 100644
> --- a/doc/lispref/positions.texi
> +++ b/doc/lispref/positions.texi
> @@ -875,6 +875,23 @@ List Motion
>  @code{backward-sentence}(@pxref{Moving by Sentences,,, emacs, The
>  extensible self-documenting text editor}).
>  
> +@defvar treesit-sexp-type-regexp
> +The value of this variable is a regexp matching the node type of sexp
> +nodes.  (For ``node'' and ``node type'', @pxref{Parsing Program
> +Source}.)
> +@end defvar
> +
> +@findex treesit-forward-sexp
> +@findex forward-sexp
> +@findex backward-sexp
> +If Emacs is compiled with tree-sitter, it can use the tree-sitter
> +parser information to move across syntax constructs.  Since what
> +exactly is considered a sexp varies between languages, a major mode
> +should set @code{treesit-sentence-type-regexp} to determine that.
> +Then the mode can get navigation-by-sexp functionality for free, by
> +using @code{forward-sexp} and @code{backward-sexp}(@pxref{Moving by
> +Sentences,,, emacs, The extensible self-documenting text editor}).

The last 2 index entries should either not be there or be qualified:

  @findex forward-sexp@r{, and tree-sitter}

That's because these two commands are described in another place in
the manual, and the unqualified index entries should go there.
Otherwise, if the readers type in Info "i forward-s TAB", they will
see something like this:

  forward-sexp
  forward-sexp<1>

and will not know which one of these two they want.  And similarly in
the printed version of the manual: you will get "forward-sexp" with 2
page numbers -- which one is the one you are looking for?

> +*** New function 'treesit-forward-sexp'.
> +treesit.el conditionally sets 'forward-sexp-function` for major modes
> +that have defined 'treesit-sexp-type-regexp' to enable sexp related
> +commands.

"sexp-related motion commands" should be better.  (If "motion" is not
inclusive enough, we could use additional descriptions.)

Thanks.