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

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Thu, 16 Jul 2020 08:12:24 -0700 (PDT)
>> From: Drew Adams <drew.adams@oracle.com>
>> 
>> 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:

> ‘;;;’
>      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".

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