emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Headings and Headlines
@ 2021-07-23 13:32 André A. Gomes
  2021-07-23 13:56 ` Eric S Fraga
                   ` (5 more replies)
  0 siblings, 6 replies; 32+ messages in thread
From: André A. Gomes @ 2021-07-23 13:32 UTC (permalink / raw)
  To: emacs-orgmode

Hi,

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.

If the community finds this valuable, I could prepare a patch.

Thank you.


--
André A. Gomes
"Free Thought, Free World"


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 13:32 Headings and Headlines André A. Gomes
@ 2021-07-23 13:56 ` Eric S Fraga
  2021-07-23 15:43   ` Christopher Dimech
  2021-07-23 14:04 ` Marco Wahl
                   ` (4 subsequent siblings)
  5 siblings, 1 reply; 32+ messages in thread
From: Eric S Fraga @ 2021-07-23 13:56 UTC (permalink / raw)
  To: André A. Gomes; +Cc: emacs-orgmode

I agree that consistency would be good and I also think heading is a
better choice than headline.  The former's definition fits what it means
in org; the latter's is more equivalent to a title than anything else.
-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.6-598-g604bfd
: Latest paper written in org: https://arxiv.org/abs/2106.05096


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 13:32 Headings and Headlines André A. Gomes
  2021-07-23 13:56 ` Eric S Fraga
@ 2021-07-23 14:04 ` Marco Wahl
  2021-07-23 15:03   ` Kaushal Modi
  2021-07-23 14:34 ` Timothy
                   ` (3 subsequent siblings)
  5 siblings, 1 reply; 32+ messages in thread
From: Marco Wahl @ 2021-07-23 14:04 UTC (permalink / raw)
  To: André A. Gomes; +Cc: emacs-orgmode

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.

Agreed.  E.g. no more thinking waste about the question if it is
headline or heading?

> If I had to choose between the two, I'd go with heading.

+1

> If the community finds this valuable, I could prepare a patch.

+1


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 13:32 Headings and Headlines André A. Gomes
  2021-07-23 13:56 ` Eric S Fraga
  2021-07-23 14:04 ` Marco Wahl
@ 2021-07-23 14:34 ` Timothy
  2021-07-23 14:56   ` André A. Gomes
  2021-07-24  2:06 ` Tim Cross
                   ` (2 subsequent siblings)
  5 siblings, 1 reply; 32+ messages in thread
From: Timothy @ 2021-07-23 14:34 UTC (permalink / raw)
  To: André A. Gomes; +Cc: emacs-orgmode


André A. Gomes <andremegafone@gmail.com> writes:

> If the community finds this valuable, I could prepare a patch.

I am certainly of the mind that this would be a worthwhile change :)

--
Timothy


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 14:34 ` Timothy
@ 2021-07-23 14:56   ` André A. Gomes
  2021-07-23 15:39     ` Timothy
  0 siblings, 1 reply; 32+ messages in thread
From: André A. Gomes @ 2021-07-23 14:56 UTC (permalink / raw)
  To: Timothy; +Cc: emacs-orgmode

Timothy <tecosaur@gmail.com> writes:

> I am certainly of the mind that this would be a worthwhile change :)

There's a problem though.  Function names would have to be changed,
which would have to wait for version 10 otherwise we'd ruin backwards
compatibility.

I think there's little sense in changing the wording in the
documentation alone.

More feedback from the maintainers is welcome.


--
André A. Gomes
"Free Thought, Free World"


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 14:04 ` Marco Wahl
@ 2021-07-23 15:03   ` Kaushal Modi
  0 siblings, 0 replies; 32+ messages in thread
From: Kaushal Modi @ 2021-07-23 15:03 UTC (permalink / raw)
  To: Marco Wahl; +Cc: André A. Gomes, emacs-org list

