bug#50041: Add font-lock-doc-markup-face

["Mattias Engdegård" <mattiase@acm.org>]

[-- Attachment #1: Type: text/plain, Size: 864 bytes --]

13 aug. 2021 kl. 15.08 skrev Eli Zaretskii <eliz@gnu.org>:

> Which one of these justifies having these faces in font-lock.el, as
> opposed in markdown mode itself, or in rst.el?

All of them -- it's not primarily intended for editing whole texts in those formats (and modes) but for doc comments specific to each programming language. Fontifying those is done by the respective language mode, such as haskell-mode or java-mode.

Sorry if I was unclear on that point. I've made the NEWS entry a bit less ambiguous.

>  It is unusual to have
> mode-specific faces in a general-purpose Lisp file, let alone a
> preloaded one.

The face is not mode-specific. It's like font-lock-doc-face.


13 aug. 2021 kl. 14.15 skrev Lars Ingebrigtsen <larsi@gnus.org>:

> Should have a :version.

Yes it should, thank you! Added.

Revised patch attached.


[-- Attachment #2: 0001-Add-font-lock-doc-markup-face-bug-50041.patch --]
[-- Type: application/octet-stream, Size: 3928 bytes --]

From 6e3ab0ece0ebf4db1326d8ddf0c7b7e0dd1b0d0f 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 | 5 +++++
 etc/NEWS               | 7 +++++++
 lisp/cus-theme.el      | 2 +-
 lisp/font-lock.el      | 9 +++++++++
 4 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d48c9cc1af..7a651b6390 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3447,6 +3447,11 @@ 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 constructs in text using @code{font-lock-doc-face}.
+This 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..58c76a5f0a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -149,6 +149,13 @@ 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.  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..60b6c82676 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,12 @@ 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."
+  :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)