From 4884d2d33322844db35ff67991e336765d4a880f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Fri, 13 Aug 2021 12:47:39 +0200
Subject: [PATCH] Add font-lock-doc-markup-face (bug#50041)

This face is intended for mark-up syntax and constructs inside text
using font-lock-doc-face; ie, documentation comments and strings in
programming modes.

* lisp/font-lock.el (font-lock-doc-markup-face): New face and variable.
* lisp/cus-theme.el (custom-theme--listed-faces): Add it to the list.
* doc/lispref/modes.texi (Faces for Font Lock): Document it.
* etc/NEWS: Mention it.
---
 doc/lispref/modes.texi |  6 ++++++
 etc/NEWS               |  8 ++++++++
 lisp/cus-theme.el      |  2 +-
 lisp/font-lock.el      | 11 +++++++++++
 4 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d48c9cc1af..6d54cd460b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3447,6 +3447,12 @@ Faces for Font Lock
 for documentation strings in the code.  This inherits, by default, from
 @code{font-lock-string-face}.
 
+@item font-lock-doc-markup-face
+@vindex font-lock-doc-markup-face
+for mark-up elements in text using @code{font-lock-doc-face}.
+It is typically used for mark-up in documentation embedded in program code.
+This face inherits, by default, from @code{font-lock-constant-face}.
+
 @item font-lock-negation-char-face
 @vindex font-lock-negation-char-face
 for easily-overlooked negation characters.
diff --git a/etc/NEWS b/etc/NEWS
index 26ede71523..5d396dde0f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -149,6 +149,14 @@ invoked with the '--declarations' command-line option.
 ** New command 'font-lock-update', bound to 'C-x x f'.
 This command updates the syntax highlighting in this buffer.
 
++++
+** A new standard face 'font-lock-doc-markup-face'.
+Intended for documentation mark-up syntax and tags inside text that
+uses 'font-lock-doc-face'.  It would typically be used in structured
+documentation comments in program source code by language-specific
+modes, for mark-up conventions like Haddock, Javadoc or Doxygen.
+By default this face inherits from 'font-lock-constant-face'.
+
 ** The new NonGNU ELPA archive is enabled by default alongside GNU ELPA.
 
 +++
diff --git a/lisp/cus-theme.el b/lisp/cus-theme.el
index f4885d0f52..7457d9e323 100644
--- a/lisp/cus-theme.el
+++ b/lisp/cus-theme.el
@@ -66,7 +66,7 @@ custom-theme--listed-faces
   shadow secondary-selection trailing-whitespace
   font-lock-builtin-face font-lock-comment-delimiter-face
   font-lock-comment-face font-lock-constant-face
-  font-lock-doc-face font-lock-function-name-face
+  font-lock-doc-face font-lock-doc-markup-face font-lock-function-name-face
   font-lock-keyword-face font-lock-negation-char-face
   font-lock-preprocessor-face font-lock-regexp-grouping-backslash
   font-lock-regexp-grouping-construct font-lock-string-face
diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 4dc42d9cf6..4b8e94e892 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -312,6 +312,9 @@ font-lock-string-face
 (defvar font-lock-doc-face		'font-lock-doc-face
   "Face name to use for documentation.")
 
+(defvar font-lock-doc-markup-face       'font-lock-doc-markup-face
+  "Face name to use for documentation mark-up.")
+
 (defvar font-lock-keyword-face		'font-lock-keyword-face
   "Face name to use for keywords.")
 
@@ -2006,6 +2009,14 @@ font-lock-doc-face
   "Font Lock mode face used to highlight documentation."
   :group 'font-lock-faces)
 
+(defface font-lock-doc-markup-face
+  '((t :inherit font-lock-constant-face))
+  "Font Lock mode face used to highlight documentation mark-up.
+It is meant for mark-up elements in text using `font-lock-doc-face', in
+documentation embedded in program code."
+  :version "28.1"
+  :group 'font-lock-faces)
+
 (defface font-lock-keyword-face
   '((((class grayscale) (background light)) :foreground "LightGray" :weight bold)
     (((class grayscale) (background dark))  :foreground "DimGray" :weight bold)
-- 
2.21.1 (Apple Git-122.3)

