Re: [RFC] Document level property drawer

["Gustav Wikström" <gustav@whil.se>]

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

Hi Adam,



> > In no way is this a major, breaking change.  No document you have

> > today will break by the introduction of this.  The only thing changing

> > is if you *actively* create a document level property drawer and

> > choose to enter a property there that you already have defined in the

> > same document, using a property keyword.

>

> There is a bigger picture which you seem to be ignoring.



No I'm not ignoring any bigger picture. Hence the RFC which I'm asking

for comments about. So far a couple of positive remarks and your

comments on the other end of the spectrum.



> Org is distributed with Emacs itself.  Emacs versions are long-lived.

> People use old Emacs and Org versions for years, because few people

> build and install Emacs themselves, so most users use the versions

> included with their OS or other distributions.



Yes.



> Your proposed change would introduce a major change in the way document

> properties are interpreted.  This means that the same document, when

> used on Emacs/Org versions before and after this change, would be

> interpreted differently.  That's breaking forward-compatibility between

> versions, ones which will be in the wild for years.  That decision

> should not be taken lightly.



No, not really. Here we disagree again. I already interpret the

documents as an outline. And it seems others agree with me on that as

well. Your interpretation may be different but I fail to see where the

documentation agrees with your sentiment. The fact that some commands

that works for the outline doesn't work before the first headline has

been a shortcoming for a long time. I don't think that shortcoming is

something to continue to strive for.



Forward compatibility should indeed be taken into account. I don't

think the argument to stop this change due to breaking forward

compatibility is that strong though. If I as a user choose to use new

features, I agree to also use new software. As a package author you

can continue to rely on Org element and assume the user understands

that relation. If your packages creates property keywords today you

can continue to do so, or consider upgrading your package to depend on

Org mode 9.3 and start using the new feature to more easily insert

properties into a document level property drawer. If you do that you

of course have to mark your dependency to Org mode 9.3 as well.



> > Keywords that previously had file-wide effects will continue to have

> > that. That's not removed. So you must have misunderstood something

> > here.

>

> I did not misunderstand; I am looking from a different perspective.  In

> your proposal, line-based keywords can be overridden by document-level

> property drawers, while they currently are applied to the entire file

> regardless of any drawers.  That is a major change.



Ok, so correct me if I'm wrong here. The thing you object to in my

patch is the fact that the properties in the document level drawer

have a higher precedence over property keywords? Since it means that

outline level 0 have higher precedence than file level keywords? I've

already argued why I think that's natural. This order seems fine to

me: (from lowest to highest rank)

1. File level property keyword

2. Node level 0 property drawer property (file level property drawer)

3. Node level 1 property drawer property

4. Node level 2 property drawer property

5. ...and so on...



This feels less unintuitive and will be more difficult to explain to

new users:

1. Node level 0 property drawer property (file level property drawer)

2. File level property keyword

3. Node level 1 property drawer property

4. Node level 2 property drawer property

5. ...and so on...



I can't agree on changing to the second ranking only based on your

concerns. If more people were to back you up I think it's fair to have

that discussion though!



> >> What you're proposing is actually a fundamental change to the way Org

> >> documents are interpreted.  Org documents are not currently an

> >> outline, just a series of elements which may include an outline.

> >> Text and elements before a first heading are not part of a node,

> >> they're just text and elements in the document.

> >

> > I don't agree here. What I'm proposing in this patch doesn't change

> > the fundament of an Org mode document. I'd rather say it enhances the

> > fundament! Since the outline to a large extent is the fundament! The

> > following quote is from the documentation - Chapter 2, Document

> > Structure:

> >

> >   #+begin_quote Org is an outliner.  Outlines allow a document to be

> >   organized in a hierarchical structure, which, least for me, is the

> >   best representation of notes and thoughts.  #+end_quote

>

> Org is a collection of Emacs code built on top of Outline Mode, which

> interprets plain-text files in a certain way.  Since the beginning, such

> files have been interpreted such that content before the first heading

> is not part of an outline node.  Your proposal would change that.  For

> better or worse, it is a major change that has implications which you

> seem to be unconcerned with.



Of course I'm not unconcerned. I just don't know what you’re

trying to do here. Please take a look at your comment again and then

switch over to ORG-NEWS. Version 9.3 (I.e. a MINOR version) have 9

incompatible changes and 23 new features already pushed to master.

Those 32 changes all have implications for how Org mode documents are

interpreted. Your way of arguing in this thread could be done for many

of those changes. But then, why haven't you? Things change. Most

things to the better! This change being a big step to the better

according to me. And the change I'm proposing here isn't even a

breaking one. I get that it may have struck a nerve for you. But

please argue to the point of the issue instead of trying to blow this

thing up into some mayor breaking incompatible thing. Because it

isn't. It's a harmonization of a feature that already exist. To use it

you have to agree that things before the first headline symbolizes a

level-0 node. If you don't sympathize with that, then simply don't use

it. Your external packages won't need any modifications for this, Org

element already understands it.



> > Thus, saying Org documents are not currently an outline again feels

> > disingenuous and at this point I struggle to take your comments

> > seriously.

>

> As a fellow Org developer, I empathize with the work you have put into

> your proposal and its code.  However, it would be best if you would

> consider these issues impartially.



Which is what I'm doing. I got your comments and your sentiment now

Adam. If you have anything new to add then please do. But please stop

arguing that this change is a major breaking one. If you really still

think that then persuade other members of this community who share

your concern to make their voices heard. Only your comment is on the

side of reject due to major breaking change. The others are positive.

But still few comments all together.



> Like it or not, there is a wider "ecosystem" around Org today, and it is

> growing.  Your proposal would have effects rippling downstream for years

> to come, and other people would have to spend time making changes to

> accommodate them.  Thus, the wider implications of your proposal should

> be very carefully considered.



For this proposed addition to Org mode I don't see where any change is

needed in the wider ecosystem. I do however encourage such change. For

some packages it can resolve issues and simplify development. Because

after this patch is applied there is support for programmatic insertion

of properties that applies to whole files, without having to worry

about positional preferences of the user for property keywords. The

preference when there is a conflict for a property between the keyword

and the drawer is already discussed. That is not a breaking change. If

existing documents break, then please let me know where and how, so I

can try to fix it.



> Org is a big, and growing, project with thousands of users.  We have a

> duty to take these considerations into account, so major changes, like

> your proposal, should be taken very seriously.



Of course it is taken seriously. Your responding to the RFC on the

mailing list. And I'm taking comments on the patch just due to that

concern.



/Gustav

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