Re: Regarding outline headings in emacs-lisp libraries

[Jonas Bernoulli]

Jonas Bernoulli <jonas@bernoul.li> writes:

> I think we will have to wait for more feedback then.  We would probably
> want to hear from more than one person (me) that uses this in a way that
> is even affected by whether we nest more or less.

No protests so far so here is what I would like to use to replace the
last two items in (info "(elisp)Comment Tips"):

‘;;;’ and more
     Comments that start with three (or more) semicolons, ‘;;;’, 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:

          ;;; backquote.el --- implement the ` Lisp construct...
          ;;; Commentary:...
          ;;; Code:...
          ;;; backquote.el ends here

     (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.)

     Historically, we recommended that all sections that contain code
     should be subsections of the ‘;;; Code:’ section, but because
     that needlessly introduces an additional nesting level we now
     recommend that use top-level sections for all the major code
     sections of the library.  The ‘;;; Code:’ section itself should
     be used for the ‘require’ forms and for other such "front
     matter".

     Finally, we recommend that you don't end headings with a colon or
     any other punctuation for that matter.  For historic reasons the
     ‘;;; Code:’ and ‘;;; Commentary:’ headings end with a colon, but
     we recommend that you don't do the same for other headings anyway.

Personally I would also recommend that people use a "back matter"
section similar to the "front matter" section that is ";;; Code:", but
I fear my preferred heading for that, ";;; _", might not find too many
fans.  But then again, I might be wrong, what do you think about ending
with this instead:

          ;;; backquote.el ends here

     Historically, we recommended that all sections that contain code
     should be subsections of the ‘;;; Code:’ section, but because
     that needlessly introduces an additional nesting level we now
     recommend that use top-level sections for all the major code
     sections of the library.

     The ‘;;; Code:’ section itself should be used for the ‘require’
     forms and for other such "front matter".

     If you would like to analogously place the ‘provide’ form and other
     "back matter" in their own section, then do not abuse the ";;; FILE
     ends here" line for that purpose.  In a sense that is not a heading
     because it must never be followed by any text; after all its
     purpose is to mark the very end of the file.  We recommend that you
     use just ‘;;; _’ as the heading of the "back matter" section.

     Finally, we recommend that you don't end headings with a colon or
     any other punctuation for that matter.  For historic reasons the
     ‘;;; Code:’ and ‘;;; Commentary:’ headings end with a colon, but
     we recommend that you don't do the same for other headings anyway.