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

[Eli Zaretskii]

> 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