bug#35595: [PATCH] ; update

bug#35595: [PATCH] ; update

[Van L]

---
 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

bug#35595: subr.el Commentary + Code sections

[npostavs]

retitle 35595 subr.el Commentary + Code sections
quit

Van L <van@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.

bug#35595: subr.el Commentary + Code sections

[Van L]

> 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:

...>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* …

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.

bug#35595: subr.el Commentary + Code sections

[Van L]

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

bug#35595: subr.el Commentary + Code sections

[Lars Ingebrigtsen]

npostavs@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@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