Re: [RFC] Re: Headings and Headlines

[Bastien]

Ihor Radchenko  writes:

> I looked into this further and I do not think that it is a good idea to
> make this change in the coming release. Renaming some things is very too
> easy to get wrong and cause failures.

Yes, there is absolutely no rush for this.

-- 
 Bastien

Re: [RFC] Re: Headings and Headlines

[Ihor Radchenko]

Ihor Radchenko  writes:

> Bastien  writes:
>
>>> 2. We introduce a new constant: org-element-heading-type, defaulting to
>>>'headline
>>> 3. We use the new constant instead of 'headline element type symbol
>>> 4. We announce loudly that 'headline will be deprecated in favour of the
>>>new constant
>>> 5. Few years later, we change the org-element-heading-type value to
>>>'heading
>>
>> I think this is okay too, though `org-element-heading-type' might not
>> be explicit enough: what about `org-element-heading-type-symbol'?
>
> Agree. I was leaning towards having "symbol" in the name as well after
> sleeping with the idea.

I looked into this further and I do not think that it is a good idea to
make this change in the coming release. Renaming some things is very too
easy to get wrong and cause failures.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [RFC] Re: Headings and Headlines

[Ihor Radchenko]

Bastien  writes:

>> 2. We introduce a new constant: org-element-heading-type, defaulting to
>>'headline
>> 3. We use the new constant instead of 'headline element type symbol
>> 4. We announce loudly that 'headline will be deprecated in favour of the
>>new constant
>> 5. Few years later, we change the org-element-heading-type value to
>>'heading
>
> I think this is okay too, though `org-element-heading-type' might not
> be explicit enough: what about `org-element-heading-type-symbol'?

Agree. I was leaning towards having "symbol" in the name as well after
sleeping with the idea.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [RFC] Re: Headings and Headlines

[Bastien]

Ihor Radchenko  writes:

> The best idea I can come up with is the following:
>
> 1. We replace headline -> heading where it is safe

Yes, let's do this.

> 2. We introduce a new constant: org-element-heading-type, defaulting to
>'headline
> 3. We use the new constant instead of 'headline element type symbol
> 4. We announce loudly that 'headline will be deprecated in favour of the
>new constant
> 5. Few years later, we change the org-element-heading-type value to
>'heading

I think this is okay too, though `org-element-heading-type' might not
be explicit enough: what about `org-element-heading-type-symbol'?

-- 
 Bastien

Re: [RFC] Re: Headings and Headlines

[Ihor Radchenko]

Tim Cross  writes:

> I think we are needlessly complicating this. We are talking about the
> use of a term in an internal code base. While I would agree heading is
> more correct, I don't think it is such a big issue to use headline if
> that make the transition to a consistent usage easier. When it comes to
> code, I think consistency trumps correctness.

Changing documentation means changing function symbols.
Changing function symbols means changing the code.
Changing the code should not reduce code readability, which is of
paramount importance to keep new contributions coming.

That's why I also consider code consistency important.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [RFC] Re: Headings and Headlines

[Vikas Rawal]

>
>
>
> I think we are needlessly complicating this. We are talking about the
> use of a term in an internal code base. While I would agree heading is
> more correct, I don't think it is such a big issue to use headline if
> that make the transition to a consistent usage easier. When it comes to
> code, I think consistency trumps correctness.
>
>
I agree. I think the original post was about inconsistency in the
documentation. We should just correct the documentation, use the word
heading consistently throughout, and mention at a prominent place that the
headline symbol is used in the code to parse headings. There is nothing
wrong with that.

Re: [RFC] Re: Headings and Headlines

[Tim Cross]

Ihor Radchenko  writes:

> Bastien  writes:
>
>> Ihor Radchenko  writes:
>>
>>> 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)).
>>
>> We cannot make symbol aliases in Elisp but maybe we can support both
>> symbols for a transitory period during which we warn third-part devs
>> about replacing the deprecated 'headline symbol?
>
> The best idea I can come up with is the following:
>
> 1. We replace headline -> heading where it is safe
> 2. We introduce a new constant: org-element-heading-type, defaulting to
>'headline
> 3. We use the new constant instead of 'headline element type symbol
> 4. We announce loudly that 'headline will be deprecated in favour of the
>new constant
> 5. Few years later, we change the org-element-heading-type value to
>'heading
>
>>> 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.
>>
>> Given Vikas and Tim feedback, I would rather move forward by changing
>> "headline" to "heading" *where it does not break anything* then see if
>> the proposed scenario above is workable.
>>
>> In this case, I believe it's better to be partially correct (heading
>> where possible) than to be consistently wrong (headline everywhere) :)
>>
>> WDYT?
>
> I tried, but it will be confusing when we talk about Org elements.
> Phrases like "Headline element" now make sense as they correspond to the
> element type. Changing to "Heading element" while keeping the actual
> element as (headline ...) sounds extremely confusing.
>
> That said, we may do what I proposed above and then use
> "`org-element-heading-type' element". Somewhat cumbersome, but at least
> less confusing.

I think we are needlessly complicating this. We are talking about the
use of a term in an internal code base. While I would agree heading is
more correct, I don't think it is such a big issue to use headline if
that make the transition to a consistent usage easier. When it comes to
code, I think consistency trumps correctness.

If agreement is not possible, my second vote would be for the status
quo. Leave it as it is and focus on more important issues that have a
real impact on users. 

Re: [RFC] Re: Headings and Headlines

[Ihor Radchenko]

Bastien  writes:

