From: "Mattias Engdegård" <mattiase@acm.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: larsi@gnus.org, 50041@debbugs.gnu.org
Subject: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 19:41:06 +0200 [thread overview]
Message-ID: <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> (raw)
In-Reply-To: <83y295banl.fsf@gnu.org>
[-- 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)
next prev parent reply other threads:[~2021-08-13 17:41 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-08-13 10:53 bug#50041: Add font-lock-doc-markup-face Mattias Engdegård
2021-08-13 12:15 ` Lars Ingebrigtsen
2021-08-13 13:08 ` Eli Zaretskii
2021-08-13 14:08 ` Mattias Engdegård
2021-08-13 14:12 ` Eli Zaretskii
2021-08-13 14:34 ` Mattias Engdegård
2021-08-13 15:57 ` Eli Zaretskii
2021-08-13 17:41 ` Mattias Engdegård [this message]
2021-08-13 18:31 ` Eli Zaretskii
2021-08-13 21:24 ` Mattias Engdegård
2021-08-14 5:56 ` Eli Zaretskii
2021-08-14 9:01 ` Mattias Engdegård
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org \
--to=mattiase@acm.org \
--cc=50041@debbugs.gnu.org \
--cc=eliz@gnu.org \
--cc=larsi@gnus.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).