Re: master 5c70ff9: New user option 'font-lock-ignore'

[Eli Zaretskii]

> From: Augusto Stoffel <arstoffel@gmail.com>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  emacs-devel@gnu.org
> Date: Sat, 02 Apr 2022 09:34:25 +0200
> 
> >> +@example
> >> +(@var{mode} @var{rule} @dots{})
> >> +@end example
> >> +
> >> +Here, @var{mode} is a symbol, say a major or minor mode.
> >
> > Why "say"?  Can it usefully be something else? if so, what can it be?
> 
> This is easiest to explain with code.  A rule for a given xyz-mode
> applies if
> 
>     (or (bound-and-true-p xyz-mode)
>         (derived-mode-p xyz-mode))
> 
> Do you think it's better to just say “Here, @var{mode} a major or minor
> mode”?  This would be slightly imprecise, because technically 'mode' can
> be any variable.

If MODE could be any symbol that is bound-and-true-p, does it mean
that just by defining a variable with a non-nil value will trigger
such a rule?

> >> +subsequent rules apply if the current major mode is derived from
> >> +@var{mode} or @var{mode} is bound and true as a variable.  Each
> >> +@var{rule} can be one of the following:
> >> +
> >> +@table @code
> >> +@cindex @var{font-lock-ignore} rules
> >> +@item @var{symbol}
> >> +A symbol, say a face name, matches any Font Lock keyword containing
> >> +the symbol in its definition.
> >
> > I don't think I understand how can a keyword "contain" a symbol.
> > Please elaborate or suggest a different text that clarifies this.
> 
> Okay, as a general remark, this feature has been bolted on the existing
> font lock mechanism, and it shows.  So the user has to interact to some
> degree with the font-lock internals to make any meaningful use of it.
> 
> Specifically regarding your question, the user has to be aware that
> 'font-lock-keywords' is a list where (quoting the docstring):
> 
>     Each element [...] should have one of these forms:
> 
>      MATCHER
>      (MATCHER . SUBEXP)
>      (MATCHER . FACENAME)
>      (MATCHER . HIGHLIGHT)
>      (MATCHER HIGHLIGHT ...)
>      (eval . FORM)
> 
>     where MATCHER can be either the regexp to search for, or the
>     function name to call to make the search (called with one
> 
> So here I mean that 'symbol' equals the MATCHER, or the FACENAME, or is
> a member of (flatten-tree FORM), and so on.

It can equal _any_ symbol in those places?  Even stuff like 'and'
etc.?  What a strange feature!  Why not enable just a test against the
MATCHER part?

> >> The symbol is interpreted as a glob
> >> +pattern; in particular, @code{*} matches everything.
> >
> > Do you mean shell glob patterns?  AFAIK, we don't use them in Emacs
> > except for shell wildcards, so why are they used here? why not
> > regexps?  And in any case, those patterns need a thorough description,
> > since we don't use them elsewhere.  For example, the way to quote
> > meta-characters such as '*' must be documented, because it isn't
> > self-evident.
> 
> The intention is that the user can write, for instance
> 
>     (setq font-lock-ignore '((prog-mode font-lock-*-face)))
> 
> and this will be equivalent to
> 
>     (setq font-lock-ignore '((prog-mode (pred (lambda (obj)
>                                                  (and (symbolp obj)
>                                                       (string-match-p
>                                                        
> "\\`font-lock-.*-face\\'"
>                                                        (symbol-name 
> obj))))))))
> 
> Do you agree this is a sensible and convenient mini-language?  I guess
> Stefan liked the idea, at least :-).

I understand the intent.  I'm saying that we should document this
"mini-language" in sufficient detail, so that Lisp programmers knew
how to use it.

> >> +@item @var{string}
> >> +A string matches any font-lock keyword defined by a regexp that
> >> +matches the string.
> >
> > I don't think I understand this sentence.  In particular, saying "a
> > regexp that matches the string" is at least unusual: we usually say it
> > the other way around: "a string that matches the regexp".  And what
> > does it mean for a keyword to be "defined by a regexp"?
> 
> Just to make sure we're on the same page, this refers, for instance, to
> the rule
> 
>     (emacs-lisp-mode ";;;###autoload")
> 
> which would deactivate the highlighting of autoload cookies.
> 
> So, we could say "A string matches any font-lock rule which would
> highlight that string".

What do you mean by "font-lock rule" here?

> > And why doesn't the example show all the possible forms of a "rule",
> > but just one of them?
> 
> Well, I just wanted to keep true to this being a "@smallexample".

I see no problem with this: adding a couple of lines shouldn't make
the example too large.

> >> +*** New user option 'font-lock-ignore'.
> >> +This variable provides a mechanism to selectively disable font-lock
> >> +keywords.
> >
> > I don't think it disables keywords, I think it disables
> > fontifications.  (How can one disable a keyword?)
> 
> Hum, I'm not sure I understand the fine-grained distinction your are
> making here.  font-lock.el speaks of "font lock keywords"; the thing
> that fontifies variable names with font-lock-variable-face would be a
> "font lock keyword" in that terminology.  I'm just following along the
> terminology.

That terminology (if this is how you perceive it) is wrong, and I'm
about to change it to make that more clear.  font-lock-keywords are
not just keywords, they are rules for fontification.  This new feature
allows to selectively disable some of those fontifications without
editing the rules themselves.

> >> +(defun font-lock--match-keyword (rule keyword)
> >> +  "Return non-nil if font-lock KEYWORD matches RULE.
> >> +See `font-lock-ignore' for the possible rules."
> >> +  (pcase-exhaustive rule
> >> +    ('* t)
> >> +    ((pred symbolp)
> >> +     (let ((regexp (when (string-match-p "[*?]" (symbol-name rule))
> >> +                     (wildcard-to-regexp (symbol-name rule)))))
> >
> > So "[abcd]" isn't supported by these "glob patterns"?  This should be
> > documented.
> 
> Ah, okay, I guess we should use the regexp "[][*?]" in that test.

Why not allow a regexp to begin with?  Then 2 problems will be solved
in one blow: (1) the need to change the code, and (2) the need to
describe what is allowed and what isn't.

> > I'm okay with clarifying the docs myself if you explain enough for me
> > to understand how to do that.
> 
> I guess yes, it would be great if we could have the perspective of a
> different person incorporated in the documentation, so please go ahead!
> I'll be glad to provide further clarifications.

Will do, after you reply to this followup message.

Thanks.