Feedback on Org syntax document

Feedback on Org syntax document

[Ihor Radchenko]

Hi,

It has been a while since I looked into the Org syntax document at
https://orgmode.org/worg/dev/org-syntax.html. So, I am not again ready
to see and comment on things with a fresh eye.

Below, I am listing my further feedback on the document.
I encourage other Org users to look into it as well.
This is one of the big projects that need to be finished as a
prerequisite for registering Org format in RFC:

Submit an IETF RFC to register Org as a MIME type
https://list.orgmode.org/87r1qt9cf0.fsf@gnu.org/

I also answered all the notes. I think that we should remove them for
good and instead spin off email treads from here, if necessary.

-------------

1. Introduction
> Should markdown be mentioned at all?
I see no problem with it.

> 2.2. The minimal and standard sets of objects

> excluding citation references and table cells.

"citation references" could be a link to the relevant 4.6 section.

> 2.4. Indentation

We can mention that Org parser discards common indentation.
For example

   This paragraph will not contain
   a long sequence of spaces before "a".

Also,

   This paragraph does not have leading spaces according to the parser.

This feature is also important in src blocks for whitespace-sensitive
programming languages.

> 3.1.1. Headings
> TITLE (optional)
> A series of objects from the standard set, excluding line break
> objects. It is matched after every other part.

"after every other part" is a bit confusing. I would name what exactly
is matches (KEYWORD and PRIORITY).

Also, at least one space is mandatory after STARS.

> If the TITLE of a heading is exactly the value of org-footnote-section
> (Footnotes by default)

I think that we can clarify a bit about using lisp variables across the
document in 2. Terminology and conventions.

> All content following a heading — up to either the next heading, or
> the end of the document, forms a section contained by the heading.
> This is optional, as the next heading may occur immediately in which
> case no section is formed.

Note that leading blank lines after heading before section are not
included into the section.

In particular, this means that

* Heading without section, but with blank lines


* Another heading with section

This is a section. It includes everything from "This is" down to "Last
heading", including the trailing blank lines.

* Last heading


Top-section follows the same rule:

---------

Paragraph after blank lines after bob. The parent section starts at
"Paragraph".

> Since sections are usually thought of as a larger group that includes
> nested content (e.g. “section 3”), and this isn’t what Org sections
> are, maybe this should be called something slightly different?

Org manual indeed uses "section" as a larger group. In contrast to the
parser.

However, it is difficult to rename section element in Org code for
backwards compatibility reasons. I do not see any easy way to rename
sections, unfortunately.

Thus, I am inclined to keep "section" in Org parser's sense within
syntax document. Possibly, adding a visible disclaimer to the syntax
document.

> 3.2.1. Greater Blocks
> A collection of zero or more elements, subject to two conditions:
>   No line may start with #+end_NAME.

There is just one condition.

> 3.2.4. Footnote Definitions
> [fn:LABEL] CONTENTS
> LABEL
> Either a number or an instance of the pattern fn:WORD, where WORD
> represents a string consisting of word-constituent characters, hyphens
> and underscores (-_).

This is a bit misleading. I am reading this as "LABEL .. an instance of
... fn:WORD ...", which implies [fn:fn:WORD].

> 3.2.5. Inlinetasks
> Urgh, this syntax is ugly. — Tom G, Timothy

Oh, well. This note is not very useful. Lets remote it. You'd better
open a feature request.

> 3.2.6. Items
> TAG (optional)
> ... does not contain the substring "\nbsp{}::\nbsp{}"

What is \nbsp? Something is likely wrong with Org source formatting.

> 3.2.7. Plain Lists
> At a glance it may appear as though nested lists are not possible.
> They are, as items may themselves contain lists.

I am stumbling upon this wording. Maybe

  Note that item elements can contain nested plain list elements.

> if both types are present consecutively then they parse as separate
> lists.

"are parsed"?

> (ordered-plain-list
> (item)
> (item
>  (descriptive-plain-list
>   (item))))

This is wrong. Need

(ordered-plain-list
 (item
   (paragraph))
 (item
  (paragraph)
  (descriptive-plain-list
   (item
     (paragraph)))))

> The failure mode for malformed contents needs to be determined more
> clearly here. We don’t want property draws to suddenly become plain
> drawers just because a user has a malformed line, that could be
> disastrous if certain settings in the property drawer mask settings
> from further up the tree. In short, malformed contents should not
> poison the whole property drawer. — Tom G

Yet, malformed property drawers do become ordinary drawers. If we want
to do something about this, let's discuss in a separate thread.

> Example

> :PROPERTIES:
> :CUSTOM_ID: someid
> :END:

