From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Noam Postavsky Newsgroups: gmane.emacs.bugs Subject: bug#35595: subr.el Commentary + Code sections Date: Wed, 08 May 2019 07:45:34 -0400 Message-ID: <87woj1jhk1.fsf@gmail.com> References: <20190505232719.1375-1-van@scratch.space> <85pnouxds6.fsf@gmail.com> <4A02DA2E-E698-4F25-BB66-FC7C2365FBDD@scratch.space> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="131234"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.2 (gnu/linux) Cc: 35595@debbugs.gnu.org To: Van L Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed May 08 13:46:13 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hOL1Y-000Y0U-Rf for geb-bug-gnu-emacs@m.gmane.org; Wed, 08 May 2019 13:46:13 +0200 Original-Received: from localhost ([127.0.0.1]:35388 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hOL1X-0005UH-D5 for geb-bug-gnu-emacs@m.gmane.org; Wed, 08 May 2019 07:46:11 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:42922) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hOL1P-0005U0-NV for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 07:46:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hOL1O-0005GB-PZ for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 07:46:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46933) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hOL1O-0005G2-Lx for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 07:46:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hOL1O-0007yc-Bu for bug-gnu-emacs@gnu.org; Wed, 08 May 2019 07:46:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Noam Postavsky Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 08 May 2019 11:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35595 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 35595-submit@debbugs.gnu.org id=B35595.155731594430633 (code B ref 35595); Wed, 08 May 2019 11:46:02 +0000 Original-Received: (at 35595) by debbugs.gnu.org; 8 May 2019 11:45:44 +0000 Original-Received: from localhost ([127.0.0.1]:60477 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hOL16-0007y0-8R for submit@debbugs.gnu.org; Wed, 08 May 2019 07:45:44 -0400 Original-Received: from mail-it1-f170.google.com ([209.85.166.170]:35894) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hOL14-0007xl-EF for 35595@debbugs.gnu.org; Wed, 08 May 2019 07:45:43 -0400 Original-Received: by mail-it1-f170.google.com with SMTP id o190so3435436itc.1 for <35595@debbugs.gnu.org>; Wed, 08 May 2019 04:45:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=u2ryb9edBY7gmBiRrV+4H36r1WG2hTYzfeZEefGtF7s=; b=hvwomlc4mdX1gU4q4VUaOz8O+6H0jM+cqq/sQb/M1A3o92F3xuUuOfxqJYdXScAJ/D 1IZQhKYUO4XnZkaBfP7ZQLlJGgrucZgGbXuGae+QCe6qVCjqAW1X0O6ghxHfpF1Rbt3L DQXM0Rr5MfjDmLfzGKJYOR79sV4eFWsiBa25v+1nIvEa1z4LDRlTUgy2qfotTe1AYj8q 11Aks4qgj1joU9OIpdkqG+1hcitz8VrrD7W0nasEMl589/JOyIgXGd8lPiAczR6Cz6c1 mZGkx+KYAS9erREUhqA2VAXJh4GGGV/I91vfGCr8SiRSTQnjRwF1libSaFRazpx23B1e PbzA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=u2ryb9edBY7gmBiRrV+4H36r1WG2hTYzfeZEefGtF7s=; b=E430idvndprEnigUsjXSl2RNBzJbVRuz1yGASpafKuRmqSKPdPLeAKOOYxFADH73vb BVZLBVG01mJDhwWsia/0UJQsacXDmxgZLt2QnVaCJ5+VsuAL0h/GOhkS3zy9OIAVRQ9o V5/zngLSqbsYywNZw5b3/wtRDMb8ShZ3e/+DbD+wT43zaE3Km6t0YnuMAgxLhWGLktRO mifJkWzLsKO2H7/1xmIvFNmAc/rS98ecRxfOhot2e7eWVuVxfxyra2P9UDusz5Hp8HkS aTvj/2eeikmCf6O24CQ+40OvLnec2wRVXoogCo53cM9cmbNfaHHecelvKXXJlLEZknVT W3gA== X-Gm-Message-State: APjAAAVl/iGbZ9H8/7gIerH8jKUlodX8mGIfwHQBlBneso9pPvrgnjjU 1UGroUcYeQEYrUwWmNG55iNdd3zS X-Google-Smtp-Source: APXvYqzHSangcHx1HBouxWQrkr//+WnL/yPAwurmuh8FqMozG2IizrxRprNNS4efzTuguoCernndVw== X-Received: by 2002:a24:2901:: with SMTP id p1mr3366577itp.54.1557315936207; Wed, 08 May 2019 04:45:36 -0700 (PDT) Original-Received: from minid (cbl-45-2-119-34.yyz.frontiernetworks.ca. [45.2.119.34]) by smtp.gmail.com with ESMTPSA id i24sm6177120ioh.60.2019.05.08.04.45.35 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 08 May 2019 04:45:35 -0700 (PDT) In-Reply-To: <4A02DA2E-E698-4F25-BB66-FC7C2365FBDD@scratch.space> (Van L.'s message of "Wed, 8 May 2019 13:40:23 +1000") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:158933 Archived-At: Van L 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.