Re: Some commentary on the Org Syntax document

[Tom Gillespie <tgbugs@gmail.com>]

Hi Timothy,
    Replies in line. Best!
Tom

On Thu, Dec 2, 2021 at 1:32 AM Timothy <tecosaur@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