From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Van L Newsgroups: gmane.emacs.bugs Subject: bug#35595: subr.el Commentary + Code sections Date: Thu, 9 May 2019 09:31:19 +1000 Message-ID: <581B9446-AFEC-4418-927C-15A89815368A@scratch.space> References: <20190505232719.1375-1-van@scratch.space> <85pnouxds6.fsf@gmail.com> <4A02DA2E-E698-4F25-BB66-FC7C2365FBDD@scratch.space> <87woj1jhk1.fsf@gmail.com> Mime-Version: 1.0 (Mac OS X Mail 9.3 \(3124\)) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="95380"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 35595@debbugs.gnu.org To: Noam Postavsky Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu May 09 01:32:12 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hOW2m-000Ogf-5t for geb-bug-gnu-emacs@m.gmane.org; Thu, 09 May 2019 01:32:12 +0200 Original-Received: from localhost ([127.0.0.1]:45086 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hOW2l-0000Wl-1r for geb-bug-gnu-emacs@m.gmane.org; Wed, 08 May 2019 19:32:11 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:49250) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hOW2e-0000Wg-H3 for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 19:32:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hOW2d-0000sZ-AC for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 19:32:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:48996) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hOW2c-0000pp-0f for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 19:32:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hOW2b-0005kB-QM for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 19:32:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Van L Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 08 May 2019 23:32:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35595 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 35595-submit@debbugs.gnu.org id=B35595.155735829122043 (code B ref 35595); Wed, 08 May 2019 23:32:01 +0000 Original-Received: (at 35595) by debbugs.gnu.org; 8 May 2019 23:31:31 +0000 Original-Received: from localhost ([127.0.0.1]:34307 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hOW27-0005jS-Fx for submit@debbugs.gnu.org; Wed, 08 May 2019 19:31:31 -0400 Original-Received: from relay3-d.mail.gandi.net ([217.70.183.195]:45795) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hOW24-0005jI-2e for 35595@debbugs.gnu.org; Wed, 08 May 2019 19:31:29 -0400 X-Originating-IP: 123.243.243.121 Original-Received: from epi.local (123-243-243-121.tpgi.com.au [123.243.243.121]) (Authenticated sender: van@scratch.space) by relay3-d.mail.gandi.net (Postfix) with ESMTPSA id 4830760011; Wed, 8 May 2019 23:31:23 +0000 (UTC) In-Reply-To: <87woj1jhk1.fsf@gmail.com> X-Mailer: Apple Mail (2.3124) 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: 209.51.188.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" Xref: news.gmane.org gmane.emacs.bugs:158965 Archived-At: > Noam Postavsky writes: >=20 > Sorry, I was a bit terse above. I was quoting (elisp) Library = Headers, > where it says >=20 > `;;; Commentary:' > This begins introductory comments that explain how the library > works. It should come right after the copying permissions, > terminated by a `Change Log', `History' or `Code' comment = line. > This text is used by the Finder package, so it should make = sense > in that context. >=20 > [...] >=20 > `;;; Code:' > This begins the actual code of the program. >=20 > So I'm not sure if the "Beware..." comment belongs under the > "Commentary" header, perhaps it's better put under the "Code:" header, > like the comment about declare-function. And perhaps it makes no = sense > to add these headers in the first place, since subr.el isn't exactly a > library. I have no idea how important the "Beware... " comment is. An important = enough comment IMO should go on oneline topline WARNING as a wrinkle to = be ironed out in time. Perhaps an autoconfiguring function generates the = final file that fits ascii-only or wider charsets after environment = detection in the early build staging. IMO a familiar pattern of = headlines makes sense in any file in or out of the lib. Thanks. I'll = make sure I take a first look at (elisp) for norms/conventions before = sending what I may mistaken as a fix for what I see is missing.=