Re: [RFC] Document level property drawer
>> Sebastian Miele writes: >>> I would like to be able to make a clear distinction between properties >>> that are visible by default and properties that are not. Maybe it would >>> be possible to allow some #+.. syntax following headings for subtree >>> properties that are visible by default. A requirement could be made that >>> such property specifications always have to be followed by a property >>> drawer, even if that is empty. Then everything #+.. that is before the >>> property drawer would belong to the heading/subtree, and everything #+.. >>> that follows the drawer would be treated as it is until now. >>> >>> Please tell me if I missed something and Org is already capable of >>> something like that. If not, are there others who would like >>> visible-by-default property specifications for headings/subtrees in >>> addition to invisible-by-default property specifications in drawers, >>> too? >> >> I don't think Org is capable of this out of the box right now. Further >> I don't feel the need for a visible-by-default property, but that's just >> me. > > After a few more months of living without that feature I must say that I > basically live perfectly well without that, too. I just do not define > source block header args in property drawers. It gets a bit verbose at > times. But not to the degree of being painful. Sounds good to me. >>> Finally, I would like to state an opinion: If there is >>> visible-by-default (by #+..) and invisible-by-default (by drawers) >>> syntax for headings/subtrees, including level 0, it may be viable to >>> require them to be disjoint for each heading/subtree. Most probably it >>> would be good practice, anyway. And the precedence question raised >>> previously in this thread would be eliminated. >> >> I may not feel the need for the visible/invisible-by-default properties >> but actually I like the idea of #+ properties parallel to the property >> drawers as visible by default properties. But since the #+ properties >> may appear anywhere in the Org file and affect the whole file it would >> be difficult or even impossible to give them reliable meaning for >> subtrees AFAICS. > > In the meantime I had a look into worg/dev/org-syntax.org. From the > document: "Property drawers are a special type of drawer containing > properties attached to a headline. They are located right after a > headline and its planning information." Thanks for the quote. > So, currently, #+ properties may not appear between a heading and a > property drawer. At least not without turning the property drawer into a > non-special drawer. So, in principle, it would be possible to change the > syntax of Org to allow #+ properties between headings and (possibly > empty) property drawers in order to denote visible-by-default > properties attached to a heading. Sounds true AFAICS. > Moreover, this change probably would introduce very little to no > backwards incompatibility. With the change it would not be possible to > turn property drawers into non-special drawers by putting a #+ property > before them. Now it is possible to sort of uncomment property drawers by > putting #+ properties before them. This "feature" probably is hardly > used, if at all. I also think this is very corner case-y. All in all I think your idea is good. But the masses did not scream for that change so I think your idea is something for a wishlist to wait for further discussion. Best regards, -- Marco
Re: [RFC] Document level property drawer
Marco Wahl writes: > Sebastian Miele writes: > >> But for such properties to satisfactorily work for me, they would have >> to be visible by default. E.g. I would want the header-args to be >> immediately visible just like they are when they are written after >> #+BEGIN_SRC or #+HEADER. Otherwise I would find myself constantly >> wondering whether this or that property drawer contains something >> essential and every TAB on a collapsed headline would have be followed >> by an accompanying move to the property drawer and a TAB there. >> >> On the other hand, there are properties that are very good candidates >> for remaining hidden by default, like ID. >> >> I would like to be able to make a clear distinction between properties >> that are visible by default and properties that are not. Maybe it would >> be possible to allow some #+.. syntax following headings for subtree >> properties that are visible by default. A requirement could be made that >> such property specifications always have to be followed by a property >> drawer, even if that is empty. Then everything #+.. that is before the >> property drawer would belong to the heading/subtree, and everything #+.. >> that follows the drawer would be treated as it is until now. >> >> Please tell me if I missed something and Org is already capable of >> something like that. If not, are there others who would like >> visible-by-default property specifications for headings/subtrees in >> addition to invisible-by-default property specifications in drawers, >> too? > > I don't think Org is capable of this out of the box right now. Further > I don't feel the need for a visible-by-default property, but that's just > me. After a few more months of living without that feature I must say that I basically live perfectly well without that, too. I just do not define source block header args in property drawers. It gets a bit verbose at times. But not to the degree of being painful. >> Finally, I would like to state an opinion: If there is >> visible-by-default (by #+..) and invisible-by-default (by drawers) >> syntax for headings/subtrees, including level 0, it may be viable to >> require them to be disjoint for each heading/subtree. Most probably it >> would be good practice, anyway. And the precedence question raised >> previously in this thread would be eliminated. > > I may not feel the need for the visible/invisible-by-default properties > but actually I like the idea of #+ properties parallel to the property > drawers as visible by default properties. But since the #+ properties > may appear anywhere in the Org file and affect the whole file it would > be difficult or even impossible to give them reliable meaning for > subtrees AFAICS. In the meantime I had a look into worg/dev/org-syntax.org. From the document: "Property drawers are a special type of drawer containing properties attached to a headline. They are located right after a headline and its planning information." So, currently, #+ properties may not appear between a heading and a property drawer. At least not without turning the property drawer into a non-special drawer. So, in principle, it would be possible to change the syntax of Org to allow #+ properties between headings and (possibly empty) property drawers in order to denote visible-by-default properties attached to a heading. Moreover, this change probably would introduce very little to no backwards incompatibility. With the change it would not be possible to turn property drawers into non-special drawers by putting a #+ property before them. Now it is possible to sort of uncomment property drawers by putting #+ properties before them. This "feature" probably is hardly used, if at all.
Re: [RFC] Document level property drawer
Sebastian Miele writes: > But for such properties to satisfactorily work for me, they would have > to be visible by default. E.g. I would want the header-args to be > immediately visible just like they are when they are written after > #+BEGIN_SRC or #+HEADER. Otherwise I would find myself constantly > wondering whether this or that property drawer contains something > essential and every TAB on a collapsed headline would have be followed > by an accompanying move to the property drawer and a TAB there. > > On the other hand, there are properties that are very good candidates > for remaining hidden by default, like ID. > > I would like to be able to make a clear distinction between properties > that are visible by default and properties that are not. Maybe it would > be possible to allow some #+.. syntax following headings for subtree > properties that are visible by default. A requirement could be made that > such property specifications always have to be followed by a property > drawer, even if that is empty. Then everything #+.. that is before the > property drawer would belong to the heading/subtree, and everything #+.. > that follows the drawer would be treated as it is until now. > > Please tell me if I missed something and Org is already capable of > something like that. If not, are there others who would like > visible-by-default property specifications for headings/subtrees in > addition to invisible-by-default property specifications in drawers, > too? I don't think Org is capable of this out of the box right now. Further I don't feel the need for a visible-by-default property, but that's just me. > Finally, I would like to state an opinion: If there is > visible-by-default (by #+..) and invisible-by-default (by drawers) > syntax for headings/subtrees, including level 0, it may be viable to > require them to be disjoint for each heading/subtree. Most probably it > would be good practice, anyway. And the precedence question raised > previously in this thread would be eliminated. I may not feel the need for the visible/invisible-by-default properties but actually I like the idea of #+ properties parallel to the property drawers as visible by default properties. But since the #+ properties may appear anywhere in the Org file and affect the whole file it would be difficult or even impossible to give them reliable meaning for subtrees AFAICS. My 2ct, -- Marco
Re: [RFC] Document level property drawer
Hi,
> One issue for me is the positioning of the level 0 property drawer.
> Having the requirement for that drawer starting in the very first
> line is too strong for me. I guess one would at least like to have
> the option to add some configuration with the ‘-*-...-*-’ construct
> which currently only works in the first line.
Hmm, that should work right now. 0..n comment lines are supposed to be
allowed anyways. I can debug that a bit later to see if something has
gone amiss.
> Further I think one would also like to place #+: configuration lines
> there in particular the #+title: line. What about allowing lines
> starting with character # above the level 0 property drawer? And put
> a newly created level 0 property drawer below the first line in the
> file that does not start with #?
The first patch allowed both coments ("# "-lines) and keyword lines
(#+...:) as well. But I removed keyword lines for now to start with a
bit more strict definition, per request from Nicolas. I think the
parser will be happy if there is as little information abouve the
drawer as possible, since it will have to retrace itself from the
first line of the buffer every time it needs to verify that the drawer
actually is the "proper" property drawer. If that makes sense. So the
more restrictive we can allow us to be, the better the performance and
the easier it will be to understand where the drawer goes. And less
complexity.
Happy to get more feedback on that decision though!
Thanks! Gustav
Re: [RFC] Document level property drawer
>> One issue for me is the positioning of the level 0 property drawer.
>> Having the requirement for that drawer starting in the very first
>> line is too strong for me. I guess one would at least like to have
>> the option to add some configuration with the ‘-*-...-*-’ construct
>> which currently only works in the first line.
>
> Hmm, that should work right now. 0..n comment lines are supposed to be
> allowed anyways. I can debug that a bit later to see if something has
> gone amiss.
You are right! No need to debug anything. I had #+: lines before the
first property drawer. Sorry for the confusion.
>> Further I think one would also like to place #+: configuration lines
>> there in particular the #+title: line. What about allowing lines
>> starting with character # above the level 0 property drawer? And put
>> a newly created level 0 property drawer below the first line in the
>> file that does not start with #?
>
> The first patch allowed both coments ("# "-lines) and keyword lines
> (#+...:) as well. But I removed keyword lines for now to start with a
> bit more strict definition, per request from Nicolas. I think the
> parser will be happy if there is as little information abouve the
> drawer as possible, since it will have to retrace itself from the
> first line of the buffer every time it needs to verify that the drawer
> actually is the "proper" property drawer. If that makes sense. So the
> more restrictive we can allow us to be, the better the performance and
> the easier it will be to understand where the drawer goes. And less
> complexity.
Okay. I keep going with this setting.
I can imagine that the parser is happy with less possibilities
and the user is happy with fast parsing.
But I'm not 100% convinced that #+: lines should not be allowed before
the level 0 property drawer. E.g. #+title: in the first line looks nice
AFAICT.
> Happy to get more feedback on that decision though!
Hopefully some more feedback comes in...
Best regards,
--
Marco
Re: [O] [RFC] Document level property drawer
Hi Adam, Adam Porter writes: > There are a lot of deprecation recommendations in your attached > document: > > > I propose to depricate property-keywords > > I propose to depricate the Options-keyword > > I propose to relabel these keywords as document keywords > > I propose to depricate the #+CATEGORY syntax > > I propose to depricate the #+FILETAGS syntax > > I propose to depricate the #+COLUMNS syntax > > I propose to depricate the #+ARCHIVE syntax > > I propose to depricate the TODO-keywords > > I propose to depricate the priorities-keyword > > I propose to depricate the tags-keyword > > I propose to depricate the link-keyword > > I propose to depricate the constants-keyword > > I propose to depricate the setupfile-keyword > > I propose to depricate the Macro-keyword > > The thoroughness of your investigation is admirable. Thanks! > However, I propose that we don't deprecate any of those. Org has been > around for over a decade now. Such drastic changes would not serve > users well. I think you're right in the fact that Org mode will need to continue to understand them. I'll say again that I wrote the document quite a while ago. It's unedited and initially meant for my eyes only. So "to deprecate" may be perceived to strong and I certainly didn't mean to cut them out straight away. I don't think the diverse use of keywords are good for the future of Org mode though, and I do think there is value in trying to consolidate functionality and possibly promote something that is more clear and easy to understand. Many of the existing keywords have a corresponding property-syntax. For those I think it would be good to start promoting using properties instead of keywords (as I've written over and over again :) ). Other keywords affect the Org mode configuration for the current buffer. They are basically shortcuts to customization for the current buffer. Which led me to proposing a settings drawer. It may be that it initially is enough to just update the documentation with a chapter about keywords and categorizing them in some groups based on intended purpose. I do however still like the idea of collecting those keywords in a drawer instead of having them spread out in the document. > Note that I'm taking your use of the word "deprecate" to mean what > it's expected to mean in this context: that the software developers > recommend against using it, with the intention to eventually remove > support for the feature. We shouldn't be removing any such features > from Org. > > Not only would it not serve users well, but it would make the software > much more complicated. As it stands, finding, e.g. a #+CATEGORY: > keyword and getting its value is as simple as: > > (save-excursion > (goto-char (point-min)) > (when (re-search-forward (rx bol "#+CATEGORY:" (1+ blank) >(group (1+ nonl))) >nil t) > (match-string 1))) > > Hiding those keywords in drawers means that either: > > a) Eligible drawers must be located, and then the desired > property must be searched for inside of them. > > b) Possibly valid properties must be located, and each one must be > confirmed to be inside an eligible drawer. > > What benefit would this added complexity serve? To put the keywords > in one place in the document? There are already multiple ways to > achieve that. I don't agree here. Keywords today break the outline and have no positional requirements. Both a property and a settings drawer would have a fixed position to make it easy to locate, both programmatically, visually and by search. > I can't emphasize enough how important stability and consistency is > for Org and its file formats right now. As I've said, there are new > implementations in development, which have the potential to bring a > lot of publicity and new users to Org. For example, this one was > mentioned on a Hacker News post a few days ago: There is always a balance between stability, backwards compatibility and progression. I agree that backwards compatibility and stability is important. But I also argue that progression is important. Good if Org mode is gaining traction! But that doesn't mean we can't improve it further, for it to gain even more traction! And in the larger scheme of things, Org mode still is tiny. So let's not oversell ourselves here. It's almost like a catch 22. But the largest hinderance for Org mode to grow further is probably its ties with Emacs, the very thing that makes Org mode into the powerhouse it is! > https://github.com/mickael-kerjean/filestash > > In the same HN post were examples of implementations for Vim and > VSCode. Already, especially in the VSCode ones, there were apparent > incompatibilities in their implementations of the Org file format. I've been a promoter of separating the Org mode syntax from Emacs for a long time. I think I've written about it on this list previously as well. So I know what you mean.
Re: [RFC] Document level property drawer
Hi,
> One issue for me is the positioning of the level 0 property drawer.
> Having the requirement for that drawer starting in the very first
> line is too strong for me. I guess one would at least like to have
> the option to add some configuration with the ‘-*-...-*-’ construct
> which currently only works in the first line.
Hmm, that should work right now. 0..n comment lines are supposed to be
allowed anyways. I can debug that a bit later to see if something has
gone amiss.
> Further I think one would also like to place #+: configuration lines
> there in particular the #+title: line. What about allowing lines
> starting with character # above the level 0 property drawer? And put
> a newly created level 0 property drawer below the first line in the
> file that does not start with #?
The first patch allowed both coments ("# "-lines) and keyword lines
(#+...:) as well. But I removed keyword lines for now to start with a
bit more strict definition, per request from Nicolas. I think the
parser will be happy if there is as little information abouve the
drawer as possible, since it will have to retrace itself from the
first line of the buffer every time it needs to verify that the drawer
actually is the "proper" property drawer. If that makes sense. So the
more restrictive we can allow us to be, the better the performance and
the easier it will be to understand where the drawer goes. And less
complexity.
Happy to get more feedback on that decision though!
Thanks! Gustav
Re: [O] [RFC] Document level property drawer
Gustav, There are a lot of deprecation recommendations in your attached document: > I propose to depricate property-keywords > I propose to depricate the Options-keyword > I propose to relabel these keywords as document keywords > I propose to depricate the #+CATEGORY syntax > I propose to depricate the #+FILETAGS syntax > I propose to depricate the #+COLUMNS syntax > I propose to depricate the #+ARCHIVE syntax > I propose to depricate the TODO-keywords > I propose to depricate the priorities-keyword > I propose to depricate the tags-keyword > I propose to depricate the link-keyword > I propose to depricate the constants-keyword > I propose to depricate the setupfile-keyword > I propose to depricate the Macro-keyword The thoroughness of your investigation is admirable. However, I propose that we don't deprecate any of those. Org has been around for over a decade now. Such drastic changes would not serve users well. Note that I'm taking your use of the word "deprecate" to mean what it's expected to mean in this context: that the software developers recommend against using it, with the intention to eventually remove support for the feature. We shouldn't be removing any such features from Org. Not only would it not serve users well, but it would make the software much more complicated. As it stands, finding, e.g. a #+CATEGORY: keyword and getting its value is as simple as: (save-excursion (goto-char (point-min)) (when (re-search-forward (rx bol "#+CATEGORY:" (1+ blank) (group (1+ nonl))) nil t) (match-string 1))) Hiding those keywords in drawers means that either: a) Eligible drawers must be located, and then the desired property must be searched for inside of them. b) Possibly valid properties must be located, and each one must be confirmed to be inside an eligible drawer. What benefit would this added complexity serve? To put the keywords in one place in the document? There are already multiple ways to achieve that. I can't emphasize enough how important stability and consistency is for Org and its file formats right now. As I've said, there are new implementations in development, which have the potential to bring a lot of publicity and new users to Org. For example, this one was mentioned on a Hacker News post a few days ago: https://github.com/mickael-kerjean/filestash In the same HN post were examples of implementations for Vim and VSCode. Already, especially in the VSCode ones, there were apparent incompatibilities in their implementations of the Org file format. As well, there are now parsers in JavaScript, Python, and Rust. Markdown is by far the most popular plain-text format, and has been for years, but it has long suffered from competing, slightly incompatible flavors and implementations. Reddit has theirs, GitHub has theirs, etc. Org's file format may finally be gaining some momentum. Let's not jeopardize Org's chances by making implementors' job more difficult than it already is.
Re: [O] [RFC] Document level property drawer
> Sooo, a separate branch is created in the Org mode repository named > "next". I'm not entirely sure how we're supposed to work with it. But > I've anyways pushed my (non-breaking) patch there. Thanks again. One issue for me is the positioning of the level 0 property drawer. Having the requirement for that drawer starting in the very first line is too strong for me. I guess one would at least like to have the option to add some configuration with the ‘-*-...-*-’ construct which currently only works in the first line. Further I think one would also like to place #+: configuration lines there in particular the #+title: line. What about allowing lines starting with character # above the level 0 property drawer? And put a newly created level 0 property drawer below the first line in the file that does not start with #?
Re: [O] [RFC] Document level property drawer
Gustav Wikström writes: [...] > Sooo, a separate branch is created in the Org mode repository named > "next". I'm not entirely sure how we're supposed to work with it. But > I've anyways pushed my (non-breaking) patch there. Okay, thanks. I try to follow the development on the 'next' branch. [...] >> Noteworthy observations AFAICT: >> >> 1. I could not translate my personal "#+TODO: . N ~ | x c g >" into a >> respective :TODO: property. > > Yes, that's true. The reason is that there is no TODO-property that > fits in property drawers right now. I.e. special properties such as > TODO, TAGS, priority, scheduling and deadlines that have special > syntax for the outline still have no defined meaning for outline level > 0. I ofc. think that's an oversight ;) But I may also be a bit crazy. > > A conclusion to draw from that, that may be worth writing more about, > is that the property drawer for node level 0 will not be able to > replace all file-level keywords that exist today. Only properties that > currently can also be defined in property drawers in the outline will > work in the property drawer on level 0. Makes sense? Absolutely. > The idea I had for all the other keywords that apply for the whole > file was to create another drawer, what I called a settings drawer. > Because the TODO-keyword you refer to above really is a setting that > you're making for the current file, much the same as when you make > changes in global, folder local or file local variables using the > standard emacs framework. The idea of a settings drawer makes sense AFAICS. For the special case of TODO-keywords one could think about defining them per subtree. Possibly there are some low hanging fruit among the whole-file-properties that have a natural interpretation per subtree. > I've attached an investigation I did of the world of Org mode > keywords. It was done quite a while back and some things in there are > subjective and may not represent my current picture of the "ideal". > Nonetheless, maybe an interesting read for the ... other crazy people > out there? Okay, I'll have a look at your investigation. ;) BTW this document looks great to me at the first glance. Thanks, -- Marco
Re: [O] [RFC] Document level property drawer
Hi! I'll start with the most important info at the top. I've applied the patch! But before anyone comes screaming I'll just say it's applied on a separate branch. After consultation with Nicolas Goaziou that was seen as the most reasonable thing to do. The idea is that it's high time to start wrapping up 9.3 for a release and (even though I personally would like to have this in there) since this patch might continue to generate discussion and possibly bugs and fixes it's more safe to let this come after the 9.3 release. Sooo, a separate branch is created in the Org mode repository named "next". I'm not entirely sure how we're supposed to work with it. But I've anyways pushed my (non-breaking) patch there. Comments on what you've written below! Marco Wahl writes: > > @Marco Wahl; As I understand you've applied the patch and tried it > > out. Have you found any issues yet? What do you think of the patch > > after having used it for a while? > > Indeed I applied your patch and have it applied still. Please note that > I did nothing fancy and in particular I did not try to break the patch. Got it. > The patch works good for me. Nice to hear! > Noteworthy observations AFAICT: > > 1. I could not translate my personal "#+TODO: . N ~ | x c g >" into a > respective :TODO: property. Yes, that's true. The reason is that there is no TODO-property that fits in property drawers right now. I.e. special properties such as TODO, TAGS, priority, scheduling and deadlines that have special syntax for the outline still have no defined meaning for outline level 0. I ofc. think that's an oversight ;) But I may also be a bit crazy. A conclusion to draw from that, that may be worth writing more about, is that the property drawer for node level 0 will not be able to replace all file-level keywords that exist today. Only properties that currently can also be defined in property drawers in the outline will work in the property drawer on level 0. Makes sense? The idea I had for all the other keywords that apply for the whole file was to create another drawer, what I called a settings drawer. Because the TODO-keyword you refer to above really is a setting that you're making for the current file, much the same as when you make changes in global, folder local or file local variables using the standard emacs framework. I've attached an investigation I did of the world of Org mode keywords. It was done quite a while back and some things in there are subjective and may not represent my current picture of the "ideal". Nonetheless, maybe an interesting read for the ... other crazy people out there? > 2. With org-ids turned on and point before the first heading, function > org-store-link creates an org-id property at the document level. > > Regarding number 1. I think a list of document-level properties which > don't behave the same when used in the document property drawer would be > nice. Ideally this list is empty AFAICT. Maybe I overlook something. > Is this an issue? Ahh, see the attachment ;) Maybe can give answers to some of your thoughts. > I think observation 2. is just a little surprise but turns out to be > natural when the document level property drawer is enabled. Glad to hear! > > > Still +1 for the inclusion of the patch and HTH, > -- Thanks Gustav Investigation.org Description: Investigation.org
Re: [O] [RFC] Document level property drawer
Gustav Wikström writes: > I'd like to take the next step with this patch. I'm hesitant to do it > without wider support though, since only a few people have commented. > > @Marco Wahl; As I understand you've applied the patch and tried it > out. Have you found any issues yet? What do you think of the patch > after having used it for a while? Indeed I applied your patch and have it applied still. Please note that I did nothing fancy and in particular I did not try to break the patch. The patch works good for me. Noteworthy observations AFAICT: 1. I could not translate my personal "#+TODO: . N ~ | x c g >" into a respective :TODO: property. 2. With org-ids turned on and point before the first heading, function org-store-link creates an org-id property at the document level. Regarding number 1. I think a list of document-level properties which don't behave the same when used in the document property drawer would be nice. Ideally this list is empty AFAICT. Maybe I overlook something. Is this an issue? I think observation 2. is just a little surprise but turns out to be natural when the document level property drawer is enabled. Still +1 for the inclusion of the patch and HTH, -- Marco
Re: [O] [RFC] Document level property drawer
Gustav Wikström writes: > Hi again, > > I'd like to take the next step with this patch. I'm hesitant to do it > without wider support though, since only a few people have commented. > > @Marco Wahl; As I understand you've applied the patch and tried it > out. Have you found any issues yet? What do you think of the patch > after having used it for a while? > > Any other thoughts/comments/objections/praises? Please do not merge your patch without the approval of the Org maintainers.
Re: [O] [RFC] Document level property drawer
Hi again, I'd like to take the next step with this patch. I'm hesitant to do it without wider support though, since only a few people have commented. @Marco Wahl; As I understand you've applied the patch and tried it out. Have you found any issues yet? What do you think of the patch after having used it for a while? Any other thoughts/comments/objections/praises? Regards Gustav > -Original Message- > From: Gustav Wikström > Sent: den 29 september 2019 12:27 > To: emacs-orgmode@gnu.org > Cc: Nicolas Goaziou > Subject: [RFC] Document level property drawer > > Hi, > > This patch introduces a document level property drawer. > > This has been discussed previously in a larger context: > - https://lists.gnu.org/archive/html/emacs-orgmode/2019-06/msg0.html > - https://lists.gnu.org/archive/html/emacs-orgmode/2019-08/msg00339.html > - https://lists.gnu.org/archive/html/emacs-orgmode/2019-09/msg00010.html > > The patch is a somewhat modified version of what was included in the third > link above. > > The following will be true for document level property drawers: > 1) In the same way that one can have a property drawer for a heading, one >can have a property drawer for a whole document. > 2) All existing commands that can work with property drawers will >(shall) work also on property drawers before the first heading. > 3) Properties defined in a property drawer will have precedence over >properties defined as a property keyword, if the same property is >defined using both conventions. > 4) The position for the document level property drawer is: >- At the first line in a file that is not a comment or a keyword. > > I.e. the following will work: > #+begin_src org ># -*- mode: org -*- >,#+TITLE: Test >:PROPERTIES: >:CATEGORY: Test >:END: > >Preamble > >,* Some heading >Some content > #+end_src > > but not this: > #+begin_src org >Some comment and/or empty line > >:PROPERTIES: >:CATEGORY: Test >:END: > >,* Some heading >Some content > #+end_src > > What do you say? > > Regards > Gustav Wikström
Re: [O] [RFC] Document level property drawer
Adam Porter writes: > 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 let's forget about fading out the "#+"-file-wide property for now. I understand that the file-wide properties in their current meaning need to stay a good while, maybe even as long as Org lives. Back to the issue of the document level property drawer: could it be we talk about literally nothing when talking about the "breaking"? What is an example which shows how the introduction of a document level property drawer breaks something in the Org universe? (I think there is none.) Ciao, -- Marco
Re: [O] [RFC] Document level property drawer
Hi Matt, Thanks for your comment! I can assure you that you need not worry about the propsed patch here in terms of your workflow. This is in no way a hasty, sloppy work. Care has been taken when developing it to not break anything existing. I hear your concerns on the larger topic of keywords though. But that's not something that is changing in this patch. Some more comments below. > 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. Again, caution is ofc taken. In no way does this patch change any of your existing properties. If something, it proposes a way for you to simplify your setup if you at any time in the future choose to do that. The patch that is applied is tested and no existing functionailty is changed. Ofc, if you have a critical flow I'd advice you to use the stable branch of Org mode and not rely on the master branch, since that branch from time to time will get bugs in it. Regards Gustav
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
Re: [O] [RFC] Document level property drawer
Adam Porter writes: > Marco Wahl writes: >> You say the visibility is better for the #+-property keywords. I say >> they can occur _anywhere_ in the file and even in some drawers. See >> above "#+CATEGORY: cat-doc-prop-keyword-2". >> >> Further you say >> > - However, it seems to me that the simplest, most natural protocol would > be for later declarations to override earlier ones. >> >> This means that cat-doc-prop-keyword-2 from the example defines the >> CATEGORY property which at least I find not so natural. And I already >> stated what I find natural. > Org may allow #+KEYWORD: lines to appear anywhere in a file, including > in arbitrary drawers, but that's up to the user. If the user chooses to > hide them in drawers, it's his responsibility. > > AFAICT that's not a common or generally recommended thing to do. Most > Org files have such lines at the top of the file, and some under a > heading at the bottom of the file with other settings. Such lines don't > need to be in drawers, and this proposal wouldn't change that. > > So I think it would be confusing if settings in a drawer at the top of > the file were to absolutely override settings outside of drawers (which > would mean that hidden settings could override plainly visible ones). > The most natural protocol would be like written language: later > declarations override earlier ones. Hi Adam, Just I got the idea that for a good part this discussion is about personal preferences. For me for example it's not a big deal if a property is placed within a drawer or not. I don't care much about the "visibility" of a property setting. Of course I respect other views about this. 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. BTW I find it completely natural that--let's for simplicity assume an Org file without any drawers--#+KEYWORD: settings that appear later in a file replace earlier settings. Best regards, -- Marco
Re: [O] [RFC] Document level property drawer
Adam Porter writes: > Gustav Wikström writes: > >> I'd argue that precedence already works that way. One has to take >> inheritance into account. With inheritance turned on, tell me which >> value for Property1 is used for the nodes in the following example: >> >> #+begin_src org >> ,* Node 1 >> ,* Node 2 >> :PROPERTIES: >> :Property1: Value1 >> :END: >> >> ,#+PROPERTY: Property1 Value2 >> #+end_src >> >> As you'll see line number already isn't the deciding factor. >> >> With two ways to define properties it makes sense to first think of >> which syntax to promote as "more important" and then to think of >> precedence rules for duplicates within each syntax. >> >> Having the same syntax for node level 0 as for regular nodes makes the >> property functionality easy to understand and congruent. Something I >> think is worth promoting by saying that property blocks on file-level >> has precedence over the keyword syntax. > > I think this example illustrates the issue better. This is how Org > currently works: > > #+BEGIN_SRC org > # Category here is "Alpha" > > ,* Node 1 > > # Category here is "Alpha" > > ,* Node 2 > :PROPERTIES: > :CATEGORY: Beta > :END: > > # Category here is "Beta" > > ,#+CATEGORY: Alpha > #+END_SRC > > > 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 > > So the #+CATEGORY: line has no effect because of the first-line 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. IIUC Org files not using a file level property drawer would not be affected from the change at all. With the proposition the user gets a further option to define a file wide property. >> 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. > > If Org were a new project, I think your proposal might be very > suitable. But at this point, it would be a significant, breaking > change, even without the org-element parser changes. > > Consider as well that the Org format has recently been seeing wider use, > with more implementations becoming available in several languages and on > several platforms. Fundamental changes like this would affect more than > just the official Org software, and the costs of breaking software in > the wider Org community should be carefully considered. The proposal is an extension leaving all operations and tools intact for Org files not using the file wide property drawer AFAICS. If a tool depends on a file wide property then it needs to be adapted. Possibly this could be called "breaking" but I think this should not hold back the proposal. 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.) Personally I think it's a good idea to work for an Org mode where an Org file behaves very much like an Org subtree. Ciao, -- Marco
Re: [O] [RFC] Document level property drawer
Hi Gustav, Gustav Wikström writes: > I'd argue that precedence already works that way. One has to take > inheritance into account. With inheritance turned on, tell me which > value for Property1 is used for the nodes in the following example: > > #+begin_src org > ,* Node 1 > ,* Node 2 > :PROPERTIES: > :Property1: Value1 > :END: > > ,#+PROPERTY: Property1 Value2 > #+end_src > > As you'll see line number already isn't the deciding factor. > > With two ways to define properties it makes sense to first think of > which syntax to promote as "more important" and then to think of > precedence rules for duplicates within each syntax. > > Having the same syntax for node level 0 as for regular nodes makes the > property functionality easy to understand and congruent. Something I > think is worth promoting by saying that property blocks on file-level > has precedence over the keyword syntax. I think this example illustrates the issue better. This is how Org currently works: #+BEGIN_SRC org # Category here is "Alpha" ,* Node 1 # Category here is "Alpha" ,* Node 2 :PROPERTIES: :CATEGORY: Beta :END: # Category here is "Beta" ,#+CATEGORY: Alpha #+END_SRC 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 So the #+CATEGORY: line has no effect because of the first-line 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. > 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. If Org were a new project, I think your proposal might be very suitable. But at this point, it would be a significant, breaking change, even without the org-element parser changes. Consider as well that the Org format has recently been seeing wider use, with more implementations becoming available in several languages and on several platforms. Fundamental changes like this would affect more than just the official Org software, and the costs of breaking software in the wider Org community should be carefully considered.
Re: [O] [RFC] Document level property drawer
Marco Wahl writes: > You say the visibility is better for the #+-property keywords. I say > they can occur _anywhere_ in the file and even in some drawers. See > above "#+CATEGORY: cat-doc-prop-keyword-2". > > Further you say > - However, it seems to me that the simplest, most natural protocol would be for later declarations to override earlier ones. > > This means that cat-doc-prop-keyword-2 from the example defines the > CATEGORY property which at least I find not so natural. And I already > stated what I find natural. Hi Marco, Org may allow #+KEYWORD: lines to appear anywhere in a file, including in arbitrary drawers, but that's up to the user. If the user chooses to hide them in drawers, it's his responsibility. AFAICT that's not a common or generally recommended thing to do. Most Org files have such lines at the top of the file, and some under a heading at the bottom of the file with other settings. Such lines don't need to be in drawers, and this proposal wouldn't change that. So I think it would be confusing if settings in a drawer at the top of the file were to absolutely override settings outside of drawers (which would mean that hidden settings could override plainly visible ones). The most natural protocol would be like written language: later declarations override earlier ones.
Re: [O] [RFC] Document level property drawer
Hi Sebastian, > From: Sebastian Miele > Subject: Re: [O] [RFC] Document level property drawer > Date: Tue, 01 Oct 2019 12:38:12 + > ... > I would like to be able to make a clear distinction between properties > that are visible by default and properties that are not. Maybe it would > be possible to allow some #+.. syntax following headings for subtree > properties that are visible by default. A requirement could be made that > such property specifications always have to be followed by a property > drawer, even if that is empty. Then everything #+.. that is before the > property drawer would belong to the heading/subtree, and everything #+.. > that follows the drawer would be treated as it is until now. That maps quite well to what I also had in mind initially. What I called "Document property keywords" in [fn:1]: #+begin_quote I propose to allow properties to be defined also as document property keywords. All keywords in the top of a buffer, before any non-comment line, are document-level keywords. In effect, they are properties that apply in exactly the same way as properties defined in the property drawer. The only reason for using a document keyword instead of defining it inside the property drawer is to make it more visible. One example would be the title-keyword (#+TITLE: ...). #+end_quote Although I didn't think of generalizing it to also work for the outline nodes. Something that makes sense to do though, given the use case you describe! [fn:1] https://lists.gnu.org/archive/html/emacs-orgmode/2019-06/msg0.html FWIW Gustav
Re: [O] [RFC] Document level property drawer
Adam Porter writes: > Marco Wahl writes: > >> Adam Porter writes: >> >>> Gustav Wikström writes: >>> 3) Properties defined in a property drawer will have precedence over properties defined as a property keyword, if the same property is defined using both conventions. >>> >>> That protocol seems unnatural and confusing to me: >>> >>> - If precedence were to be defined by something other than file-order, >>> it seems to me that those defined with #+ keywords should have >>> precedence, because they are more visible, while those in drawers are >>> hidden. >>> - However, it seems to me that the simplest, most natural protocol would >>> be for later declarations to override earlier ones. >> >> I think it would be quite natural to use the tree structure of Org. A >> property setting in a subtree overrides the setting in a parent (which >> could be the document(= the whole file.)) > > Hi Marco, > > I think you misunderstood his point #3 and my objection to it. :) Hi Adam, that's possible but I don't think so. But I'm willing to learn if I didn't get it. :) Possibly a concrete example can help. Let's take Org property CATEGORY for illustration. First to Gustav's statement 3): Let the file be this: --8<---cut here---start->8--- #+title: file :PROPERTIES: :CATEGORY: cat-doc-prop-drawer :END: * foo SCHEDULED: <2019-10-02 Wed> #+CATEGORY: cat-doc-prop-keyword-1 ** bar :somedrawer: #+CATEGORY: cat-doc-prop-keyword-2 :END: --8<---cut here---end--->8--- With Gustav's proposition the CATEGORY of task foo is cat-doc-prop-drawer. Next to your statements: You say the visibility is better for the #+-property keywords. I say they can occur _anywhere_ in the file and even in some drawers. See above "#+CATEGORY: cat-doc-prop-keyword-2". Further you say >>> - However, it seems to me that the simplest, most natural protocol would >>> be for later declarations to override earlier ones. This means that cat-doc-prop-keyword-2 from the example defines the CATEGORY property which at least I find not so natural. And I already stated what I find natural. Best regards, Marco
Re: [O] [RFC] Document level property drawer
Marco Wahl writes: > Adam Porter writes: > >> Gustav Wikström writes: >> >>> 3) Properties defined in a property drawer will have precedence over >>>properties defined as a property keyword, if the same property is >>>defined using both conventions. >> >> That protocol seems unnatural and confusing to me: >> >> - If precedence were to be defined by something other than file-order, >> it seems to me that those defined with #+ keywords should have >> precedence, because they are more visible, while those in drawers are >> hidden. >> - However, it seems to me that the simplest, most natural protocol would >> be for later declarations to override earlier ones. > > I think it would be quite natural to use the tree structure of Org. A > property setting in a subtree overrides the setting in a parent (which > could be the document(= the whole file.)) Hi Marco, I think you misunderstood his point #3 and my objection to it. :)
Re: [O] [RFC] Document level property drawer
Marco Wahl writes: > [..] > > I think the distinction between Org file and Org subtree should be kept > to a minimum. Wouldn't it be nice if Org files can be considered as Org > subtrees? Yes, this would be very nice. I have a related question or proposal. Up until now, I basically do not use property drawers except absolutely necessary, because properties are invisible by default. Properties "need to be inserted into a [..] drawer", and "in order to look inside the drawer, you need to move point to the drawer line and press ‘’ there." A place that comes to mind where I really would like to use properties is the header-args property in order to specify parameters related to tangling for all src blocks in certain subtrees. But for such properties to satisfactorily work for me, they would have to be visible by default. E.g. I would want the header-args to be immediately visible just like they are when they are written after #+BEGIN_SRC or #+HEADER. Otherwise I would find myself constantly wondering whether this or that property drawer contains something essential and every TAB on a collapsed headline would have be followed by an accompanying move to the property drawer and a TAB there. On the other hand, there are properties that are very good candidates for remaining hidden by default, like ID. I would like to be able to make a clear distinction between properties that are visible by default and properties that are not. Maybe it would be possible to allow some #+.. syntax following headings for subtree properties that are visible by default. A requirement could be made that such property specifications always have to be followed by a property drawer, even if that is empty. Then everything #+.. that is before the property drawer would belong to the heading/subtree, and everything #+.. that follows the drawer would be treated as it is until now. Please tell me if I missed something and Org is already capable of something like that. If not, are there others who would like visible-by-default property specifications for headings/subtrees in addition to invisible-by-default property specifications in drawers, too? Finally, I would like to state an opinion: If there is visible-by-default (by #+..) and invisible-by-default (by drawers) syntax for headings/subtrees, including level 0, it may be viable to require them to be disjoint for each heading/subtree. Most probably it would be good practice, anyway. And the precedence question raised previously in this thread would be eliminated.
Re: [O] [RFC] Document level property drawer
Hi Adam, > How does it differ from what was previously proposed? It differs by not introducing the document concept in Org element. Removing that means there is no reason to wait for another major version of Org mode. > What exactly does "will (shall)" mean? You can ignore the inside of the parentheses. It carries no important meaning. > > 3) Properties defined in a property drawer will have precedence over > >properties defined as a property keyword, if the same property is > >defined using both conventions. > > That protocol seems unnatural and confusing to me: > > - If precedence were to be defined by something other than file-order, > it seems to me that those defined with #+ keywords should have > precedence, because they are more visible, while those in drawers are > hidden. > - However, it seems to me that the simplest, most natural protocol would > be for later declarations to override earlier ones. I'd argue that precedence already works that way. One has to take inheritance into account. With inheritance turned on, tell me which value for Property1 is used for the nodes in the following example: #+begin_src org ,* Node 1 ,* Node 2 :PROPERTIES: :Property1: Value1 :END: ,#+PROPERTY: Property1 Value2 #+end_src As you'll see line number already isn't the deciding factor. With two ways to define properties it makes sense to first think of which syntax to promote as "more important" and then to think of precedence rules for duplicates within each syntax. Having the same syntax for node level 0 as for regular nodes makes the property functionality easy to understand and congruent. Something I think is worth promoting by saying that property blocks on file-level has precedence over the keyword syntax. > > 4) The position for the document level property drawer is: > >- At the first line in a file that is not a comment or a keyword. > > > > I.e. the following will work: > > > > #+begin_src org > ># -*- mode: org -*- > >,#+TITLE: Test > >:PROPERTIES: > >:CATEGORY: Test > >:END: > > > >Preamble > > > >,* Some heading > >Some content > > #+end_src > > > > > > but not this: > > > > #+begin_src org > >Some comment and/or empty line > > > >:PROPERTIES: > >:CATEGORY: Test > >:END: > > > >,* Some heading > >Some content > > #+end_src > > That feels unintuitive to me. Document-level property keywords may > appear anywhere in a file, so it seems inconsistent for document-level > property drawers to be limited in this way, as if there were an implied > headline at the top of the file. If it were so, I would expect to see > many mailing list posts by users asking why the properties defined in > their document-level property drawers aren't working. Given that there > is no enforcement in Org's UI to keep such drawers in certain places, I > think the implementation should be tolerant of users' preferences and > mistakes (cf. Postel's Law). 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. Regarding the placement of drawers, if you apply my patch on your end to test it out you'll see that the built in functionality to define properties creates the drawer for you. That's easy to do since it's positional rule is easy to derive by the system. Try for example org-set-property (C-c C-x p) and you'll get the drawer defined for you. In exactly the same way as it already works when you're inside a heading today. The lack of posts asking why properties defined on their outline nodes doesn't work tells me that positional requirements for property drawers already is well understood. Kind regards Gustav
Re: [O] [RFC] Document level property drawer
Adam Porter writes: > Gustav Wikström writes: > >> 3) Properties defined in a property drawer will have precedence over >>properties defined as a property keyword, if the same property is >>defined using both conventions. > > That protocol seems unnatural and confusing to me: > > - If precedence were to be defined by something other than file-order, > it seems to me that those defined with #+ keywords should have > precedence, because they are more visible, while those in drawers are > hidden. > - However, it seems to me that the simplest, most natural protocol would > be for later declarations to override earlier ones. I think it would be quite natural to use the tree structure of Org. A property setting in a subtree overrides the setting in a parent (which could be the document(= the whole file.)) >> 4) The position for the document level property drawer is: >>- At the first line in a file that is not a comment or a keyword. >> >> I.e. the following will work: >> >> #+begin_src org >># -*- mode: org -*- >>,#+TITLE: Test >>:PROPERTIES: >>:CATEGORY: Test >>:END: >> >>Preamble >> >>,* Some heading >>Some content >> #+end_src [...] > That feels unintuitive to me. Document-level property keywords may > appear anywhere in a file, so it seems inconsistent for document-level > property drawers to be limited in this way, as if there were an implied > headline at the top of the file. If it were so, I would expect to see > many mailing list posts by users asking why the properties defined in > their document-level property drawers aren't working. Given that there > is no enforcement in Org's UI to keep such drawers in certain places, I > think the implementation should be tolerant of users' preferences and > mistakes (cf. Postel's Law). TBH allowing document-level properties anywhere in an Org file looks rather messy to me. When a user is interested in all the document-level properties she needs to scan the whole file. Also the spread out document-level properties introduce a distinction between a whole Org file and an Org subtree. I think the distinction between Org file and Org subtree should be kept to a minimum. Wouldn't it be nice if Org files can be considered as Org subtrees? In this sense a property drawer for the document is a step in the right direction. Ciao, -- Marco
Re: [O] [RFC] Document level property drawer
Gustav Wikström writes: > Hi, > > This patch introduces a document level property drawer. > > This has been discussed previously in a larger context: > - https://lists.gnu.org/archive/html/emacs-orgmode/2019-06/msg0.html > - https://lists.gnu.org/archive/html/emacs-orgmode/2019-08/msg00339.html > - https://lists.gnu.org/archive/html/emacs-orgmode/2019-09/msg00010.html > > The patch is a somewhat modified version of what was included in the third > link above. How does it differ from what was previously proposed? > The following will be true for document level property drawers: > 1) In the same way that one can have a property drawer for a heading, one >can have a property drawer for a whole document. > 2) All existing commands that can work with property drawers will >(shall) work also on property drawers before the first heading. What exactly does "will (shall)" mean? > 3) Properties defined in a property drawer will have precedence over >properties defined as a property keyword, if the same property is >defined using both conventions. That protocol seems unnatural and confusing to me: - If precedence were to be defined by something other than file-order, it seems to me that those defined with #+ keywords should have precedence, because they are more visible, while those in drawers are hidden. - However, it seems to me that the simplest, most natural protocol would be for later declarations to override earlier ones. > 4) The position for the document level property drawer is: >- At the first line in a file that is not a comment or a keyword. > > I.e. the following will work: > > #+begin_src org ># -*- mode: org -*- >,#+TITLE: Test >:PROPERTIES: >:CATEGORY: Test >:END: > >Preamble > >,* Some heading >Some content > #+end_src > > > but not this: > > #+begin_src org >Some comment and/or empty line > >:PROPERTIES: >:CATEGORY: Test >:END: > >,* Some heading >Some content > #+end_src That feels unintuitive to me. Document-level property keywords may appear anywhere in a file, so it seems inconsistent for document-level property drawers to be limited in this way, as if there were an implied headline at the top of the file. If it were so, I would expect to see many mailing list posts by users asking why the properties defined in their document-level property drawers aren't working. Given that there is no enforcement in Org's UI to keep such drawers in certain places, I think the implementation should be tolerant of users' preferences and mistakes (cf. Postel's Law).
Re: [O] [RFC] Document level property drawer
Hi, > This patch introduces a document level property drawer. [...] > What do you say? I'll install the patch and have a look how it feels in my little personal Org universe. Thanks, -- Marco
[O] [RFC] Document level property drawer
Hi, This patch introduces a document level property drawer. This has been discussed previously in a larger context: - https://lists.gnu.org/archive/html/emacs-orgmode/2019-06/msg0.html - https://lists.gnu.org/archive/html/emacs-orgmode/2019-08/msg00339.html - https://lists.gnu.org/archive/html/emacs-orgmode/2019-09/msg00010.html The patch is a somewhat modified version of what was included in the third link above. The following will be true for document level property drawers: 1) In the same way that one can have a property drawer for a heading, one can have a property drawer for a whole document. 2) All existing commands that can work with property drawers will (shall) work also on property drawers before the first heading. 3) Properties defined in a property drawer will have precedence over properties defined as a property keyword, if the same property is defined using both conventions. 4) The position for the document level property drawer is: - At the first line in a file that is not a comment or a keyword. I.e. the following will work: #+begin_src org # -*- mode: org -*- ,#+TITLE: Test :PROPERTIES: :CATEGORY: Test :END: Preamble ,* Some heading Some content #+end_src but not this: #+begin_src org Some comment and/or empty line :PROPERTIES: :CATEGORY: Test :END: ,* Some heading Some content #+end_src What do you say? Regards Gustav Wikström 0001-Org-document-property-drawers.patch Description: 0001-Org-document-property-drawers.patch
