bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Eli Zaretskii <eliz@gnu.org>]

> From: Jonas Bernoulli <jonas@bernoul.li>
> 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?