Re: [O] [RFC] Document level property drawer
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
Re: [O] [RFC] Document level property drawer
On Sat., Oct. 5, 2019, 6:10 p.m. Adam Porter, wrote: > Marco Wahl writes: > > > Just I got the idea that for a good part this discussion is about > > personal preferences. > > Personal preferences are relevant to this issue in that Org is flexible > and allows users to configure it accordingly. But that is not the only > consideration at stake. Consistency, compatibility, and longevity are > even more important. > > > What I really find irritating is that "Org ... allows #+KEYWORD: lines > > to appear anywhere in a file" (This sentence is from you) with the > > meaning that the settings apply to the whole file. I think this > > interpretation of #+KEYWORD: lines is unnecessary and confusing. > > Regardless, that is the way Org works, and how it has for many years. > We can't break that. > I'd like to just quickly chime in in support of Adam's caution on this issue. I can absolutely see advantages to document level properties, I have written many code fragments that rely on the use of keywords and expect org filensyntax to be consistent with what actually exists. I use these code fragments to hold together a somewhat fragile workflow that allows me to use org in a work environment that is not especially receptive to simple text documents. I have invested a lot of time in making those systems run and sometimes even I don't entirely remember what I did to make them possible. It would really, really suck to have those systems break. It would take me a lot of time to track down the causes and change what I needed to. VMs that currently pull in Emacs andnorg and my code would stop working. Old versions of my files would no longer render properly. My efforts to make my courses and other writings effectively reproducible by others would be significantly set back. Etc. I think these are the kinds of difficulties Adam means to describe. > >
Re: [O] [RFC] Document level property drawer
Marco Wahl writes: > Just I got the idea that for a good part this discussion is about > personal preferences. Personal preferences are relevant to this issue in that Org is flexible and allows users to configure it accordingly. But that is not the only consideration at stake. Consistency, compatibility, and longevity are even more important. > What I really find irritating is that "Org ... allows #+KEYWORD: lines > to appear anywhere in a file" (This sentence is from you) with the > meaning that the settings apply to the whole file. I think this > interpretation of #+KEYWORD: lines is unnecessary and confusing. Regardless, that is the way Org works, and how it has for many years. We can't break that.
Re: [O] [RFC] Document level property drawer
Marco Wahl writes: > One could even think about letting fade out the "#+"-file-wide > property definition syntax or at least think about a good place within > a file or a subtree for those definitions. (There is at least > Sebastian Miele who wants to keep that syntax as he stated in another > thread AFAIR.) You do realize, don't you, how much software and how many documents such a change would break? One of the primary reasons Org users use Org is that its file format is very long-lived and flexible. There are even academic papers written in Org, exported to LaTeX, and a change such as that would break them, creating needless work for their authors or other interested parties to fix them up in order to still be exportable. Please think of other users.
Re: [O] [RFC] Document level property drawer
Gustav Wikström writes: >> In Org, some keywords are special, like #+CATEGORY. For many years, >> such keywords have had file-wide effects regardless of their placement >> in the file. IIUC, your proposal would change that, and that would >> still be a major, breaking change. > > This seems disingenuous. To be disingenuous means, e.g. Not ingenuous; wanting in noble candor or frankness; not frank or open; uncandid; unworthily or meanly artful. It's not friendly to imply that of me over a difference of interpretation of Org syntax and traditions. I hope you meant something else. I wouldn't spend my time studying your proposals and offering feedback if I didn't want what's best for Org and its users. > 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. 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. 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. > Keywords that previously had file-wide effects will continue to have > that. That's not removed. So you must have missunderstood 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. >> > If you think of the document as an outline, something Org mode is >> > all about, it makes sense to also think of things before the first >> > headline as "node level 0". And with that way of conceptually >> > thinking of the document it makes perfect sense to have a property >> > drawer fixed at the top - in the same way as it is required for all >> > other node levels. >> >> 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. > 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. 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. 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.
Re: [O] [RFC] Document level property drawer
Hi again Adam, > IIUC, your proposal would work like this: > > #+BEGIN_SRC org > :PROPERTIES: > :CATEGORY: Gamma > :END: > > # Category here is "Gamma" > > ,* Node 1 > > # Category here is "Gamma" > > ,* Node 2 > :PROPERTIES: > :CATEGORY: Beta > :END: > > # Category here is "Beta" > > ,#+CATEGORY: Alpha > #+END_SRC You understand correctly. In that case precedence would kick in since a category is defined using both a category keyword and a category inside the document property drawer. The example above is mostly theoretical since there is no use-case for having category set on document level using both conventions. If the example above was a real document I'd suggest removing either the category keyword or the category property from the document property drawer. > In Org, some keywords are special, like #+CATEGORY. For many years, > such keywords have had file-wide effects regardless of their placement > in the file. IIUC, your proposal would change that, and that would > still be a major, breaking change. This seems disingenuous. 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. Keywords that previously had file-wide effects will continue to have that. That's not removed. So you must have missunderstood something here. I understand you dislike the preference of letting the property drawer have a higher precedance than property keywords, if the same property is defined in both ways. I've already argued why I think that is the sane choice to make. But having that precedance doesn't break anything since you cannot define a property drawer on document level today. > > If you think of the document as an outline, something Org mode is all > > about, it makes sense to also think of things before the first > > headline as "node level 0". And with that way of conceptually thinking > > of the document it makes perfect sense to have a property drawer fixed > > at the top - in the same way as it is required for all other node > > levels. > > 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 Thus, saying Org documents are not currently an outline again feels disingenuous and at this point I struggle to take your comments seriously. Regards Gustav
