Re: Regarding outline headings in emacs-lisp libraries

[Thorsten Jolitz]

Jonas Bernoulli <jonas@bernoul.li> writes:

Hallo,

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

Quite some time ago when writing outshine.el (with outorg.el and
navi.el) I saw a lot of strange behaviour wrt comments and outlining in
Emacs core elisp files, and wrote quite an extensive analysis about it:

https://lists.gnu.org/archive/html/emacs-devel/2013-10/msg00112.html

Maybe that is still of some interest today. 
I critizised that ;;;Code: convention too in that mail, since it leads
to extremely unbalanced outlining. But during that discussion in 2013, it was
concluded too that a change is not worth the pain. 

I just wanted to mention this, since this old thread from 2013 might
already be forgetten. I apologize, if it has been mentioned already and
I did not read the current thread from the start. 

-- 
cheers,
Thorsten