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

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

[Mattias Engdegård]

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

Add a standard face for mark-up syntax and keywords inside code documentation (doc comments/strings) whose body text is typically set in font-lock-doc-face. This could include various tags, brackets, quotes, keywords or other syntactically special characters.

Justification:

- A standard face means that users and theme authors can set it once for all modes needing it.
- Having a face that harmonises with font-lock-doc-face reduces the risk of bad ergonomics and aesthetics.
- Setting doc mark-up in a distinct face makes in-source documentation more readable.
- It also aids writing documentation by providing feed-back to the programmer in the same way as fontifying regular language constructs.

The CC modes have the foresight of already using `font-lock-doc-markup-face` if defined, anticipating its eventual addition, defaulting to `font-lock-constant-face`. I therefore propose that the new face will inherit from `font-lock-constant-face` by default.

Proposed patch attached.


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

From 6265617a428a60db9ca932a2bff33c70a94a9bc0 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

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

* 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      | 8 ++++++++
 4 files changed, 21 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..6fce7c6a43 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'.  This would typically be used in
+documentation comments for systems such as Doxygen, Haddock, Javadoc etc.
+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..32b7819533 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,11 @@ 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."
+  :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)

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

[Lars Ingebrigtsen]

Mattias Engdegård <mattiase@acm.org> writes:

> Add a standard face for mark-up syntax and keywords inside code
> documentation (doc comments/strings) whose body text is typically set
> in font-lock-doc-face. This could include various tags, brackets,
> quotes, keywords or other syntactically special characters.

Looks good to me.  Minor comment:

> +(defface font-lock-doc-markup-face
> +  '((t :inherit font-lock-constant-face))
> +  "Font Lock mode face used to highlight documentation mark-up."
> +  :group 'font-lock-faces)

Should have a :version.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 13 Aug 2021 12:53:04 +0200
> 
> Add a standard face for mark-up syntax and keywords inside code documentation (doc comments/strings) whose body text is typically set in font-lock-doc-face. This could include various tags, brackets, quotes, keywords or other syntactically special characters.
> 
> Justification:
> 
> - A standard face means that users and theme authors can set it once for all modes needing it.
> - Having a face that harmonises with font-lock-doc-face reduces the risk of bad ergonomics and aesthetics.
> - Setting doc mark-up in a distinct face makes in-source documentation more readable.
> - It also aids writing documentation by providing feed-back to the programmer in the same way as fontifying regular language constructs.
> 
> The CC modes have the foresight of already using `font-lock-doc-markup-face` if defined, anticipating its eventual addition, defaulting to `font-lock-constant-face`. I therefore propose that the new face will inherit from `font-lock-constant-face` by default.

Which one of these justifies having these faces in font-lock.el, as
opposed in markdown mode itself, or in rst.el?  It is unusual to have
mode-specific faces in a general-purpose Lisp file, let alone a
preloaded one.

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

[Mattias Engdegård]

[-- 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)

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

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 13 Aug 2021 16:08:59 +0200
> Cc: 50041@debbugs.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.

Sorry, I still don't get it.  Could you show a couple of examples of
use of this face, and tell how these use cases are handled without
that face?  TIA.

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

[Mattias Engdegård]

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

> Could you show a couple of examples of
> use of this face, and tell how these use cases are handled without
> that face?

Sure! Here is a Java doc comment:

/**
* Wag the dog.
* @return <code>true</code> iff the dog was already wagged.
*/

Here, it would be reasonable to set @return, <code> and </code> in font-lock-doc-markup-face since these are markup elements; the rest of the comment would be in font-lock-doc-face. And indeed, this is precisely what java-mode does today given the new face. 

Without the face it uses font-lock-constant-face which is not necessarily a good choice. The new face enables users and theme authors to select the markup element appearance independently for a good fit with the doc face, and have it work automatically with all language modes that make use of the new face.

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

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 13 Aug 2021 16:34:25 +0200
> Cc: larsi@gnus.org, 50041@debbugs.gnu.org
> 
> Sure! Here is a Java doc comment:
> 
> /**
> * Wag the dog.
> * @return <code>true</code> iff the dog was already wagged.
> */
> 
> Here, it would be reasonable to set @return, <code> and </code> in font-lock-doc-markup-face since these are markup elements; the rest of the comment would be in font-lock-doc-face. And indeed, this is precisely what java-mode does today given the new face. 

So this face is for portions of the buffer that are markup for the
text intended to be extracted into the documentation, like JavaDoc or
Doxygen do?  If so, I think the NEWS entry and the doc string should
say so, at least as an example of the intended usage.  I've read the
doc string you suggested several time, and still couldn't figure out
what the face is for: the description seems too abstract.

> Without the face it uses font-lock-constant-face

I'd expect font-lock-comment-face, what am I missing?

Thanks.

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

[Mattias Engdegård]

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

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

> So this face is for portions of the buffer that are markup for the
> text intended to be extracted into the documentation, like JavaDoc or
> Doxygen do?

Yes.

>  If so, I think the NEWS entry and the doc string should
> say so, at least as an example of the intended usage.  I've read the
> doc string you suggested several time, and still couldn't figure out
> what the face is for: the description seems too abstract.

It was assumed that the user of the new face would already be familiar with font-lock-doc-face and its uses.
The first version of the patch did mention both Javadoc and Doxygen but I re-wrote it after your comments indicated that it might have been unclear. I've now put that explanation back and extended the face doc string and manual entry.

>> Without the face it uses font-lock-constant-face
> 
> I'd expect font-lock-comment-face, what am I missing?

`font-lock-comment-face` is used for ordinary comments, not doc comments. The language mode uses the standard conventions to decide whether a comment is one or the other. To continue with Java as the example,

/* An ordinary comment. */  -- set in font-lock-comment-face
/** A javadoc comment. */   -- set in font-lock-doc-face

java-mode uses font-lock-doc-face for doc comments as intended. It also needs a face for doc markup but since there is none it repurposes font-lock-constant-face for that. See cc-fonts.el.

You can try this yourself in a buffer with java-mode.


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

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)

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

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 13 Aug 2021 19:41:06 +0200
> Cc: larsi@gnus.org, 50041@debbugs.gnu.org
> 
> >  If so, I think the NEWS entry and the doc string should
> > say so, at least as an example of the intended usage.  I've read the
> > doc string you suggested several time, and still couldn't figure out
> > what the face is for: the description seems too abstract.
> 
> It was assumed that the user of the new face would already be familiar with font-lock-doc-face and its uses.

