From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id sM9ODgCsgWNUhQEAbAwnHQ (envelope-from ) for ; Sat, 26 Nov 2022 07:02:40 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id yHMzDgCsgWPjFAEAauVa8A (envelope-from ) for ; Sat, 26 Nov 2022 07:02:40 +0100 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 6A87C3EE81 for ; Sat, 26 Nov 2022 07:02:39 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oyoGD-00021J-D0; Sat, 26 Nov 2022 01:01:57 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oyoGB-000210-31 for emacs-orgmode@gnu.org; Sat, 26 Nov 2022 01:01:55 -0500 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oyoG7-0007aB-2w for emacs-orgmode@gnu.org; Sat, 26 Nov 2022 01:01:54 -0500 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id B7126240101 for ; Sat, 26 Nov 2022 07:01:47 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1669442507; bh=qgAyjpZDGPa3g7Qte7zl59H6bVVr7mSl/eba/uyP9ao=; h=From:To:Cc:Subject:Date:From; b=An0mz5tVy6kSMHx+DyPeqdJX6RsUBifQA8Zho+wAv5axPvkaqiYbC7g+7+I+U4k/D R4xvfJedyVeDlbFgbnRR8c1tkRqEZUWweePnrM/7MDKFi/JX9QQN3dJHCpuepHUNd/ zZgQ6JmSLSwTeDIvrdAiDRIp82IQTnG1qNOdeyhGdCz6JIMhCVPMxbrkWPjNGujWOc 0xUv06C4PWnm6kUepRHdRz49j/aTqEk+gpggFazuUk9fOw0TjqSkbkvsOM+vkA+rRv c2PH/sJtkDsjNAxYCfDsdW8URN9140TH7eQBVwbv7+G6doWMTEf2fPHYcseJOs0YL7 9yL+LdMoUVUlA== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4NK1MZ2Q5Cz9rxL; Sat, 26 Nov 2022 07:01:45 +0100 (CET) From: Ihor Radchenko To: emacs-orgmode@gnu.org Cc: Timothy , Bastien Subject: Re: Feedback on Org syntax document In-Reply-To: <877d08bkze.fsf@localhost> References: <877d08bkze.fsf@localhost> Date: Sat, 26 Nov 2022 06:02:21 +0000 Message-ID: <87ilj2l0cy.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1669442559; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=XXMAYMxRcdLqQTnRckP9fc9cRYgdmaExSOAH+wWDAKM=; b=Fc44Qo9Y/+BaViWmtiZQbh89xcRnQmerN4fdkrVB9pvVgQ+46N4FrsKCVu+Ah7dAYwGR/y YosmHGuu31pXlLIvaePfcduJszIf5xiNSjWZfGuJUtaL/alj65OuYsog3rRdliyP9TLPI/ DwFtnSvAwx9SGf9PoWIPrUSSvDkyKbPPAUv7RnrvMdl7IPFQwVc5T7rH6DOYKysUs/G8uN oofG4yiwP0c6//Uz3KcjKSoETLzL/hfyK2ZjxG6itV7tv+c/sjesBf+YCYt1ezc94G2fAA 0vDTbwRoTKH8kuZlqByRW/UTSNNjpio4b1+5wGT+vdFAYxbe7yYYf5tOMhh6aw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1669442559; a=rsa-sha256; cv=none; b=T5NKwcAX0X87QDa/sycL/7MPzOBXrgnX9F21WQO4PAs02nkG+0yEzZ1/zPEx4LlPZYm289 jI9L24qgSuNds1kj+V9AbkVDAveoHhdNTF0NVHxtu6NGtM5ZforwI0I2aPQvOqyPtVPdAw lFJupC01/9BUQqOBigIC+/T9fbHtK6ADo94w+3OjbyRPx9hSg51VyIGCX3E3YvzZ4uWLb4 qf/vv6Z3Katcn73wTjTUHEUIAk505H6n+WimDGY6ZEveoZ3aYRfeTIOmt+oy0b30oWG2xJ H1yGUTDDzGU+jwZ9b+gNW4tD6YoRRoJ2S7F1ieMBBQABYVUcYS+Fi/1/suUkKg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=An0mz5tV; dmarc=pass (policy=none) header.from=posteo.net; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -3.67 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=An0mz5tV; dmarc=pass (policy=none) header.from=posteo.net; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 6A87C3EE81 X-Spam-Score: -3.67 X-Migadu-Scanner: scn1.migadu.com X-TUID: pojtjkN+hVGv --=-=-= Content-Type: text/plain Ihor Radchenko 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. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-dev-org-syntax.org-Remove-all-the-notes.patch >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 --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: inline; filename=0002-dev-org-syntax.org-Address-some-comments.patch Content-Transfer-Encoding: quoted-printable >From b01a41c7a956ff053634fe2e8cdab34dc78f232a Mon Sep 17 00:00:00 2001 Message-Id: In-Reply-To: References: From: Ihor Radchenko 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 /<<>> 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 /<<>> of objects/ refers to the entire set of objects, exclu= ding -citation references and [[#Table_Cells][table cells]]. +[[#Citation references][citation references]] and [[#Table_Cells][table ce= lls]]. =20 ** Blank lines =20 @@ -98,10 +98,22 @@ ** Blank lines ** Indentation =20 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]], [[#Fo= otnote_Definitions][footnote definitions]], and [[#Diary_Sexp][diary sexps]]. Indentation is only syntactically meaningful in plain lists. =20 +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 =20 *** General form @@ -153,6 +165,16 @@ *** Case significance =20 In this document, unless specified otherwise, case is insignificant. =20 +** 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 =3Dorg-inlinetask=3D 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. =20 + 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". =20 + 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 =3DKEYWORD=3D and + =3DPRIORITY=3D. =20 + 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 =20 +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 =3D#+end_NAME=3D. =20 *** Drawers and Property Drawers @@ -349,7 +390,7 @@ *** Footnote Definitions [fn:LABEL] CONTENTS #+end_example =20 -+ LABEL :: Either a number or an instance of the pattern =3Dfn:WORD=3D, wh= ere ++ LABEL :: Either a number or an instance of the pattern =3DWORD=3D, where =3DWORD=3D represents a string consisting of word-constituent characters, hyphens and underscores (=3D-_=3D). =20 @@ -423,7 +464,7 @@ *** Items character, or a hyphen enclosed by square brackets (i.e. =3D[ ]=3D, =3D[= X]=3D, or =3D[-]=3D). + TAG (optional) :: An instance of the pattern =3DTAG-TEXT ::=3D where =3DTAG-TEXT=3D represents a string consisting of non-newline characters - that does not contain the substring =3D"\nbsp{}::\nbsp{}"=3D (two colons= surrounded by + that does not contain the substring =3D"=C2=A0::=C2=A0"=3D (two colons s= urrounded 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 inden= tation. =20 #+begin_info -At a glance it may appear as though nested lists are not possible. They ar= e, as -items may themselves contain lists. +Note that item elements can contain other lists. This allows creating +nested lists. #+end_info =20 If first item in a plain list has a COUNTER in its BULLET, the plain @@ -474,10 +515,13 @@ *** Plain Lists =20 #+begin_example (ordered-plain-list - (item) (item + (paragraph)) + (item + (paragraph) (descriptive-plain-list - (item)))) + (item + (paragraph))))) #+end_example =20 *** Property Drawers @@ -498,6 +542,17 @@ *** Property Drawers PROPERTYDRAWER #+end_example =20 +Property drawer can also be present in [[#Zeroth_section][zeroth section]]: + +#+begin_example +BEGINNING-OF-FILE +BLANK-LINES +COMMENT +PROPERTYDRAWER +#+end_example + +=3DBLANK-LINES=3D and =3DCOMMENT=3D are optional. + Property Drawers are structured according to the following pattern: =20 #+begin_example @@ -512,6 +567,7 @@ *** Property Drawers *Example* =20 #+begin_example +,* Heading :PROPERTIES: :CUSTOM_ID: someid :END: @@ -909,7 +965,7 @@ *** Table Rows + A hyphen (=3D-=3D), forming a "rule" type row. Any non-newline characte= rs can follow the hyphen and this will still be a "rule" type row =20 -Table rows can only exist in [[#Tables][tables]]. +Table rows can only exist in [[#Tables][tables]] with Org type. =20 * Objects :PROPERTIES: @@ -936,15 +992,19 @@ * Objects blank line often terminates the element that the object is a part of, such as a paragraph. =20 +Trailing spaces at the end of objects are considered a part of those +objects. + ** Entities :PROPERTIES: :CUSTOM_ID: Entities :END: =20 -Entities are structured according to the following pattern: +Entities are structured according to the following patterns: =20 #+begin_example \NAME POST +\NAME{} #+end_example =20 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 =3D{}=3D. - A non-alphabetic character. =20 *Example* @@ -1178,9 +1237,10 @@ ** Line Breaks are structured according to the following pattern: =20 #+begin_example -\\SPACE +PRE\\SPACE #+end_example =20 ++ [[#Special_Tokens][PRE]] :: Anything but backspace (=3D\=3D).=20 + SPACE :: Zero or more tab and space characters. =20 ** Links @@ -1371,9 +1431,9 @@ ** Statistics Cookies [NUM1/NUM2] #+end_example =20 -+ 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. =20 ** Subscript and Superscript :PROPERTIES: @@ -1414,10 +1474,11 @@ ** Table Cells :CUSTOM_ID: Table_Cells :END: =20 -Table cells are structured according to the following pattern: +Table cells are structured according to the following patterns: =20 #+begin_example CONTENTS SPACES| +CONTENTS SPACES END-OF-LINE #+end_example =20 + 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_Targ= ets][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. =20 The final vertical bar (=3D|=3D) may be omitted in the last cell of a [[#T= able_Rows][table row]]. =20 @@ -1454,9 +1516,10 @@ ** Timestamps - Y, M, D :: A digit. - DAYNAME (optional) :: A string consisting of non-whitespace characters except =3D+=3D, =3D-=3D, =3D]=3D, =3D>=3D, a digit, or =3D\= n=3D. -+ TIME (optional) :: An instance of the pattern =3DH:MM=3D where =3DH=3D r= epresents a one to - two digit number (and can start with =3D0=3D), and =3DM=3D represents a = single - digit. ++ TIME (optional) :: An instance of the pattern =3DH:MMREST=3D where =3DH= =3D + represents a one to two digit number (and can start with =3D0=3D), and = =3DM=3D + represents a single digit. =3DREST=3D can contain anything but =3D\n=3D= or + closing bracket. + REPEATER-OR-DELAY (optional) :: An instance of the following pattern: #+begin_example MARK VALUE UNIT --=20 2.35.1 --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0003-dev-org-syntax.org-Remove-change-summary-section.patch >From 210d0ffbdeafeef524ce1c1a739f98e897569e88 Mon Sep 17 00:00:00 2001 Message-Id: <210d0ffbdeafeef524ce1c1a739f98e897569e88.1669442423.git.yantar92@posteo.net> In-Reply-To: References: From: Ihor Radchenko 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 --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0004-dev-org-syntax.org-Bump-version.patch >From 3b12fa182cb2626a423124da841f84c8104c8d37 Mon Sep 17 00:00:00 2001 Message-Id: <3b12fa182cb2626a423124da841f84c8104c8d37.1669442423.git.yantar92@posteo.net> In-Reply-To: References: From: Ihor Radchenko 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 --=-=-= Content-Type: text/plain -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at --=-=-=--