GNU bug report logs - #50041
Add font-lock-doc-markup-face

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50041 in the body.
You can then email your comments to 50041 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: bug-gnu-emacs <at> gnu.org
Subject: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 12:53:04 +0200

[Message part 1 (text/plain, inline)]

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.

[0001-Add-font-lock-doc-markup-face.patch (application/octet-stream, attachment)]

Message #8 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 14:15:33 +0200

Mattias Engdegård <mattiase <at> 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

Message #11 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 16:08:11 +0300

> From: Mattias Engdegård <mattiase <at> 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.

Message #14 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Eli Zaretskii <eliz <at> gnu.org>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 16:08:59 +0200

[Message part 1 (text/plain, inline)]

13 aug. 2021 kl. 15.08 skrev Eli Zaretskii <eliz <at> 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 <at> gnus.org>:

> Should have a :version.

Yes it should, thank you! Added.

Revised patch attached.

[0001-Add-font-lock-doc-markup-face-bug-50041.patch (application/octet-stream, attachment)]

Message #17 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 17:12:50 +0300

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

Message #20 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 16:34:25 +0200

13 aug. 2021 kl. 16.12 skrev Eli Zaretskii <eliz <at> 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.

Message #23 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 18:57:02 +0300

> From: Mattias Engdegård <mattiase <at> acm.org>
> Date: Fri, 13 Aug 2021 16:34:25 +0200
> Cc: larsi <at> gnus.org, 50041 <at> 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.

Message #26 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 19:41:06 +0200

[Message part 1 (text/plain, inline)]

13 aug. 2021 kl. 17.57 skrev Eli Zaretskii <eliz <at> 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.

[0001-Add-font-lock-doc-markup-face-bug-50041.patch (application/octet-stream, attachment)]

Message #29 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 21:31:33 +0300

> From: Mattias Engdegård <mattiase <at> acm.org>
> Date: Fri, 13 Aug 2021 19:41:06 +0200
> Cc: larsi <at> gnus.org, 50041 <at> 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.

Message #32 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 23:24:13 +0200

[Message part 1 (text/plain, inline)]

13 aug. 2021 kl. 20.31 skrev Eli Zaretskii <eliz <at> 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.

[0001-Add-font-lock-doc-markup-face-bug-50041.patch (application/octet-stream, attachment)]

Message #35 received at 50041 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Sat, 14 Aug 2021 08:56:47 +0300

> From: Mattias Engdegård <mattiase <at> acm.org>
> Date: Fri, 13 Aug 2021 23:24:13 +0200
> Cc: larsi <at> gnus.org, 50041 <at> 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.

Message #40 received at 50041-done <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50041-done <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#50041: Add font-lock-doc-markup-face
Date: Sat, 14 Aug 2021 11:01:45 +0200

Thank you, pushed to master.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.