From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#50041: Add font-lock-doc-markup-face Date: Fri, 13 Aug 2021 21:31:33 +0300 Message-ID: <83tujtb3i2.fsf@gnu.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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4057"; mail-complaints-to="usenet@ciao.gmane.io" Cc: larsi@gnus.org, 50041@debbugs.gnu.org To: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Aug 13 20:33:11 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 1mEbzT-0000rM-CR for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 13 Aug 2021 20:33:11 +0200 Original-Received: from localhost ([::1]:32994 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mEbzR-0006gt-NZ for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 13 Aug 2021 14:33:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:45416) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mEbzK-0006gk-P5 for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 14:33:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:59757) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mEbzK-0002rM-47 for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 14:33:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mEbzJ-0001ox-UR for bug-gnu-emacs@gnu.org; Fri, 13 Aug 2021 14:33:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 13 Aug 2021 18:33:01 +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.16288795236930 (code B ref 50041); Fri, 13 Aug 2021 18:33:01 +0000 Original-Received: (at 50041) by debbugs.gnu.org; 13 Aug 2021 18:32:03 +0000 Original-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 Original-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 Original-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 Original-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 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) 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:211786 Archived-At: > 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.