This example does not include a heading, which might be misleading.

Also, it is a good idea to mention top-level property drawer and provide
examples.

> Maybe drop table.el from the spec?

No.

> Can we drop switch support? This seems like a fairly good idea. The functionality can simply be shifted to ARGUMENTS with the well-established :key val forms.
> “For the love of all that is sane” — Tom G

I believe that it is a good idea to drop switches _from syntax document_.
For the Org parser, we should first deprecate it.

> 3.3.4. Planning

> Tom G has requested adding a OPENED keyword to track task
> creation/registration.

Let's discuss it in a separate thread.

> 3.3.8. Keywords

> Perhaps this should be changed to be #+KEY[OPT]: VAL? It would make
> the syntax more regular, considering affiliated keywords. I can’t see
> any backwards compatibility concerns.
> This was suggested by Tom G, but I’m a fan — Timothy.

I think that it is a good idea. Also, see my comment on affiliated
keywords below.

> 3.3.8. Keywords
> Note that while instances of this pattern are preferentially parsed as
> affiliated keywords

Affiliated keywords are described later, making this paragraph hard to
digest. Maybe we can restructure this section to described special
keywords (affiliated and call) first?

> Should this be distinguished from other keywords at the AST
> interpretation stage, instead of the base syntax? — Tom G

I am not sure if I understand the issue. AST has a special babel-call
element.

> Repeating an affiliated keyword before an element will usually result
> in the prior VALUEs being overwritten by the last instance of KEY. The
> sole exception to this is #+header: keywords, where in the case of
> multiple :opt val declarations the last declaration on the first line
> it occurs on has priority.

This is not accurate.
We may instead follow `org-element--collect-affiliated-keywords' and describe
`org-element-keyword-translation-alist', `org-element-parsed-keywords',
`org-element-dual-keywords', and `org-element-multiple-keywords'.

