Re: [O] [RFC] Org document concept + document property drawers
Hi again, I'm separating the Org document concept from the document property drawer to not block the document property drawer by syntax changes. New RFC coming in a moment. Now only for the document property drawer functionality. /G > -Original Message- > From: Nicolas Goaziou > Sent: den 6 september 2019 22:10 > To: Gustav Wikström > Cc: emacs-orgmode@gnu.org > Subject: Re: [RFC] Org document concept + document property drawers > > Hello, > > Gustav Wikström writes: > > > I'm starting out slow by making this a non-breaking change. At least > > I'm trying to. I.e. everything that worked before should continue to > > work. > > This still is a syntax change, which is not to be taken lightly. Since > Org 9.3 is way overdue (I'm not blaming anyone for it, mind you), > I suggest to wait, and discuss about it with users meanwhile. I'll separate the patches and propose to go ahead with the document property drawer without the conceptual addition of Org documents in the parser. > > >> > Patch 0001 introduces the document element into org-element.el, and > >> > some restructuring related to that. > >> > >> This should be explained in comments, and, if it lands at some point, > >> Worg pages about syntax and exporter should be updated, too. > > > > Which comments do you mean? I've tried to be rigorous in the patch > > notes. But you mean in the mail itself? > > In the "org-element.el" file. There are some comments there. You could > add some info about the changes there. Got it. > > > Noted, except in this case I think it's warranted since > > org-back-to-heading behaves exactly the same with the exception of > > raising an error if before the first heading. Since both functions are > > defined next to another I'm sure a later refactor will take care of > > both since they're structurally identical and defined two lines apart. > > Your call. My call is to follow current pattern and make sure it's at least not adding any complexity for possible later refactor. > > > I've just "pattern-matched" myself into that docstring. It matches the > > existing definitions of org-at-drawer-p, org-at-comment-p, > > org-at-block-p. Which are defined around this. > > Then, these docstrings should be fixed too. Actually, "Non-nil if..." is > for variables with a boolean value. For predicates, like these > functions, it should be : "Return t if ...". > > See (info "(elisp) Documentation Tips") for more information about the > subject. Fixed existing docstrings in separate patch already pushed to master. > > Hmm... I see your point. Have to think a bit here - because I have the > > feeling that defining the predicate using org-element-at-point will > > incur quite a performance hit. > > Of course it will be slower. But "almost correct" predicates are also > bad, in other ways. Besides, it may be premature optimization at this > point. I've not made any changes to this just yet. It may be worth a revisit later though, because I do see your point. The issue is bigger than the one added predicate here though, and should most likely be looked at more holistically. I propose to take that in a separate change as refactoring isn't made more complicated by the patch I've suggested (although the amount of work will increase slightly). BR Gustav
Re: [O] [RFC] Org document concept + document property drawers
Hello, Gustav Wikström writes: > I'm starting out slow by making this a non-breaking change. At least > I'm trying to. I.e. everything that worked before should continue to > work. This still is a syntax change, which is not to be taken lightly. Since Org 9.3 is way overdue (I'm not blaming anyone for it, mind you), I suggest to wait, and discuss about it with users meanwhile. >> > Patch 0001 introduces the document element into org-element.el, and >> > some restructuring related to that. >> >> This should be explained in comments, and, if it lands at some point, >> Worg pages about syntax and exporter should be updated, too. > > Which comments do you mean? I've tried to be rigorous in the patch > notes. But you mean in the mail itself? In the "org-element.el" file. There are some comments there. You could add some info about the changes there. >> Keep in mind that Org Element library should ultimately be as >> independent as possible to the other parts of Org, including "org.el". > > Got it - is it preferred to do it the other way around - I.e. define > the regexp in org-element.el rather than org.el if there is use of the > regexp in both files? Currently, syntax regexp are mainly defined in "org.el". At some point, they could move into "org-element.el". Just something to keep in mind. > Noted, except in this case I think it's warranted since > org-back-to-heading behaves exactly the same with the exception of > raising an error if before the first heading. Since both functions are > defined next to another I'm sure a later refactor will take care of > both since they're structurally identical and defined two lines apart. Your call. > I've just "pattern-matched" myself into that docstring. It matches the > existing definitions of org-at-drawer-p, org-at-comment-p, > org-at-block-p. Which are defined around this. Then, these docstrings should be fixed too. Actually, "Non-nil if..." is for variables with a boolean value. For predicates, like these functions, it should be : "Return t if ...". See (info "(elisp) Documentation Tips") for more information about the subject. > Hmm... I see your point. Have to think a bit here - because I have the > feeling that defining the predicate using org-element-at-point will > incur quite a performance hit. Of course it will be slower. But "almost correct" predicates are also bad, in other ways. Besides, it may be premature optimization at this point. > Or what is your intuition regarding that? I think that if used correctly (i.e., not called too often), the overhead can be acceptable. In fact, by experience, this kind of function is hardly useful. I generally use Org Element higher up in functions, and can operate on the element with Org Element function without requesting another full parsing. YMMV. Regards, -- Nicolas Goaziou
Re: [O] [RFC] Org document concept + document property drawers
(Resending this mail due to formatting-issues. Sorry!) > From: Adam Porter > Subject: Re: [O] [RFC] Org document concept + document property drawers > Date: Sun, 01 Sep 2019 11:11:22 -0500 > > > #+begin_src org > > :PROPERTIES: > > :DIR: ~/ > > :ID: 730e0151-8e34-4dd9-b978-187c3c81e6b4 > > :CATEGORY: Test > > :END: > > > > Section 1 before first headline. > > > > ,* TODO Headline 1 > > Section 1 in first headline. > > > > ,** TODO Sub-headline 1 :Testtag: > > :PROPERTIES: > > :DIR: _2018/1809 Spark/ > > :CATEGORY: Test-cat > > :END: > > #+end_src > > If I may be honest, I don't feel very enthusiastic about this > document-level property drawer. I think it's because I'm accustomed to > thinking of property drawers as not affecting the entire document, and > expecting "#+KEYWORD:" for in-buffer settings. You can think of property drawers in exactly the same way as before. There is nothing magical about this drawer. Just think of a document as a level-0 node. Things won't be inherited into level-1 and above nodes unless explicitly set so by your configuration. In exactly the same way as was previously done. To be clear - this property drawer is not a substitute for all kinds of keywords - this drawer only aims at substituting the "#+PROPERTY:" keyword. The end goal is alignment of functionality, to make it more obvious both in code and for the user what a property is and how it's defined. > I do recognize the advantage of being able to collapse them to hide > clutter. However, as the manual explains, almost the same benefit can > be achieved by putting them in an outline node at the bottom of the > file, or in another file altogether: > > In-buffer settings may appear anywhere in the file, either directly > or indirectly through a file included using `#+SETUPFILE: filename' > syntax. > > I usually put a "Config" or "Footer" node at the bottom of the file, > marked "COMMENT" and ":noexport:", containing such settings that I don't > want cluttering the top of the file. Configurations is something else than setting properties in my opinion. I've addressed configurations in my first mail (calling them "settings", but "options" or "config" can be seen as synonyms if you like). Keywords today is a source of confusion. They are the multi-purpose swiss army knife for everything that didn't fit elsewhere. I'd like to change that too - I've done a fairly rigorous investigation of the multiple uses of keywords today. Simplifying how we use keywords will aid both users and plug-in developers, I'm sure. But that, too, is another topic! Not something that is a part of the patch I'm bringing forward here anyways. > > [1] Sidenote: We already define projects today when we declare that > > multiple files together are seen as our "agendas" for example. Or when > > we configure publishing. But we lack a common framework for what a > > "project" is in our code. > > As you said, that's another issue--however, if I may, I'll point out > that that's your concept of what "project" means, and not all users > think of a "project" in those terms. For example, it's not at all what > it means in "GTD" terms, which many Org users think in. Yes, project can be a dangerous word. A word of many meanings. I'm not very attached to it in this context but think it fits well even though it is overloaded. I'm a GTD'er myself and have learnt to separate the meaning of the word (any overloaded word really) depending on context. "Collection" might be another fitting word for what I have in mind. I'm not sure this thread is the place to share my thoughts about Org mode projects/collections though. We can start a separate thread for that if you like! Humbly Gustav
Re: [O] [RFC] Org document concept + document property drawers
> From: Adam Porter > Gustav Wikström writes: > > > Previous tree: > > (org-data nil CONTENTS) > > > > With this patch: > > (org-data nil (document (doc-props) CONTENTS)) > > > > Yeah.. The structure changed a bit. But it's a fairly trivial change > > in my opinion. Everything else works as before AFAIK... But I might be > > overseeing something. Please enlighten me in that case! > > Thanks, that's a helpful illustration of the difference. > > I'm glad that it only changes the result of parsing entire buffers. > That will limit the breakage. > > However, there is code in the wild that does parse entire buffers that > way. So that will break some code. At least the necessary changes > would be minor. > > However, if it does indeed precipitate a major Org version increment, > then such code will likely need to maintain compatibility with > older code for some time, because, like Emacs, Org versions tend to > stick around for a while. I'd like very much to avoid this patch be pushed into a major version update. Which leads me to think of your first suggestion to maybe provide some backwards-compatibility for the parser. Specifically for the insertion of the document-node in the syntax-tree. I'm not sure how to go about that in a nice way though. > Another question: how does this patch affect org-export backends? I've > only a passing familiarity with them. I'm guessing that some may break, > some of which may live outside of the Org repo. It might be a good idea > to take a look at some of the ones on MELPA to see if they would be > affected. I'm relying heavily on the test suite of org-mode for this, but I've only made a few lines of changes inside ox.el and as far as I can see no breakage at all for the respective built in exporters. Which leads me to believe that if some external exports are built on the ox.el core they'll have the same no-breakage behavior. Either that, or we have holes to patch in our test suite. Thanks again Adam for your comments! Regards Gustav
Re: [O] [RFC] Org document concept + document property drawers
> From: Adam Porter > > #+begin_src org > > :PROPERTIES: > > :DIR: ~/ > > :ID: 730e0151-8e34-4dd9-b978-187c3c81e6b4 > > :CATEGORY: Test > > :END: > > > > Section 1 before first headline. > > > > ,* TODO Headline 1 > > Section 1 in first headline. > > > > ,** TODO Sub-headline 1:Testtag: > > :PROPERTIES: > > :DIR: _2018/1809 Spark/ > > :CATEGORY: Test-cat > > :END: > > #+end_src > > If I may be honest, I don't feel very enthusiastic about this > document-level property drawer. I think it's because I'm accustomed to > thinking of property drawers as not affecting the entire document, and > expecting "#+KEYWORD:" for in-buffer settings. You can think of property drawers in exactly the same way as before. There is nothing magical about this drawer. Just think of a document as a level-0 node. Things won't be inherited into level-1 and above nodes unless explicitly set so by your configuration. In exactly the same way as was previously done. To be clear - this property drawer is not a substitute for all kinds of keywords - this drawer only aims at substituting the "#+PROPERTY:" keyword. The end goal is alignment of functionality, to make it more obvious both in code and for the user what a property is and how it's defined. > I do recognize the advantage of being able to collapse them to hide > clutter. However, as the manual explains, almost the same benefit can > be achieved by putting them in an outline node at the bottom of the > file, or in another file altogether: > > In-buffer settings may appear anywhere in the file, either directly > or indirectly through a file included using `#+SETUPFILE: filename' > syntax. > > I usually put a "Config" or "Footer" node at the bottom of the file, > marked "COMMENT" and ":noexport:", containing such settings that I don't > want cluttering the top of the file. Configurations is something else than setting properties in my opinion. I've addressed configurations in my first mail (calling them "settings", but "options" or "config" can be seen as synonyms if you like). Keywords today is a source of confusion. They are the multi-purpose swiss army knife for everything that didn't fit elsewhere. I'd like to change that too - I've done a fairly rigorous investigation of the multiple uses of keywords today. Simplifying how we use keywords will aid both users and plug-in developers, I'm sure. But that, too, is another topic! Not something that is a part of the patch I'm bringing forward here anyways. > > [1] Sidenote: We already define projects today when we declare that > > multiple files together are seen as our "agendas" for example. Or when > > we configure publishing. But we lack a common framework for what a > > "project" is in our code. > > As you said, that's another issue--however, if I may, I'll point out > that that's your concept of what "project" means, and not all users > think of a "project" in those terms. For example, it's not at all what > it means in "GTD" terms, which many Org users think in. Yes, project can be a dangerous word. A word of many meanings. I'm not very attached to it in this context but think it fits well even though it is overloaded. I'm a GTD'er myself and have learnt to separate the meaning of the word (any overloaded word really) depending on context. "Collection" might be another fitting word for what I have in mind. I'm not sure this thread is the place to share my thoughts about Org mode projects/collections though. We can start a separate thread for that if you like! Humbly Gustav
Re: [O] [RFC] Org document concept + document property drawers
Gustav Wikström writes: Hi Gustav, Thanks for your reply. I sent my most recent message, which reiterated my question, before this message of yours came through. >> This is a very interesting idea, and I don't want to dismiss your work, >> but I am concerned about how much third-party code will likely break by >> changing the results returned by org-element for parsing an Org buffer. >> I haven't thoroughly studied all of the code in your patches, so I may >> be wrong, but I think the breakage could be extensive. For example, >> simple operations like destructuring the results of org-element parsing >> functions may be broken. Have you done any investigation into this >> issue? >> >> Maybe there should be a transitional period in which the existing >> org-element parsing functions would work as before, and the new >> document-level elements would be returned by a new org-element >> document-level parsing function. Frankly, if there is breakage,the >> transition would probably take a few years, because there is a lot of >> code out there that has worked for years and may not be updated or >> replaced for years. > > I have not investigated much into that to be honest. I'd argue that > it's a fairly trivial change in terms of the parser though. Everything > will work as before except when you're after the whole buffer > syntax-tree. In that case one will have to dig one step deeper into > the tree to find the content. > > Previous tree: > (org-data nil CONTENTS) > > With this patch: > (org-data nil (document (doc-props) CONTENTS)) > > Yeah.. The structure changed a bit. But it's a fairly trivial change > in my opinion. Everything else works as before AFAIK... But I might be > overseeing something. Please enlighten me in that case! Thanks, that's a helpful illustration of the difference. I'm glad that it only changes the result of parsing entire buffers. That will limit the breakage. However, there is code in the wild that does parse entire buffers that way. So that will break some code. At least the necessary changes would be minor. However, if it does indeed precipitate a major Org version increment, then such code will likely need to maintain compatibility with older code for some time, because, like Emacs, Org versions tend to stick around for a while. Another question: how does this patch affect org-export backends? I've only a passing familiarity with them. I'm guessing that some may break, some of which may live outside of the Org repo. It might be a good idea to take a look at some of the ones on MELPA to see if they would be affected.
Re: [O] [RFC] Org document concept + document property drawers
Hi Adam, > This is a very interesting idea, and I don't want to dismiss your work, > but I am concerned about how much third-party code will likely break by > changing the results returned by org-element for parsing an Org buffer. > I haven't thoroughly studied all of the code in your patches, so I may > be wrong, but I think the breakage could be extensive. For example, > simple operations like destructuring the results of org-element parsing > functions may be broken. Have you done any investigation into this > issue? > > Maybe there should be a transitional period in which the existing > org-element parsing functions would work as before, and the new > document-level elements would be returned by a new org-element > document-level parsing function. Frankly, if there is breakage,the > transition would probably take a few years, because there is a lot of > code out there that has worked for years and may not be updated or > replaced for years. I have not investigated much into that to be honest. I'd argue that it's a fairly trivial change in terms of the parser though. Everything will work as before except when you're after the whole buffer syntax-tree. In that case one will have to dig one step deeper into the tree to find the content. Previous tree: (org-data nil CONTENTS) With this patch: (org-data nil (document (doc-props) CONTENTS)) Yeah.. The structure changed a bit. But it's a fairly trivial change in my opinion. Everything else works as before AFAIK... But I might be overseeing something. Please enlighten me in that case! I've made specification-changes only at two locations in the test-cases for org-element. (ref. patch nr.1) Best Gustav
Re: [O] [RFC] Org document concept + document property drawers
Gustav Wikström writes: > Nicolas requested a more thorough introduction to the patch so here it > comes. Thank you, this is helpful. > The first patch deals with formalities. It introduces one new greater > element called "document". Parsers and everything around it are > modified to work with this new concept. No new functionality is > introduced. I'd call this patch an "enabler" since it allows us to > (hopefully) reason better about intended behaviors and such moving > forward, but doesn't really do anything. I guess you mean that no new user-facing functionality is introduced, because it does introduce new functionality into the code, and as you say, it modifies "parsers and everything around it." > The second patch introduces property-drawers on document level. No > existing code will stop working, i.e. property keywords and all other > keywords will behave just as today. In my previous message in this thread, I asked about third-party packages and how your code may impact them. Would you please address that question specifically? Have you investigated this concern at all? I'm especially concerned about the results of org-element parsing functions changing, e.g. being nested inside an extra level of something like (document ...) would likely break a lot of code. As well, code that expects to find "in-buffer settings" in the form of "#+KEYWORD:", having been parsed by org-element, won't work properly if instead it finds document-level property drawers that are supposed to apply to the entire buffer. It's a very significant change that would have rippling effects on downstream code. > The first five lines in the following example will work just as > property drawers inside headings with this patch. All commands and > functions that work with "regular" property-drawers are updated to > work also with this document level drawer. > > #+begin_src org > :PROPERTIES: > :DIR: ~/ > :ID: 730e0151-8e34-4dd9-b978-187c3c81e6b4 > :CATEGORY: Test > :END: > > Section 1 before first headline. > > ,* TODO Headline 1 > Section 1 in first headline. > > ,** TODO Sub-headline 1:Testtag: > :PROPERTIES: > :DIR: _2018/1809 Spark/ > :CATEGORY: Test-cat > :END: > #+end_src If I may be honest, I don't feel very enthusiastic about this document-level property drawer. I think it's because I'm accustomed to thinking of property drawers as not affecting the entire document, and expecting "#+KEYWORD:" for in-buffer settings. I do recognize the advantage of being able to collapse them to hide clutter. However, as the manual explains, almost the same benefit can be achieved by putting them in an outline node at the bottom of the file, or in another file altogether: In-buffer settings may appear anywhere in the file, either directly or indirectly through a file included using `#+SETUPFILE: filename' syntax. I usually put a "Config" or "Footer" node at the bottom of the file, marked "COMMENT" and ":noexport:", containing such settings that I don't want cluttering the top of the file. > [1] Sidenote: We already define projects today when we declare that > multiple files together are seen as our "agendas" for example. Or when > we configure publishing. But we lack a common framework for what a > "project" is in our code. As you said, that's another issue--however, if I may, I'll point out that that's your concept of what "project" means, and not all users think of a "project" in those terms. For example, it's not at all what it means in "GTD" terms, which many Org users think in.
Re: [O] [RFC] Org document concept + document property drawers
Hi again, Nicolas requested a more thorough introduction to the patch so here it comes. To start with, this relates to the topic presented here: - https://lists.gnu.org/archive/html/emacs-orgmode/2019-06/msg0.html The first patch deals with formalities. It introduces one new greater element called "document". Parsers and everything around it are modified to work with this new concept. No new functionality is introduced. I'd call this patch an "enabler" since it allows us to (hopefully) reason better about intended behaviors and such moving forward, but doesn't really do anything. As an example I for one wouldn't mind to take it even one step further by introducing "project" as another concept[1]. But that is for another day. The second patch introduces property-drawers on document level. No existing code will stop working, i.e. property keywords and all other keywords will behave just as today. The first five lines in the following example will work just as property drawers inside headings with this patch. All commands and functions that work with "regular" property-drawers are updated to work also with this document level drawer. #+begin_src org :PROPERTIES: :DIR: ~/ :ID: 730e0151-8e34-4dd9-b978-187c3c81e6b4 :CATEGORY: Test :END: Section 1 before first headline. ,* TODO Headline 1 Section 1 in first headline. ,** TODO Sub-headline 1 :Testtag: :PROPERTIES: :DIR: _2018/1809 Spark/ :CATEGORY: Test-cat :END: #+end_src I wouldn't be surprised if I've managed to hide a few bugs in the code. But all tests, and a couple of new ones as well, signal an OK. Thoughts? Comments? Kind regards Gustav [1] Sidenote: We already define projects today when we declare that multiple files together are seen as our "agendas" for example. Or when we configure publishing. But we lack a common framework for what a "project" is in our code. > -Original Message- > From: Gustav Wikström > Sent: den 31 augusti 2019 20:50 > To: emacs-orgmode@gnu.org > Cc: Nicolas Goaziou ; Carsten Dominik > > Subject: [RFC] Org document concept + document property drawers > > Hi! > > I'm continuing on my proposal to introduce a "document" element in > org-mode and the idea of seeing everything before the first headline > as the base level 0 outline for a file. I've attached two patches that > I'd like some public review of before pushing to master. > > Patch 0001 introduces the document element into org-element.el, and > some restructuring related to that. > > Patch 0002 makes it possible to use property drawers at the document > level. I've hopefully covered all related commands to make this work. > And I've added a bunch of tests to guard against future regressions. > > Waiting for your comments! > > Kind regards Gustav
Re: [O] [RFC] Org document concept + document property drawers
Hi Nicolas, > -Original Message- > From: Nicolas Goaziou > > > I'm continuing on my proposal to introduce a "document" element in > > org-mode and the idea of seeing everything before the first headline > > as the base level 0 outline for a file. I've attached two patches that > > I'd like some public review of before pushing to master. > > I will not review fully the patches, as I have no time for that. > However, I will make a few comments about it. > > First, you should show a few examples of what an Org document would look > like, compared to what we have already, focusing particularly on the > advantages, and what is now invalid. It is a good thing to do if you > expect comments, as you cannot ask everyone to eyeball through the whole > patch set. Sure, I'll do that as a reply to my own mail to not make that comment disappear among the details here. > Also, whatever the outcome of the discussion is, /nothing should go in > master as long as Org 9.3 is not released/. This looks like a breaking > change at the most lower level (syntax, parser...), I think it may > trigger a new major release. I'm starting out slow by making this a non-breaking change. At least I'm trying to. I.e. everything that worked before should continue to work. > > Patch 0001 introduces the document element into org-element.el, and > > some restructuring related to that. > > This should be explained in comments, and, if it lands at some point, > Worg pages about syntax and exporter should be updated, too. Which comments do you mean? I've tried to be rigorous in the patch notes. But you mean in the mail itself? > > > ** (renamed, modified) org--setup-collect-keywords -> org-collect-keywords > > Renamed and generalized org--setup-collect-keywords to make it work > > for multiple purposes. Is not limited to a fixed set of keywords any > > longer. New name: org-collect-keywords. > > An important typo note: we use "Org mode", or "an Org document", not > "Org-mode" and "an org-document". Hyphens are only used to refer > explicitly to a Lisp symbol, or its value or function. Ah of course. I keep forgetting that one. > > > ** (modified) org-element-keyword-parser > > Uses (new) org-keyword-regexp instead of hardcoding it's own regexp. > > Keep in mind that Org Element library should ultimately be as > independent as possible to the other parts of Org, including "org.el". Got it - is it preferred to do it the other way around - I.e. define the regexp in org-element.el rather than org.el if there is use of the regexp in both files? > > +;; Org-element can parse org-mode documents. The top-node in the > > +;; parse-tree will always have TYPE `org-data' and PROPERTIES nil. > > See my remark about typography above. Got it. > > > +;; The following part creates a fully recursive org-mode parser. > > Ditto. Ok, ofc. > > +(defun org-back-to-heading-or-point-min ( invisible-ok) > > + "Go back to heading or first point in buffer. > > +If point is before first heading go to first point in buffer > > +instead of back to heading." > > + (condition-case nil > > + (outline-back-to-heading invisible-ok) > > +(error > > + (goto-char (point-min) > > Try to limit use of Outline functions. They are generally slower than > their Org counterpart. This is not true in this case, but, one day, we > might optimize `org-back-to-heading'. Noted, except in this case I think it's warranted since org-back-to-heading behaves exactly the same with the exception of raising an error if before the first heading. Since both functions are defined next to another I'm sure a later refactor will take care of both since they're structurally identical and defined two lines apart. > > +(defun org-at-keyword-p nil > > + "Is cursor at a keyword-line?" > > Non-nil if ... I've just "pattern-matched" myself into that docstring. It matches the existing definitions of org-at-drawer-p, org-at-comment-p, org-at-block-p. Which are defined around this. > > + (save-excursion > > +(move-beginning-of-line 1) > > +(looking-at org-keyword-regexp))) > > While this is technically correct today, please don't write a predicate > only based on regexps, use the parser for that. For example, the parser > can understand > > #+begin_example > #+keyword: not a keyword > #+end_example > > whereas your function cannot. Hmm... I see your point. Have to think a bit here - because I have the feeling that defining the predicate using org-element-at-point will incur quite a performance hit. Or what is your intuition regarding that? > > Also, you could use `org-match-line' in this case. > > > Regards, > > -- > Nicolas Goaziou Thanks for your initial thoughts. /G
Re: [O] [RFC] Org document concept + document property drawers
Hello, Gustav Wikström writes: > I'm continuing on my proposal to introduce a "document" element in > org-mode and the idea of seeing everything before the first headline > as the base level 0 outline for a file. I've attached two patches that > I'd like some public review of before pushing to master. I will not review fully the patches, as I have no time for that. However, I will make a few comments about it. First, you should show a few examples of what an Org document would look like, compared to what we have already, focusing particularly on the advantages, and what is now invalid. It is a good thing to do if you expect comments, as you cannot ask everyone to eyeball through the whole patch set. Also, whatever the outcome of the discussion is, /nothing should go in master as long as Org 9.3 is not released/. This looks like a breaking change at the most lower level (syntax, parser...), I think it may trigger a new major release. > Patch 0001 introduces the document element into org-element.el, and > some restructuring related to that. This should be explained in comments, and, if it lands at some point, Worg pages about syntax and exporter should be updated, too. > ** (renamed, modified) org--setup-collect-keywords -> org-collect-keywords > Renamed and generalized org--setup-collect-keywords to make it work > for multiple purposes. Is not limited to a fixed set of keywords any > longer. New name: org-collect-keywords. An important typo note: we use "Org mode", or "an Org document", not "Org-mode" and "an org-document". Hyphens are only used to refer explicitly to a Lisp symbol, or its value or function. > ** (modified) org-element-keyword-parser > Uses (new) org-keyword-regexp instead of hardcoding it's own regexp. Keep in mind that Org Element library should ultimately be as independent as possible to the other parts of Org, including "org.el". > +;; Org-element can parse org-mode documents. The top-node in the > +;; parse-tree will always have TYPE `org-data' and PROPERTIES nil. See my remark about typography above. > +;; The following part creates a fully recursive org-mode parser. Ditto. > +(defun org-back-to-heading-or-point-min ( invisible-ok) > + "Go back to heading or first point in buffer. > +If point is before first heading go to first point in buffer > +instead of back to heading." > + (condition-case nil > + (outline-back-to-heading invisible-ok) > +(error > + (goto-char (point-min) Try to limit use of Outline functions. They are generally slower than their Org counterpart. This is not true in this case, but, one day, we might optimize `org-back-to-heading'. > +(defun org-at-keyword-p nil > + "Is cursor at a keyword-line?" Non-nil if ... > + (save-excursion > +(move-beginning-of-line 1) > +(looking-at org-keyword-regexp))) While this is technically correct today, please don't write a predicate only based on regexps, use the parser for that. For example, the parser can understand #+begin_example #+keyword: not a keyword #+end_example whereas your function cannot. Also, you could use `org-match-line' in this case. Regards, -- Nicolas Goaziou
Re: [O] [RFC] Org document concept + document property drawers
Gustav Wikström writes: > I'm continuing on my proposal to introduce a "document" element in > org-mode and the idea of seeing everything before the first headline > as the base level 0 outline for a file. I've attached two patches that > I'd like some public review of before pushing to master. > > Patch 0001 introduces the document element into org-element.el, and > some restructuring related to that. > > Patch 0002 makes it possible to use property drawers at the document > level. I've hopefully covered all related commands to make this work. > And I've added a bunch of tests to guard against future regressions. > > Waiting for your comments! This is a very interesting idea, and I don't want to dismiss your work, but I am concerned about how much third-party code will likely break by changing the results returned by org-element for parsing an Org buffer. I haven't thoroughly studied all of the code in your patches, so I may be wrong, but I think the breakage could be extensive. For example, simple operations like destructuring the results of org-element parsing functions may be broken. Have you done any investigation into this issue? Maybe there should be a transitional period in which the existing org-element parsing functions would work as before, and the new document-level elements would be returned by a new org-element document-level parsing function. Frankly, if there is breakage,the transition would probably take a few years, because there is a lot of code out there that has worked for years and may not be updated or replaced for years.
