From f411e423214c113ef44ba23b09093395d7910e0c Mon Sep 17 00:00:00 2001 Message-Id: From: Ihor Radchenko 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