From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id cFWECxkYqWGS4wAAgWs5BA (envelope-from ) for ; Thu, 02 Dec 2021 20:01:45 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id WJopBxkYqWEUJQAAB5/wlQ (envelope-from ) for ; Thu, 02 Dec 2021 19:01:45 +0000 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 A4AD68416 for ; Thu, 2 Dec 2021 20:01:44 +0100 (CET) Received: from localhost ([::1]:49632 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1msrKw-0001TL-U7 for larch@yhetil.org; Thu, 02 Dec 2021 14:01:42 -0500 Received: from eggs.gnu.org ([209.51.188.92]:42500) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1msrKB-0001Sz-1d for emacs-orgmode@gnu.org; Thu, 02 Dec 2021 14:00:55 -0500 Received: from [2a00:1450:4864:20::330] (port=38862 helo=mail-wm1-x330.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1msrK8-00058F-2s for emacs-orgmode@gnu.org; Thu, 02 Dec 2021 14:00:54 -0500 Received: by mail-wm1-x330.google.com with SMTP id p3-20020a05600c1d8300b003334fab53afso3061746wms.3 for ; Thu, 02 Dec 2021 11:00:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc:content-transfer-encoding; bh=K7vVr5Yo7wJDrDPmtRA0P9XrcCR8C24r1cB3bSIFIOA=; b=nR/qLNuvEA7ZIeS22P6P7U7jNWCOFqIbVR+O1xTzVDo9gRt8pXL5dp9hlGrMDLV8Qm moI96Q+CiSQRBbPim55QPKGjW8iADFx/eZ6aFeRO3hGncay3sYQGf3RxNXT/15l73Und FaQXYitcAlBjjMyVI0rbuud5nsI0exxffCK/4+uZ/8eZjloIdQSc9oK+RhZLrzeuHIlD O21/Hlg+AJPOlTff2rvG82oUSV/hmSSW5gkVXtwzBtUrDP6ktMrzTOiQPWPJSDAvr2Eo qv0fWOR38VYiqBHQZEmMYlT4rMuPEoQkv8l98qwMOMT2IwNuxrz++XKdLWEBLYYjN12h Arcg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=K7vVr5Yo7wJDrDPmtRA0P9XrcCR8C24r1cB3bSIFIOA=; b=8Jlo9hdR51R5MRLMpaOmkAgxTeTOnSFBMpWDGPDLyxuobl8/8u5GWKIvv16t2ejK6O em63XJxZCUfrmVIAg6cxg++xbyYZnXLAyg3knRuhfiLcJIllf70PsiWqaoyd6YnIxtza or5L6TY25RMWZteKIEEk3/3HFiu72SQ+sWKoNiA/A0kPtgzFsil7WFu+PZE/x5Ca6MZ9 4LSP7ZVBlowbCw5MVu5HVpspuHWmwmGxMbQcldxo/DDQwP/LuVJF8bhcqchpeokj5Vcz bOenVlx1to+TDUVfrj4NXvd+l0IQCwN9r68wkCe1dCvyDDXe4eCLqD6GCQzfLDE8YIvr NjrA== X-Gm-Message-State: AOAM531yfFtCNb+rcbIAwogD+AAzNytRFtPYWLGPOyXX4hFCNR/XUtiD 5Y4Rx1gh/JriIM6GZw6SJM/k/Yv/iAmoBfrB0e8= X-Google-Smtp-Source: ABdhPJxdYjF8XlsKxvHc6X7u119mQ1jLj4w8e5OzhOt/dYcsFdyKHGPaUtL0D69qaL+BfYLe6chGoYhtR6Y8uNoS3mM= X-Received: by 2002:a7b:c5c2:: with SMTP id n2mr8565892wmk.141.1638471650769; Thu, 02 Dec 2021 11:00:50 -0800 (PST) MIME-Version: 1.0 References: <87mtljpd1w.fsf@gmail.com> In-Reply-To: <87mtljpd1w.fsf@gmail.com> From: Tom Gillespie Date: Thu, 2 Dec 2021 11:00:39 -0800 Message-ID: Subject: Re: Some commentary on the Org Syntax document To: Timothy Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::330 (failed) Received-SPF: pass client-ip=2a00:1450:4864:20::330; envelope-from=tgbugs@gmail.com; helo=mail-wm1-x330.google.com X-Spam_score_int: -12 X-Spam_score: -1.3 X-Spam_bar: - X-Spam_report: (-1.3 / 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, FREEMAIL_FROM=0.001, PDS_HP_HELO_NORDNS=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no 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: , Cc: emacs-orgmode Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" 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=1638471704; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=K7vVr5Yo7wJDrDPmtRA0P9XrcCR8C24r1cB3bSIFIOA=; b=JPE9POGO5zukso8lMtP4Wf8UZCx+4FamM7vNBvRTUUtSArLe5XOvTiXKnvFvTq3UZrWKMn lfRWFo0R0QK5mmwnF5jVZlmSxfZWX14O24/jFCFBktUVSGT0ZREuWpvK9kOIzOlROKHbmQ rKXndlq7aHSuLK8G7u7dyb7e9u6nq78fdoKj+mkoBDU3Q++yXawAAEvwAXM7Jpuk/Qpxyo CQXkFZmoTUufSC/MVqrAc9RofKEOH85zLlOFrtpX1vUjhdfuDcwzYJzTNQALuagGYELnf2 qdCCLNZueVSttsFGTggh6zBT+PgXQRj/ycwOgNYviX6VjyiNfcDOBBQ6D8xmdQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1638471704; a=rsa-sha256; cv=none; b=P6C7fm+141f6UMQ4IIUGWdGiA4HwTJti5PbGisWxfB0/jugv28SnC9RLvs5mgQrSV7Rd7U LC1K7CPgNZ5IPrzSuimUqS5qlYsKmd6KtGMgj2nQV1s31ILSGD2dLn+M8KeH9QEfxg4zec kASm3WyWI7Pn/VfTptxhnRz3Iy1aLmKHs1ZizpMV4rVkzE6cgBkTlvLYpXCtRalis2Sg8u 2SIl51z+uWpycQGBGZkBCvIY5h4UjBGA8doJ3k/LfmuVhMu4TOe+4/RqBxZ+SaLnpxj4tK +6NFRDGQIO8Hjo2FZopeGJqLm+6lObaCEAOxN0Idpk2+1MxlRv+If5QhcfnCbg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b="nR/qLNuv"; dmarc=pass (policy=none) header.from=gmail.com; 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: -4.12 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b="nR/qLNuv"; dmarc=pass (policy=none) header.from=gmail.com; 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: A4AD68416 X-Spam-Score: -4.12 X-Migadu-Scanner: scn0.migadu.com X-TUID: oEOxDwA1YOER Hi Timothy, Replies in line. Best! Tom On Thu, Dec 2, 2021 at 1:32 AM Timothy wrote: > > Hi All (& Nicolas in particular again), > > With my recent efforts to write a parser based on > , I=E2=80=99ve developed a = few thoughts on > that document. Hopefully, they can lead to some improvements and > clarifications. > > =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95= =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2= =80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80= =95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95= =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2= =80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80= =95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95= =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2= =80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2=80=95 > > As a general comment, in many places the Org Syntax document states what > characters a component can contain, but not what objects/elements. This f= eels > 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 newline= s 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 > =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90 > > Heading > =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > > =E2=81=83 Ok, so `TITLE' can have any character but a newline, but what O= rg components can it contain? > I=E2=80=99m 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 > =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90= =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2= =95=90=E2=95=90=E2=95=90 > > > Greater Elements > =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90= =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90 > > Greater blocks > =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > > =E2=81=83 It is not explained what is ment by a =E2=80=9Cspecial block=E2= =80=9D > =E2=81=83 Aren=E2=80=99t lines starting with `#+' also quoted by a comma? > > > Drawers and Property Drawers > =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80 > > =E2=81=83 =E2=80=9CContents can contain any element but another drawer=E2= =80=9D > =E2=80=A2 Does =E2=80=9Cany element=E2=80=9D mean =E2=80=9Cany Element = or Greater Element=E2=80=9D Any element that does not have greater precedence, so that would be only a heading. > > Dynamic Blocks > =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > > =E2=81=83 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. > =E2=81=83 Surely `PARAMETERS' cannot contain a newline? Termination by newline is implicit in the example, but the text is confusin= g. > Plain Lists and Items > =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > > =E2=81=83 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 > =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > > =E2=81=83 Surely newlines are not allowed in `FORMULAS' No newlines are implicit in the use of "lines" but still confusing. > > Elements > =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90 > > Clocks > =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > > Two allowed forms are listed, but are all four of the below allowed or on= ly two? > =E2=94=8C=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > =E2=94=82 CLOCK: INACTIVE-TIMESTAMP > =E2=94=82 CLOCK: INACTIVE-TIMESTAMP DURATION > =E2=94=82 CLOCK: INACTIVE-TIMESTAMP-RANGE > =E2=94=82 CLOCK: INACTIVE-TIMESTAMP-RANGE DURATION > =E2=94=94=E2=94=80=E2=94=80=E2=94=80=E2=94=80 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