From unknown Fri Aug 15 14:16:34 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#50041 <50041@debbugs.gnu.org> To: bug#50041 <50041@debbugs.gnu.org> Subject: Status: Add font-lock-doc-markup-face Reply-To: bug#50041 <50041@debbugs.gnu.org> Date: Fri, 15 Aug 2025 21:16:34 +0000 retitle 50041 Add font-lock-doc-markup-face reassign 50041 emacs submitter 50041 Mattias Engdeg=C3=A5rd severity 50041 normal thanks From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 06:53:18 2021 Received: (at submit) by debbugs.gnu.org; 13 Aug 2021 10:53:18 +0000 Received: from localhost ([127.0.0.1]:40561 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEUoQ-0001Hm-Hc for submit@debbugs.gnu.org; Fri, 13 Aug 2021 06:53:18 -0400 Received: from lists.gnu.org ([209.51.188.17]:47488) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEUoM-0001Hb-VS for submit@debbugs.gnu.org; Fri, 13 Aug 2021 06:53:17 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:46768) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEUoM-0008Km-MW for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 06:53:14 -0400 Received: from mail1434c50.megamailservers.eu ([91.136.14.34]:59514 helo=mail263c50.megamailservers.eu) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEUoI-0004Cl-Qz for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 06:53:14 -0400 X-Authenticated-User: mattiase@bredband.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1628851986; bh=DBMzd2IYZCcykUI+lwKz+riDeLHSlgDhR8HGWDMLDOA=; h=From:Subject:Date:To:From; b=XAy5Xgvw4kEVqo9Y7G+jLI+BXW1iKbNmvsLMRHtbVURqzn399NrlPFyjeyDwuKCNM 486XcDqkG14toot9i95Ql8tqHScPw9bAWSXAwnGvDjdA3lbAOzBEg9GNZKaBO9ku+F y6fDEoxFNrlNDwgSOfQC4TfEtG4yc9D+jlsLUwc0= Feedback-ID: mattiase@acm.or Received: from stanniol.lan (c-b952e353.032-75-73746f71.bbcust.telenor.se [83.227.82.185]) (authenticated bits=0) by mail263c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 17DAr4d0020036 for ; Fri, 13 Aug 2021 10:53:06 +0000 From: =?utf-8?Q?Mattias_Engdeg=C3=A5rd?= Content-Type: multipart/mixed; boundary="Apple-Mail=_5B279EAD-8007-4E5C-9327-AEE0D6C12AD6" Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\)) Subject: Add font-lock-doc-markup-face Message-Id: Date: Fri, 13 Aug 2021 12:53:04 +0200 To: bug-gnu-emacs@gnu.org X-Mailer: Apple Mail (2.3445.104.21) X-CTCH-RefID: str=0001.0A742F1C.61164F12.0037, 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-Rules: X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=St3uF8G0 c=1 sm=1 tr=0 a=von4qPfY+hyqc0zmWf0tYQ==:117 a=von4qPfY+hyqc0zmWf0tYQ==:17 a=M51BFTxLslgA:10 a=3vtEJ0S4cZPj5zxcCqQA:9 a=CjuIK1q_8ugA:10 a=b3X37vTZZnmG3GshoWUA:9 a=7Zwj6sZBwVKJAoWSPKxL6X1jA+E=:19 a=B2y7HmGcmWMA:10 X-Origin-Country: SE Received-SPF: softfail client-ip=91.136.14.34; envelope-from=mattiase@acm.org; helo=mail263c50.megamailservers.eu X-Spam_score_int: -11 X-Spam_score: -1.2 X-Spam_bar: - X-Spam_report: (-1.2 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, SPF_HELO_NONE=0.001, SPF_SOFTFAIL=0.665 autolearn=no autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.3 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) --Apple-Mail=_5B279EAD-8007-4E5C-9327-AEE0D6C12AD6 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 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. --Apple-Mail=_5B279EAD-8007-4E5C-9327-AEE0D6C12AD6 Content-Disposition: attachment; filename=0001-Add-font-lock-doc-markup-face.patch Content-Type: application/octet-stream; x-unix-mode=0644; name="0001-Add-font-lock-doc-markup-face.patch" Content-Transfer-Encoding: quoted-printable =46rom=206265617a428a60db9ca932a2bff33c70a94a9bc0=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=0A=0AThis=20face=20= is=20intended=20for=20mark-up=20syntax=20and=20constructs=20inside=20= text=0Ausing=20font-lock-doc-face;=20ie,=20documentation=20comments=20= and=20strings.=0A=0A*=20lisp/font-lock.el=20(font-lock-doc-markup-face):=20= New=20face=20and=20variable.=0A*=20lisp/cus-theme.el=20= (custom-theme--listed-faces):=20Add=20it=20to=20the=20list.=0A*=20= doc/lispref/modes.texi=20(Faces=20for=20Font=20Lock):=20Document=20it.=0A= *=20etc/NEWS:=20Mention=20it.=0A---=0A=20doc/lispref/modes.texi=20|=205=20= +++++=0A=20etc/NEWS=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20|=207=20= +++++++=0A=20lisp/cus-theme.el=20=20=20=20=20=20|=202=20+-=0A=20= lisp/font-lock.el=20=20=20=20=20=20|=208=20++++++++=0A=204=20files=20= changed,=2021=20insertions(+),=201=20deletion(-)=0A=0Adiff=20--git=20= a/doc/lispref/modes.texi=20b/doc/lispref/modes.texi=0Aindex=20= d48c9cc1af..7a651b6390=20100644=0A---=20a/doc/lispref/modes.texi=0A+++=20= b/doc/lispref/modes.texi=0A@@=20-3447,6=20+3447,11=20@@=20Faces=20for=20= Font=20Lock=0A=20for=20documentation=20strings=20in=20the=20code.=20=20= This=20inherits,=20by=20default,=20from=0A=20= @code{font-lock-string-face}.=0A=20=0A+@item=20font-lock-doc-markup-face=0A= +@vindex=20font-lock-doc-markup-face=0A+for=20mark-up=20constructs=20in=20= text=20using=20@code{font-lock-doc-face}.=0A+This=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..6fce7c6a43=20100644=0A---=20= a/etc/NEWS=0A+++=20b/etc/NEWS=0A@@=20-149,6=20+149,13=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=20This=20would=20= typically=20be=20used=20in=0A+documentation=20comments=20for=20systems=20= such=20as=20Doxygen,=20Haddock,=20Javadoc=20etc.=0A+By=20default=20this=20= face=20inherits=20from=20'font-lock-constant-face'.=0A+=0A=20**=20The=20= new=20NonGNU=20ELPA=20archive=20is=20enabled=20by=20default=20alongside=20= GNU=20ELPA.=0A=20=0A=20+++=0Adiff=20--git=20a/lisp/cus-theme.el=20= b/lisp/cus-theme.el=0Aindex=20f4885d0f52..7457d9e323=20100644=0A---=20= a/lisp/cus-theme.el=0A+++=20b/lisp/cus-theme.el=0A@@=20-66,7=20+66,7=20= @@=20custom-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..32b7819533=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,11=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+=20=20:group=20= 'font-lock-faces)=0A+=0A=20(defface=20font-lock-keyword-face=0A=20=20=20= '((((class=20grayscale)=20(background=20light))=20:foreground=20= "LightGray"=20:weight=20bold)=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=20Git-122.3)=0A=0A= --Apple-Mail=_5B279EAD-8007-4E5C-9327-AEE0D6C12AD6-- From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 08:15:46 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 12:15:46 +0000 Received: from localhost ([127.0.0.1]:40698 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEW6E-0007ts-3y for submit@debbugs.gnu.org; Fri, 13 Aug 2021 08:15:46 -0400 Received: from quimby.gnus.org ([95.216.78.240]:50744) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEW6C-0007tf-PI for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 08:15:45 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Transfer-Encoding:Content-Type:MIME-Version:Message-ID :In-Reply-To:Date:References:Subject:Cc:To:From:Sender:Reply-To:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=tTswbkWzxpvciCglhwN4F+48y6CsATmtvj9mCxWBfIc=; b=DYjA63ldVte3EcFqc5W4p9pfJB +j4l2Ee20cropLtNYQULYzlf5/k+VznepjOOyQkC/Vd84jS4Yx9qUmm0CAmd8/QJcA1VFzMGYgUPf zwY/39WjPEjiwqYSFV4xk9raOpEi7GACm46eKQqB72eOeJ+4pCxA2lFmQTcCS2v9h3F8=; Received: from [84.212.220.105] (helo=elva) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mEW62-0003N2-EM; Fri, 13 Aug 2021 14:15:38 +0200 From: Lars Ingebrigtsen To: Mattias =?utf-8?Q?Engdeg=C3=A5rd?= Subject: Re: bug#50041: Add font-lock-doc-markup-face References: Date: Fri, 13 Aug 2021 14:15:33 +0200 In-Reply-To: ("Mattias =?utf-8?Q?Engdeg=C3=A5rd=22's?= message of "Fri, 13 Aug 2021 12:53:04 +0200") Message-ID: <87r1exee1m.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Mattias Engdegård 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, brac [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 50041 Cc: 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Mattias Engdeg=C3=A5rd 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. --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 09:08:52 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 13:08:52 +0000 Received: from localhost ([127.0.0.1]:40848 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEWvb-0005F6-Pb for submit@debbugs.gnu.org; Fri, 13 Aug 2021 09:08:51 -0400 Received: from eggs.gnu.org ([209.51.188.92]:56322) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEWvW-0005Em-6Q for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 09:08:49 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:42186) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mEWvQ-0005zQ-GH; Fri, 13 Aug 2021 09:08:40 -0400 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:3713 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEWvO-0000E0-27; Fri, 13 Aug 2021 09:08:40 -0400 Date: Fri, 13 Aug 2021 16:08:11 +0300 Message-Id: <837dgpcx1g.fsf@gnu.org> From: Eli Zaretskii To: Mattias =?utf-8?Q?Engdeg=C3=A5rd?= In-Reply-To: (message from Mattias =?utf-8?Q?Engdeg=C3=A5rd?= on Fri, 13 Aug 2021 12:53:04 +0200) Subject: Re: bug#50041: Add font-lock-doc-markup-face References: MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 50041 Cc: 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Mattias Engdegård > 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 10:09:13 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 14:09:13 +0000 Received: from localhost ([127.0.0.1]:42791 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEXs1-0005TX-41 for submit@debbugs.gnu.org; Fri, 13 Aug 2021 10:09:13 -0400 Received: from mail1442c50.megamailservers.eu ([91.136.14.42]:39488 helo=mail264c50.megamailservers.eu) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEXrx-0005TH-Sv for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 10:09:11 -0400 X-Authenticated-User: mattiase@bredband.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1628863742; bh=eosv6fQnHQTKx3TiF1Ny12ASaGb2Qr4FjR5AXU22w5U=; h=From:Subject:Date:In-Reply-To:Cc:To:References:From; b=dUpsW7hgwyzODH5pvTy+4Vz12wBNzy5Ht5cRZMV4dncYEoHeTdk6OKoE7ERg/J7GJ 0cjqv1qrOYTijUGhi/NxjpRxuljWSZANLziUNxdXDfKluHWX9ZApcsFE+W44QjjGvo y69sAsFZ0eba81HkOFaOV9rfbYNQPFB3zIcZfAD0= Feedback-ID: mattiase@acm.or Received: from stanniol.lan (c-b952e353.032-75-73746f71.bbcust.telenor.se [83.227.82.185]) (authenticated bits=0) by mail264c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 17DE8x0O022542; Fri, 13 Aug 2021 14:09:01 +0000 From: =?utf-8?Q?Mattias_Engdeg=C3=A5rd?= Message-Id: <1A815899-9854-4042-B4C1-BCF85BF4E794@acm.org> Content-Type: multipart/mixed; boundary="Apple-Mail=_BFF885C1-13BD-4FED-B1B5-78A08A33D393" Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\)) Subject: Re: bug#50041: Add font-lock-doc-markup-face Date: Fri, 13 Aug 2021 16:08:59 +0200 In-Reply-To: <837dgpcx1g.fsf@gnu.org> To: Eli Zaretskii , Lars Ingebrigtsen References: <837dgpcx1g.fsf@gnu.org> X-Mailer: Apple Mail (2.3445.104.21) X-CTCH-RefID: str=0001.0A742F22.61167CFE.005F, 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-Rules: X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=Xdb3M7x5 c=1 sm=1 tr=0 a=von4qPfY+hyqc0zmWf0tYQ==:117 a=von4qPfY+hyqc0zmWf0tYQ==:17 a=M51BFTxLslgA:10 a=mDV3o1hIAAAA:8 a=OocQHUDgAAAA:8 a=PmBe4BAdstBwyuMgsZ4A:9 a=CjuIK1q_8ugA:10 a=b3X37vTZZnmG3GshoWUA:9 a=7Zwj6sZBwVKJAoWSPKxL6X1jA+E=:19 a=B2y7HmGcmWMA:10 a=_FVE-zBwftR9WsbkzFJk:22 a=xUZTl98r3Qw_uB5NK3jt:22 X-Origin-Country: SE X-Spam-Score: 1.4 (+) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: 13 aug. 2021 kl. 15.08 skrev Eli Zaretskii : > 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 l [...] Content analysis details: (1.4 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.4 KHOP_HELO_FCRDNS Relay HELO differs from its IP's reverse DNS X-Debbugs-Envelope-To: 50041 Cc: 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) --Apple-Mail=_BFF885C1-13BD-4FED-B1B5-78A08A33D393 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 13 aug. 2021 kl. 15.08 skrev Eli Zaretskii : > 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 : > Should have a :version. Yes it should, thank you! Added. Revised patch attached. --Apple-Mail=_BFF885C1-13BD-4FED-B1B5-78A08A33D393 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=206e3ab0ece0ebf4db1326d8ddf0c7b7e0dd1b0d0f=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|=205=20+++++=0A=20etc/NEWS=20=20=20=20=20=20=20= =20=20=20=20=20=20=20=20|=207=20+++++++=0A=20lisp/cus-theme.el=20=20=20=20= =20=20|=202=20+-=0A=20lisp/font-lock.el=20=20=20=20=20=20|=209=20= +++++++++=0A=204=20files=20changed,=2022=20insertions(+),=201=20= deletion(-)=0A=0Adiff=20--git=20a/doc/lispref/modes.texi=20= b/doc/lispref/modes.texi=0Aindex=20d48c9cc1af..7a651b6390=20100644=0A---=20= a/doc/lispref/modes.texi=0A+++=20b/doc/lispref/modes.texi=0A@@=20-3447,6=20= +3447,11=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=20constructs=20in=20text=20using=20@code{font-lock-doc-face}.=0A= +This=20inherits,=20by=20default,=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..58c76a5f0a=20100644=0A---=20= a/etc/NEWS=0A+++=20b/etc/NEWS=0A@@=20-149,6=20+149,13=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.=20=20By=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..60b6c82676=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,12=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+=20=20= :version=20"28.1"=0A+=20=20:group=20'font-lock-faces)=0A+=0A=20(defface=20= font-lock-keyword-face=0A=20=20=20'((((class=20grayscale)=20(background=20= light))=20:foreground=20"LightGray"=20:weight=20bold)=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=20Git-122.3)=0A=0A= --Apple-Mail=_BFF885C1-13BD-4FED-B1B5-78A08A33D393-- From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 10:13:25 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 14:13:25 +0000 Received: from localhost ([127.0.0.1]:42806 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEXw5-0005aT-Bl for submit@debbugs.gnu.org; Fri, 13 Aug 2021 10:13:25 -0400 Received: from eggs.gnu.org ([209.51.188.92]:42594) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEXw3-0005aH-Fz for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 10:13:24 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:44210) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mEXvy-0004ga-76; Fri, 13 Aug 2021 10:13:18 -0400 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:3699 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEXvv-0006rB-OS; Fri, 13 Aug 2021 10:13:18 -0400 Date: Fri, 13 Aug 2021 17:12:50 +0300 Message-Id: <8335rdcu1p.fsf@gnu.org> From: Eli Zaretskii To: Mattias =?utf-8?Q?Engdeg=C3=A5rd?= In-Reply-To: <1A815899-9854-4042-B4C1-BCF85BF4E794@acm.org> (message from Mattias =?utf-8?Q?Engdeg=C3=A5rd?= on Fri, 13 Aug 2021 16:08:59 +0200) Subject: Re: bug#50041: Add font-lock-doc-markup-face References: <837dgpcx1g.fsf@gnu.org> <1A815899-9854-4042-B4C1-BCF85BF4E794@acm.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 50041 Cc: larsi@gnus.org, 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Mattias Engdegård > 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 10:34:41 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 14:34:41 +0000 Received: from localhost ([127.0.0.1]:42841 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEYGb-0008I5-0E for submit@debbugs.gnu.org; Fri, 13 Aug 2021 10:34:41 -0400 Received: from mail33c50.megamailservers.eu ([91.136.10.43]:39108) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEYGV-0008Hk-N7 for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 10:34:36 -0400 X-Authenticated-User: mattiase@bredband.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1628865269; bh=PIMhyFme8RPslnzIhpp9iWpzvMYtC7AKga3Dx8ObOE8=; h=Subject:From:In-Reply-To:Date:Cc:References:To:From; b=WaLJTMoxKhC6wO4z5cHjT8jEzf0eSB8QyNmrpH3ADX1k92RIYt3kRzck/WSi4RX3F eKWDDjnRkTezdW20Dy5aDuxO9wMBgB3GMRXXBGUeVmkaguMT26CN7Kb9WZUNdRshH1 /UJUM9YfcWlN0CGQPwzi8BXoWt1EOScpgcgklDkw= Feedback-ID: mattiase@acm.or Received: from stanniol.lan (c-b952e353.032-75-73746f71.bbcust.telenor.se [83.227.82.185]) (authenticated bits=0) by mail33c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 17DEYQ8n018984; Fri, 13 Aug 2021 14:34:28 +0000 Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\)) Subject: Re: bug#50041: Add font-lock-doc-markup-face From: =?utf-8?Q?Mattias_Engdeg=C3=A5rd?= In-Reply-To: <8335rdcu1p.fsf@gnu.org> Date: Fri, 13 Aug 2021 16:34:25 +0200 Content-Transfer-Encoding: quoted-printable Message-Id: <5FDD6903-3ECB-4F3E-90D8-FA591A5A143D@acm.org> References: <837dgpcx1g.fsf@gnu.org> <1A815899-9854-4042-B4C1-BCF85BF4E794@acm.org> <8335rdcu1p.fsf@gnu.org> To: Eli Zaretskii X-Mailer: Apple Mail (2.3445.104.21) X-CTCH-RefID: str=0001.0A742F1C.611682F5.003F, 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-Rules: X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=Rbbu9Glv c=1 sm=1 tr=0 a=von4qPfY+hyqc0zmWf0tYQ==:117 a=von4qPfY+hyqc0zmWf0tYQ==:17 a=kj9zAlcOel0A:10 a=M51BFTxLslgA:10 a=mDV3o1hIAAAA:8 a=Q0M6dKJd0JmYDeNnNiMA:9 a=CjuIK1q_8ugA:10 a=_FVE-zBwftR9WsbkzFJk:22 X-Origin-Country: SE X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: 50041 Cc: larsi@gnus.org, 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) 13 aug. 2021 kl. 16.12 skrev Eli Zaretskii : > 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 true iff the dog was already wagged. */ Here, it would be reasonable to set @return, and 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.=20 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 11:57:38 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 15:57:38 +0000 Received: from localhost ([127.0.0.1]:42975 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEZYr-0006KD-Vb for submit@debbugs.gnu.org; Fri, 13 Aug 2021 11:57:38 -0400 Received: from eggs.gnu.org ([209.51.188.92]:32946) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEZYm-0006Jv-QD for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 11:57:32 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:46490) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mEZYh-0005iE-69; Fri, 13 Aug 2021 11:57:23 -0400 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:2141 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEZYf-0008F8-Vc; Fri, 13 Aug 2021 11:57:23 -0400 Date: Fri, 13 Aug 2021 18:57:02 +0300 Message-Id: <83y295banl.fsf@gnu.org> From: Eli Zaretskii To: Mattias =?utf-8?Q?Engdeg=C3=A5rd?= In-Reply-To: <5FDD6903-3ECB-4F3E-90D8-FA591A5A143D@acm.org> (message from Mattias =?utf-8?Q?Engdeg=C3=A5rd?= on Fri, 13 Aug 2021 16:34:25 +0200) Subject: Re: bug#50041: Add font-lock-doc-markup-face References: <837dgpcx1g.fsf@gnu.org> <1A815899-9854-4042-B4C1-BCF85BF4E794@acm.org> <8335rdcu1p.fsf@gnu.org> <5FDD6903-3ECB-4F3E-90D8-FA591A5A143D@acm.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 50041 Cc: larsi@gnus.org, 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Mattias Engdegård > 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 true iff the dog was already wagged. > */ > > Here, it would be reasonable to set @return, and 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 13:42:40 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 17:42:40 +0000 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 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 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 From: =?utf-8?Q?Mattias_Engdeg=C3=A5rd?= Message-Id: <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> Content-Type: multipart/mixed; boundary="Apple-Mail=_07CCCC5B-FDA2-47B2-80E4-BA3685FDCBDD" Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\)) Subject: Re: bug#50041: Add font-lock-doc-markup-face Date: Fri, 13 Aug 2021 19:41:06 +0200 In-Reply-To: <83y295banl.fsf@gnu.org> To: Eli Zaretskii 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> 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-Rules: 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-Spam-Score: 1.4 (+) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: 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? Content analysis details: (1.4 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.4 KHOP_HELO_FCRDNS Relay HELO differs from its IP's reverse DNS X-Debbugs-Envelope-To: 50041 Cc: larsi@gnus.org, 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) --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-- From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 14:32:03 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 18:32:03 +0000 Received: from localhost ([127.0.0.1]:43070 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEbyJ-0001nN-CB for submit@debbugs.gnu.org; Fri, 13 Aug 2021 14:32:03 -0400 Received: from eggs.gnu.org ([209.51.188.92]:57048) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEbyD-0001n7-O9 for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 14:31:57 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:52156) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mEby8-00022P-1L; Fri, 13 Aug 2021 14:31:48 -0400 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:3717 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEby7-0007kW-2b; Fri, 13 Aug 2021 14:31:47 -0400 Date: Fri, 13 Aug 2021 21:31:33 +0300 Message-Id: <83tujtb3i2.fsf@gnu.org> From: Eli Zaretskii To: Mattias =?utf-8?Q?Engdeg=C3=A5rd?= In-Reply-To: <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> (message from Mattias =?utf-8?Q?Engdeg=C3=A5rd?= on Fri, 13 Aug 2021 19:41:06 +0200) Subject: Re: bug#50041: Add font-lock-doc-markup-face 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> <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 50041 Cc: larsi@gnus.org, 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Mattias Engdegård > 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Aug 13 17:24:35 2021 Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 21:24:35 +0000 Received: from localhost ([127.0.0.1]:43143 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEefG-00067Q-SZ for submit@debbugs.gnu.org; Fri, 13 Aug 2021 17:24:34 -0400 Received: from mail1436c50.megamailservers.eu ([91.136.14.36]:37388 helo=mail263c50.megamailservers.eu) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEefA-000675-88 for 50041@debbugs.gnu.org; Fri, 13 Aug 2021 17:24:29 -0400 X-Authenticated-User: mattiase@bredband.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1628889857; bh=+O+z076bda98rB3CNhP/SXGEDyon/3A4nluzDhWhz3A=; h=From:Subject:Date:In-Reply-To:Cc:To:References:From; b=jhRPm/SHz6Rc7sWt+N19NEKJ5Hd3S34qtLazNxDxHkGxanF5oAmV4URHVvdoxvaLV +hue3Ij84IFzV9LLyoKxc9rQT/9neYkhsU4NGX1XryR18PmX2YyxDd04ouQBlRco/g IQFK2nolWmT3Wi22Jp752N+4v41A9sYhJAQbkjGk= Feedback-ID: mattiase@acm.or Received: from stanniol.lan (c-b952e353.032-75-73746f71.bbcust.telenor.se [83.227.82.185]) (authenticated bits=0) by mail263c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 17DLOEVm003540; Fri, 13 Aug 2021 21:24:16 +0000 From: =?utf-8?Q?Mattias_Engdeg=C3=A5rd?= Message-Id: <9A060FF9-242D-47DE-AA4D-D41BFA5779EE@acm.org> Content-Type: multipart/mixed; boundary="Apple-Mail=_13CFC61E-CCD3-4CCE-A881-6CE16CB559D4" Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\)) Subject: Re: bug#50041: Add font-lock-doc-markup-face Date: Fri, 13 Aug 2021 23:24:13 +0200 In-Reply-To: <83tujtb3i2.fsf@gnu.org> To: Eli Zaretskii 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> <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> <83tujtb3i2.fsf@gnu.org> X-Mailer: Apple Mail (2.3445.104.21) X-CTCH-RefID: str=0001.0A742F22.6116E300.0045, 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-Rules: X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=St3uF8G0 c=1 sm=1 tr=0 a=von4qPfY+hyqc0zmWf0tYQ==:117 a=von4qPfY+hyqc0zmWf0tYQ==:17 a=M51BFTxLslgA:10 a=mDV3o1hIAAAA:8 a=1QcKgq9P0uKerFDTY_wA:9 a=CjuIK1q_8ugA:10 a=U1segf-gdD-uHBxTOu8A:9 a=7Zwj6sZBwVKJAoWSPKxL6X1jA+E=:19 a=B2y7HmGcmWMA:10 a=_FVE-zBwftR9WsbkzFJk:22 X-Origin-Country: SE X-Spam-Score: 1.4 (+) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: 13 aug. 2021 kl. 20.31 skrev Eli Zaretskii : > 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 high [...] Content analysis details: (1.4 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.4 KHOP_HELO_FCRDNS Relay HELO differs from its IP's reverse DNS X-Debbugs-Envelope-To: 50041 Cc: larsi@gnus.org, 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) --Apple-Mail=_13CFC61E-CCD3-4CCE-A881-6CE16CB559D4 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 13 aug. 2021 kl. 20.31 skrev Eli Zaretskii : > 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: >=20 > "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. --Apple-Mail=_13CFC61E-CCD3-4CCE-A881-6CE16CB559D4 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=20a4899a0bd18aa5498d9fb66987901d57715be104=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.=0A*=20= lisp/cus-theme.el=20(custom-theme--listed-faces):=20Add=20it=20to=20the=20= list.=0A*=20doc/lispref/modes.texi=20(Faces=20for=20Font=20Lock):=20= Document=20it.=0A*=20etc/NEWS:=20Mention=20it.=0A---=0A=20= doc/lispref/modes.texi=20|=2010=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|=20= 14=20+++++++++++++-=0A=204=20files=20changed,=2031=20insertions(+),=203=20= deletions(-)=0A=0Adiff=20--git=20a/doc/lispref/modes.texi=20= b/doc/lispref/modes.texi=0Aindex=20d48c9cc1af..17eba15660=20100644=0A---=20= a/doc/lispref/modes.texi=0A+++=20b/doc/lispref/modes.texi=0A@@=20-3444,9=20= +3444,17=20@@=20Faces=20for=20Font=20Lock=0A=20=0A=20@item=20= font-lock-doc-face=0A=20@vindex=20font-lock-doc-face=0A-for=20= documentation=20strings=20in=20the=20code.=20=20This=20inherits,=20by=20= default,=20from=0A+for=20documentation=20embedded=20in=20program=20code=20= inside=20specially-formed=0A+comments=20or=20strings.=20=20This=20face=20= inherits,=20by=20default,=20from=0A=20@code{font-lock-string-face}.=0A=20= =0A+@item=20font-lock-doc-markup-face=0A+@vindex=20= font-lock-doc-markup-face=0A+for=20mark-up=20elements=20in=20text=20= using=20@code{font-lock-doc-face}.=0A+It=20is=20typically=20used=20for=20= the=20mark-up=20constructs=20in=20documentation=20embedded=0A+in=20= program=20code,=20following=20conventions=20such=20as=20Haddock,=20= Javadoc=20and=20Doxygen.=0A+This=20face=20inherits,=20by=20default,=20= from=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..c00a62a160=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-2003,7=20= +2006,16=20@@=20font-lock-string-face=0A=20=0A=20(defface=20= font-lock-doc-face=0A=20=20=20'((t=20:inherit=20font-lock-string-face))=0A= -=20=20"Font=20Lock=20mode=20face=20used=20to=20highlight=20= documentation."=0A+=20=20"Font=20Lock=20mode=20face=20used=20to=20= highlight=20documentation=20embedded=20in=20program=20code.=0A+It=20is=20= typically=20used=20for=20special=20documentation=20comments=20or=20= strings."=0A+=20=20:group=20'font-lock-faces)=0A+=0A+(defface=20= font-lock-doc-markup-face=0A+=20=20'((t=20:inherit=20= font-lock-constant-face))=0A+=20=20"Font=20Lock=20mode=20face=20used=20= to=20highlight=20embedded=20documentation=20mark-up.=0A+It=20is=20meant=20= for=20mark-up=20elements=20in=20text=20that=20uses=20= `font-lock-doc-face',=20such=0A+as=20the=20constructs=20of=20Haddock,=20= Javadoc=20and=20similar=20systems."=0A+=20=20:version=20"28.1"=0A=20=20=20= :group=20'font-lock-faces)=0A=20=0A=20(defface=20font-lock-keyword-face=0A= --=20=0A2.21.1=20(Apple=20Git-122.3)=0A=0A= --Apple-Mail=_13CFC61E-CCD3-4CCE-A881-6CE16CB559D4-- From debbugs-submit-bounces@debbugs.gnu.org Sat Aug 14 01:57:14 2021 Received: (at 50041) by debbugs.gnu.org; 14 Aug 2021 05:57:14 +0000 Received: from localhost ([127.0.0.1]:43426 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEmfO-0001gW-03 for submit@debbugs.gnu.org; Sat, 14 Aug 2021 01:57:14 -0400 Received: from eggs.gnu.org ([209.51.188.92]:44374) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEmfI-0001g0-2h for 50041@debbugs.gnu.org; Sat, 14 Aug 2021 01:57:08 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:42976) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mEmfC-00068v-ER; Sat, 14 Aug 2021 01:56:58 -0400 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:2011 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEmfB-0002KA-TH; Sat, 14 Aug 2021 01:56:58 -0400 Date: Sat, 14 Aug 2021 08:56:47 +0300 Message-Id: <83r1ewbmcg.fsf@gnu.org> From: Eli Zaretskii To: Mattias =?utf-8?Q?Engdeg=C3=A5rd?= In-Reply-To: <9A060FF9-242D-47DE-AA4D-D41BFA5779EE@acm.org> (message from Mattias =?utf-8?Q?Engdeg=C3=A5rd?= on Fri, 13 Aug 2021 23:24:13 +0200) Subject: Re: bug#50041: Add font-lock-doc-markup-face 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> <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> <83tujtb3i2.fsf@gnu.org> <9A060FF9-242D-47DE-AA4D-D41BFA5779EE@acm.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 50041 Cc: larsi@gnus.org, 50041@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Mattias Engdegård > 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. From debbugs-submit-bounces@debbugs.gnu.org Sat Aug 14 05:02:04 2021 Received: (at 50041-done) by debbugs.gnu.org; 14 Aug 2021 09:02:04 +0000 Received: from localhost ([127.0.0.1]:43534 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEpYG-0006Mf-Nw for submit@debbugs.gnu.org; Sat, 14 Aug 2021 05:02:04 -0400 Received: from mail1435c50.megamailservers.eu ([91.136.14.35]:36304 helo=mail263c50.megamailservers.eu) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mEpYB-0006ML-Tc for 50041-done@debbugs.gnu.org; Sat, 14 Aug 2021 05:02:00 -0400 X-Authenticated-User: mattiase@bredband.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1628931708; bh=0/O3gHbCKH4pCXtiaT3jmA6ziZiPqQOMgUd53dUNAfw=; h=Subject:From:In-Reply-To:Date:Cc:References:To:From; b=HIYXI5sJW4VkapSTC6hIjMPriABRhSz69bx7RsVosINTQdfHDh1VtOuVkWVq8q/SE rn12qJPP59LUCG9ZHjBqG13PorpOd4FD1yLLBUh3Q5EhN0tT7K8SLyW4HNOkv5FRmC lXKa6Sb6SEyBWEMMo7WRhQP2EtKd82l1rP9Nhoyw= Feedback-ID: mattiase@acm.or Received: from stanniol.lan (c-b952e353.032-75-73746f71.bbcust.telenor.se [83.227.82.185]) (authenticated bits=0) by mail263c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 17E91ktR005726; Sat, 14 Aug 2021 09:01:47 +0000 Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\)) Subject: Re: bug#50041: Add font-lock-doc-markup-face From: =?utf-8?Q?Mattias_Engdeg=C3=A5rd?= In-Reply-To: <83r1ewbmcg.fsf@gnu.org> Date: Sat, 14 Aug 2021 11:01:45 +0200 Content-Transfer-Encoding: 7bit Message-Id: <2A04DC25-3187-4CB4-9414-6F78871EEC03@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> <34CEA0B4-3AE8-4E70-A092-D57341741D33@acm.org> <83tujtb3i2.fsf@gnu.org> <9A060FF9-242D-47DE-AA4D-D41BFA5779EE@acm.org> <83r1ewbmcg.fsf@gnu.org> To: Eli Zaretskii X-Mailer: Apple Mail (2.3445.104.21) X-CTCH-RefID: str=0001.0A742F18.6117867C.0043, 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-Rules: X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=St3uF8G0 c=1 sm=1 tr=0 a=von4qPfY+hyqc0zmWf0tYQ==:117 a=von4qPfY+hyqc0zmWf0tYQ==:17 a=kj9zAlcOel0A:10 a=M51BFTxLslgA:10 a=49v7qfUpYNSXf0-Y1lcA:9 a=CjuIK1q_8ugA:10 X-Origin-Country: SE X-Spam-Score: 1.4 (+) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: Thank you, pushed to master. Content analysis details: (1.4 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.4 KHOP_HELO_FCRDNS Relay HELO differs from its IP's reverse DNS X-Debbugs-Envelope-To: 50041-done Cc: 50041-done@debbugs.gnu.org, Lars Ingebrigtsen X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) Thank you, pushed to master. From unknown Fri Aug 15 14:16:34 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sat, 11 Sep 2021 11:24:06 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator