Re: Regarding outline headings in emacs-lisp libraries

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Richard Stallman <rms@gnu.org>
>> Date: Fri, 31 Jul 2020 22:53:46 -0400
>> Cc: emacs-devel@gnu.org
>> 
>> I suggest we allow two ways of structuring the code into sections.
>> 
>> 1. A single top-level section called "Code", which can have subsections.
>> 
>> 2. Multiple top-level sections, none called just "Code", but their
>> names should contain the word "Code".
>
> Both possibilities are fine with me.
>
> However, AFAIU Jonas didn't like 1, and both Stefan and Jonas didn't
> like 2 (although the way 2 was discussed, we didn't consider having
> "Code" in each of the top-level sections, so maybe this will make the
> difference).

I find that even less appealing.

While I would prefer if we could just stick to "Code:", I am not
fundamentally opposed to using some other name.

I think we should not enforce some new standard name for the first code
section.  "Dependencies" would often make sense, and we could suggest
that name but when it doesn't make sense, then people should be free to
use something else.

I have mentioned that if we don't enforce some common name for the first
code section, then one could no longer determine with 100% accuracy
which section is the first code section from the section headings alone.
That is a bit unfortunate, but not really a big deal IMO.

Stefan seems to dislike the idea of doing away with the "Code:" name
more strongly than I do.  Maybe we could grandfather that name as a
compromise?  I.e. existing libraries could keep using "Code:" but new
libraries and when splitting up an existing library into sections for
the first time, then some other name should be picked.

     Peace,
     Jonas