From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id sAATKC9iZ2OUbAAAbAwnHQ (envelope-from ) for ; Sun, 06 Nov 2022 08:28:47 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id YC9EJy9iZ2M5HAEAG6o9tA (envelope-from ) for ; Sun, 06 Nov 2022 08:28:47 +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 19D251C6F0 for ; Sun, 6 Nov 2022 08:28:47 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ora47-0006Cp-5v; Sun, 06 Nov 2022 02:27:35 -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 1ora46-0006Cb-4F for emacs-orgmode@gnu.org; Sun, 06 Nov 2022 02:27:34 -0500 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ora43-0000Z7-E8 for emacs-orgmode@gnu.org; Sun, 06 Nov 2022 02:27:33 -0500 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 9C059240027 for ; Sun, 6 Nov 2022 08:27:28 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1667719648; bh=OwqED1rtX+tyZAFLjzhz56uLZQ5a7s/EjI9tAzUi+i8=; h=From:To:Subject:Date:From; b=j8ZfpBCV734g8Mx8XSuA6aVxsE2IHV7vEVczG8qZa+2E6WUdz1m2aK0tQY/RsdDYq IN+YFos8BIMOc2bA2ZMEDL1zrYYUBgbkCd+sU5Bk4kHvCxT9SY0aRM6kZnjp25EQtA k+8IXSwGYX2TEe698Rr2jEwgaz+kyFLD7Z6Y2ov836yoslIrTPLhkogNLEhbJMfCy3 pjQ0zEiJ5kRSuT8hFiUGS5S3ilyXEaIdolBbUQbuFm4UMcK6HMv2K9sn9J7zT46Pyr 1cvIVFfZ9v1HG0A1e2yv+UOdJ1xrdVvZXc89c8LiIVlo3meOsaX/kqhIjigexyah1o vf4RjcJiwveRg== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4N4mCg26hdz9rxD; Sun, 6 Nov 2022 08:27:25 +0100 (CET) From: Ihor Radchenko To: emacs-orgmode@gnu.org, Timothy , Bastien Subject: Feedback on Org syntax document Date: Sun, 06 Nov 2022 07:28:05 +0000 Message-ID: <877d08bkze.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@posteo.net; helo=mout01.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, 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: , Sender: "Emacs-orgmode" Errors-To: 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=1667719727; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=cdyPEqRpL968qGUTQbdEEQPE4tGeJRQVnlep9im2sgc=; b=bCzurt3Wa6HDCntdemR6hVIBkLxpkpnwWUYNsccgvc6UJCN2iTQcuRg9CGdlynkz4ilswS 9qBKRO9/Bwgc84T/sEonFMEREurniPDLBIba7o/XxN0MHV5GtWmVO4GvtPN22Bu8A/npoj C6LwPdrAJ2R/WhJjGvKg1ze4qRZ9jPfvoiQk4PLUfZ3CToLtBG8RUOQner7LvgpFiv+QrX PjVlptGmf9wFiT54yXtNcqzmwdXYEc87A3ISDgied4JmWyLBGtAErK6MMa7kerWSyjpPWL U2CpReRL0QV55XrvWnQd35OsCNtx2foPelJ4CZWoVriHUs6gQnaE4Jwq94nCFg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667719727; a=rsa-sha256; cv=none; b=Hox2RjZVofMAFPliUJEti/9hUeMMO0s1r3H+1j/AWJcQV2Z6YcKK810aMRtGeWyS1NtT45 ibHUYH6Do2jpZotIyQpfK2EoDFUJeFjFvGy+8Kyo7lK364k5QuSYMvNeI57J9Rkv2gTO71 AHVU+Qqy25KzIAZHGeZeo9CCcgiM/kHVly+AFZ+PKeMcLN5JcqrQYmfLkj3e6X7kdAOmkt gcOwToBLJf49OrPLiqAxyJe9omqWh6QDYBTihSdauEXCljbG/gIZtthCSGqMKbBa/dWBMD vxwDInIkkwegfMi4G6/9EDJEgDc99a5Ga24m1XW5P159bAr8Qc38jEa33vGnrQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=j8ZfpBCV; 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.80 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=j8ZfpBCV; 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: 19D251C6F0 X-Spam-Score: -3.80 X-Migadu-Scanner: scn0.migadu.com X-TUID: xes9tLNN2Wrv 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 =E2=80=94 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. =E2=80=9Csection 3=E2=80=9D), and this isn=E2=80=99t= 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. =E2=80=94 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=E2=80=99t want property draws to suddenly become pla= in > 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. =E2=80=94 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 funct= ionality can simply be shifted to ARGUMENTS with the well-established :key = val forms. > =E2=80=9CFor the love of all that is sane=E2=80=9D =E2=80=94 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=E2=80=99t= see > any backwards compatibility concerns. > This was suggested by Tom G, but I=E2=80=99m a fan =E2=80=94 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? =E2=80=94 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 descri= be `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=E2=80=99s been raised that =E2=80=9C{}=E2=80=9D is really part of the = entity, and so probably shouldn=E2=80=99t be considered part of POST =E2=80= =94 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 lin= ks? 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 num= ber (and can start with 0), and M represents a single digit. > Tom G has some syntax extensions he=E2=80=99d like to suggest for histori= cal / > 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 > =3D_ =3D ??? Also, footnote 12 looks wrong. --=20 Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at