bug#60983: 29.0.60; Tree-sitter user-level control

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Thu, 2 Feb 2023 19:07:07 -0800
> Cc: Bug Report Emacs <bug-gnu-emacs@gnu.org>,
>  Theodor Thornhill <theo@thornhill.no>
> 
> I just read the new manual sections, thanks for the work! Do we want to 
> mention treesit-font-lock-recompute-features in the user manual? That’s the 
> only way for someone to add/remove specific features (as opposed to changing 
> the decoration level). (We might also want to mention that changing 
> treesit-font-lock-features directly doesn’t have any effect, similar to 
> treesit-font-lock-level.)

treesit-font-lock-recompute-features is a non-interactive function, so
mentioning it in the user manual is generally inappropriate.  Users
are unlikely to add features that aren't already defined in the mode's
font-lock setup.

This function and its use in these situations are described in the
ELisp manual, where I think it belongs.

As for the fact that changing treesit-font-lock-feature-list directly
doesn't have any effect, that is already in the doc string.  I'm not
opposed to mentioning that in the manual as well, but I see no problem
with what we have.

> treesit-font-lock-recompute-features is intended to be used in major mode 
> hooks, like
> 
> (add-hook 'c-ts-mode-hook #'c-ts-setup)
> 
> (defun c-ts-mode-setup ()
>   (treesit-font-lock-recompute-features
>    '(emacs-devel)
>    '(property bracket delimiter operator variable function)))

This belongs to the ELisp manual, IMO.