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

[Yuan Fu <casouri@gmail.com>]

Theodor Thornhill <theo@thornhill.no> writes:

> 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

Thanks! I don’t have a ton of free time right now either.

Yuan