From: Van L <van@scratch.space>
To: Noam Postavsky <npostavs@gmail.com>
Cc: 35595@debbugs.gnu.org
Subject: bug#35595: subr.el Commentary + Code sections
Date: Thu, 9 May 2019 09:31:19 +1000 [thread overview]
Message-ID: <581B9446-AFEC-4418-927C-15A89815368A@scratch.space> (raw)
In-Reply-To: <87woj1jhk1.fsf@gmail.com>
> 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.
next prev parent reply other threads:[~2019-05-08 23:31 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2019-06-23 17:05 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=581B9446-AFEC-4418-927C-15A89815368A@scratch.space \
--to=van@scratch.space \
--cc=35595@debbugs.gnu.org \
--cc=npostavs@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.