[-- Attachment #1: Type: text/plain, Size: 933 bytes --]

On Fri, Jul 23, 2021 at 10:07 AM Marco Wahl <marcowahlsoft@gmail.com> wrote:

> 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.
>
> Agreed.  E.g. no more thinking waste about the question if it is
> headline or heading?
>

+1

> If I had to choose between the two, I'd go with heading.
>
> +1
>

+1

> If the community finds this valuable, I could prepare a patch.
>
> +1
>

+1

@André

> There's a problem though.  Function names would have to be changed,
> which would have to wait for version 10 otherwise we'd ruin backwards
> compatibility.

It doesn't have to break things drastically. When such changes are made,
you would define function aliases using `define-obsolete-function-alias'.
And then that obsoletion warning is removed after a few years.

[-- Attachment #2: Type: text/html, Size: 1809 bytes --]

^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 14:56   ` André A. Gomes
@ 2021-07-23 15:39     ` Timothy
  0 siblings, 0 replies; 32+ messages in thread
From: Timothy @ 2021-07-23 15:39 UTC (permalink / raw)
  To: André A. Gomes; +Cc: emacs-orgmode


André A. Gomes <andremegafone@gmail.com> writes:

>> I am certainly of the mind that this would be a worthwhile change :)
>
> There's a problem though.  Function names would have to be changed,
> which would have to wait for version 10 otherwise we'd ruin backwards
> compatibility.

I see 61 functions with "headline" and 49 with "heading".
So, a near even split. I think it would be a good idea to consolidate this.

We can always use `define-obsolete-function-alias' and give a few years
for people to shift over.

> I think there's little sense in changing the wording in the
> documentation alone.

Agreed, we should be consistent across the board.

--
Timothy


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Headings and Headlines
  2021-07-23 13:56 ` Eric S Fraga
@ 2021-07-23 15:43   ` Christopher Dimech
  2021-07-23 15:47     ` Timothy
  0 siblings, 1 reply; 32+ messages in thread
From: Christopher Dimech @ 2021-07-23 15:43 UTC (permalink / raw)
  To: Eric S Fraga; +Cc: André A. Gomes, emacs-orgmode

Headline gave an indication that the heading is contained in a single line.

> Sent: Saturday, July 24, 2021 at 1:56 AM
> From: "Eric S Fraga" <e.fraga@ucl.ac.uk>
> To: "André A. Gomes" <andremegafone@gmail.com>
> Cc: emacs-orgmode@gnu.org
> Subject: Re: Headings and Headlines
>
> I agree that consistency would be good and I also think heading is a
> better choice than headline.  The former's definition fits what it means
> in org; the latter's is more equivalent to a title than anything else.
> -- 
> : Eric S Fraga via Emacs 28.0.50, Org release_9.4.6-598-g604bfd
> : Latest paper written in org: https://arxiv.org/abs/2106.05096
> 
>


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 15:43   ` Christopher Dimech
@ 2021-07-23 15:47     ` Timothy
  2021-07-23 15:55       ` Eric S Fraga
  0 siblings, 1 reply; 32+ messages in thread
From: Timothy @ 2021-07-23 15:47 UTC (permalink / raw)
  To: Christopher Dimech; +Cc: André A. Gomes, emacs-orgmode, Eric S Fraga


Christopher Dimech <dimech@gmx.com> writes:

> Headline gave an indication that the heading is contained in a single line.

I feel the need to add that the strongest association with "headline" to
me is newspaper headlines, and I never think of an article having more
than one headline. On the other hand, I don't bat an eye at multiple
headings --- which pushes me towards supporting that as the canonical
term that Org should use.

--
Timothy


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 15:47     ` Timothy
@ 2021-07-23 15:55       ` Eric S Fraga
  0 siblings, 0 replies; 32+ messages in thread
From: Eric S Fraga @ 2021-07-23 15:55 UTC (permalink / raw)
  To: Timothy; +Cc: André A. Gomes, Christopher Dimech, emacs-orgmode

Just for completeness, definitions of both terms from WordNet:

  heading
      n 1: a line of text serving to indicate what the passage below
           it is about; "the heading seemed to have little to do with
           the text" [syn: {heading}, {header}, {head}]
  headline
      n 1: the heading or caption of a newspaper article [syn:
           {headline}, {newspaper headline}]

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.6-598-g604bfd
: Latest paper written in org: https://arxiv.org/abs/2106.05096


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 13:32 Headings and Headlines André A. Gomes
                   ` (2 preceding siblings ...)
  2021-07-23 14:34 ` Timothy
@ 2021-07-24  2:06 ` Tim Cross
  2021-07-24  4:04   ` Tom Gillespie
  2021-07-24 18:56   ` Charles Millar
  2021-07-24 19:23 ` Timothy
  2022-11-13  6:59 ` [RFC] " Ihor Radchenko
  5 siblings, 2 replies; 32+ messages in thread
From: Tim Cross @ 2021-07-24  2:06 UTC (permalink / raw)
  To: emacs-orgmode


André A. Gomes <andremegafone@gmail.com> writes:

> Hi,
>
> 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.
>
> If the community finds this valuable, I could prepare a patch.
>

I think heading is better than headline - to me headline is a line at
the top of the buffer (like a newpaper headline). Note that in addition
to changes in the manual, it will probably be necessary to make changes
to variable and function names in the code. This may require marking
some old names as obsolete and creating aliases to allow a transition to
the new names and avoid breakage etc. 


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-24  2:06 ` Tim Cross
@ 2021-07-24  4:04   ` Tom Gillespie
  2021-07-24 11:49     ` Matt Price
  2021-07-24 18:56   ` Charles Millar
  1 sibling, 1 reply; 32+ messages in thread
From: Tom Gillespie @ 2021-07-24  4:04 UTC (permalink / raw)
  To: emacs-orgmode

I enthusiastically support changing the documentation to use heading.
I use heading in my formal grammar because I have found there are more
ways that it can be modified and remain grammatically correct when
used in english sentences. The internal implementation in elisp still
refers to headlines, but changing the docs would be a good first step.
Best!
Tom


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-24  4:04   ` Tom Gillespie
@ 2021-07-24 11:49     ` Matt Price
  0 siblings, 0 replies; 32+ messages in thread
From: Matt Price @ 2021-07-24 11:49 UTC (permalink / raw)
  To: Tom Gillespie; +Cc: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 604 bytes --]

I don't really have a strong preference for either but I would love to
remove the cognitive load of wondering whether the name is heading or
header!

On Sat., Jul. 24, 2021, 12:04 a.m. Tom Gillespie, <tgbugs@gmail.com> wrote:

> I enthusiastically support changing the documentation to use heading.
> I use heading in my formal grammar because I have found there are more
> ways that it can be modified and remain grammatically correct when
> used in english sentences. The internal implementation in elisp still
> refers to headlines, but changing the docs would be a good first step.
> Best!
> Tom
>
>

[-- Attachment #2: Type: text/html, Size: 889 bytes --]

^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-24  2:06 ` Tim Cross
  2021-07-24  4:04   ` Tom Gillespie
@ 2021-07-24 18:56   ` Charles Millar
  1 sibling, 0 replies; 32+ messages in thread
From: Charles Millar @ 2021-07-24 18:56 UTC (permalink / raw)
  To: emacs-orgmode

On 7/23/21 10:06 PM, Tim Cross wrote:
> 
> André A. Gomes <andremegafone@gmail.com> writes:
> 
>> Hi,
>>
>> 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.
>>
>> If the community finds this valuable, I could prepare a patch.
>>
> 
> I think heading is better than headline - to me headline is a line at
> the top of the buffer (like a newpaper headline). Note that in addition
> to changes in the manual, it will probably be necessary to make changes
> to variable and function names in the code. This may require marking
> some old names as obsolete and creating aliases to allow a transition to
> the new names and avoid breakage etc.
> 

Since org requires outline.el, org.el line 4793, why not follow and 
mirror outline.el conventions?

It appears that outline.el uses
`
	"header" for some early set-up(?) functions and

	"heading" for what appears to provide the outline itself.

Furthermore, "headline" shows up only in comments, and only four or five 
times, at that.

After all, org is an, "Outline-based notes management and organize."


Best,

Charlie Millar


^ permalink raw reply	[flat|nested] 32+ messages in thread

* Re: Headings and Headlines
  2021-07-23 13:32 Headings and Headlines André A. Gomes
                   ` (3 preceding siblings ...)
  2021-07-24  2:06 ` Tim Cross
@ 2021-07-24 19:23 ` Timothy
  2022-11-13  6:59 ` [RFC] " Ihor Radchenko
  5 siblings, 0 replies; 32+ messages in thread
From: Timothy @ 2021-07-24 19:23 UTC (permalink / raw)
  To: André A. Gomes; +Cc: emacs-orgmode


André A. Gomes <andremegafone@gmail.com> writes:

> If the community finds this valuable, I could prepare a patch.

I think at this point the community view is pretty clearly in favour of
consolidating "headlines" to "headings".

I think at this stage a patch would be warranted. Should you still be
happy to make one that would be great, otherwise I might try whipping
one up.

--
Timothy


^ permalink raw reply	[flat|nested] 32+ messages in thread

* [RFC] Re: Headings and Headlines
  2021-07-23 13:32 Headings and Headlines André A. Gomes
                   ` (4 preceding siblings ...)
  2021-07-24 19:23 ` Timothy
@ 2022-11-13  6:59 ` Ihor Radchenko
  2022-11-13 21:10   ` Rudolf Adamkovič
                     ` (3 more replies)
  5 siblings, 4 replies; 32+ messages in thread
From: Ihor Radchenko @ 2022-11-13  6:59 UTC (permalink / raw)
  To: André A. Gomes, Bastien, Timothy; +Cc: emacs-orgmode

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?

-- 
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-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 21:10   ` Rudolf Adamkovič
@ 2022-11-14  4:36     ` Ihor Radchenko
  0 siblings, 0 replies; 32+ messages in thread
From: Ihor Radchenko @ 2022-11-14  4:36 UTC (permalink / raw)
  To: Rudolf Adamkovič
  Cc: André A. Gomes, Bastien, Timothy, emacs-orgmode

Rudolf Adamkovič <salutis@me.com> 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 <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-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-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: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-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

* Re: [RFC] Re: Headings and Headlines
  2022-11-27  3:33           ` Ihor Radchenko
@ 2022-11-27 10:32             ` Bastien
  0 siblings, 0 replies; 32+ messages in thread
From: Bastien @ 2022-11-27 10:32 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: André A. Gomes, Timothy, emacs-orgmode

Ihor Radchenko <yantar92@posteo.net> 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


^ permalink raw reply	[flat|nested] 32+ messages in thread

end of thread, other threads:[~2022-11-27 10:33 UTC | newest]

Thread overview: 32+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-07-23 13:32 Headings and Headlines André A. Gomes
2021-07-23 13:56 ` Eric S Fraga
2021-07-23 15:43   ` Christopher Dimech
2021-07-23 15:47     ` Timothy
2021-07-23 15:55       ` Eric S Fraga
2021-07-23 14:04 ` Marco Wahl
2021-07-23 15:03   ` Kaushal Modi
2021-07-23 14:34 ` Timothy
2021-07-23 14:56   ` André A. Gomes
2021-07-23 15:39     ` Timothy
2021-07-24  2:06 ` Tim Cross
2021-07-24  4:04   ` Tom Gillespie
2021-07-24 11:49     ` Matt Price
2021-07-24 18:56   ` Charles Millar
2021-07-24 19:23 ` Timothy
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
2022-11-19 13:46   ` Bastien Guerry
2022-11-19 14:34     ` Vikas Rawal
2022-11-19 15:03       ` Timothy
2022-11-19 15:54         ` Bastien Guerry
2022-11-19 15:54   ` Bastien
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
2022-11-20  5:53         ` Ihor Radchenko
2022-11-27  3:33           ` Ihor Radchenko
2022-11-27 10:32             ` Bastien

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).