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 v2 16/16] Update section heading conventions for libraries Date: Mon, 10 Aug 2020 23:14:30 +0200 Message-ID: <20200810211430.22502-17-jonas@bernoul.li> References: <20200716144707.16857-1-jonas@bernoul.li> <20200810211430.22502-1-jonas@bernoul.li> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="18743"; mail-complaints-to="usenet@ciao.gmane.io" To: 42397@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Aug 10 23:23:00 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 1k5FFz-0004lu-Ku for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 10 Aug 2020 23:22:59 +0200 Original-Received: from localhost ([::1]:35766 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5FFy-0008TG-Dp for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 10 Aug 2020 17:22:58 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37522) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5F9K-0003LS-MS for bug-gnu-emacs@gnu.org; Mon, 10 Aug 2020 17:16:06 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:54373) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5F9K-000644-9P for bug-gnu-emacs@gnu.org; Mon, 10 Aug 2020 17:16:06 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1k5F9K-0007ZY-5W for bug-gnu-emacs@gnu.org; Mon, 10 Aug 2020 17:16:06 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Jonas Bernoulli Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 10 Aug 2020 21:16:06 +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.159709415529015 (code B ref 42397); Mon, 10 Aug 2020 21:16:06 +0000 Original-Received: (at 42397) by debbugs.gnu.org; 10 Aug 2020 21:15:55 +0000 Original-Received: from localhost ([127.0.0.1]:37677 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k5F98-0007Xu-Rg for submit@debbugs.gnu.org; Mon, 10 Aug 2020 17:15:55 -0400 Original-Received: from mail.hostpark.net ([212.243.197.30]:56222) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k5F97-0007Xn-DU for 42397@debbugs.gnu.org; Mon, 10 Aug 2020 17:15:53 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by mail.hostpark.net (Postfix) with ESMTP id CB3F816B2A; Mon, 10 Aug 2020 23:15:52 +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 ZULUrxF0aBax; Mon, 10 Aug 2020 23:15:52 +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 X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mail.hostpark.net (Postfix) with ESMTPSA id 939AC15FD0; Mon, 10 Aug 2020 23:15:52 +0200 (CEST) X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200810211430.22502-1-jonas@bernoul.li> 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:184600 Archived-At: * doc/lispref/tips.texi (Comment Tips): Update information on section headings to reflect common usage. Previously the tips stated that if the code is split up into multiple sections, then that should be done by splitting up the ";;; Code:" section into multiple sub-sections. However about half the libraries in Emacs instead use multiple top-level sections. We update the tips (aka conventions) to allow this common usage, but because it is awkward if there is a section named "Code", which contains only some of the code instead of all of it, we now recommend that that section should be empty in this case. We cannot just give up on the "Code:" section/heading because that is an old convention that is followed be nearly every library and because it is likely that there are some utilities out there that depend on its presence. This was discussed in https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00444.html https://lists.gnu.org/archive/html/emacs-devel/2020-08/msg00001.html --- doc/lispref/tips.texi | 65 ++++++++++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 19 deletions(-) diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 5b09b2ccea..6292054d30 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -918,29 +918,56 @@ Comment Tips strings, though. @item ;;; -Comments that start with three semicolons, @samp{;;;}, 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. - -@item ;;;; -Comments that start with four (or more) semicolons, @samp{;;;;}, -should be aligned to the left margin and are used for headings of -major sections of a program. For example: + +Comments that start with three (or more) semicolons, @samp{;;;}, +should start at the left margin. We use them for comments that 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 section 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 in +favor of using just two semicolons. This also applies when commenting +out entire functions; when doing that use two semicolons as well.) + +Three semicolons are used for top-level sections, four for +sub-sections, five for sub-sub-sections and so on. + +Typically libraries have at least four top-level sections. For +example when the bodies of all of these sections are hidden: @smallexample -;;;; The kill ring +@group +;;; backquote.el --- implement the ` Lisp construct... +;;; Commentary:... +;;; Code:... +;;; backquote.el ends here +@end group @end smallexample -If you wish to have sub-headings under these heading, use more -semicolons to nest these sub-headings. +(In a sense the last line is not a section heading as it must +never be followed by any text; after all it marks the end of the +file.) + +For longer libraries it is advisable to split the code into multiple +sections. This can be done by splitting the @samp{Code:} section into +multiple sub-sections. Even though that was the only recommended +approach for a long time, many people have chosen to use multiple +top-level code sections instead. You may chose either style. + +Using multiple top-level code sections has the advanatage that it +avoids introducing an additional nesting level but it also means that +the section named @samp{Code} does not contain all the code, which is +awkward. To avoid that, you should put no code at all inside that +section; that way it can be considered a seperator instead of a +section heading. + +Finally, we recommend that you don't end headings with a colon or any +other punctuation for that matter. For historic reasons the +@samp{Code:} and @samp{Commentary:} headings end with a colon, but we +recommend that you don't do the same for other headings anyway. + @end table @noindent -- 2.28.0