GNU bug report logs - #35595
subr.el Commentary + Code sections

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 35595 in the body.
You can then email your comments to 35595 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] ; update
Date: Mon,  6 May 2019 09:27:19 +1000

---
 lisp/subr.el | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lisp/subr.el b/lisp/subr.el
index f68f9dd419..41040e53b5 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -22,9 +22,12 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
+;;; Commentary:
+
 ;; Beware: while this file has tag `utf-8', before it's compiled, it gets
 ;; loaded as "raw-text", so non-ASCII chars won't work right during bootstrap.
 
+;;; Code:
 
 ;; declare-function's args use &rest, not &optional, for compatibility
 ;; with byte-compile-macroexpand-declare-function.
-- 
2.20.1

Message #8 received at 35595 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> gmail.com
To: Van L <van <at> scratch.space>
Cc: 35595 <at> debbugs.gnu.org
Subject: Re: bug#35595: subr.el Commentary + Code sections
Date: Tue, 07 May 2019 15:31:05 -0400

retitle 35595 subr.el Commentary + Code sections
quit

Van L <van <at> scratch.space> writes:

> +++ b/lisp/subr.el
> @@ -22,9 +22,12 @@
>  ;; You should have received a copy of the GNU General Public License
>  ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
>  
> +;;; Commentary:
> +
>  ;; Beware: while this file has tag `utf-8', before it's compiled, it gets
>  ;; loaded as "raw-text", so non-ASCII chars won't work right during bootstrap.

Not sure if this really qualifies as "introductory comments that explain
how the library works."  Also, where it says "has tag `utf-8'" what is
it referring to?  A coding cookie that was since removed perhaps?
  
> +;;; Code:
>  
>  ;; declare-function's args use &rest, not &optional, for compatibility
>  ;; with byte-compile-macroexpand-declare-function.

Message #13 received at 35595 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: npostavs <at> gmail.com
Cc: 35595 <at> debbugs.gnu.org
Subject: Re: bug#35595: subr.el Commentary + Code sections
Date: Wed, 8 May 2019 13:40:23 +1000

> On 8 May 2019, at 05:31, npostavs <at> gmail.com wrote:
> 
>> ;; Beware: while this file has tag `utf-8', before it's compiled, it gets
>> ;; loaded as "raw-text", so non-ASCII chars won't work right during bootstrap.
> 
> Not sure if this really qualifies as "introductory comments that explain
> how the library works."  Also, where it says "has tag `utf-8'" what is
> it referring to?  A coding cookie that was since removed perhaps?

To quote from htdp.org/prologue:

...>8

… comments are intended for human readers. It is a “back channel” of 
communication between the author of the program and
all of its future readers to convey information about the
program.

...>8

*Magic Numbers* …

Message #16 received at 35595 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Van L <van <at> scratch.space>
Cc: 35595 <at> debbugs.gnu.org
Subject: Re: bug#35595: subr.el Commentary + Code sections
Date: Wed, 08 May 2019 07:45:34 -0400

Van L <van <at> scratch.space> writes:

>> On 8 May 2019, at 05:31, npostavs <at> gmail.com wrote:
>> 
>>> ;; Beware: while this file has tag `utf-8', before it's compiled, it gets
>>> ;; loaded as "raw-text", so non-ASCII chars won't work right during bootstrap.
>> 
>> Not sure if this really qualifies as "introductory comments that explain
>> how the library works."  Also, where it says "has tag `utf-8'" what is
>> it referring to?  A coding cookie that was since removed perhaps?
>
> To quote from htdp.org/prologue:

Sorry, I was a bit terse above.  I was quoting (elisp) Library Headers,
where it says

    `;;; 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.

    [...]

    `;;; Code:'
         This begins the actual code of the program.

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.

Message #19 received at 35595 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 35595 <at> debbugs.gnu.org
Subject: Re: bug#35595: subr.el Commentary + Code sections
Date: Thu, 9 May 2019 09:31:19 +1000

> Noam Postavsky writes:
> 
> Sorry, I was a bit terse above.  I was quoting (elisp) Library Headers,
> where it says
> 
>    `;;; 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.
> 
>    [...]
> 
>    `;;; Code:'
>         This begins the actual code of the program.
> 
> 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.

Message #22 received at 35595 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: npostavs <at> gmail.com
Cc: Van L <van <at> scratch.space>, 35595 <at> debbugs.gnu.org
Subject: Re: bug#35595: subr.el Commentary + Code sections
Date: Sun, 23 Jun 2019 19:05:10 +0200

npostavs <at> gmail.com writes:

>> +;;; Commentary:
>> +
>>  ;; Beware: while this file has tag `utf-8', before it's compiled, it gets
>>  ;; loaded as "raw-text", so non-ASCII chars won't work right during
>> bootstrap.
>
> Not sure if this really qualifies as "introductory comments that explain
> how the library works."  Also, where it says "has tag `utf-8'" what is
> it referring to?  A coding cookie that was since removed perhaps?

Yup:

commit 166a6556d0ec9926035aa2bce3dc0b0827b447ef
Author: Dmitry Gutov <dgutov <at> yandex.ru>
Date:   Tue Sep 29 01:39:14 2015 +0300

    ; Remove extraneous "coding: utf-8" specifications in Elisp files

So the comment is wrong, and I'll just apply the Code bit from Van's patch.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.