Hi Timothy, Replies in line. Best! Tom On Thu, Dec 2, 2021 at 1:32 AM Timothy <tecos...@gmail.com> wrote: > > Hi All (& Nicolas in particular again), > > With my recent efforts to write a parser based on > <https://orgmode.org/worg/dev/org-syntax.html>, I’ve developed a few thoughts > on > that document. Hopefully, they can lead to some improvements and > clarifications. > > ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― > > As a general comment, in many places the Org Syntax document states what > characters a component can contain, but not what objects/elements. This feels > like a bit of a hole in the current specifications.
This is indeed confusing because there are some implicit constraints that are not listed because they never come up. For example, you cannot have two newlines inside an inline footnote because the two newlines break the paragraph and the thing that appears to be an inline footnote is just plain text that is never terminated. Ensuring that font locking is in sync org-element and org-export is critical to ensure that users know what will actually happen. > > > Sections > ════════ > > Heading > ─────── > > ⁃ Ok, so `TITLE' can have any character but a newline, but what Org > components can it contain? > I’m going to assume any object? Via org-element-object-restrictions it is standard-set-no-line-break which is all elements except citation-reference, table-cell, and line-break. > > > Affiliated Keywords > ═══════════════════ > > > Greater Elements > ════════════════ > > Greater blocks > ────────────── > > ⁃ It is not explained what is ment by a “special block” > ⁃ Aren’t lines starting with `#+' also quoted by a comma? > > > Drawers and Property Drawers > ──────────────────────────── > > ⁃ “Contents can contain any element but another drawer” > • Does “any element” mean “any Element or Greater Element” Any element that does not have greater precedence, so that would be only a heading. > > Dynamic Blocks > ────────────── > > ⁃ It is not specified what `CONTENTS' may be Implicitly follows the same rules as drawers, no headings and no nesting of dynamic blocks. Text should be added that states this explicitly. > ⁃ Surely `PARAMETERS' cannot contain a newline? Termination by newline is implicit in the example, but the text is confusing. > Plain Lists and Items > ───────────────────── > > ⁃ It is not completely clear what content an item may have. > I assume any Object? By my reading it may contain anything, objects and elements, except for a heading, but that is already implied by the de-indent. To quote from the docs: An item ends before the next item, the first line less or equally indented than its starting line, or two consecutive empty lines. Indentation of lines within other greater elements do not count, neither do inlinetasks boundaries. This makes plain lists one of the most complex elements to parse. > > Tables > ────── > > ⁃ Surely newlines are not allowed in `FORMULAS' No newlines are implicit in the use of "lines" but still confusing. > > Elements > ════════ > > Clocks > ────── > > Two allowed forms are listed, but are all four of the below allowed or only > two? > ┌──── > │ CLOCK: INACTIVE-TIMESTAMP > │ CLOCK: INACTIVE-TIMESTAMP DURATION > │ CLOCK: INACTIVE-TIMESTAMP-RANGE > │ CLOCK: INACTIVE-TIMESTAMP-RANGE DURATION > └──── No. Only the two are allowed. An inactive timestamp alone is a starting point, adding a duration without the end point means that there is no way to check that the range and duration match. > All the best, > Timothy