From: Tom Gillespie <tgbugs@gmail.com>
To: Timothy <tecosaur@gmail.com>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Some commentary on the Org Syntax document
Date: Thu, 2 Dec 2021 11:00:39 -0800 [thread overview]
Message-ID: <CA+G3_POCnBGU1pb4pZXm7iBpZDX-LevE3QJFPrE7vPDJ_jpLbw@mail.gmail.com> (raw)
In-Reply-To: <87mtljpd1w.fsf@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
next prev parent reply other threads:[~2021-12-02 19:01 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-02 9:23 Some commentary on the Org Syntax document Timothy
2021-12-02 19:00 ` Tom Gillespie [this message]
2021-12-02 19:16 ` Timothy
2021-12-04 5:26 ` Tom Gillespie
2021-12-04 6:17 ` Ihor Radchenko
2021-12-04 6:48 ` Timothy
2021-12-04 7:40 ` Ihor Radchenko
2021-12-04 8:09 ` Timothy
2021-12-04 9:41 ` Nicolas Goaziou
2021-12-04 14:00 ` Ihor Radchenko
2021-12-04 14:43 ` Nicolas Goaziou
2021-12-05 6:30 ` Ihor Radchenko
2021-12-05 9:28 ` Nicolas Goaziou
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CA+G3_POCnBGU1pb4pZXm7iBpZDX-LevE3QJFPrE7vPDJ_jpLbw@mail.gmail.com \
--to=tgbugs@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=tecosaur@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).