From: Noam Postavsky <npostavs@gmail.com>
Date: Fri, 19 Apr 2019 04:55:14 +0000 (-0400)
Subject: Recommend using font-lock-face over face (Bug#35044)
X-Git-Tag: emacs-26.2.90~78
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=140e7f890fa94f8b6381dfa3e0682cacfa92a593;p=emacs.git

Recommend using font-lock-face over face (Bug#35044)

* doc/lispref/modes.texi (Precalculated Fontification): Explain
advantages of using font-lock-face over face.
---

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 919816f3dee..0ff13d72e2f 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3201,7 +3201,12 @@ is disabled, @code{font-lock-face} has no effect on the display.
   It is ok for a mode to use @code{font-lock-face} for some text and
 also use the normal Font Lock machinery.  But if the mode does not use
 the normal Font Lock machinery, it should not set the variable
-@code{font-lock-defaults}.
+@code{font-lock-defaults}.  In this case the @code{face} property will
+not be overriden, so using the @code{face} property could work too.
+However, using @code{font-lock-face} is generally preferable as it
+allows the user to control the fontification by toggling
+@code{font-lock-mode}, and lets the code work regardless of whether
+the mode uses Font Lock machinery or not.
 
 @node Faces for Font Lock
 @subsection Faces for Font Lock