Re: Regarding outline headings in emacs-lisp libraries

[Jonas Bernoulli]

Jonas Bernoulli <jonas@bernoul.li> writes:

> Let me summarize the conversation so far:
>
> 1. I make some arguments as to why it is better for the sections that
>    contain code to be top-level sections instead of sub-sections of a
>    single top-level section.
>
>    One can of course disagree with those arguments but that has not
>    really happened.  Stefan stated that he ever so slightly prefers
>    the nested approach but also that he is fine with either style.
>
> 2. Eli approves the change as long as we adjust the documentation and
>    rename the "Code:" section to something else because if it does not
>    contain all the code anymore, then keeping the old name would be a
>    misnomer.
>
>    > But after the proposed changes, almost none of the code will be
>    > under "Code:", so the name will be a misnomer, no?
>
> 3. Stefan does not want to rename "Code:" to something else because it
>    is the one bit that in nearly all elisp files.
>
>    > I definitely don't want to rename "Code:" to something else.  It
>    > would be a rather gratuitous change, since "Code:" is basically the
>    > only section that appears in virtually all Elisp files and renaming
>    > it would provide very little concrete benefits.
>
>    Stefan also thinks that what Eli calls a "lie" is just a "very minor
>    cosmetic problem".
>
> Is that what they call a Mexican Standoff?
>
> I think the conversation should be about whether my arguments as to
> *why* we should change the recommended style are sound, but we discuss
> whether "Code:" should be renamed or not.  (I tend to agree with Stefan
> that it {should not / does not have to be} renamed.)  Nothing wrong with
> discussing that detail, but I fear that disagreement about it is what
> will ultimately derail my proposal; not disagreement about the merit of
> my arguments as to why it is preferable to skip one nesting level.
>
>      Jonas

One round of arguments later, I think the above sadly still summarizes
the situation pretty well.

  I have one last argument:

What I have proposed is not some crazy new idea of mine, which may or
may not proof to be useful.  It is already common practice.  I wasn't
even aware that this is controversial.  I have seen so many libraries
that split the code across multiple top-level sections that I though
this was accepted practice (even though I was aware that the tips say
that everything should go within "Code:").

These are the statistics for Emacs itself:

  658 libraries use child sections exclusively.
  730 libraries use sibling sections exclusively.
   36 libraries use both child and sibling sections.

It's about fifty/fifty!

(There are also 22 libraries that lack a "Code:" section and 14 sections
 that lack a "... ends here" footer; and I am ignoring those here.)

(Some sections may only appear to use multiple top-level code sections
 because the use the obsolete method of commenting out parts of functions
 with three semicolons instead of just two.  But even if we generously
 account for that and guess that that affects about a hundred libraries,
 then it still is about fifty/fifty.)

Eli, this is common practice and it has been for years -- decades
probably.  Please consider just accepting the fact that many people like
to use multiple top-level code sections while not minding that a section
named "Code:" exists that does not contain *all* the code.

I think this common practice should be officially allowed by updating
the conventions to say that both forms are acceptable.

     Legalize it!
     Jonas