> Ihor Radchenko  writes:
>
>> 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)).
>
> We cannot make symbol aliases in Elisp but maybe we can support both
> symbols for a transitory period during which we warn third-part devs
> about replacing the deprecated 'headline symbol?

The best idea I can come up with is the following:

1. We replace headline -> heading where it is safe
2. We introduce a new constant: org-element-heading-type, defaulting to
   'headline
3. We use the new constant instead of 'headline element type symbol
4. We announce loudly that 'headline will be deprecated in favour of the
   new constant
5. Few years later, we change the org-element-heading-type value to
   'heading

>> 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.
>
> Given Vikas and Tim feedback, I would rather move forward by changing
> "headline" to "heading" *where it does not break anything* then see if
> the proposed scenario above is workable.
>
> In this case, I believe it's better to be partially correct (heading
> where possible) than to be consistently wrong (headline everywhere) :)
>
> WDYT?

I tried, but it will be confusing when we talk about Org elements.
Phrases like "Headline element" now make sense as they correspond to the
element type. Changing to "Heading element" while keeping the actual
element as (headline ...) sounds extremely confusing.

That said, we may do what I proposed above and then use
"`org-element-heading-type' element". Somewhat cumbersome, but at least
less confusing.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [RFC] Re: Headings and Headlines

[Bastien Guerry]

Timothy  writes:

> Unfortunately I’m completely with you (and previous comments here). The 
> meaning
> of “headline” is closer to “title” than “heading”. A document can have 
> multiple
> headings but only a single headline (which is specifically the line at the 
> top,
> e.g. “Newspaper headline”).

Ah, thanks a lot for this very clear explanation!

-- 
 Bastien

Re: [RFC] Re: Headings and Headlines

[Bastien]

Ihor Radchenko  writes:

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

We cannot make symbol aliases in Elisp but maybe we can support both
symbols for a transitory period during which we warn third-part devs
about replacing the deprecated 'headline symbol?

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

Given Vikas and Tim feedback, I would rather move forward by changing
"headline" to "heading" *where it does not break anything* then see if
the proposed scenario above is workable.

In this case, I believe it's better to be partially correct (heading
where possible) than to be consistently wrong (headline everywhere) :)

WDYT?

-- 
 Bastien

Re: [RFC] Re: Headings and Headlines

[Timothy]

Hi Vikas,

> I think, from a linguistic perspective, “heading” and “subheading” are more
> appropriate than “headline” and “subheadline”.

Unfortunately I’m completely with you (and previous comments here). The meaning
of “headline” is closer to “title” than “heading”. A document can have multiple
headings but only a single headline (which is specifically the line at the top,
e.g. “Newspaper headline”).

As Ihor points out though, from a compat perspective, a change to “heading” may
be intractable. This gives me rather mixed feelings, as I’m of a similar mind
regarding the org-element headline->heading change being too problematic, but
settling on the less accurate term seems quite undesirable too, and doesn’t sit
well with me.

All the best,
Timothy

-- 
Timothy (‘tecosaur’/‘TEC’), Org mode contributor.
Learn more about Org mode at .
Support Org development at ,
or support my work at .

Re: [RFC] Re: Headings and Headlines

[Vikas Rawal]

On Sat, 19 Nov 2022 at 19:17, Bastien Guerry  wrote:

> Ihor Radchenko  writes:
>
> > I came to the conclusion that it will, in fact, be easier to change all
> > things to use "headline"
>
> FWIW, I'm fine with such a change.  I'm not a native english speaker,
> but a "headline" sounds like it's a one-line heading, so it's okay.
>
>
I think, from a linguistic perspective, "heading" and "subheading" are more
appropriate than "headline" and "subheadline".

Vikas

Re: [RFC] Re: Headings and Headlines

[Bastien Guerry]

Ihor Radchenko  writes:

> I came to the conclusion that it will, in fact, be easier to change all
> things to use "headline"

FWIW, I'm fine with such a change.  I'm not a native english speaker,
but a "headline" sounds like it's a one-line heading, so it's okay.

-- 
 Bastien

Re: [RFC] Re: Headings and Headlines

[Tim Cross]

Ihor Radchenko  writes:

> André A. Gomes  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.

Re: [RFC] Re: Headings and Headlines

[Ihor Radchenko]

Rudolf Adamkovič  writes:

> P.S. We should also harmonize `evaluate' and `execute'; I can never tell
> which one to look for when completing.

Please open a separate thread. I am not sure which one is better.
For "execute" vs. "evaluate" we just need to rename function/variable
names and replace in text/docstrings.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [RFC] Re: Headings and Headlines

[Rudolf Adamkovič]

Ihor Radchenko  writes:

> I came to the conclusion that it will, in fact, be easier to change
> all things to use "headline" -- [...]

And by "easier" you mean "possible", right?  :)

> On the other hand, overwhelming feedback in this thread is the
> opposite -- change "headline" to "heading".

If Emacs Lisp cannot create aliases for symbols, well then it does not
matter what we all like.  Ha-ha!  Still, better to use a "less pretty"
(but precise) term than to have inconsistent naming across APIs.

P.S. We should also harmonize `evaluate' and `execute'; I can never tell
which one to look for when completing.

Rudy
-- 
"It is no paradox to say that in our most theoretical moods we may be
nearest to our most practical applications."
-- Alfred North Whitehead, 1861-1947

Rudolf Adamkovič  [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

[RFC] Re: Headings and Headlines

[Ihor Radchenko]

André A. Gomes  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?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at