[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 838a1a3 15/15: Update section heading conventions for libraries
From: |
Jonas Bernoulli |
Subject: |
master 838a1a3 15/15: Update section heading conventions for libraries |
Date: |
Thu, 13 Aug 2020 05:36:57 -0400 (EDT) |
branch: master
commit 838a1a313caf9695a518c69b553abc1389b22495
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>
Update section heading conventions for libraries
* 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 5b09b2c..6292054 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -918,29 +918,56 @@ values. It is much better to convert such comments to
documentation
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
- master updated (804a0e8 -> 838a1a3), Jonas Bernoulli, 2020/08/13
- master 7ba7591 02/15: ; * lisp/epg.el (epg-signature-to-string): Tiny refactor., Jonas Bernoulli, 2020/08/13
- master 562bbd0 03/15: ; * lisp/epg.el (epg-no-data-reason-alist): Fix typo in message., Jonas Bernoulli, 2020/08/13
- master 9446088 01/15: ; * lisp/epg.el (epg-signature-to-string): Use cl-case., Jonas Bernoulli, 2020/08/13
- master cb58a3c 09/15: * test/src/emacs-module-tests.el: Use proper outline headings., Jonas Bernoulli, 2020/08/13
- master e118b79 10/15: * lisp/obsolete/longlines.el: Use proper outline headings., Jonas Bernoulli, 2020/08/13
- master b88e5b4 12/15: * lisp/font-lock.el: Split the Commentary into subsections., Jonas Bernoulli, 2020/08/13
- master c5b9d2a 04/15: Split EasyPG libraries into outline sections, Jonas Bernoulli, 2020/08/13
- master 838a1a3 15/15: Update section heading conventions for libraries,
Jonas Bernoulli <=
- master 2d93342 13/15: * lisp/font-lock.el: No longer use headings as end of section markers., Jonas Bernoulli, 2020/08/13
- master aaa69dc 06/15: * lisp/progmodes/compile.el: Remove unnecessary comments., Jonas Bernoulli, 2020/08/13
- master 7cb029d 14/15: ; * lisp/emacs-lisp/autoload.el: Begin summary line with three semicolons., Jonas Bernoulli, 2020/08/13
- master 5409732 11/15: * lisp/net/imap.el: Use proper outline headings, Jonas Bernoulli, 2020/08/13
- master 0bc9e7b 05/15: Merge two conditions and fix indentation, Jonas Bernoulli, 2020/08/13
- master d59c018 07/15: ; * lisp/whitespace.el: Capitalize "Code" section heading., Jonas Bernoulli, 2020/08/13
- master 9d267db 08/15: * lisp/mail/smtpmail.el: Use outline headings., Jonas Bernoulli, 2020/08/13