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

[Theodor Thornhill via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: 60983@debbugs.gnu.org, theo@thornhill.no
>> Date: Mon, 23 Jan 2023 18:52:33 +0200
>> From: Eli Zaretskii <eliz@gnu.org>
>> 
>> > From: Theodor Thornhill <theo@thornhill.no>
>> > Cc: Yuan Fu <casouri@gmail.com>
>> > Date: Sat, 21 Jan 2023 12:48:58 +0100
>> > 
>> > Eli Zaretskii <eliz@gnu.org> writes:
>> > 
>> > > I started looking into providing user-level documentation for
>> > > tree-sitter based modes, and bumped into some issues:
>> > >
>> > >  . How does one use treesit-font-lock-level?
>> > >
>> > >    - It is not a customizable user option (unlike
>> > >      font-lock-maximum-decoration), so it cannot be set via
>> > >      customize-variable.  Is there a reason not to make it a
>> > >      defcustom?
>> > >    - It automatically becomes buffer-local when set, and OTOH setting
>> > >      it in a buffer does not produce fontifications according to the
>> > >      level, and neither does setting it in a mode hook.  So the only
>> > >      way to change its value is by using setq-default, which I don't
>> > >      think is the intent?
>> > >    - Should we make the variable a defcustom?
>> > >    - Should it be possible to customize it separately for each mode?
>> > >    - Should we allow to change the level and then call some function
>> > >      to re-fontify the current buffer according to the new level?
>> > 
>> > I struggled with this too.  I ended up setting it with setq-default,
>> > assuming I was just missing something very simple.  I'm in favor for
>> > either a defcustom or honoring the font-lock-maximum-decoration values,
>> > specifically these settings:
>> > 
>> > ```
>> > If t, use the maximum decoration available.
>> > If a number, use that level of decoration (or if not available the maximum).
>> > ```
>
> Let's just make it a defcustom for now, with the values it has today,
> including the default.
>
> The problems with honoring the value of font-lock-maximum-decoration
> are that (a) its default value is t in most (all?) modes, whereas we
> decided not to use 4 as the default value of treesit-font-lock-level;
> and (b) if changing treesit-font-lock-level's value doesn't require to
> kill the buffer and revisit the file (as I hope we will make it work),
> the instructions regarding changing the value of
> font-lock-maximum-decoration will depend on whether the mode does or
> doesn't use tree-sitter, which will make the instructions confusingly
> complex.
>
> Yuan or Theo, would one of you please make the change of making
> treesit-font-lock-level a defcustom, with a proper :set functions to
> avoid the need to revisit the file?  My hands are too full ATM, and
> this issue is basically the only one which prevents me from updating
> the Emacs user manual with the tree-sitter info, which in turn is the
> only issue that blocks the move to releasing the 29.0.90 pretest
> tarball.
>
> TIA


I can take a stab at it :)

Theo