From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#9130: Document Lisp mode fontification for strings after :documentation Date: Fri, 18 Dec 2015 17:35:33 +0200 Message-ID: <83oadnwz0a.fsf@gnu.org> References: <83y4cuz3er.fsf@gnu.org> <83wpsez0wr.fsf@gnu.org> <83si32z0hh.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1450458927 1175 80.91.229.3 (18 Dec 2015 17:15:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 18 Dec 2015 17:15:27 +0000 (UTC) Cc: 9130@debbugs.gnu.org To: Shakthi Kannan Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Dec 18 18:15:17 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1a9ycZ-00026R-3f for geb-bug-gnu-emacs@m.gmane.org; Fri, 18 Dec 2015 18:15:11 +0100 Original-Received: from localhost ([::1]:34013 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9ycY-00040N-7G for geb-bug-gnu-emacs@m.gmane.org; Fri, 18 Dec 2015 12:15:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36158) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9yMz-0005RW-Ai for bug-gnu-emacs@gnu.org; Fri, 18 Dec 2015 11:59:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9yMw-0000fi-2L for bug-gnu-emacs@gnu.org; Fri, 18 Dec 2015 11:59:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:48318) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9yMv-0000fe-Tm for bug-gnu-emacs@gnu.org; Fri, 18 Dec 2015 11:59:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1a9yMv-0001Et-Ls for bug-gnu-emacs@gnu.org; Fri, 18 Dec 2015 11:59:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 18 Dec 2015 16:59:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 9130 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-Cc: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.14504579214737 (code B ref -1); Fri, 18 Dec 2015 16:59:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 18 Dec 2015 16:58:41 +0000 Original-Received: from localhost ([127.0.0.1]:55920 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1a9yMa-0001EL-Vx for submit@debbugs.gnu.org; Fri, 18 Dec 2015 11:58:41 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:45076) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1a9yMa-0001E8-3l for submit@debbugs.gnu.org; Fri, 18 Dec 2015 11:58:40 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9yMP-0000c3-Cr for submit@debbugs.gnu.org; Fri, 18 Dec 2015 11:58:34 -0500 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:52857) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9yMP-0000bx-9N for submit@debbugs.gnu.org; Fri, 18 Dec 2015 11:58:29 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38568) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9x3q-0005Af-Ud for bug-gnu-emacs@gnu.org; Fri, 18 Dec 2015 10:35:15 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9x3m-0002sQ-Ut for bug-gnu-emacs@gnu.org; Fri, 18 Dec 2015 10:35:14 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:42420) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9x3m-0002sM-Su; Fri, 18 Dec 2015 10:35:10 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1917 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1a9x3m-0001yC-7w; Fri, 18 Dec 2015 10:35:10 -0500 In-reply-to: (message from Shakthi Kannan on Thu, 17 Dec 2015 22:29:27 +0530) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 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.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:110134 Archived-At: > Date: Thu, 17 Dec 2015 22:29:27 +0530 > From: Shakthi Kannan > Cc: bug-gnu-emacs@gnu.org > > Attached patch with updated manual, NEWS and docstrings: > > * doc/emacs/display.texi > * etc/NEWS > * lisp/emacs-lisp/lisp-mode.el Thanks. Some comments below: > diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi > index a722ec4..73a5112 100644 > --- a/doc/emacs/display.texi > +++ b/doc/emacs/display.texi > @@ -867,6 +867,11 @@ any string or comment. Therefore, you should avoid placing an > open-parenthesis or open-brace in the leftmost column, if it is inside > a string or comment. @xref{Left Margin Paren}, for details. > > +@findex lisp-mode > + Documentation of the form (:documentation ``the doc string'') now > +support fontification in Lisp mode. These forms are used in Common > +Lisp code for CLOS class and slot documentation. After looking at this node and at several other candidates, I concluded that there's no place in any manual which should mention this. In particular, the node in which you made the change is about user-level customizations of font-lock, whereas this new feature cannot be customized on the user level. In any case, please don't say "now" in the manual -- this is appropriate for NEWS entries, which are read once when the user upgrades, but not for a manual which will include the added text from now on. > diff --git a/etc/NEWS b/etc/NEWS > index 2788f5c..2e0ea44 100644 > --- a/etc/NEWS > +++ b/etc/NEWS > @@ -631,7 +631,12 @@ respectively, `show-paren-when-point-inside-paren' or > `show-paren-when-point-in-periphery'. > > ** Lisp mode > + > ++++ > *** Strings after `:documentation' are highlighted as docstrings. Therefore, this should now be marked with "---", not "+++". > diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el > index 9ce0dfd..446afb5 100644 > --- a/lisp/emacs-lisp/lisp-mode.el > +++ b/lisp/emacs-lisp/lisp-mode.el > @@ -486,6 +486,7 @@ This will generate compile-time constants from BINDINGS." > "Default expressions to highlight in Lisp modes.") > > (defun lisp-string-in-doc-position-p (listbeg startpos) > + "Returns true if Lisp string is in docstring position" We use 'nil' and 'non-nil' for false and true. Also, the doc string should explain the meaning of the function arguments. By contrast, you just say "string" and don't explain how that string relates to LISTBEG and STARTPOS. Finally, just say "string", there's no need to add "Lisp" -- this is Lisp code, after all, so every string is a Lisp string. Could you fix the patch along these lines and resubmit, please? Thanks in advance.