Re: Regarding outline headings in emacs-lisp libraries

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jonas Bernoulli <jonas@bernoul.li>
>> Date: Tue, 28 Jul 2020 21:18:03 +0200
>> 
>> Is that what they call a Mexican Standoff?
>
> According to https://en.wikipedia.org/wiki/Mexican_standoff,
>
>   A "Mexican standoff" is a confrontation in which no strategy exists
>   that allows any party to achieve victory.
>
> I don't think we are in that situation here, because several exit
> strategies exist:
>
>  . you can disregard my opinion and go with Stefan's
>  . you can disregard Stefan's opinion and go with mine
>  . we can still try reaching some compromise (from my POV I'd like to
>    understand better why renaming "Code" would be a problem; the fact
>    that it's present in every ELisp file doesn't seem to explain that)

I mostly agree, but disregarding either your or Stefan's opinion is not
something I would be comfortable with, so the only option that I saw was
to somehow get one of you to change their mind.

>> 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 don't think there's disagreement about the essence of your proposal,
> that's why we are not talking about it.

Ah good, thanks for clarifying.

The common ground that we are starting from is that we all agree that
the _section title_ "Code:" is a misnomer if it stops containing all
the code.  (Though it still contains _some of_ the code. ;)

Writing the following lines helped me understand my own perspective
better and I am changing my stated position from something like "'Code:'
is good enough to stick to, if only for historic reasons" to "this is a
good name and actually the best name we could possibly come up with".

I primarily think of "Code:" as a section heading and was going to say
that it could also (as in "other people do that") be though of as a
separator, similar to , only to realize that I myself actually think
of it in both ways simultaneously.

The ";;; Code:" line makes a distinction between the code on one side
(and the non-code on the other).  A line "End of X" in the same spot
would serve a similar purpose, but naming X would be much harder.  All
that follows this line is code and all code goes after this line, but
what comes before this line is not the same in all files.  Usually there
is a copyright notice and a permission statement, some header keywords,
and some documentation, but any of these parts could be missing, so X
would not always be the same.

But the other side of the distinction/line is always the same, its the
code.  If we _had_ to pick a name for the non-code side that always
works, then it would be ... "metadata" ... shudder.

Sticking to "Code:" also has practical advantages along the same lines.

Often this section is preceded by "Commentary:".  If that section gets
long, then it may be split into sub-sections.  In other cases it may
be followed by other top-level non-code sections such as "History",
"Install" or "TODO".

There are many reasons why one would prefer to use sibling- instead of,
sub-sections, all that matters here is that there are _legit_ reasons
to have additional top-level non-code sections between "Commentary" and
The Section (Formerly Known as Code).

Whatever alternative name we choose for "Code:", nothing else can so
clearly say "this is the first section that contains code".  Given any
other name it would not be 100% clear whether it contains prose or code,
i.e. whether this line marks the boarder between the prose and the code.

It would be even worse if we did not insist that every library's first
code section must have a certain common name.  In such a scenario, and
when sections are collapsed imagine that "Commentary" is followed by
"Dependencies" -- there is no way of knowing whether "Dependencies" is
a prose section that talks about external required executables and/or
C libraries or if it basically contains a bunch of `require' forms.

     Jonas