Re: [O] [RFC] Org document concept + document property drawers

[Nicolas Goaziou]

Hello,

Gustav Wikström <address@hidden> 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