master 9c30276c42: ; Improve documentation of 'font-lock-ignore'

[Eli Zaretskii]

branch: master
commit 9c30276c426e0b67d288b479a9570428673de331
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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'.
---
 doc/emacs/display.texi |   5 +++
 doc/lispref/modes.texi | 113 +++++++++++++++++++++++++++----------------------
 etc/NEWS               |   4 +-
 lisp/font-lock.el      |  55 +++++++++++++-----------
 4 files changed, 100 insertions(+), 77 deletions(-)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 4fcd2a3f7d..534bf5881e 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 b61ba56e18..ff09a78749 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 9196e9fb90..199f07a033 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 8af3c30c9a..5034c98d26 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")