all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#35595: [PATCH] ; update
@ 2019-05-05 23:27 Van L
  2019-05-07 19:31 ` bug#35595: subr.el Commentary + Code sections npostavs
  0 siblings, 1 reply; 6+ messages in thread
From: Van L @ 2019-05-05 23:27 UTC (permalink / raw)
  To: 35595

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






^ permalink raw reply related	[flat|nested] 6+ messages in thread

* bug#35595: subr.el Commentary + Code sections
  2019-05-05 23:27 bug#35595: [PATCH] ; update Van L
@ 2019-05-07 19:31 ` npostavs
  2019-05-08  3:40   ` Van L
  2019-06-23 17:05   ` Lars Ingebrigtsen
  0 siblings, 2 replies; 6+ messages in thread
From: npostavs @ 2019-05-07 19:31 UTC (permalink / raw)
  To: Van L; +Cc: 35595

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.





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#35595: subr.el Commentary + Code sections
  2019-05-07 19:31 ` bug#35595: subr.el Commentary + Code sections npostavs
@ 2019-05-08  3:40   ` Van L
  2019-05-08 11:45     ` Noam Postavsky
  2019-06-23 17:05   ` Lars Ingebrigtsen
  1 sibling, 1 reply; 6+ messages in thread
From: Van L @ 2019-05-08  3:40 UTC (permalink / raw)
  To: npostavs; +Cc: 35595


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






^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#35595: subr.el Commentary + Code sections
  2019-05-08  3:40   ` Van L
@ 2019-05-08 11:45     ` Noam Postavsky
  2019-05-08 23:31       ` Van L
  0 siblings, 1 reply; 6+ messages in thread
From: Noam Postavsky @ 2019-05-08 11:45 UTC (permalink / raw)
  To: Van L; +Cc: 35595

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.





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#35595: subr.el Commentary + Code sections
  2019-05-08 11:45     ` Noam Postavsky
@ 2019-05-08 23:31       ` Van L
  0 siblings, 0 replies; 6+ messages in thread
From: Van L @ 2019-05-08 23:31 UTC (permalink / raw)
  To: Noam Postavsky; +Cc: 35595


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




^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#35595: subr.el Commentary + Code sections
  2019-05-07 19:31 ` bug#35595: subr.el Commentary + Code sections npostavs
  2019-05-08  3:40   ` Van L
@ 2019-06-23 17:05   ` Lars Ingebrigtsen
  1 sibling, 0 replies; 6+ messages in thread
From: Lars Ingebrigtsen @ 2019-06-23 17:05 UTC (permalink / raw)
  To: npostavs; +Cc: Van L, 35595

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





^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2019-06-23 17:05 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-05-05 23:27 bug#35595: [PATCH] ; update Van L
2019-05-07 19:31 ` bug#35595: subr.el Commentary + Code sections npostavs
2019-05-08  3:40   ` Van L
2019-05-08 11:45     ` Noam Postavsky
2019-05-08 23:31       ` Van L
2019-06-23 17:05   ` Lars Ingebrigtsen

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.