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

Previous Next

Full log

View this message in rfc822 format

From: Noam Postavsky <npostavs <at> gmail.com>
To: Van L <van <at> scratch.space>
Cc: 35595 <at> debbugs.gnu.org
Subject: 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.

Previous Next

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