If the doc string of font-lock-doc-face would explain its usage,
having a link to it might be sufficient.  But doc string of
font-lock-doc-face is just this:

  "Font Lock mode face used to highlight documentation."

I hope you agree with me that this is insufficient, and thus
mentioning it in the doc string of this new face is not enough?

Also, I think "for mark-up elements" is too terse and assumes too much
of prior knowledge; we should make more clear what that means, or
provide a couple of examples.

> The first version of the patch did mention both Javadoc and Doxygen but I re-wrote it after your comments indicated that it might have been unclear. I've now put that explanation back and extended the face doc string and manual entry.

Thanks.  The NEWS entry is now clear enough, but I think the manual
and the doc string still need some work.

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

[Mattias Engdegård]

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

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

> If the doc string of font-lock-doc-face would explain its usage,
> having a link to it might be sufficient.  But doc string of
> font-lock-doc-face is just this:
> 
>  "Font Lock mode face used to highlight documentation."

All faces have very terse doc strings and I naturally assumed that was the preferred style; it certainly didn't prevent me from understanding it. Anyway, I have amended the doc strings of both font-lock-doc-face and font-lock-doc-markup-face.

> Also, I think "for mark-up elements" is too terse and assumes too much
> of prior knowledge; we should make more clear what that means, or
> provide a couple of examples.

Maybe, but let's not exaggerate; this is standard terminology. Nevertheless, the text has been extended.

> The NEWS entry is now clear enough, but I think the manual
> and the doc string still need some work.

Very well, they have now all been expanded further.


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

From a4899a0bd18aa5498d9fb66987901d57715be104 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.
* 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 | 10 +++++++++-
 etc/NEWS               |  8 ++++++++
 lisp/cus-theme.el      |  2 +-
 lisp/font-lock.el      | 14 +++++++++++++-
 4 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d48c9cc1af..17eba15660 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3444,9 +3444,17 @@ Faces for Font Lock
 
 @item font-lock-doc-face
 @vindex font-lock-doc-face
-for documentation strings in the code.  This inherits, by default, from
+for documentation embedded in program code inside specially-formed
+comments or strings.  This face 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 the mark-up constructs in documentation embedded
+in program code, following conventions such as Haddock, Javadoc and Doxygen.
+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..c00a62a160 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.")
 
@@ -2003,7 +2006,16 @@ font-lock-string-face
 
 (defface font-lock-doc-face
   '((t :inherit font-lock-string-face))
-  "Font Lock mode face used to highlight documentation."
+  "Font Lock mode face used to highlight documentation embedded in program code.
+It is typically used for special documentation comments or strings."
+  :group 'font-lock-faces)
+
+(defface font-lock-doc-markup-face
+  '((t :inherit font-lock-constant-face))
+  "Font Lock mode face used to highlight embedded documentation mark-up.
+It is meant for mark-up elements in text that uses `font-lock-doc-face', such
+as the constructs of Haddock, Javadoc and similar systems."
+  :version "28.1"
   :group 'font-lock-faces)
 
 (defface font-lock-keyword-face
-- 
2.21.1 (Apple Git-122.3)

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

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 13 Aug 2021 23:24:13 +0200
> Cc: larsi@gnus.org, 50041@debbugs.gnu.org
> 
> >  "Font Lock mode face used to highlight documentation."
> 
> All faces have very terse doc strings and I naturally assumed that was the preferred style; it certainly didn't prevent me from understanding it. Anyway, I have amended the doc strings of both font-lock-doc-face and font-lock-doc-markup-face.
> 
> > Also, I think "for mark-up elements" is too terse and assumes too much
> > of prior knowledge; we should make more clear what that means, or
> > provide a couple of examples.
> 
> Maybe, but let's not exaggerate; this is standard terminology. Nevertheless, the text has been extended.
> 
> > The NEWS entry is now clear enough, but I think the manual
> > and the doc string still need some work.
> 
> Very well, they have now all been expanded further.

Thanks, this LGTM.

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

[Mattias Engdegård]

Thank you, pushed to master.