From: Eli Zaretskii Date: Sat, 2 Apr 2022 13:45:26 +0000 (+0300) Subject: ; Improve documentation of 'font-lock-ignore' X-Git-Tag: emacs-29.0.90~1931^2~817 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=9c30276c426e0b67d288b479a9570428673de331;p=emacs.git ; Improve documentation of 'font-lock-ignore' * etc/NEWS: * lisp/font-lock.el (font-lock-ignore): * doc/lispref/modes.texi (Customizing Keywords): Clarify the documentation of 'font-lock-ignore'. * doc/emacs/display.texi (Font Lock): Mention 'font-lock-ignore'. --- diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 4fcd2a3f7de..534bf5881e7 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -1011,10 +1011,15 @@ in C comments, use this: @end example @findex font-lock-remove-keywords +@vindex font-lock-ignore @noindent To remove keywords from the font-lock highlighting patterns, use the function @code{font-lock-remove-keywords}. @xref{Search-based Fontification,,, elisp, The Emacs Lisp Reference Manual}. +Alternatively, you can selectively disable highlighting due to some +keywords by customizing the @code{font-lock-ignore} option, +@pxref{Customizing Keywords,,, elisp, The Emacs Lisp Reference +Manual}. @cindex just-in-time (JIT) font-lock @cindex background syntax highlighting diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index b61ba56e189..ff09a787490 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -3204,9 +3204,9 @@ Non-@code{nil} means that regular expression matching for the sake of You can use @code{font-lock-add-keywords} to add additional search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to remove rules. You can also set -the @code{font-lock-ignore} variable to disable keywords that match -certain criteria. +@code{font-lock-remove-keywords} to remove rules. You can also +customize the @code{font-lock-ignore} option to selectively disable +fontification rules for keywords that match certain criteria. @defun font-lock-add-keywords mode keywords &optional how This function adds highlighting @var{keywords}, for the current buffer @@ -3276,51 +3276,64 @@ mode @emph{and} all modes derived from it, do this instead: font-lock-keyword-face))))) @end smallexample -@defvar font-lock-ignore -This variable contains rules to selectively disable Font Lock -keywords. It is a list with elements of the following form: +@defopt font-lock-ignore +@cindex selectively disabling font-lock fontifications +This option defines conditions for selectively disabling +fontifications due to certain Font Lock keywords. If non-@code{nil}, +its value is a list of elements of the following form: @example -(@var{mode} @var{rule} @dots{}) +(@var{symbol} @var{condition} @dots{}) @end example -Here, @var{mode} is a symbol, say a major or minor mode. The -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. The symbol is interpreted as a glob -pattern; in particular, @code{*} matches everything. - -@item @var{string} -A string matches any font-lock keyword defined by a regexp that -matches the string. - -@item (pred @var{function}) -A rule of this form matches if @var{function}, called with the -Font Lock keyword as argument, returns non-@code{nil}. - -@item (not @var{rule}) -A rule of this form matches if @var{rule} doesn’t. - -@item (and @var{rule} @dots{}) -A rule of this form matches if each @var{rule} matches. - -@item (or @var{rule} @dots{}) -A rule of this form matches if some @var{rule} matches. - -@item (except @var{rule}) -A rule of this form can only be used at top level or inside an -@code{or} clause. It undoes the effect of a previously matching rule. +Here, @var{symbol} is a symbol, usually a major or minor mode. The +subsequent @var{condition}s of a @var{symbol}'s list element will be in +effect if @var{symbol} is bound and its value is non-@code{nil}. For +a mode's symbol, it means that the current major mode is derived from +that mode, or that minor mode is enabled in the buffer. When a +@var{condition} is in effect, any fontifications caused by +@code{font-lock-keywords} elements that match the @var{condition} will +be disabled. + +Each @var{condition} can be one of the following: + +@table @asis +@item a symbol +This condition matches any element of Font Lock keywords that +references the symbol. This is usually a face, but can be any symbol +referenced by an element of the @code{font-lock-keywords} list. The +symbol can contain wildcards: @code{*} matches any string in the +symbol'ss name, @code{?} matches a single character, and +@code{[@var{char-set}]}, where @var{char-set} is a string of one or +more characters, matches a single character from the set. + +@item a string +This condition matches any element of Font Lock keywords whose +@var{matcher} is a regexp which matches the string. In other words, +this condition matches a Font Lock rule which highlights the string. +Thus, the string could be a specific program keyword whose +highlighting you want to disable. + +@item @code{(pred @var{function})} +This condition matches any element of Font Lock keywords for which +@var{function}, when called with the element as the argument, returns +non-@code{nil}. + +@item @code{(not @var{condition})} +This matches if @var{condition} doesn’t. + +@item @code{(and @var{condition} @dots{})} +This matches if each of the @var{condition}s matches. + +@item @code{(or @var{condition} @dots{})} +This matches if at least one of the @var{condition}s matches. + +@item @code{(except @var{condition})} +This condition can only be used at top level or inside an +@code{or} clause. It undoes the effect of a previously matching +condition on the same level. @end table - -In each buffer, Font Lock keywords that match at least one applicable -rule are disabled. -@end defvar +@end defopt As an example, consider the following setting: @@ -3337,23 +3350,23 @@ Line by line, this does the following: @enumerate @item -In all programming modes, disable all font-lock keywords that apply -one of the standard font-lock faces (excluding strings and comments, -which are covered by syntactic Font Lock). +In all programming modes, disable fontifications due to all font-lock +keywords that apply one of the standard font-lock faces (excluding +strings and comments, which are covered by syntactic Font Lock). @item However, keep any keywords that add a @code{help-echo} text property. @item In Emacs Lisp mode, also keep the highlighting of autoload cookies, -which would have been excluded by rule 1. +which would have been excluded by the first condition. @item -In @code{whitespace-mode} (a minor mode), don't highlight an empty -line at beginning of buffer. +When @code{whitespace-mode} (a minor mode) is enabled, also don't +highlight an empty line at beginning of buffer. @item -Finally, in Makefile mode, don't apply any ignore rules. +Finally, in Makefile mode, don't apply any conditions. @end enumerate @node Other Font Lock Variables diff --git a/etc/NEWS b/etc/NEWS index 9196e9fb909..199f07a0334 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1142,8 +1142,8 @@ support for pipelines which will move a lot of data. See section +++ *** New user option 'font-lock-ignore'. -This variable provides a mechanism to selectively disable font-lock -keywords. +This option provides a mechanism to selectively disable font-lock +keyword-driven fontifications. +++ *** New package vtable.el for formatting tabular data. diff --git a/lisp/font-lock.el b/lisp/font-lock.el index 8af3c30c9a3..5034c98d26e 100644 --- a/lisp/font-lock.el +++ b/lisp/font-lock.el @@ -281,37 +281,42 @@ decoration for buffers in C++ mode, and level 1 decoration otherwise." :group 'font-lock) (defcustom font-lock-ignore nil - "Rules to selectively disable font-lock keywords. -This is a list of rule sets of the form + "Rules to selectively disable fontifications due to `font-lock-keywords'. +If non-nil, the value should be a list of condition sets of the form - (MODE RULE ...) + (SYMBOL CONDITION ...) where: - - MODE is a symbol, say a major or minor mode. The subsequent - rules apply if the current major mode is derived from MODE or - MODE is bound and true as a variable. + - SYMBOL is a symbol, usually a major or minor mode. The subsequent + CONDITIONs apply if SYMBOL is bound as variable and its value is non-nil. + If SYMBOL is a symbol of a mode, that means the buffer has that mode + enabled (for major modes, it means the buffer's major mode is derived + from SYMBOL's mode). - - Each RULE can be one of the following: - - A symbol, say a face name. It matches any font-lock keyword - containing the symbol in its definition. The symbol is + - Each CONDITION can be one of the following: + - A symbol, typically a face. It matches any element of + `font-lock-keywords' that references the symbol. The symbol is interpreted as a glob pattern; in particular, `*' matches - everything. - - A string. It matches any font-lock keyword defined by a regexp - that matches the string. - - A form (pred FUNCTION). It matches if FUNCTION, which is called - with the font-lock keyword as argument, returns non-nil. - - A form (not RULE). It matches if RULE doesn't. - - A form (and RULE ...). It matches if all the provided rules - match. - - A form (or RULE ...). It matches if any of the provided rules - match. - - A form (except RULE ...). This can be used only at top level or - inside an `or' clause. It undoes the effect of a previous - matching rule. - -In each buffer, font lock keywords that match at least one -applicable rule are disabled." + everything, `?' matches any single character, and `[abcd]' + matches one character from the set. + - A string. It matches any element of `font-lock-keywords' whose + MATCHER is a regexp that matches the string. This can be used to + disable fontification of a particular programming keyword. + - A form (pred FUNCTION). It matches an element of `font-lock-keywords' + if FUNCTION, when called with the element as the argument, returns + non-nil. + - A form (not CONDITION). It matches if CONDITION doesn't. + - A form (and CONDITION ...). It matches if all the provided + CONDITIONs match. + - A form (or CONDITION ...). It matches if at least one of the + provided CONDITIONs matches. + - A form (except CONDITIONs ...). This can be used only at top level + or inside an `or' clause. It undoes the effect of previous + matching CONDITIONs on the same level. + +In each buffer, fontifications due to the elements of `font-lock-keywords' +that match at least one applicable CONDITION are disabled." :type '(alist :key-type symbol :value-type sexp) :group 'font-lock :version "29.1")