Note caveat about remapping basic faces

* doc/lispref/display.texi (Face Remapping): Note caveat about
basic faces (bug#53636).

2 files changed, 13 insertions, 0 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b749d3d8922..280ea534555 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3320,6 +3320,13 @@ if you need to remove the remapping later.
 ;; Increase the size of the 'default' face by 50%:
 (face-remap-add-relative 'default :height 1.5)
 @end example
+
+Note that face remapping does not work reliably parent faces of
+@dnf{basic faces}.  (These are the faces that are used in mode lines,
+header lines and the like.)  For instance, @code{mode-line-inactive}
+inherits from @code{mode-line}, but remapping @code{mode-line} won't
+normally have the desired effect on @code{mode-line-inactive}.
+Instead you have to remap @code{mode-line-inactive} directly.
 @end defun
 
 @defun face-remap-remove-relative cookie
diff --git a/etc/NEWS b/etc/NEWS
index cd8cec32d5d..657088c98de 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -992,6 +992,12 @@ Emacs buffers, like indentation and the like.  The new ert function
 
 * Incompatible Lisp Changes in Emacs 29.1
 
++++
+** Remapping 'mode-line' no longer works as expected.
+'mode-line' is now the parent face of the new 'mode-line-active' face,
+and remapping parent of basic faces does not work reliably.
+Instead of remapping 'mode-line', you have to remap 'mode-line-active'.
+
 ** User option 'mail-source-ignore-errors' is now obsolete.
 The whole mechanism for prompting users to continue in case of
 mail-source errors has been removed, so this option is no longer