Hello, Gustav Wikström <gus...@whil.se> 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
