From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jonas Bernoulli Newsgroups: gmane.emacs.bugs Subject: bug#42397: [PATCH 00/14] Use outline headings and some cosmetics Date: Thu, 16 Jul 2020 20:34:51 +0200 Message-ID: <878sfjpaus.fsf@bernoul.li> References: <20200716144707.16857-1-jonas@bernoul.li> <4c040cd2-8df0-4761-822f-8cd318ee629e@default> <83blkflboc.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6949"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 42397@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jul 16 20:38:55 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 1jw8mT-0001dQ-Ux for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 16 Jul 2020 20:38:53 +0200 Original-Received: from localhost ([::1]:35028 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jw8jH-0000R7-Ek for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 16 Jul 2020 14:35:35 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58848) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jw8ik-0000Qz-37 for bug-gnu-emacs@gnu.org; Thu, 16 Jul 2020 14:35:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:44454) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jw8ij-0007Mq-QJ for bug-gnu-emacs@gnu.org; Thu, 16 Jul 2020 14:35:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jw8ij-0004bI-M6 for bug-gnu-emacs@gnu.org; Thu, 16 Jul 2020 14:35:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Jonas Bernoulli Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 16 Jul 2020 18:35:01 +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.159492449617671 (code B ref 42397); Thu, 16 Jul 2020 18:35:01 +0000 Original-Received: (at 42397) by debbugs.gnu.org; 16 Jul 2020 18:34:56 +0000 Original-Received: from localhost ([127.0.0.1]:56000 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jw8ie-0004ax-AE for submit@debbugs.gnu.org; Thu, 16 Jul 2020 14:34:56 -0400 Original-Received: from mail.hostpark.net ([212.243.197.30]:50320) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jw8ib-0004am-CN for 42397@debbugs.gnu.org; Thu, 16 Jul 2020 14:34:54 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by mail.hostpark.net (Postfix) with ESMTP id F1022160BA; Thu, 16 Jul 2020 20:34:51 +0200 (CEST) X-Virus-Scanned: by Hostpark/NetZone Mailprotection at hostpark.net Original-Received: from mail.hostpark.net ([127.0.0.1]) by localhost (mail1.hostpark.net [127.0.0.1]) (amavisd-new, port 10124) with ESMTP id ogZbCSGHY9wB; Thu, 16 Jul 2020 20:34:51 +0200 (CEST) Original-Received: from customer (localhost [127.0.0.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-256) server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mail.hostpark.net (Postfix) with ESMTPSA id B36F2160AE; Thu, 16 Jul 2020 20:34:51 +0200 (CEST) In-Reply-To: <83blkflboc.fsf@gnu.org> 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:183106 Archived-At: Eli Zaretskii writes: >> Date: Thu, 16 Jul 2020 08:12:24 -0700 (PDT) >> From: Drew Adams >>=20 >> I thought we had a pretty standard header format. I thought so too... and that I was following them. Maybe it is just that our respective selective memory focuses on a different aspect? >> I've been respecting that for decades in my own >> libraries. Now it's changed? > > You have a point there. > > Jonas, please compare what you propose with the tips we have in the > "Comment Tips" node of the ELisp manual, and seed if there's any > discrepancies. If there are, I think we should discuss first (on > emacs-devel). After reading (info "(elisp) Comment Tips") again, I think I remembered correctly. Quoting the ;;; entry in full: > =E2=80=98;;;=E2=80=99 > Comments that start with three semicolons, =E2=80=98;;;=E2=80=99, sh= ould 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. >=20 > When commenting out entire functions, use two semicolons. This says that three semicolons are for "headings". There is no mention of "separators". And the only node to older conventions is about using three semicolons to comment out parts of functions. 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? Normally I don't divide the ";;; Commentary:" section into multiple sub-sections. In this particular case I have done so because (a) it is long (b) splitting into sibling sections, as was done before, seems wrong to me. 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. If so, then I disagree based on my experience. 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. Ps: I have written a few packages to make `outline-minor-mode' a bit nicer: mainly `bicycle', but also `outline-minor-faces' and `backline'. https://github.com/tarsius/bicycle https://github.com/tarsius/outline-minor-faces https://github.com/tarsius/backline