Re: [RFC] Re: Headings and Headlines

[Tim Cross]

Ihor Radchenko <yantar92@posteo.net> writes:

> André A. Gomes <andremegafone@gmail.com> writes:
>
>> The project's documentation refers to headings and headlines as
>> synonyms.  Relying on a single definition would be beneficial.  If I had
>> to choose between the two, I'd go with heading.
>
> I've been looking into changing all the instances of "headline" to
> "heading" and I ran into a serious issue: We use `headline' _symbol_ in
> multiple places in the code.
>
> Most importantly, org-element.el uses element type `headline' to parse
> headings. We cannot easily change this symbol for backwards
> compatibility reasons.
>
> I'm afraid that a complete switch to use "heading" everywhere consistently
> is not possible without backwards-incompatible change. I know for sure
> that changing `headline' element to `heading' element type will break
> important packages like org-roam. And there is no good way to work
> around this. We cannot make symbol aliases in Elisp in scenarios like
> (memq (org-element-type ...) '(headline inlinetask)).
>
> I came to the conclusion that it will, in fact, be easier to change all
> things to use "headline" -- all the instances of "heading" in Org code
> are in function names, variable names, and docstrings. All can be
> changed using obsolete aliases.
>
> On the other hand, overwhelming feedback in this thread is the
> opposite -- change "headline" to "heading".
>
> Maybe others have better ideas how to deal with `headline' symbol issue?

I think consistency is the highest priority. Most people preferred
heading, but that was based on the assumption adopting one or the other
was of roughly equal complexity.

Given we cannot change headline to heading without introducing backwards
and external compatibility issues, I would favour just changing to
headline and documenting what deadline defines/means.