From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: [RFC] Org syntax (draft) Date: Thu, 07 Mar 2013 21:37:22 +0100 Message-ID: <8738w7c5fh.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([208.118.235.92]:40347) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UDhZM-0004ug-H5 for emacs-orgmode@gnu.org; Thu, 07 Mar 2013 15:37:44 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UDhZI-0005Hj-Go for emacs-orgmode@gnu.org; Thu, 07 Mar 2013 15:37:40 -0500 Received: from mail-wg0-f49.google.com ([74.125.82.49]:51603) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UDhZI-0005HY-4O for emacs-orgmode@gnu.org; Thu, 07 Mar 2013 15:37:36 -0500 Received: by mail-wg0-f49.google.com with SMTP id 15so1629631wgd.28 for ; Thu, 07 Mar 2013 12:37:35 -0800 (PST) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Org Mode List Hello, As discussed a few days ago, here is a document describing the complete Org syntax as read by the parser. I also added some comments. I am going to put the Org file on Worg, so anyone can update it and fix mistakes. =E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2= =94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94= =81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81 ORG SYNTAX (DRAFT) =E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2= =94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94= =81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81 Table of Contents =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 1 Headlines and Sections 2 Affiliated Keywords 3 Greater Elements .. 3.1 Greater Blocks .. 3.2 Drawers and Property Drawers .. 3.3 Dynamic Blocks .. 3.4 Footnote Definitions .. 3.5 Inlinetasks .. 3.6 Plain Lists and Items .. 3.7 Tables 4 Elements .. 4.1 Babel Call .. 4.2 Blocks .. 4.3 Clock, Diary Sexp and Planning .. 4.4 Comments .. 4.5 Fixed Width Areas .. 4.6 Horizontal Rules .. 4.7 Keywords .. 4.8 LaTeX Environments .. 4.9 Node Properties .. 4.10 Paragraphs .. 4.11 Table Rows 5 Objects .. 5.1 Entities and LaTeX Fragments .. 5.2 Export Snippets .. 5.3 Footnote References .. 5.4 Inline Babel Calls and Source Blocks .. 5.5 Line Breaks .. 5.6 Links .. 5.7 Macros .. 5.8 Targets and Radio Targets .. 5.9 Statistics Cookies .. 5.10 Subscript and Superscript .. 5.11 Table Cells .. 5.12 Timestamps .. 5.13 Text Markup This document describes and comments Org syntax as it is currently read by its parser (Org Elements) and, therefore, by the export framework. It also includes a few comments on that syntax. A core concept in this syntax is that only headlines and sections are context-free[1][2]. Every other syntactical part only exists within specific environments. Three categories are used to classify these environments: =E2=80=9CGreater elements=E2=80=9D, =E2=80=9Celements=E2=80=9D, and =E2=80=9Cobjects=E2=80= =9D, from the broadest scope to the narrowest. The paragraph is the unit of measurement. An element defines syntactical parts that are at the same level as a paragraph, i.e. which cannot contain or be included in a paragraph. An object is a part that could be included in an element. Greater elements are all parts that can contain an element. Empty lines belong to the largest element ending before them. For example, in a list, empty lines between items belong are part of the item before them, but empty lines at the end of a list belong to the plain list element. Unless specified otherwise, case is not significant. 1 Headlines and 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=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 A headline is defined as: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 STARS KEYWORD PRIORITY TITLE TAGS =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 STARS is a string starting at column 0 and containing at least one asterisk (and up to `org-inlinetask-min-level' if `org-inlinetask' library is loaded). It=E2=80=99s the sole compulsory part of a headline. KEYWORD is a TODO keyword, which have to belong to the list defined in `org-todo-keywords'. Case is significant. PRIORITY is a priority cookie, i.e. a single letter preceded by a hash sign # and enclosed within square brackets. Case is significant. TITLE can be made of any character but a new line. Though, it will match after every other part have been matched. TAGS is made of words containing any alpha-numeric character, underscore, at sign, hash sign or percent sign, and separated with colons. Examples of valid headlines include: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 * =E2=94=82=20 =E2=94=82 ** DONE =E2=94=82=20 =E2=94=82 *** Some e-mail =E2=94=82=20 =E2=94=82 **** TODO [#A] COMMENT Title :tag:a2%: =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 If the first word appearing in the title is `org-comment-keyword', the headline will be considered as =E2=80=9Ccommented=E2=80=9D. If that firs= t word is `org-quote-string', it will be considered as =E2=80=9Cquoted=E2=80=9D. I= n both situations, case is significant. If its title is `org-footnote-section', it will be considered as a =E2=80=9Cfootnote section=E2=80=9D. Case is significant. If `org-archive-tag' is one of its tags, it will be considered as =E2=80=9Carchived=E2=80=9D. Case is significant. A headline contains directly at most one section, followed by any number of headlines. Only a section can contain another section. A section contains directly any greater element or element. Only a headline can contain a section. As an exception, text before the first headline in the document also belongs to a section. In a quoted headline contains a section, the latter will be considered as a =E2=80=9Cquote section=E2=80=9D. As an example, consider the following document: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 An introduction. =E2=94=82=20 =E2=94=82 * A Headline=20 =E2=94=82=20 =E2=94=82 Some text. =E2=94=82=20 =E2=94=82 ** Sub-Topic 1 =E2=94=82=20 =E2=94=82 ** Sub-Topic 2 =E2=94=82=20 =E2=94=82 *** Additional entry=20 =E2=94=82=20 =E2=94=82 ** QUOTE Another Sub-Topic =E2=94=82=20 =E2=94=82 Some other text. =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 Its internal structure could be summarized as: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 (document =E2=94=82 (section) =E2=94=82 (headline =E2=94=82 (section) =E2=94=82 (headline) =E2=94=82 (headline =E2=94=82 (headline)) =E2=94=82 (headline =E2=94=82 (quote-section)))) =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 2 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=E2=95=90=E2=95=90 With the exception of [inlinetasks], [items], [planning], [clocks], [node properties] and [table rows], every other element type can be assigned attributes. This is done by adding specific keywords, named =E2=80=9Caffiliated keywo= rds=E2=80=9D, just above the element considered, no blank line allowed. Affiliated keywords are built upon one of the following patterns: =E2=80=9C#+KEY: VALUE=E2=80=9D, =E2=80=9C#+KEY[OPTIONAL]: VALUE=E2=80=9D = or =E2=80=9C#+ATTR_BACKEND: VALUE=E2=80=9D. KEY is either =E2=80=9CCAPTION=E2=80=9D, =E2=80=9CHEADER=E2=80=9D, =E2=80= =9CNAME=E2=80=9D, =E2=80=9CPLOT=E2=80=9D or =E2=80=9CRESULTS=E2=80=9D strin= g. BACKEND is a string constituted of alpha-numeric characters, hyphens or underscores. OPTIONAL and VALUE can contain any character but a new line. Only keywords in `org-element-dual-keywords' can have an optional value. An affiliated keyword can appear on multiple lines if KEY belongs to `org-element-multiple-keywords' or if its pattern is =E2=80=9C#+ATTR_BACK= END: VALUE=E2=80=9D. Affiliated keywords whose KEY belong to `org-element-parsed-keywords' can contain objects in their value and their optional value, if applicable. [inlinetasks] See section 3.5 [items] See section 3.6 [planning] See section 4.3 [clocks] See section 4.3 [node properties] See section 4.9 [table rows] See section 4.11 3 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=E2=95= =90=E2=95=90 Unless specified otherwise, greater elements can contain directly any other element or greater element excepted: =E2=80=A2 elements of their own type, =E2=80=A2 [node properties], which can only be found in [property drawers= ], =E2=80=A2 [items], which can only be found in [plain lists]. [node properties] See section 4.9 [property drawers] See section 3.2 [items] See section 3.6 [plain lists] See section 3.6 3.1 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=94=80=E2=94=80=E2=94= =80=E2=94=80 Greater blocks consist in the following pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 #+BEGIN_NAME PARAMETERS =E2=94=82 CONTENTS =E2=94=82 #+END_NAME =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME can contain any non-whitespace character. PARAMETERS can contain any character, and can be omitted. If NAME is =E2=80=9CCENTER=E2=80=9D, it will be a =E2=80=9Ccenter block= =E2=80=9D. If it is =E2=80=9CQUOTE=E2=80=9D, it will be a =E2=80=9Cquote block=E2=80=9D. If the block is neither a center block, a quote block or a [block element], it will be a =E2=80=9Cspecial block=E2=80=9D. CONTENTS can contain any element, but another greater block of the same type. [block element] See section 4.2 3.2 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=94=80=E2=94=80=E2=94=80=E2=94=80 Pattern for drawers is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 :NAME: =E2=94=82 CONTENTS =E2=94=82 :END: =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME has to either be =E2=80=9CPROPERTIES=E2=80=9D or belong to `org-draw= ers' list. If NAME is =E2=80=9CPROPERTIES=E2=80=9D, the drawer will become a =E2=80= =9Cproperty drawer=E2=80=9D. In a property drawers, CONTENTS can only contain [node property] elements. Otherwise it can contain any element but another drawer or property drawer. =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2= =80=95 It would be nice if users hadn=E2=80=99t to register drawers names before using them in `org-drawers' (or through the `#+DRAWERS:' keyword). Anything starting with `^[ \t]*:\w+:[ \t]$' and ending with `^[ \t]*:END:[ \t]$' could be considered as a drawer. =E2=80=94 ngz [node property] See section 4.9 3.3 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=94=80=E2=94=80=E2=94= =80=E2=94=80 Pattern for dynamic blocks is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 #+BEGIN: NAME PARAMETERS =E2=94=82 CONTENTS =E2=94=82 #+END: =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME cannot contain any whitespace character. PARAMETERS can contain any character and can be omitted. 3.4 Footnote Definitions =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 Pattern for footnote definitions is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 [LABEL] CONTENTS =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 It must start at column 0. LABEL is either a number or follows the pattern =E2=80=9Cfn:WORD=E2=80=9D= , where word can contain any word-constituent character, hyphens and underscore characters. CONTENTS can contain any element excepted another footnote definition. It ends at the next footnote definition, the next headline, two consecutive empty lines or the end of buffer. 3.5 Inlinetasks =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 Inlinetasks are defined by `org-inlinetask-min-level' contiguous asterisk characters starting at column 0, followed by a whitespace character. Optionally, inlinetasks can be ended with a string constituted of `org-inlinetask-min-level' contiguous characters starting at column 0, followed by a space and the =E2=80=9CEND=E2=80=9D string. Inlinetasks are recognized only after `org-inlinetask' library is loaded. 3.6 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=94=80=E2=94=80=E2=94=80=E2=94=80 Items are defined by a line starting with the following pattern: =E2=80=9CBULLET COUNTER-SET CHECK-BOX TAG=E2=80=9D, in which only BULLET = is mandatory. BULLET is either an asterisk, a hyphen, a plus sign character or follows either the pattern =E2=80=9CCOUNTER.=E2=80=9D or =E2=80=9CCOUNTER= )". In any case, BULLET is follwed by a whitespace character or line ending. COUNTER can be a number or a single letter. COUNTER-SET follows the pattern [@COUNTER]. CHECK-BOX is either a single whitespace character, a =E2=80=9CX=E2=80=9D = character or a hyphen, enclosed within square brackets. TAG follows =E2=80=9CTAG-TEXT ::=E2=80=9D pattern, where TAG-TEXT can con= tain any character but a new line. 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. A plain list is a set of consecutive items of the same indentation. It can only directly contain items. If first item in a plain list has a counter in its bullet, the plain list will be an =E2=80=9Cordered plain-list=E2=80=9D. If it contains a t= ag, it will be a =E2=80=9Cdescriptive list=E2=80=9D. Otherwise, it will be an =E2=80= =9Cunordered list=E2=80=9D. List types are mutually exclusive. For example, consider the following excerpt of an Org document: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 1. item 1 =E2=94=82 2. [X] item 2 =E2=94=82 - some tag :: item 2.1 =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 Its internal structure is as follows: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 (ordered-plain-list =E2=94=82 (item) =E2=94=82 (item =E2=94=82 (descriptive-plain-list =E2=94=82 (item)))) =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 3.7 Tables =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 Tables start at lines beginning with either a vertical bar or the =E2=80= =9C+-=E2=80=9D string followed by plus or minus signs only, assuming they are not preceded with lines of the same type. These lines can be indented. A table starting with a vertical bar has =E2=80=9Corg=E2=80=9D type. Oth= erwise it has =E2=80=9Ctable.el=E2=80=9D type. Org tables end at the first line not starting with a vertical bar. Table.el tables end at the first line not starting with either a vertical line or a plus sign. Such lines can be indented. An org table can only contain table rows. A table.el table does not contain anything. 4 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 Elements cannot contain any other element. Only [keywords] whose name belongs to `org-element-document-properties', [verse blocks] , [paragraphs] and [table rows] can contain objects. [keywords] See section 4.7 [verse blocks] See section 4.2 [paragraphs] See section 4.10 [table rows] See section 4.11 4.1 Babel Call =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 Pattern for babel calls is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 #+CALL: VALUE =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 VALUE is optional. It can contain any character but a new line. 4.2 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 Like [greater blocks], pattern for blocks is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 #+BEGIN_NAME DATA =E2=94=82 CONTENTS =E2=94=82 #+END_NAME =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME cannot contain any whitespace character. If NAME is =E2=80=9CCOMMENT=E2=80=9D, it will be a =E2=80=9Ccomment block= =E2=80=9D. If it is =E2=80=9CEXAMPLE=E2=80=9D, it will be an =E2=80=9Cexample block=E2=80=9D.= If it is =E2=80=9CSRC=E2=80=9D, it will be a =E2=80=9Csource block=E2=80=9D. If it is =E2=80=9CVERSE=E2=80=9D, it w= ill be a =E2=80=9Cverse block=E2=80=9D. If NAME is a string matching the name of any export back-end loaded, the block will be an =E2=80=9Cexport block=E2=80=9D. DATA can contain any character but a new line. It can be ommitted, unless the block is a =E2=80=9Csource block=E2=80=9D. In this case, it m= ust follow the pattern =E2=80=9CLANGUAGE SWITCHES ARGUMENTS=E2=80=9D, where SWITCHES= and ARGUMENTS are optional. LANGUAGE cannot contain any whitespace character. SWITCHES is made of any number of =E2=80=9CSWITCH=E2=80=9D patterns, sepa= rated by blank lines. A SWITCH pattern is either =E2=80=9C-l =E2=80=9CFORMAT"", where FORMAT ca= n contain any character but a double quote and a new line, =E2=80=9C-S=E2=80=9D or =E2= =80=9C+S=E2=80=9D, where S stands for a single letter. ARGUMENTS can contain any character but a new line. CONTENTS can contain any character, including new lines. Though it will only contain Org objects if the block is a verse block. Otherwise, contents will not be parsed. [greater blocks] See section 3.1 4.3 Clock, Diary Sexp and Planning =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=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80 A clock follows the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 CLOCK: TIMESTAMP DURATION =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 Both TIMESTAMP and DURATION are optional. TIMESTAMP is a [timestamp] object. DURATION follows the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 =3D> HH:MM =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 HH is a number containing any number of digits. MM is a two digit numbers. A diary sexp is a line starting at column 0 with =E2=80=9C%%(" string. I= t can then contain any character besides a new line. A planning is a line filled with more at most three INFO parts, where each INFO part follows the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 KEYWORD: TIMESTAMP =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 KEYWORD is a string among `org-deadline-string', `org-scheduled-string' and `org-closed-string'. TIMESTAMP is is a [timestamp] object. Even though a planning element can exist anywhere in a section or a greater element, it will only affect the headline containing the section if it is put on the line following that headline. [timestamp] See section 5.12 4.4 Comments =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 A =E2=80=9Ccomment line=E2=80=9D starts with a hash signe and a whitespac= e character or an end of line. Comments can contain any number of consecutive comment lines. 4.5 Fixed Width Areas =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 A =E2=80=9Cfixed-width line=E2=80=9D start with a colon character and a w= hitespace or an end of line. Fixed width areas can contain any number of consecutive fixed-width lines. 4.6 Horizontal Rules =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 A horizontal rule is a line made of at least 5 consecutive hyphens. It can be indented. 4.7 Keywords =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 Keywords follow the syntax: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 #+KEY: VALUE =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 KEY can contain any non-whitespace character, but it cannot be equal to =E2=80=9CCALL=E2=80=9D or any affiliated keyword. VALUE can contain any character excepted a new line. If KEY belongs to `org-element-document-properties', VALUE can contain objects. 4.8 LaTeX Environments =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 Pattern for LaTeX environments is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 \begin{NAME} =E2=94=82 CONTENTS =E2=94=82 \end{NAME} =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME is constituted of alpha-numeric characters and may end with an asterisk. CONTENTS can contain anything but the =E2=80=9C\end{NAME}=E2=80=9D string. 4.9 Node Properties =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 Patter for node properties is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 :PROPERTY: VALUE =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 PROPERTY can contain any non-whitespace character. VALUE can contain any character but a new line. Node properties can only exist in a [property drawers]. [property drawers] See section 3.2 4.10 Paragraphs =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 Paragraphs are the default element, which means that any unrecognized context is a paragraph. Empty lines and other elements end paragraphs. Paragraphs can contain every type of object. 4.11 Table Rows =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 A table rows is either constituted of a vertical bar and any number of [table cells] or a vertical bar followed by a hyphen. In the first case the table row has the =E2=80=9Cstandard=E2=80=9D type. = In the second case, it has the =E2=80=9Crule=E2=80=9D type. Table rows can only exist in [tables]. [table cells] See section 5.11 [tables] See section 3.7 5 Objects =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 Objects can only be found in the following locations: =E2=80=A2 [affiliated keywords] defined in `org-element-parsed-keywords', =E2=80=A2 [document properties], =E2=80=A2 [headline] titles, =E2=80=A2 [inlinetask] titles, =E2=80=A2 [item] tags, =E2=80=A2 [paragraphs], =E2=80=A2 [table cells], =E2=80=A2 [table rows], which can only contain table cell objects, =E2=80=A2 [verse blocks]. Most objects cannot contain objects. Those which can will be specified. [affiliated keywords] See section 2 [document properties] See section 4.7 [headline] See section 1 [inlinetask] See section 3.5 [item] See section 3.6 [paragraphs] See section 4.10 [table cells] See section 5.11 [table rows] See section 4.11 [verse blocks] See section 4.2 5.1 Entities and LaTeX Fragments =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=94=80=E2=94=80=E2=94=80=E2=94=80 An entity follows the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 \NAME POST =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 where NAME has a valid association in either `org-entities' or `org-entities-user'. POST is the end of line, "{}" string, or a non-alphabetical character. It isn=E2=80=99t separated from NAME by a whitespace character. A LaTeX fragment can follow multiple patterns: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 \NAME POST =E2=94=82 \(CONTENTS\) =E2=94=82 \[CONTENTS\] =E2=94=82 $$CONTENTS$$ =E2=94=82 PRE$CHAR$POST =E2=94=82 PRE$BORDER1 BODY BORDER2$ =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME contains alphabetical characters only and must not have an association in either `org-entities' or `org-entities-user'. POST is the same as for entities. CONTENTS can contain any character but cannot contain =E2=80=9C\)" in the second template or =E2=80=9C\]" in the third one. PRE is either the beginning of line or a character different from `$'. CHAR is a non-whitespace character different from `.', ~,~, `?', `;', ~=E2=80=99~ or a double quote. POST is any of `-', `.', ~,~, `?', `;', `:', ~=E2=80=99~, a double quote, a whitespace character and the end of line. BORDER1 is a non-whitespace character different from `.', `;', `.' and `$'. BODY can contain any character excepted `$', and may not span over more than 3 lines. BORDER2 is any non-whitespace character different from ~,~, `.' and `$'. =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2= =80=95 It would introduce incompatibilities with previous Org versions, but support for =E2=80=9C$=E2=80=A6$=E2=80=9D (and for sy= mmetry, `$$...$$') constructs ought to be removed. They are slow to parse, fragile, redundant, imply false positives and do not look good in LaTeX output anyway. Even the LaTeX community suggests to use `\(...\)' over `$...$'. =E2=80=94 ngz 5.2 Export Snippets =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 Patter for export snippets is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 @@NAME:VALUE@@ =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME can contain any alpha-numeric character and hyphens. VALUE can contain anything but =E2=80=9C@@=E2=80=9D string. 5.3 Footnote References =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 There are four patterns for footnote references: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 [MARK] =E2=94=82 [fn:LABEL] =E2=94=82 [fn:LABEL:DEFINITION] =E2=94=82 [fn::DEFINITION] =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 MARK is a number. LABEL can contain any word constituent character, hyphens and underscores. DEFINITION can contain any character. Though opening and closing square brackets must be balanced in it. It can contain any object encountered in a paragraph, even other footnote references. If the reference follows the third pattern, it is called an =E2=80=9Cinli= ne footnote=E2=80=9D. If it follows the fourth one, i.e. if LABEL is omitte= d, it is an =E2=80=9Canonymous footnote=E2=80=9D. 5.4 Inline Babel Calls and Source 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=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 Inline Babel calls follow any of the following patterns: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 call_NAME(ARGUMENTS) =E2=94=82 call_NAME[HEADER](ARGUMENTS)[HEADER] =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME can contain any character besides `(', `)' and =E2=80=9C\n=E2=80=9D. HEADER can contain any character besides `]' and =E2=80=9C\n=E2=80=9D. ARGUMENTS can contain any character besides `)' and =E2=80=9C\n=E2=80=9D. Inline source blocks follow any of the following patterns: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 src_LANG{BODY} =E2=94=82 src_LANG[OPTIONS]{BODY} =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 LANG can contain any non-whitespace character. OPTIONS and BODY can contain any character but =E2=80=9C\n=E2=80=9D. 5.5 Line Breaks =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 A line break consists in =E2=80=9C\\SPACE=E2=80=9D pattern at the end of = an otherwise non-empty line. SPACE can contain any number of tabs and spaces, including 0. 5.6 Links =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 There are 4 major types of links: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 RADIO ("radio" link) =E2=94=82 ("angle" link) =E2=94=82 PRE PROTOCOL:PATH2 POST ("plain" link) =E2=94=82 [[PATH3]DESCRIPTION] ("regular" link) =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 RADIO is a string matched by some [radio target]. It can contain [entities], [latex fragments], [subscript] and [superscript] only. PROTOCOL is a string among `org-link-types'. PATH can contain any character but `]', `<', `>' and `\n'. PRE and POST are non word constituent. They can be, respectively, the beginning or the end of a line. PATH2 can contain any non-whitespace character excepted `(', `)', `<' and `>'. It must end with a word-constituent character, or any non-whitespace non-punctuation character followed by `/'. DESCRIPTION must be enclosed within square brackets. It can contain any character but square brackets. Object-wise, it can contain any object found in a paragraph excepted a [footnote reference], a [radio target] and a [line break]. It cannot contain another link either, unless it is a plain link. DESCRIPTION is optional. PATH3 is built according to the following patterns: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 FILENAME ("file" type) =E2=94=82 PROTOCOL:PATH4 ("PROTOCOL" type) =E2=94=82 id:ID ("id" type) =E2=94=82 #CUSTOM-ID ("custom-id" type) =E2=94=82 (CODEREF) ("coderef" type) =E2=94=82 FUZZY ("fuzzy" type) =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 FILENAME is a file name, either absolute or relative. PATH4 can contain any character besides square brackets. ID is constituted of hexadecimal numbers separated with hyphens. PATH4, CUSTOM-ID, CODEREF and FUZZY can contain any character besides square brackets. =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2= =80=95 I suggest to remove angle links. If one needs spaces in PATH, she can use standard link syntax instead. I also suggest to remove `org-link-types' dependency in PROTOCOL and match `[a-zA-Z]' instead, for portability. =E2=80=94 ngz [radio target] See section 5.8 [entities] See section 5.1 [latex fragments] See section 5.1 [subscript] See section 5.10 [superscript] See section 5.10 [footnote reference] See section 5.3 [line break] See section 5.5 5.7 Macros =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 Macros follow the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 {{{NAME(ARGUMENTS)}}} =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 NAME must start with a letter and can be followed by any number of alpha-numeric characters, hyphens and underscores. ARGUMENTS can contain anything but "}}}" string. Values within ARGUMENTS are separated by commas. Non-separating commas have to be escaped with a backslash character. 5.8 Targets and Radio Targets =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=94=80 Radio targets follow the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 <<>> =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 CONTENTS can be any character besides `<', `>' and =E2=80=9C\n=E2=80=9D. = As far as objects go, it can contain [entities], [latex fragments], [subscript] and [superscript] only. Targets follow the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 <> =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 TARGET can contain any character besides `<', `>' and =E2=80=9C\n=E2=80= =9D. It cannot contain any object. [entities] See section 5.1 [latex fragments] See section 5.1 [subscript] See section 5.10 [superscript] See section 5.10 5.9 Statistics Cookies =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 Statistics cookies follow either pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 [PERCENT%] =E2=94=82 [NUM1/NUM2] =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 PERCENT, NUM1 and NUM2 are numbers or the empty string. 5.10 Subscript and Superscript =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=94=80=E2=94=80 Pattern for subscript is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 CHAR_SCRIPT =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 Pattern for superscript is: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 CHAR^SCRIPT =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 CHAR is any non-whitespace character. SCRIPT can be `*', a string made of word-constituent characters maybe preceded by a plus or a minus sign, an expression enclosed in parenthesis (resp. curly brackets) containing balanced parenthesis (resp. curly brackets). 5.11 Table Cells =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 Table cells follow the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 CONTENTS| =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 CONTENTS can contain any character excepted a vertical bar. 5.12 Timestamps =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 There are seven possible patterns for timestamps: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 <%%(SEXP)> (diary) =E2=94=82 (active) =E2=94=82 [DATE TIME REPEATER] (inactive) =E2=94=82 -- (active range) =E2=94=82 (active range) =E2=94=82 [DATE TIME REPEATER]--[DATE TIME REPEATER] (inactive range) =E2=94=82 [DATE TIME-TIME REPEATER] (inactive range) =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 SEXP can contain any character excepted `>' and `\n'. DATE follows the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 YYYY-MM-DD DAYNAME =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 Y, M and D are digits. DAYNAME can contain any non whitespace-character besides `+', `-', `]', `>', a digit or `\n'. TIME follows the pattern =3DH:MM~. H can be one or two digit long and can start with 0. REPEATER follows the patter: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 MARK VALUE UNIT =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 MARK is `+' (cumulate type), `++' (catch-up type) or `.+' (restart type). VALUE is a number. UNIT is a character among `h' (hour), `d' (day), `w' (week), `m' (month), `y' (year). MARK, VALUE and UNIT are not separated by whitespace characters. 5.13 Text Markup =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 Text markup follows the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 PRE MARKER CONTENTS MARKER POST =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 PRE is a whitespace character, `(', `{' ~=E2=80=99~ or a double quote. I= t can also be a beginning of line. MARKER is a character among `*' (bold), `=3D' (verbatim), `/' (italic), `+' (strike-through), `_' (underline), `~' (code). CONTENTS is a string following the pattern: =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 =E2=94=82 BORDER BODY BORDER =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 BORDER can be any non-whitespace character excepted ~,~, ~=E2=80=99~ or a double quote. BODY can contain contain any character but may not span over more than 3 lines. BORDER and BODY are not separated by whitespaces. CONTENTS can contain any object encountered in a paragraph when markup is =E2=80=9Cbold=E2=80=9D, =E2=80=9Citalic=E2=80=9D, =E2=80=9Cstrike-thro= ugh=E2=80=9D or =E2=80=9Cunderline=E2=80=9D. POST is a whitespace character, `-', `.', ~,~, `:', `!', `?', ~=E2=80=99~, `)', `}' or a double quote. It can also be an end of line. PRE, MARKER, CONTENTS, MARKER and POST are not separated by whitespace characters. =E2=80=95=E2=80=95=E2=80=95=E2=80=95=E2= =80=95 All of this is wrong if `org-emphasis-regexp-components' or `org-emphasis-alist' are modified. This should really be simplified and made persistent (i.e. no defcustom allowed). Otherwise, portability and parsing are jokes. Also, CONTENTS should be anything within code and verbatim emphasis, by definition. =E2=80=94 ngz Footnotes =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 [1] In particular, the parser requires stars at column 0 to be quoted by a comma when they do not define a headline. [2] It also means that only headlines and sections can be recognized just by looking at the beginning of the line. As a consequence, using `org-element-at-point' or `org-element-context' will move up to the parent headline, and parse top-down from there until context around is found. Regards, --=20 Nicolas Goaziou