However, I feel like this level of detail is probably too much for
syntax description. If we describe these details, we will restrict
ourselves from possible future syntax extensions. Moreover, merging
certain keywords in AST means that `org-element-interpret-data' simply
cannot recover the original document structure.

I will create a separate thread detailing some ideas on what we may
change in this area.

> 3.3.12. Table Rows
> Table rows can only exist in tables.

Only in Org type tables.

> 4.1. Entities
> It’s been raised that “{}” is really part of the entity, and so probably shouldn’t be considered part of POST — Timothy.

Yes. Please, fix the entity syntax description.

> 4.2. LaTeX Fragments
> It would introduce incompatibilities with previous Org versions, but
> support for $...$ (and for symmetry, $$...$$) constructs ought to be
> removed.

Let's discuss in a separate thread.

> 4.5. Citations

>  and it does not contain any semicolons (;) or subsequence that
>  matches @KEY.

I think that we need to add \semicolon and \at entities to allow
escaping.

> 4.9. Line Breaks
> SPACE
> Zero or more tab and space characters.

Note that pretty much every object includes trailing whitespace. We
should probably mention that.

Also, \\\ is not a line break -- we need to provide PRE\\SPACE pattern
in the description. PRE being not "\".

> 4.10.1. Radio Links
> Is the raw (unparsed) text or the parsed structure matched with radio links?

Unparsed text cannot contain objects.

> 4.13. Statistics Cookies
> A number.

Positive integer.

> 4.15. Table Cells
> The final vertical bar (|) may be omitted in the last cell of a table
> row.

I think that it will be clearer to define cells as

CONTENTS SPACES|
CONTENTS SPACES EOL

> 4.16. Timestamps
> TIME (optional)
> An instance of the pattern H:MM where H represents a one to two digit number (and can start with 0), and M represents a single digit.
> Tom G has some syntax extensions he’d like to suggest for historical /
> far-future dates, timezone offsets, and second/sub-second times.

I agree. We can allow non-whitespace after H:MM for forward-compatibility.

In particular, I have seen 9:34.05+000 to define seconds and time zone.

> Summary of changes compared to the current org-syntax document

Should probably be removed at this point.

>  Org Entities

> Idot
&idot; ??

> shy
Empty HTML representation

> WHITESPACE

That does not look helpful in HTML.

> zwnj
same

> =_ =
???

Also, footnote 12 looks wrong.


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Feedback on Org syntax document

[Ihor Radchenko]

[-- Attachment #1: Type: text/plain, Size: 450 bytes --]

Ihor Radchenko <yantar92@posteo.net> writes:

> Below, I am listing my further feedback on the document.
> I encourage other Org users to look into it as well.
> This is one of the big projects that need to be finished as a
> prerequisite for registering Org format in RFC:

I have addressed the most important comments that should be resolved
before the coming Org release.

See the attached patches.

I will merge them if there are no objections.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-dev-org-syntax.org-Remove-all-the-notes.patch --]
[-- Type: text/x-patch, Size: 6817 bytes --]

From f411e423214c113ef44ba23b09093395d7910e0c Mon Sep 17 00:00:00 2001
Message-Id: <f411e423214c113ef44ba23b09093395d7910e0c.1669442423.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sat, 26 Nov 2022 10:44:13 +0800
Subject: [PATCH 1/4] * dev/org-syntax.org: Remove all the notes

They are to be discussed on mailing list.  See
https://orgmode.org/list/877d08bkze.fsf@localhost
---
 dev/org-syntax.org | 86 ----------------------------------------------
 1 file changed, 86 deletions(-)

diff --git a/dev/org-syntax.org b/dev/org-syntax.org
index a249d011..c7e9ad60 100644
--- a/dev/org-syntax.org
+++ b/dev/org-syntax.org
@@ -43,10 +43,6 @@ * Introduction
 lightweight markup language.  However, while Markdown refers to a
 collection of similar syntaxes, Org is a single syntax.
 
-#+begin_notes
-Should markdown be mentioned at all?
-#+end_notes
-
 This document describes and comments on Org syntax as it is currently
 read by its parser (=org-element.el=) and, therefore, by the export
 framework. This is intended as a technical document for developers and
@@ -233,12 +229,6 @@ *** Sections
 of the text before the first heading in a document (which is
 considered a section), sections only occur within headings.
 
-#+begin_notes
-Since sections are usually thought of as a larger group that includes
-nested content (e.g. "section 3"), and this isn't what Org sections are,
-maybe this should be called something slightly different?
-#+end_notes
-
 *Example*
 
 Consider the following document:
@@ -393,10 +383,6 @@ *** Inlinetasks
 components (i.e. only STARS and TITLE provided) and the string =END= as
 the TITLE. This allows the inlinetask to contain elements.
 
-#+begin_notes
-Urgh, this syntax is ugly. --- Tom G, Timothy
-#+end_notes
-
 *Examples*
 
 #+begin_example
@@ -523,14 +509,6 @@ *** Property Drawers
 + CONTENTS :: A collection of zero or more [[#Node_Properties][node properties]], not
   separated by blank lines.
 
-#+begin_notes
-The failure mode for malformed contents needs to be determined more clearly
-here. We don't want property draws to suddenly become plain drawers just because
-a user has a malformed line, that could be disastrous if certain settings in the
-property drawer mask settings from further up the tree. In short, malformed
-contents should not poison the whole property drawer. --- Tom G
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -549,10 +527,6 @@ *** Tables
 + The string =+-= followed by a sequence of plus (=+=) and minus (=-=)
   signs, forming a "table.el" type table.
 
-#+begin_notes
-Maybe drop table.el from the spec?
-#+end_notes
-
 Tables cannot be immediately preceded by such lines, as the current
 line would the be part of the earlier table.
 
@@ -627,13 +601,6 @@ *** Blocks
   CONTENTS will contain Org objects and not support comma-quoting when
   the block is a verse block, it is otherwise not parsed.
 
-#+begin_notes
-Can we drop switch support? This seems like a fairly good idea.
-The functionality can simply be shifted to ARGUMENTS with the
-well-established =:key val= forms.\\
-"For the love of all that is sane" --- Tom G
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -715,10 +682,6 @@ *** Planning
 When a keyword is repeated in a planning element, the last instance of it has
 priority.
 
-#+begin_notes
-Tom G has requested adding a =OPENED= keyword to track task creation/registration.
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -785,13 +748,6 @@ *** Keywords
   than =call= (which would forms a [[#Babel_Call][babel call]] element).
 + VALUE :: A string consisting of any characters but a newline.
 
-#+begin_notes
-Perhaps this should be changed to be =#+KEY[OPT]: VAL=? It would make the syntax
-more regular, considering affiliated keywords. I can't see any backwards
-compatibility concerns. \\
-This was suggested by Tom G, but I'm a fan --- Timothy.
-#+end_notes
-
 When KEY is a member of ~org-element-parsed-keywords~[fn:oepkw], VALUE can contain
 the standard set objects, excluding footnote references.
 
@@ -823,11 +779,6 @@ **** Babel Call
   non-newline characters.  Opening and closing square brackets must be
   balanced.
 
-#+begin_notes
-Should this be distinguished from other keywords at the AST
-interpretation stage, instead of the base syntax? --- Tom G
-#+end_notes
-
 **** Affiliated Keywords
 :PROPERTIES:
 :CUSTOM_ID: Affiliated_Keywords
@@ -869,22 +820,12 @@ **** Affiliated Keywords
   is a series of objects from the standard set, excluding footnote
   references.
 
-#+begin_notes
-Should this even be described at a syntax level instead of an AST
-processing level? --- Tom G
-#+end_notes
-
 Repeating an affiliated keyword before an element will usually result
 in the prior VALUEs being overwritten by the last instance of KEY.
 The sole exception to this is =#+header:= keywords, where in the case of multiple
 =:opt val= declarations the last declaration on the first line it occurs on has
 priority.
 
-#+begin_notes
-Maybe this should be first-line-wins for all affiliated keywords?
-This would be a breaking change though. --- Timothy
-#+end_notes
-
 There are two situations under which the VALUEs will be concatenated:
 1. If KEY is a member of ~org-element-dual-keywords~[fn:oedkw].
 2. If the affiliated keyword is an instance of the pattern
@@ -1016,11 +957,6 @@ ** Entities
   - The string ={}=.
   - A non-alphabetic character.
 
-#+begin_notes
-It's [[https://github.com/lucasvreis/org-parser/blob/main/SPEC.org#entities][been raised]] that "{}" is really part of the entity, and so
-probably shouldn't be considered part of POST --- Timothy.
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -1089,19 +1025,6 @@ ** LaTeX Fragments
 $$1+1=2$$
 #+end_example
 
-#+begin_notes
-It would introduce incompatibilities with previous Org versions,
-but support for ~$...$~ (and for symmetry, ~$$...$$~) constructs
-ought to be removed.
-
-They are slow to parse, fragile, redundant and imply false
-positives.  --- NGZ
-
-Strong support for removing these.  --- Tom G
-
-I'm strongly in support of dropping $-syntax.  --- Timothy
-#+end_notes
-
 ** Export Snippets
 :PROPERTIES:
 :CUSTOM_ID: Export_Snippets
@@ -1281,10 +1204,6 @@ *** Radio Links
   contain the minimal set of objects.
 + [[#Special_Tokens][POST]] :: A non-alphanumeric character.
 
-#+begin_notes
-Is the raw (unparsed) text or the parsed structure matched with radio links?
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -1553,11 +1472,6 @@ ** Timestamps
 There can be two instances of =REPEATER-OR-DELAY= in the timestamp: one
 as a repeater and one as a warning delay.
 
-#+begin_notes
-Tom G has some syntax extensions he'd like to suggest for historical /
-far-future dates, timezone offsets, and second/sub-second times.
-#+end_notes
-
 *Examples*
 
 #+begin_example
-- 
2.35.1


[-- Attachment #3: 0002-dev-org-syntax.org-Address-some-comments.patch --]
[-- Type: text/x-patch, Size: 11211 bytes --]

From b01a41c7a956ff053634fe2e8cdab34dc78f232a Mon Sep 17 00:00:00 2001
Message-Id: <b01a41c7a956ff053634fe2e8cdab34dc78f232a.1669442423.git.yantar92@posteo.net>
In-Reply-To: <f411e423214c113ef44ba23b09093395d7910e0c.1669442423.git.yantar92@posteo.net>
References: <f411e423214c113ef44ba23b09093395d7910e0c.1669442423.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sat, 26 Nov 2022 13:52:50 +0800
Subject: [PATCH 2/4] * dev/org-syntax.org: Address some comments

(The minimal and standard sets of objects): Link to table cell object
section.
(Indentation): Mention that common indentation is discarded.
(References to lisp variables): Add section explaining references to
variables.
(Headings): Highlight that space after asterisk is mandatory.  Clarify
wording.
(Sections): Highlight that leading blank lines are not included into
sections.
(Greater Blocks): Fix wording.
(Footnote Definitions): Fix pattern.
(Items): Do not use entities inside verbatim.
(Plain Lists): Reword.  Fix example.
(Property Drawers): Describe property drawer in zeroth section.
Improve example.
(Table Rows): Clarify that rows can only be a part of Org type
tables.
(Objects): Clarify about spaces after objects.
(Entities): Add separate \NAME{} pattern.
(Line Breaks): Clarify that "\" is not allowed before page breaks.
(Statistics Cookies): Limit numbers to positive integers.
(Table Cells): Clarify that "|" is optional before eol.
(Timestamps): Allow arbitrary characters after time.
---
 dev/org-syntax.org | 109 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 86 insertions(+), 23 deletions(-)

diff --git a/dev/org-syntax.org b/dev/org-syntax.org
index c7e9ad60..e07564cd 100644
--- a/dev/org-syntax.org
+++ b/dev/org-syntax.org
@@ -82,7 +82,7 @@ ** The minimal and standard sets of objects
 useful sets.  The /<<<minimal set>>> of objects/ refers to [[#Plain_Text][plain text]], [[#Emphasis_Markers][text
 markup]], [[#Entities][entities]], [[#LaTeX_Fragments][LaTeX fragments]], [[#Subscript_and_Superscript][superscripts and subscripts]].  The
 /<<<standard set>>> of objects/ refers to the entire set of objects, excluding
-citation references and [[#Table_Cells][table cells]].
+[[#Citation references][citation references]] and [[#Table_Cells][table cells]].
 
 ** Blank lines
 
@@ -98,10 +98,22 @@ ** Blank lines
 ** Indentation
 
 Indentation consists of a series of space and tab characters at the
-beginning of a line. Most elements can be indentated, with the
+beginning of a line.  Most elements can be indentated, with the
 exception of [[#Headings][headings]], [[#Inlinetasks][inlinetasks]], [[#Footnote_Definitions][footnote definitions]], and [[#Diary_Sexp][diary
 sexps]].  Indentation is only syntactically meaningful in plain lists.
 
+The common indentation of all the lines within an element is
+discarded.  This also applies to single-line elements.
+
+*Examples*
+
+#+begin_example
+   This paragraph will not contain
+   a long sequence of spaces before "a".
+
+   This paragraph does not have leading spaces according to the parser.
+#+end_example
+
 ** Syntax patterns
 
 *** General form
@@ -153,6 +165,16 @@ *** Case significance
 
 In this document, unless specified otherwise, case is insignificant.
 
+** References to lisp variables
+
+Some parts of Org syntax are configurable via special keywords in the
+file or via Elisp settings in Emacs.  This syntax document exposes
+these variable parts by referencing to Elisp variables.
+
+Elisp programs utilizing the syntax may directly refer to the Elisp
+variable values.  Other users of this syntax reference can use to the
+default values we provide here.
+
 * Elements
 :PROPERTIES:
 :CUSTOM_ID: Elements
@@ -175,7 +197,8 @@ *** Headings
 + STARS :: A string consisting of one or more asterisks (up to
   ~org-inlinetask-min-level~ if the =org-inlinetask= library is loaded)
   suffixed by a space character.  The number of asterisks is used to
-  define the level of the heading.
+  define the level of the heading.  Space character after asterisks is
+  mandatory.
 
 + KEYWORD (optional) :: A string which is a member of
   ~org-todo-keywords-1~[fn:otkw1:By default, ~org-todo-keywords-1~ only
@@ -191,7 +214,8 @@ *** Headings
   is called a "priority cookie".
 
 + TITLE (optional) :: A series of objects from the standard set,
-  excluding line break objects.  It is matched after every other part.
+  excluding line break objects.  It is matched after =KEYWORD= and
+  =PRIORITY=.
 
 + TAGS (optional) :: A series of colon-separated strings consisting of
   alpha-numeric characters, underscores, at signs, hash signs, and
@@ -254,6 +278,23 @@ *** Sections
    (heading))))
 #+end_example
 
+Sections do not include blank lines immediately following the parent
+heading.  It also means that headings containing only blank lines do
+not contain any section.
+
+#+begin_example
+,* Heading without section, but with blank lines
+
+,* Another heading with section
+
+This is a section. It includes everything from "This is" down to "Last
+heading", including the trailing blank lines.
+
+,* Last heading
+#+end_example
+
+[[#The zeroth section][Zeroth section]] follows the same rule.
+
 *** The zeroth section
 :PROPERTIES:
 :CUSTOM_ID: Zeroth_section
@@ -301,8 +342,8 @@ *** Greater Blocks
   - any other value, a "special block"
 + PARAMETERS (optional) :: A string consisting of any characters other
   than a newline.
-+ CONTENTS :: A collection of zero or more elements, subject to two
-  conditions:
++ CONTENTS :: A collection of zero or more elements, subject to the
+  following condition:
   - No line may start with =#+end_NAME=.
 
 *** Drawers and Property Drawers
@@ -349,7 +390,7 @@ *** Footnote Definitions
 [fn:LABEL] CONTENTS
 #+end_example
 
-+ LABEL :: Either a number or an instance of the pattern =fn:WORD=, where
++ LABEL :: Either a number or an instance of the pattern =WORD=, where
   =WORD= represents a string consisting of word-constituent characters,
   hyphens and underscores (=-_=).
 
@@ -423,7 +464,7 @@ *** Items
   character, or a hyphen enclosed by square brackets (i.e. =[ ]=, =[X]=, or =[-]=).
 + TAG (optional) :: An instance of the pattern =TAG-TEXT ::= where
   =TAG-TEXT= represents a string consisting of non-newline characters
-  that does not contain the substring ="\nbsp{}::\nbsp{}"= (two colons surrounded by
+  that does not contain the substring =" :: "= (two colons surrounded by
   whitespace, without the quotes).
 + CONTENTS (optional) :: A collection of zero or more elements, ending
   at the first instance of one of the following:
@@ -451,8 +492,8 @@ *** Plain Lists
 A /plain list/ is a set of consecutive [[#Items][items]] of the same indentation.
 
 #+begin_info
-At a glance it may appear as though nested lists are not possible. They are, as
-items may themselves contain lists.
+Note that item elements can contain other lists.  This allows creating
+nested lists.
 #+end_info
 
 If first item in a plain list has a COUNTER in its BULLET, the plain
@@ -474,10 +515,13 @@ *** Plain Lists
 
 #+begin_example
 (ordered-plain-list
- (item)
  (item
+   (paragraph))
+ (item
+  (paragraph)
   (descriptive-plain-list
-   (item))))
+   (item
+     (paragraph)))))
 #+end_example
 
 *** Property Drawers
@@ -498,6 +542,17 @@ *** Property Drawers
 PROPERTYDRAWER
 #+end_example
 
+Property drawer can also be present in [[#Zeroth_section][zeroth section]]:
+
+#+begin_example
+BEGINNING-OF-FILE
+BLANK-LINES
+COMMENT
+PROPERTYDRAWER
+#+end_example
+
+=BLANK-LINES= and =COMMENT= are optional.
+
 Property Drawers are structured according to the following pattern:
 
 #+begin_example
@@ -512,6 +567,7 @@ *** Property Drawers
 *Example*
 
 #+begin_example
+,* Heading
 :PROPERTIES:
 :CUSTOM_ID: someid
 :END:
@@ -909,7 +965,7 @@ *** Table Rows
 + A hyphen (=-=), forming a "rule" type row.  Any non-newline characters
   can follow the hyphen and this will still be a "rule" type row
 
-Table rows can only exist in [[#Tables][tables]].
+Table rows can only exist in [[#Tables][tables]] with Org type.
 
 * Objects
 :PROPERTIES:
@@ -936,15 +992,19 @@ * Objects
 blank line often terminates the element that the object is a part of,
 such as a paragraph.
 
+Trailing spaces at the end of objects are considered a part of those
+objects.
+
 ** Entities
 :PROPERTIES:
 :CUSTOM_ID: Entities
 :END:
 
-Entities are structured according to the following pattern:
+Entities are structured according to the following patterns:
 
 #+begin_example
 \NAME POST
+\NAME{}
 #+end_example
 
 Where NAME and POST are not separated by a whitespace character.
@@ -954,7 +1014,6 @@ ** Entities
   ~org-entities-user~.
 + [[#Special_Tokens][POST]] :: Either:
   - The end of line.
-  - The string ={}=.
   - A non-alphabetic character.
 
 *Example*
@@ -1178,9 +1237,10 @@ ** Line Breaks
 are structured according to the following pattern:
 
 #+begin_example
-\\SPACE
+PRE\\SPACE
 #+end_example
 
++ [[#Special_Tokens][PRE]] :: Anything but backspace (=\=). 
 + SPACE :: Zero or more tab and space characters.
 
 ** Links
@@ -1371,9 +1431,9 @@ ** Statistics Cookies
 [NUM1/NUM2]
 #+end_example
 
-+ PERCENT (optional) :: A number.
-+ NUM1 (optional) :: A number.
-+ NUM2 (optional) :: A number.
++ PERCENT (optional) :: A non-negative integer.
++ NUM1 (optional) :: A non-negative integer.
++ NUM2 (optional) :: A non-negative integer.
 
 ** Subscript and Superscript
 :PROPERTIES:
@@ -1414,10 +1474,11 @@ ** Table Cells
 :CUSTOM_ID: Table_Cells
 :END:
 
-Table cells are structured according to the following pattern:
+Table cells are structured according to the following patterns:
 
 #+begin_example
 CONTENTS SPACES|
+CONTENTS SPACES END-OF-LINE
 #+end_example
 
 + CONTENTS :: Zero or more objects not containing the vertical bar
@@ -1426,6 +1487,7 @@ ** Table Cells
   [[#Targets_and_Radio_Targets][radio targets]], [[#Targets_and_Radio_Targets][targets]], and [[#Timestamps][timestamps]].
 + SPACES :: A string consisting of zero or more of space characters,
   used to align the table columns.
++ END-OF-LINE :: Line ending.
 
 The final vertical bar (=|=) may be omitted in the last cell of a [[#Table_Rows][table row]].
 
@@ -1454,9 +1516,10 @@ ** Timestamps
   - Y, M, D :: A digit.
   - DAYNAME (optional) :: A string consisting of non-whitespace
     characters except =+=, =-=, =]=, =>=, a digit, or =\n=.
-+ TIME (optional) :: An instance of the pattern =H:MM= where =H= represents a one to
-  two digit number (and can start with =0=), and =M= represents a single
-  digit.
++ TIME (optional) :: An instance of the pattern =H:MMREST= where =H=
+  represents a one to two digit number (and can start with =0=), and =M=
+  represents a single digit.  =REST= can contain anything but =\n= or
+  closing bracket.
 + REPEATER-OR-DELAY (optional) :: An instance of the following pattern:
   #+begin_example
 MARK VALUE UNIT
-- 
2.35.1


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #4: 0003-dev-org-syntax.org-Remove-change-summary-section.patch --]
[-- Type: text/x-patch, Size: 3857 bytes --]

From 210d0ffbdeafeef524ce1c1a739f98e897569e88 Mon Sep 17 00:00:00 2001
Message-Id: <210d0ffbdeafeef524ce1c1a739f98e897569e88.1669442423.git.yantar92@posteo.net>
In-Reply-To: <f411e423214c113ef44ba23b09093395d7910e0c.1669442423.git.yantar92@posteo.net>
References: <f411e423214c113ef44ba23b09093395d7910e0c.1669442423.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sat, 26 Nov 2022 13:59:35 +0800
Subject: [PATCH 3/4] * dev/org-syntax.org: Remove change summary section

---
 dev/org-syntax.org | 59 ----------------------------------------------
 1 file changed, 59 deletions(-)

diff --git a/dev/org-syntax.org b/dev/org-syntax.org
index e07564cd..0e4b436b 100644
--- a/dev/org-syntax.org
+++ b/dev/org-syntax.org
@@ -1618,65 +1618,6 @@ * Footnotes
 #+latex: \appendix
 * Appendix
 
-** Summary of changes compared to the current =org-syntax= document
-:PROPERTIES:
-:CUSTOM_ID: Changes
-:END:
-
-+ Rename "Headlines" -> "Headings", since while both forms are
-  currently used in the docs a change to consistently use the latter
-  seems imminent if delayed by (what looks like) an ongoing wait for
-  Bastien's final say
-+ Describe patterns with consistent phrasing, "Xs are structured
-  according to the following pattern:"
-+ Describe string patterns with consistent phrasing,"a string
-  constituted of" (and other forms) -> "a string consisting of"
-+ Describe components of a pattern using description lists
-+ Use verbatim objects for verbatim text over quotes
-+ Change the way inlinetasks are described
-+ Add =CONTENTS= component to the Item structure
-+ Some whitespace/capitalisation changes
-+ (Lots of) miscellaneous wording changes for clarity
-+ Fix some minor errors (like referencing a variable which was removed
-  7y ago, or saying that switches in source block headers should be
-  separated by blank lines)
-+ Change the babel call element syntax description to the more detailed form
-  found in the manual
-+ Change the inline babel call object syntax description to be
-  consistent with the babel call element syntax.  This does not
-  precisely match the parser behaviour, but matches a very slight
-  subset.  The previous description in some parts matched a superset
-  of the parser behaviour, and in other places a subset.
-+ Change "Greater Elements" / "Elements" to "Greater Elements"/
-  "Lesser Elements"
-+ Put all Elements under the new level-1 heading "Elements"
-+ Separate list definition into four sub-definitions
-+ Add a  "Terminology and conventions" section
-+ Mention ~plain-text~ objects (see src_elisp{(org-element-type
-  "text")}) for the sake of consistency (When something can "contain
-  an object" it can contain unformatted text. Without naming
-  ~plain-text~ as an object this is a bit funky).
-+ Specify that whitespace in plain text is semantically
-  collapsed/equivalent to a single space. It is worth noting that this
-  is not indicated by =org-element='s parsing, which grabs all the
-  whitespace as-is.  However, this feels like something which is done
-  for performance reasons, instead of a deliberate choice to make
-  whitespace significant, and there are a few things which reinforce
-  this view
-  - =ox-ascii=, the only export backend to a format which doesn't itself
-    collapse whitespace when interpreted, re-fills paragraphs and
-    collapses whitespace.
-  - We have a line break object.  If =\n= was significant in plain text
-    this would be unnecessary.
-  - ~org-fill-paragraph~ collapses whitespace
-  - Lastly, this is well-established sensible behaviour in every other
-    plaintext format that I can think of (HTML, LaTeX, Markdown, reST,
-    etc.).
-+ Added bunch of examples
-+ Probably a few bits and pieces that have slipped my mind.
-
-#+latex: \newpage
-
 ** Org Entities
 :PROPERTIES:
 :CUSTOM_ID: Entities_List
-- 
2.35.1


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #5: 0004-dev-org-syntax.org-Bump-version.patch --]
[-- Type: text/x-patch, Size: 884 bytes --]

From 3b12fa182cb2626a423124da841f84c8104c8d37 Mon Sep 17 00:00:00 2001
Message-Id: <3b12fa182cb2626a423124da841f84c8104c8d37.1669442423.git.yantar92@posteo.net>
In-Reply-To: <f411e423214c113ef44ba23b09093395d7910e0c.1669442423.git.yantar92@posteo.net>
References: <f411e423214c113ef44ba23b09093395d7910e0c.1669442423.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sat, 26 Nov 2022 10:42:52 +0800
Subject: [PATCH 4/4] * dev/org-syntax.org: Bump version

---
 dev/org-syntax.org | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dev/org-syntax.org b/dev/org-syntax.org
index 0e4b436b..6f92f3e6 100644
--- a/dev/org-syntax.org
+++ b/dev/org-syntax.org
@@ -1,5 +1,5 @@
 #+title: Org Syntax
-#+subtitle: DRAFT v2_{\beta}
+#+subtitle: v2
 #+author: Nicolas Goaziou, Timothy E Chapman
 #+options: toc:t ':t author:nil
 #+language: en
-- 
2.35.1


[-- Attachment #6: Type: text/plain, Size: 225 bytes --]



-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Feedback on Org syntax document

[Bastien Guerry]

Ihor Radchenko <yantar92@posteo.net> writes:

> I will merge them if there are no objections.

Thanks!  No objections.  (Sorry I moved org-syntax.org from worg/dev/
to worg/ right before reading this email, I hope that's okay.)

Perhaps, on top of removing Tim's comments from org-syntax.org we can
store them in a dedicated Worg page? worg/dev/org-syntax-comments.org?

To make sure we can refer to a page when we want to discuss them.

-- 
 Bastien

Re: Feedback on Org syntax document

[Ihor Radchenko]

Bastien Guerry <bzg@gnu.org> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> I will merge them if there are no objections.
>
> Thanks!  No objections.  (Sorry I moved org-syntax.org from worg/dev/
> to worg/ right before reading this email, I hope that's okay.)

Apparently git is smart enough to rebase my commits onto the new moved
file path.

Applied onto master.
https://git.sr.ht/~bzg/worg/commit/bcc7f56f
https://git.sr.ht/~bzg/worg/commit/8f5a47a2
https://git.sr.ht/~bzg/worg/commit/f10f47de
https://git.sr.ht/~bzg/worg/commit/fa554834

> Perhaps, on top of removing Tim's comments from org-syntax.org we can
> store them in a dedicated Worg page? worg/dev/org-syntax-comments.org?
>
> To make sure we can refer to a page when we want to discuss them.

Note that I listed all the comments in this thread. I was planning to
extend on them one by one branching from here.

Will it be enough?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Feedback on Org syntax document

[Bastien]

Ihor Radchenko <yantar92@posteo.net> writes:

> Will it be enough?

As long as we can point to a thread that contains all the information
and pointers that allows to quickly read Tim's comments, yes, fine.

-- 
 Bastien

Re: Feedback on Org syntax document

[Timothy]

[-- Attachment #1: Type: text/plain, Size: 555 bytes --]

Hi Ihor,

> I have addressed the most important comments that should be resolved
> before the coming Org release.
>
> See the attached patches.
>
> I will merge them if there are no objections.

Thanks for getting to this, I really appreciate you picking up the slack with
this 😀.

All the best,
Timothy

-- 
Timothy (‘tecosaur’/‘TEC’), Org mode contributor.
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/tec>.

Re: Feedback on Org syntax document

[Tom Gillespie]

Hi Ihor,
   Thank you for resurfacing this. I'll keep an eye out for the other
threads. I've been preoccupied with trying to wrap up my PhD work so
have been (and will continue to be for a bit longer) focused on other
things. I'll be back to focus on many of these questions some time in
the late winter/early spring if I had to guess. Best!
Tom