bug#35595: subr.el Commentary + Code sections

[Noam Postavsky]

Van L <van@scratch.space> writes:

>> On 8 May 2019, at 05:31, npostavs@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.