* Re: [RFC] Re: Headings and Headlines
2022-11-13 6:59 ` [RFC] " Ihor Radchenko
@ 2022-11-13 21:10 ` Rudolf Adamkovič
2022-11-14 4:36 ` Ihor Radchenko
2022-11-16 22:16 ` Tim Cross
` (2 subsequent siblings)
3 siblings, 1 reply; 32+ messages in thread
From: Rudolf Adamkovič @ 2022-11-13 21:10 UTC (permalink / raw)
To: Ihor Radchenko, André A. Gomes, Bastien, Timothy; +Cc: emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> 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č <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-13 6:59 ` [RFC] " Ihor Radchenko
2022-11-13 21:10 ` Rudolf Adamkovič
@ 2022-11-16 22:16 ` Tim Cross
2022-11-19 13:46 ` Bastien Guerry
2022-11-19 15:54 ` Bastien
3 siblings, 0 replies; 32+ messages in thread
From: Tim Cross @ 2022-11-16 22:16 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: André A. Gomes, Bastien, Timothy, emacs-orgmode
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.
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-13 6:59 ` [RFC] " Ihor Radchenko
2022-11-13 21:10 ` Rudolf Adamkovič
2022-11-16 22:16 ` Tim Cross
@ 2022-11-19 13:46 ` Bastien Guerry
2022-11-19 14:34 ` Vikas Rawal
2022-11-19 15:54 ` Bastien
3 siblings, 1 reply; 32+ messages in thread
From: Bastien Guerry @ 2022-11-19 13:46 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: André A. Gomes, Timothy, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> 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
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 13:46 ` Bastien Guerry
@ 2022-11-19 14:34 ` Vikas Rawal
2022-11-19 15:03 ` Timothy
0 siblings, 1 reply; 32+ messages in thread
From: Vikas Rawal @ 2022-11-19 14:34 UTC (permalink / raw)
To: Bastien Guerry
Cc: Ihor Radchenko, André A. Gomes, Timothy, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 499 bytes --]
On Sat, 19 Nov 2022 at 19:17, Bastien Guerry <bzg@gnu.org> wrote:
> Ihor Radchenko <yantar92@posteo.net> 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
[-- Attachment #2: Type: text/html, Size: 1033 bytes --]
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 14:34 ` Vikas Rawal
@ 2022-11-19 15:03 ` Timothy
2022-11-19 15:54 ` Bastien Guerry
0 siblings, 1 reply; 32+ messages in thread
From: Timothy @ 2022-11-19 15:03 UTC (permalink / raw)
To: Vikas Rawal
Cc: Bastien Guerry, Ihor Radchenko, André A. Gomes, Timothy,
emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1055 bytes --]
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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/tec>.
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 15:03 ` Timothy
@ 2022-11-19 15:54 ` Bastien Guerry
0 siblings, 0 replies; 32+ messages in thread
From: Bastien Guerry @ 2022-11-19 15:54 UTC (permalink / raw)
To: Timothy; +Cc: Vikas Rawal, Ihor Radchenko, André A. Gomes, emacs-orgmode
Timothy <orgmode@tec.tecosaur.net> 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
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-13 6:59 ` [RFC] " Ihor Radchenko
` (2 preceding siblings ...)
2022-11-19 13:46 ` Bastien Guerry
@ 2022-11-19 15:54 ` Bastien
2022-11-19 16:01 ` Ihor Radchenko
3 siblings, 1 reply; 32+ messages in thread
From: Bastien @ 2022-11-19 15:54 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: André A. Gomes, Timothy, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> 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
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 15:54 ` Bastien
@ 2022-11-19 16:01 ` Ihor Radchenko
2022-11-19 23:04 ` Tim Cross
2022-11-20 5:46 ` Bastien
0 siblings, 2 replies; 32+ messages in thread
From: Ihor Radchenko @ 2022-11-19 16:01 UTC (permalink / raw)
To: Bastien; +Cc: André A. Gomes, Timothy, emacs-orgmode
Bastien <bzg@gnu.org> writes:
> Ihor Radchenko <yantar92@posteo.net> 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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 16:01 ` Ihor Radchenko
@ 2022-11-19 23:04 ` Tim Cross
2022-11-20 0:56 ` Vikas Rawal
2022-11-20 5:45 ` Ihor Radchenko
2022-11-20 5:46 ` Bastien
1 sibling, 2 replies; 32+ messages in thread
From: Tim Cross @ 2022-11-19 23:04 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Bastien, André A. Gomes, Timothy, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Bastien <bzg@gnu.org> writes:
>
>> Ihor Radchenko <yantar92@posteo.net> 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.
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 23:04 ` Tim Cross
@ 2022-11-20 0:56 ` Vikas Rawal
2022-11-20 5:45 ` Ihor Radchenko
1 sibling, 0 replies; 32+ messages in thread
From: Vikas Rawal @ 2022-11-20 0:56 UTC (permalink / raw)
To: Tim Cross
Cc: Ihor Radchenko, Bastien, André A. Gomes, Timothy,
emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 649 bytes --]
>
>
>
> 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.
[-- Attachment #2: Type: text/html, Size: 918 bytes --]
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 23:04 ` Tim Cross
2022-11-20 0:56 ` Vikas Rawal
@ 2022-11-20 5:45 ` Ihor Radchenko
1 sibling, 0 replies; 32+ messages in thread
From: Ihor Radchenko @ 2022-11-20 5:45 UTC (permalink / raw)
To: Tim Cross; +Cc: Bastien, André A. Gomes, Timothy, emacs-orgmode
Tim Cross <theophilusx@gmail.com> 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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-19 16:01 ` Ihor Radchenko
2022-11-19 23:04 ` Tim Cross
@ 2022-11-20 5:46 ` Bastien
2022-11-20 5:53 ` Ihor Radchenko
1 sibling, 1 reply; 32+ messages in thread
From: Bastien @ 2022-11-20 5:46 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: André A. Gomes, Timothy, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> 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
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-20 5:46 ` Bastien
@ 2022-11-20 5:53 ` Ihor Radchenko
2022-11-27 3:33 ` Ihor Radchenko
0 siblings, 1 reply; 32+ messages in thread
From: Ihor Radchenko @ 2022-11-20 5:53 UTC (permalink / raw)
To: Bastien; +Cc: André A. Gomes, Timothy, emacs-orgmode
Bastien <bzg@gnu.org> 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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [RFC] Re: Headings and Headlines
2022-11-20 5:53 ` Ihor Radchenko
@ 2022-11-27 3:33 ` Ihor Radchenko
2022-11-27 10:32 ` Bastien
0 siblings, 1 reply; 32+ messages in thread
From: Ihor Radchenko @ 2022-11-27 3:33 UTC (permalink / raw)
To: Bastien; +Cc: André A. Gomes, Timothy, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Bastien <bzg@gnu.org> 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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 32+ messages in thread