From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#42397: [PATCH 00/14] Use outline headings and some cosmetics Date: Fri, 17 Jul 2020 09:29:42 +0300 Message-ID: <83eepak621.fsf@gnu.org> References: <20200716144707.16857-1-jonas@bernoul.li> <4c040cd2-8df0-4761-822f-8cd318ee629e@default> <83blkflboc.fsf@gnu.org> <878sfjpaus.fsf@bernoul.li> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4857"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 42397@debbugs.gnu.org To: Jonas Bernoulli Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Jul 17 08:31:11 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jwJtm-0001Ag-Ot for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 17 Jul 2020 08:31:10 +0200 Original-Received: from localhost ([::1]:49284 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwJtl-0007Vw-S8 for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 17 Jul 2020 02:31:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37318) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwJte-0007Vm-Ji for bug-gnu-emacs@gnu.org; Fri, 17 Jul 2020 02:31:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:44983) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jwJte-0003PF-AH for bug-gnu-emacs@gnu.org; Fri, 17 Jul 2020 02:31:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jwJte-000307-7M for bug-gnu-emacs@gnu.org; Fri, 17 Jul 2020 02:31:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 17 Jul 2020 06:31:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 42397 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 42397-submit@debbugs.gnu.org id=B42397.159496740911466 (code B ref 42397); Fri, 17 Jul 2020 06:31:02 +0000 Original-Received: (at 42397) by debbugs.gnu.org; 17 Jul 2020 06:30:09 +0000 Original-Received: from localhost ([127.0.0.1]:56529 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jwJsn-0002ys-49 for submit@debbugs.gnu.org; Fri, 17 Jul 2020 02:30:09 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:51472) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jwJsj-0002wr-53 for 42397@debbugs.gnu.org; Fri, 17 Jul 2020 02:30:07 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:36498) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwJsc-00033x-Q9; Fri, 17 Jul 2020 02:29:58 -0400 Original-Received: from [176.228.60.248] (port=2162 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jwJsa-0001Z9-P4; Fri, 17 Jul 2020 02:29:58 -0400 In-Reply-To: <878sfjpaus.fsf@bernoul.li> (message from Jonas Bernoulli on Thu, 16 Jul 2020 20:34:51 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:183132 Archived-At: > From: Jonas Bernoulli > Cc: 42397@debbugs.gnu.org > Date: Thu, 16 Jul 2020 20:34:51 +0200 > > > ‘;;;’ > > Comments that start with three semicolons, ‘;;;’, should start at > > the left margin. We use them for comments which should be > > considered a heading by Outline minor mode. By default, comments > > starting with at least three semicolons (followed by a single space > > and a non-whitespace character) are considered headings, comments > > starting with two or fewer are not. Historically, triple-semicolon > > comments have also been used for commenting out lines within a > > function, but this use is discouraged. > > > > When commenting out entire functions, use two semicolons. > > This says that three semicolons are for "headings". > There is no mention of "separators". Right. Unless by "separators" we allude to headings of what the manual calls "major sections of a program", see below. > It seems pretty clear to me that the use of three or more semicolons is > now reserved for (outline) headings. Of course there are also autoload > coolies but those don't have a space after the semicolons. > > Do you still think this has to be discussed on emacs-devel? Not the 3 semicolon issue, no. However, this part might need discussing: > Also note that I don't turn all the sections that contain code and > follow the ";;; Code:" heading into sub-sections of that section. I > don't think the "Comment Tips" are clear on that matter but it seems > to me that they imply that I should do so. Yes, I think that's what the manual says. > If so, then I disagree based on my experience. I don't have a strong opinion on this, but if we agree to do it your way, we should amend the manual. > Seeing this > > ,---- > | ;;; foo.el --- Foo bar baz > | ;;; Commentary:... > | ;;; Code:... > | ;;; foo.el ends here > `---- > > is almost entirely useless (because almost the same for all libraries > that do it like this), whereas > > ,---- > | ;;; foo.el --- Foo bar baz > | ;;; Commentary:... > | ;;; Code:... > | ;;; Options... > | ;;; List Mode... > | ;;; List Commands... > | ;;; Integrations > | ;;; foo.el ends here > `---- > > is very useful in my experience as it instantly gives a quick overview > of how the code is structured etc. But the above seems to say that Options, List Mode, List Commands etc. are on the same level as Code, whereas in reality they are subsections of Code, no? Anyway, like I said: we should make the manual describe our practices. Are you saying that the subsections with 4 semicolons are never actually used in Emacs?