GNU bug report logs -
#35595
subr.el Commentary + Code sections
Previous Next
Reported by: Van L <van <at> scratch.space>
Date: Sun, 5 May 2019 23:38:02 UTC
Severity: wishlist
Tags: fixed, patch
Fixed in version 27.1
Done: Lars Ingebrigtsen <larsi <at> gnus.org>
Bug is archived. No further changes may be made.
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.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#35595
; Package
emacs
.
(Sun, 05 May 2019 23:38:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Van L <van <at> scratch.space>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Sun, 05 May 2019 23:38:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
---
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
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#35595
; Package
emacs
.
(Tue, 07 May 2019 19:32:01 GMT)
Full text and
rfc822 format available.
Message #8 received at 35595 <at> debbugs.gnu.org (full text, mbox):
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.
Changed bug title to 'subr.el Commentary + Code sections' from '[PATCH] ; update'
Request was from
npostavs <at> gmail.com
to
control <at> debbugs.gnu.org
.
(Tue, 07 May 2019 19:32:02 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#35595
; Package
emacs
.
(Wed, 08 May 2019 03:41:01 GMT)
Full text and
rfc822 format available.
Message #13 received at 35595 <at> debbugs.gnu.org (full text, mbox):
> 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* …
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#35595
; Package
emacs
.
(Wed, 08 May 2019 11:46:02 GMT)
Full text and
rfc822 format available.
Message #16 received at 35595 <at> debbugs.gnu.org (full text, mbox):
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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#35595
; Package
emacs
.
(Wed, 08 May 2019 23:32:01 GMT)
Full text and
rfc822 format available.
Message #19 received at 35595 <at> debbugs.gnu.org (full text, mbox):
> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#35595
; Package
emacs
.
(Sun, 23 Jun 2019 17:06:02 GMT)
Full text and
rfc822 format available.
Message #22 received at 35595 <at> debbugs.gnu.org (full text, mbox):
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
Added tag(s) fixed.
Request was from
Lars Ingebrigtsen <larsi <at> gnus.org>
to
control <at> debbugs.gnu.org
.
(Sun, 23 Jun 2019 17:09:02 GMT)
Full text and
rfc822 format available.
bug marked as fixed in version 27.1, send any further explanations to
35595 <at> debbugs.gnu.org and Van L <van <at> scratch.space>
Request was from
Lars Ingebrigtsen <larsi <at> gnus.org>
to
control <at> debbugs.gnu.org
.
(Sun, 23 Jun 2019 17:09:02 GMT)
Full text and
rfc822 format available.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Mon, 22 Jul 2019 11:24:11 GMT)
Full text and
rfc822 format available.
This bug report was last modified 4 years and 271 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.