From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Newsgroups: gmane.emacs.bugs Subject: bug#50041: Add font-lock-doc-markup-face Date: Fri, 13 Aug 2021 19:41:06 +0200 Message-ID: <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> References: <837dgpcx1g.fsf@gnu.org> <1A815899-9854-4042-B4C1-BCF85BF4E794@acm.org> <8335rdcu1p.fsf@gnu.org> <5FDD6903-3ECB-4F3E-90D8-FA591A5A143D@acm.org> <83y295banl.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\)) Content-Type: multipart/mixed; boundary="Apple-Mail=_07CCCC5B-FDA2-47B2-80E4-BA3685FDCBDD" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7335"; mail-complaints-to="usenet@ciao.gmane.io" Cc: larsi@gnus.org, 50041@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Aug 13 19:43:20 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mEbDD-0001iV-HV for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 13 Aug 2021 19:43:19 +0200 Original-Received: from localhost ([::1]:52644 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mEbDC-0006iZ-4c for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 13 Aug 2021 13:43:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38454) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEbCx-0006iP-1p for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 13:43:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:59743) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mEbCw-0002Ri-Pf for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 13:43:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mEbCw-0000c1-9M for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 13:43:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 13 Aug 2021 17:43:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 50041 X-GNU-PR-Package: emacs Original-Received: via spool by 50041-submit@debbugs.gnu.org id=B50041.16288765602323 (code B ref 50041); Fri, 13 Aug 2021 17:43:02 +0000 Original-Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 17:42:40 +0000 Original-Received: from localhost ([127.0.0.1]:43056 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEbCa-0000bP-Ad for submit@debbugs.gnu.org; Fri, 13 Aug 2021 13:42:40 -0400 Original-Received: from mail226c50.megamailservers.eu ([91.136.10.236]:39706 helo=mail36c50.megamailservers.eu) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEbCW-0000bD-7o for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 13:42:39 -0400 X-Authenticated-User: mattiase@bredband.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1628876553; bh=g0VIDzBgrx+McbTvHmTOw+JUiniRFzwRJIaWwDT6bTg=; h=From:Subject:Date:In-Reply-To:Cc:To:References:From; b=pkrz9KdPBDzKZpZsBKvVZQ2hc97rsvSkT85cpiJS5dfVnvx3DpaGmU/ODX2hk/GG5 cvrwXLHa+qkk9zE/kazhn7AT19SxGyoQj3dK6EizWGoO9YWzvtK4qpEoO4+c9NeJ5T npFv68wH3jM+NG7p5JtB4RRKohi48tTnnEno9fpE= Feedback-ID: mattiase@acm.or Original-Received: from stanniol.lan (c-b952e353.032-75-73746f71.bbcust.telenor.se [83.227.82.185]) (authenticated bits=0) by mail36c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 17DHgUJh005192; Fri, 13 Aug 2021 17:42:32 +0000 In-Reply-To: <83y295banl.fsf@gnu.org> X-Mailer: Apple Mail (2.3445.104.21) X-CTCH-RefID: str=0001.0A742F1B.6116AF09.0066, ss=1, re=0.000, recu=0.000, reip=0.000, cl=1, cld=1, fgs=0 X-CTCH-VOD: Unknown X-CTCH-Spam: Unknown X-CTCH-Score: 0.000 X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=FNFlONgs c=1 sm=1 tr=0 a=von4qPfY+hyqc0zmWf0tYQ==:117 a=von4qPfY+hyqc0zmWf0tYQ==:17 a=M51BFTxLslgA:10 a=mDV3o1hIAAAA:8 a=JN6NTa07HxoguT4qVucA:9 a=CjuIK1q_8ugA:10 a=c9odS3n5DQ3OFn8xpM8A:9 a=7Zwj6sZBwVKJAoWSPKxL6X1jA+E=:19 a=B2y7HmGcmWMA:10 a=_FVE-zBwftR9WsbkzFJk:22 X-Origin-Country: SE X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:211785 Archived-At: --Apple-Mail=_07CCCC5B-FDA2-47B2-80E4-BA3685FDCBDD Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 13 aug. 2021 kl. 17.57 skrev Eli Zaretskii : > 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 >=20 > 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. --Apple-Mail=_07CCCC5B-FDA2-47B2-80E4-BA3685FDCBDD Content-Disposition: attachment; filename=0001-Add-font-lock-doc-markup-face-bug-50041.patch Content-Type: application/octet-stream; x-unix-mode=0644; name="0001-Add-font-lock-doc-markup-face-bug-50041.patch" Content-Transfer-Encoding: quoted-printable =46rom=204884d2d33322844db35ff67991e336765d4a880f=20Mon=20Sep=2017=20= 00:00:00=202001=0AFrom:=20=3D?UTF-8?q?Mattias=3D20Engdeg=3DC3=3DA5rd?=3D=20= =0ADate:=20Fri,=2013=20Aug=202021=2012:47:39=20+0200=0A= Subject:=20[PATCH]=20Add=20font-lock-doc-markup-face=20(bug#50041)=0A=0A= This=20face=20is=20intended=20for=20mark-up=20syntax=20and=20constructs=20= inside=20text=0Ausing=20font-lock-doc-face;=20ie,=20documentation=20= comments=20and=20strings=20in=0Aprogramming=20modes.=0A=0A*=20= lisp/font-lock.el=20(font-lock-doc-markup-face):=20New=20face=20and=20= variable.=0A*=20lisp/cus-theme.el=20(custom-theme--listed-faces):=20Add=20= it=20to=20the=20list.=0A*=20doc/lispref/modes.texi=20(Faces=20for=20Font=20= Lock):=20Document=20it.=0A*=20etc/NEWS:=20Mention=20it.=0A---=0A=20= doc/lispref/modes.texi=20|=20=206=20++++++=0A=20etc/NEWS=20=20=20=20=20=20= =20=20=20=20=20=20=20=20=20|=20=208=20++++++++=0A=20lisp/cus-theme.el=20=20= =20=20=20=20|=20=202=20+-=0A=20lisp/font-lock.el=20=20=20=20=20=20|=2011=20= +++++++++++=0A=204=20files=20changed,=2026=20insertions(+),=201=20= deletion(-)=0A=0Adiff=20--git=20a/doc/lispref/modes.texi=20= b/doc/lispref/modes.texi=0Aindex=20d48c9cc1af..6d54cd460b=20100644=0A---=20= a/doc/lispref/modes.texi=0A+++=20b/doc/lispref/modes.texi=0A@@=20-3447,6=20= +3447,12=20@@=20Faces=20for=20Font=20Lock=0A=20for=20documentation=20= strings=20in=20the=20code.=20=20This=20inherits,=20by=20default,=20from=0A= =20@code{font-lock-string-face}.=0A=20=0A+@item=20= font-lock-doc-markup-face=0A+@vindex=20font-lock-doc-markup-face=0A+for=20= mark-up=20elements=20in=20text=20using=20@code{font-lock-doc-face}.=0A= +It=20is=20typically=20used=20for=20mark-up=20in=20documentation=20= embedded=20in=20program=20code.=0A+This=20face=20inherits,=20by=20= default,=20from=20@code{font-lock-constant-face}.=0A+=0A=20@item=20= font-lock-negation-char-face=0A=20@vindex=20font-lock-negation-char-face=0A= =20for=20easily-overlooked=20negation=20characters.=0Adiff=20--git=20= a/etc/NEWS=20b/etc/NEWS=0Aindex=2026ede71523..5d396dde0f=20100644=0A---=20= a/etc/NEWS=0A+++=20b/etc/NEWS=0A@@=20-149,6=20+149,14=20@@=20invoked=20= with=20the=20'--declarations'=20command-line=20option.=0A=20**=20New=20= command=20'font-lock-update',=20bound=20to=20'C-x=20x=20f'.=0A=20This=20= command=20updates=20the=20syntax=20highlighting=20in=20this=20buffer.=0A=20= =0A++++=0A+**=20A=20new=20standard=20face=20'font-lock-doc-markup-face'.=0A= +Intended=20for=20documentation=20mark-up=20syntax=20and=20tags=20inside=20= text=20that=0A+uses=20'font-lock-doc-face'.=20=20It=20would=20typically=20= be=20used=20in=20structured=0A+documentation=20comments=20in=20program=20= source=20code=20by=20language-specific=0A+modes,=20for=20mark-up=20= conventions=20like=20Haddock,=20Javadoc=20or=20Doxygen.=0A+By=20default=20= this=20face=20inherits=20from=20'font-lock-constant-face'.=0A+=0A=20**=20= The=20new=20NonGNU=20ELPA=20archive=20is=20enabled=20by=20default=20= alongside=20GNU=20ELPA.=0A=20=0A=20+++=0Adiff=20--git=20= a/lisp/cus-theme.el=20b/lisp/cus-theme.el=0Aindex=20= f4885d0f52..7457d9e323=20100644=0A---=20a/lisp/cus-theme.el=0A+++=20= b/lisp/cus-theme.el=0A@@=20-66,7=20+66,7=20@@=20= custom-theme--listed-faces=0A=20=20=20shadow=20secondary-selection=20= trailing-whitespace=0A=20=20=20font-lock-builtin-face=20= font-lock-comment-delimiter-face=0A=20=20=20font-lock-comment-face=20= font-lock-constant-face=0A-=20=20font-lock-doc-face=20= font-lock-function-name-face=0A+=20=20font-lock-doc-face=20= font-lock-doc-markup-face=20font-lock-function-name-face=0A=20=20=20= font-lock-keyword-face=20font-lock-negation-char-face=0A=20=20=20= font-lock-preprocessor-face=20font-lock-regexp-grouping-backslash=0A=20=20= =20font-lock-regexp-grouping-construct=20font-lock-string-face=0Adiff=20= --git=20a/lisp/font-lock.el=20b/lisp/font-lock.el=0Aindex=20= 4dc42d9cf6..4b8e94e892=20100644=0A---=20a/lisp/font-lock.el=0A+++=20= b/lisp/font-lock.el=0A@@=20-312,6=20+312,9=20@@=20font-lock-string-face=0A= =20(defvar=20font-lock-doc-face=09=09'font-lock-doc-face=0A=20=20=20= "Face=20name=20to=20use=20for=20documentation.")=0A=20=0A+(defvar=20= font-lock-doc-markup-face=20=20=20=20=20=20=20'font-lock-doc-markup-face=0A= +=20=20"Face=20name=20to=20use=20for=20documentation=20mark-up.")=0A+=0A=20= (defvar=20font-lock-keyword-face=09=09'font-lock-keyword-face=0A=20=20=20= "Face=20name=20to=20use=20for=20keywords.")=0A=20=0A@@=20-2006,6=20= +2009,14=20@@=20font-lock-doc-face=0A=20=20=20"Font=20Lock=20mode=20face=20= used=20to=20highlight=20documentation."=0A=20=20=20:group=20= 'font-lock-faces)=0A=20=0A+(defface=20font-lock-doc-markup-face=0A+=20=20= '((t=20:inherit=20font-lock-constant-face))=0A+=20=20"Font=20Lock=20mode=20= face=20used=20to=20highlight=20documentation=20mark-up.=0A+It=20is=20= meant=20for=20mark-up=20elements=20in=20text=20using=20= `font-lock-doc-face',=20in=0A+documentation=20embedded=20in=20program=20= code."=0A+=20=20:version=20"28.1"=0A+=20=20:group=20'font-lock-faces)=0A= +=0A=20(defface=20font-lock-keyword-face=0A=20=20=20'((((class=20= grayscale)=20(background=20light))=20:foreground=20"LightGray"=20:weight=20= bold)=0A=20=20=20=20=20(((class=20grayscale)=20(background=20dark))=20=20= :foreground=20"DimGray"=20:weight=20bold)=0A--=20=0A2.21.1=20(Apple=20= Git-122.3)=0A=0A= --Apple-Mail=_07CCCC5B-FDA2-47B2-80E4-BA3685FDCBDD--