arch/orgize
1
0
Fork 0
Code Issues Pull requests 1 Packages Projects Releases Wiki Activity

docs(SYNTAX.md): update formatting

Browse source
This commit is contained in:
PoiScript 2020-05-16 19:01:33 +08:00
parent 630cfa1538
commit efdcb4e73a
1 changed files with 273 additions and 293 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

566
docs/SYNTAX.md
View file

@ -27,7 +27,8 @@
1. [Entities and LaTeX Fragments](#Entities_and_LaTeX_Fragments) 1. [Entities and LaTeX Fragments](#Entities_and_LaTeX_Fragments)
2. [Export Snippets](#Export_Snippets) 2. [Export Snippets](#Export_Snippets)
3. [Footnote References](#Footnote_References) 3. [Footnote References](#Footnote_References)
4. [Inline Babel Calls and Source Blocks](#Inline_Babel_Calls_and_Source_Blocks) 4. [Inline Babel Calls and Source
Blocks](#Inline_Babel_Calls_and_Source_Blocks)
5. [Line Breaks](#Line_Breaks) 5. [Line Breaks](#Line_Breaks)
6. [Links](#Links) 6. [Links](#Links)
7. [Macros](#Macros) 7. [Macros](#Macros)
@ -38,29 +39,29 @@
12. [Timestamps](#Timestamp) 12. [Timestamps](#Timestamp)
13. [Text Markup](#Emphasis_Markers) 13. [Text Markup](#Emphasis_Markers)
This document describes and comments Org syntax as it is currently This document describes and comments Org syntax as it is currently read by its
read by its parser (Org Elements) and, therefore, by the export parser (Org Elements) and, therefore, by the export framework. It also includes
framework. It also includes a few comments on that syntax. a few comments on that syntax.
A core concept in this syntax is that only headlines, sections, A core concept in this syntax is that only headlines, sections, planning lines
planning lines and property drawers are context-free<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup><sup>, </sup><sup><a id="fnr.2" class="footref" href="#fn.2">2</a></sup>. and property drawers are context-free<sup><a id="fnr.1" class="footref"
Every other syntactical part only exists within specific environments. href="#fn.1">1</a></sup><sup>, </sup><sup><a id="fnr.2" class="footref"
href="#fn.2">2</a></sup>. Every other syntactical part only exists within
specific environments.
Three categories are used to classify these environments: &ldquo;Greater Three categories are used to classify these environments: **Greater elements**,
elements&rdquo;, &ldquo;elements&rdquo;, and &ldquo;objects&rdquo;, from the broadest scope to the **elements**, and **objects**, from the broadest scope to the narrowest. The
narrowest. The word &ldquo;element&rdquo; is used for both Greater and non-Greater word **element** is used for both Greater and non-Greater elements, the context
elements, the context should make that clear. should make that clear.
The paragraph is the unit of measurement. An element defines The paragraph is the unit of measurement. An element defines syntactical parts
syntactical parts that are at the same level as a paragraph, that are at the same level as a paragraph, i.e. which cannot contain or be
i.e. which cannot contain or be included in a paragraph. An object is included in a paragraph. An object is a part that could be included in an
a part that could be included in an element. Greater elements are all element. Greater elements are all parts that can contain an element.
parts that can contain an element.
Empty lines belong to the largest element ending before them. For Empty lines belong to the largest element ending before them. For example, in a
example, in a list, empty lines between items belong are part of the list, empty lines between items belong are part of the item before them, but
item before them, but empty lines at the end of a list belong to the empty lines at the end of a list belong to the plain list element.
plain list element.
Unless specified otherwise, case is not significant. Unless specified otherwise, case is not significant.
@ -72,24 +73,22 @@ A headline is defined as:
STARS KEYWORD PRIORITY TITLE TAGS STARS KEYWORD PRIORITY TITLE TAGS
STARS is a string starting at column 0, containing at least one STARS is a string starting at column 0, containing at least one asterisk (and up
asterisk (and up to `org-inlinetask-min-level` if `org-inlinetask` to `org-inlinetask-min-level` if `org-inlinetask` library is loaded) and ended
library is loaded) and ended by a space character. The number of by a space character. The number of asterisks is used to define the level of the
asterisks is used to define the level of the headline. It&rsquo;s the headline. It's the sole compulsory part of a headline.
sole compulsory part of a headline.
KEYWORD is a TODO keyword, which has to belong to the list defined KEYWORD is a TODO keyword, which has to belong to the list defined in
in `org-todo-keywords-1`. Case is significant. `org-todo-keywords-1`. Case is significant.
PRIORITY is a priority cookie, i.e. a single letter preceded by PRIORITY is a priority cookie, i.e. a single letter preceded by a hash sign #
a hash sign # and enclosed within square brackets. and enclosed within square brackets.
TITLE can be made of any character but a new line. Though, it will TITLE can be made of any character but a new line. Though, it will match after
match after every other part have been matched. every other part have been matched.
TAGS is made of words containing any alpha-numeric character, TAGS is made of words containing any alpha-numeric character, underscore, at
underscore, at sign, hash sign or percent sign, and separated with sign, hash sign or percent sign, and separated with colons.
colons.
Examples of valid headlines include: Examples of valid headlines include:
@ -101,21 +100,21 @@ Examples of valid headlines include:
**** TODO [#A] COMMENT Title :tag:a2%: **** TODO [#A] COMMENT Title :tag:a2%:
If the first word appearing in the title is &ldquo;COMMENT&rdquo;, the headline If the first word appearing in the title is `COMMENT`, the headline will be
will be considered as &ldquo;commented&rdquo;. Case is significant. considered as **commented**. Case is significant.
If its title is `org-footnote-section`, it will be considered as If its title is `org-footnote-section`, it will be considered as a **footnote
a &ldquo;footnote section&rdquo;. Case is significant. section**. Case is significant.
If &ldquo;ARCHIVE&rdquo; is one of its tags, it will be considered as If `ARCHIVE` is one of its tags, it will be considered as **archived**. Case is
&ldquo;archived&rdquo;. Case is significant. significant.
A headline contains directly one section (optionally), followed by A headline contains directly one section (optionally), followed by any number of
any number of deeper level headlines. deeper level headlines.
A section contains directly any greater element or element. Only A section contains directly any greater element or element. Only a headline can
a headline can contain a section. As an exception, text before the contain a section. As an exception, text before the first headline in the
first headline in the document also belongs to a section. document also belongs to a section.
As an example, consider the following document: As an example, consider the following document:
@ -145,42 +144,44 @@ Its internal structure could be summarized as:
# Affiliated Keywords # Affiliated Keywords
With the exception of [inlinetasks](#Inlinetasks), [items](#Plain_Lists_and_Items), [planning](#Clock,_Diary_Sexp_and_Planning), [clocks](#Clock,_Diary_Sexp_and_Planning), [node With the exception of [inlinetasks](#Inlinetasks),
properties](#Node_Properties) and [table rows](#Table_Rows), every other element type can be assigned [items](#Plain_Lists_and_Items), [planning](#Clock,_Diary_Sexp_and_Planning),
[clocks](#Clock,_Diary_Sexp_and_Planning), [node properties](#Node_Properties)
and [table rows](#Table_Rows), every other element type can be assigned
attributes. attributes.
This is done by adding specific keywords, named &ldquo;affiliated This is done by adding specific keywords, named **affiliated keywords**, just
keywords&rdquo;, just above the element considered, no blank line above the element considered, no blank line allowed.
allowed.
Affiliated keywords are built upon one of the following patterns: Affiliated keywords are built upon one of the following patterns: `#+KEY: VALUE`,
&ldquo;#+KEY: VALUE&rdquo;, &ldquo;#+KEY[OPTIONAL]: VALUE&rdquo; or &ldquo;#+ATTR<sub>BACKEND</sub>: VALUE&rdquo;. `#+KEY[OPTIONAL]: VALUE` or `#+ATTR_BACKEND: VALUE`.
KEY is either &ldquo;CAPTION&rdquo;, &ldquo;HEADER&rdquo;, &ldquo;NAME&rdquo;, &ldquo;PLOT&rdquo; or &ldquo;RESULTS&rdquo; KEY is either `CAPTION`, `HEADER`, `NAME`, `PLOT` or `RESULTS` string.
string.
BACKEND is a string constituted of alpha-numeric characters, hyphens BACKEND is a string constituted of alpha-numeric characters, hyphens or
or underscores. underscores.
OPTIONAL and VALUE can contain any character but a new line. Only OPTIONAL and VALUE can contain any character but a new line. Only `CAPTION` and
&ldquo;CAPTION&rdquo; and &ldquo;RESULTS&rdquo; keywords can have an optional value. `RESULTS` keywords can have an optional value.
An affiliated keyword can appear more than once if KEY is either An affiliated keyword can appear more than once if KEY is either `CAPTION` or
&ldquo;CAPTION&rdquo; or &ldquo;HEADER&rdquo; or if its pattern is &ldquo;#+ATTR<sub>BACKEND</sub>: VALUE&rdquo;. `HEADER` or if its pattern is `#+ATTR_BACKEND: VALUE`.
&ldquo;CAPTION&rdquo;, &ldquo;AUTHOR&rdquo;, &ldquo;DATE&rdquo; and &ldquo;TITLE&rdquo; keywords can contain objects `CAPTION`, `AUTHOR`, `DATE` and `TITLE` keywords can contain objects in their
in their value and their optional value, if applicable. value and their optional value, if applicable.
<a id="Greater_Elements"></a> <a id="Greater_Elements"></a>
# Greater Elements # Greater Elements
Unless specified otherwise, greater elements can contain directly Unless specified otherwise, greater elements can contain directly any other
any other element or greater element excepted: element or greater element excepted:
- elements of their own type, - elements of their own type,
- [node properties](#Node_Properties), which can only be found in [property drawers](#Property_Drawers), - [node properties](#Node_Properties), which can only be found in [property
- [items](#Plain_Lists_and_Items), which can only be found in [plain lists](#Plain_Lists_and_Items). drawers](#Property_Drawers),
- [items](#Plain_Lists_and_Items), which can only be found in [plain
lists](#Plain_Lists_and_Items).
<a id="Greater_Blocks"></a> <a id="Greater_Blocks"></a>
@ -194,18 +195,16 @@ Greater blocks consist in the following pattern:
NAME can contain any non-whitespace character. NAME can contain any non-whitespace character.
PARAMETERS can contain any character other than new line, and can PARAMETERS can contain any character other than new line, and can be omitted.
be omitted.
If NAME is &ldquo;CENTER&rdquo;, it will be a &ldquo;center block&rdquo;. If it is If NAME is `CENTER`, it will be a **center block**. If it is `QUOTE`, it will be
&ldquo;QUOTE&rdquo;, it will be a &ldquo;quote block&rdquo;. a **quote block**.
If the block is neither a center block, a quote block or a [block If the block is neither a center block, a quote block or a [block
element](#Blocks), it will be a &ldquo;special block&rdquo;. element](#Blocks), it will be a **special block**.
CONTENTS can contain any element, except : a line `#+END_NAME` on CONTENTS can contain any element, except : a line `#+END_NAME` on its own. Also
its own. Also lines beginning with STARS must be quoted by lines beginning with STARS must be quoted by a comma.
a comma.
<a id="Drawers"></a> <a id="Drawers"></a>
@ -217,8 +216,7 @@ Pattern for drawers is:
CONTENTS CONTENTS
:END: :END:
NAME can contain word-constituent characters, hyphens and NAME can contain word-constituent characters, hyphens and underscores.
underscores.
CONTENTS can contain any element but another drawer. CONTENTS can contain any element but another drawer.
@ -246,63 +244,58 @@ Pattern for footnote definitions is:
It must start at column 0. It must start at column 0.
LABEL is either a number or follows the pattern &ldquo;fn:WORD&rdquo;, where LABEL is either a number or follows the pattern `fn:WORD`, where word can
word can contain any word-constituent character, hyphens and contain any word-constituent character, hyphens and underscore characters.
underscore characters.
CONTENTS can contain any element excepted another footnote CONTENTS can contain any element excepted another footnote definition. It ends
definition. It ends at the next footnote definition, the next at the next footnote definition, the next headline, two consecutive empty lines
headline, two consecutive empty lines or the end of buffer. or the end of buffer.
<a id="Inlinetasks"></a> <a id="Inlinetasks"></a>
## Inlinetasks ## Inlinetasks
Inlinetasks are defined by `org-inlinetask-min-level` contiguous Inlinetasks are defined by `org-inlinetask-min-level` contiguous asterisk
asterisk characters starting at column 0, followed by a whitespace characters starting at column 0, followed by a whitespace character.
character.
Optionally, inlinetasks can be ended with a string constituted of Optionally, inlinetasks can be ended with a string constituted of
`org-inlinetask-min-level` contiguous asterisk characters starting `org-inlinetask-min-level` contiguous asterisk characters starting at column 0,
at column 0, followed by a space and the &ldquo;END&rdquo; string. followed by a space and the `END` string.
Inlinetasks are recognized only after `org-inlinetask` library is Inlinetasks are recognized only after `org-inlinetask` library is loaded.
loaded.
<a id="Plain_Lists_and_Items"></a> <a id="Plain_Lists_and_Items"></a>
## Plain Lists and Items ## Plain Lists and Items
Items are defined by a line starting with the following pattern: Items are defined by a line starting with the following pattern:
&ldquo;BULLET COUNTER-SET CHECK-BOX TAG&rdquo;, in which only BULLET is `BULLET COUNTER-SET CHECK-BOX TAG`, in which only BULLET is mandatory.
mandatory.
BULLET is either an asterisk, a hyphen, a plus sign character or BULLET is either an asterisk, a hyphen, a plus sign character or follows either
follows either the pattern &ldquo;COUNTER.&rdquo; or &ldquo;COUNTER)&rdquo;. In any case, the pattern `COUNTER.` or `COUNTER)`. In any case, BULLET is follwed by a
BULLET is follwed by a whitespace character or line ending. whitespace character or line ending.
COUNTER can be a number or a single letter. COUNTER can be a number or a single letter.
COUNTER-SET follows the pattern [@COUNTER]. COUNTER-SET follows the pattern [@COUNTER].
CHECK-BOX is either a single whitespace character, a &ldquo;X&rdquo; character CHECK-BOX is either a single whitespace character, a `X` character or a hyphen,
or a hyphen, enclosed within square brackets. enclosed within square brackets.
TAG follows &ldquo;TAG-TEXT ::&rdquo; pattern, where TAG-TEXT can contain any TAG follows `TAG-TEXT ::` pattern, where TAG-TEXT can contain any character but
character but a new line. a new line.
An item ends before the next item, the first line less or equally An item ends before the next item, the first line less or equally indented than
indented than its starting line, or two consecutive empty lines. its starting line, or two consecutive empty lines. Indentation of lines within
Indentation of lines within other greater elements do not count, other greater elements do not count, neither do inlinetasks boundaries.
neither do inlinetasks boundaries.
A plain list is a set of consecutive items of the same indentation. A plain list is a set of consecutive items of the same indentation. It can only
It can only directly contain items. directly contain items.
If first item in a plain list has a counter in its bullet, the If first item in a plain list has a counter in its bullet, the plain list will
plain list will be an &ldquo;ordered plain-list&rdquo;. If it contains a tag, be an **ordered plain-list**. If it contains a tag, it will be a **descriptive
it will be a &ldquo;descriptive list&rdquo;. Otherwise, it will be an list**. Otherwise, it will be an **unordered list**. List types are mutually
&ldquo;unordered list&rdquo;. List types are mutually exclusive. exclusive.
For example, consider the following excerpt of an Org document: For example, consider the following excerpt of an Org document:
@ -322,8 +315,8 @@ Its internal structure is as follows:
## Property Drawers ## Property Drawers
Property drawers are a special type of drawer containing properties Property drawers are a special type of drawer containing properties attached to
attached to a headline. They are located right after a [headline](#Headlines_and_Sections) a headline. They are located right after a [headline](#Headlines_and_Sections)
and its [planning](#Clock,_Diary_Sexp_and_Planning) information. and its [planning](#Clock,_Diary_Sexp_and_Planning) information.
HEADLINE HEADLINE
@ -345,23 +338,22 @@ where CONTENTS consists of zero or more [node properties](#Node_Properties).
## Tables ## Tables
Tables start at lines beginning with either a vertical bar or the Tables start at lines beginning with either a vertical bar or the `+-` string
&ldquo;+-&rdquo; string followed by plus or minus signs only, assuming they are followed by plus or minus signs only, assuming they are not preceded with lines
not preceded with lines of the same type. These lines can be of the same type. These lines can be indented.
indented.
A table starting with a vertical bar has &ldquo;org&rdquo; type. Otherwise it A table starting with a vertical bar has `org` type. Otherwise it has `table.el`
has &ldquo;table.el&rdquo; type. type.
Org tables end at the first line not starting with a vertical bar. Org tables end at the first line not starting with a vertical bar. Table.el
Table.el tables end at the first line not starting with either tables end at the first line not starting with either a vertical line or a plus
a vertical line or a plus sign. Such lines can be indented. sign. Such lines can be indented.
An org table can only contain table rows. A table.el table does An org table can only contain table rows. A table.el table does not contain
not contain anything. anything.
One or more &ldquo;#+TBLFM: FORMULAS&rdquo; lines, where &ldquo;FORMULAS&rdquo; can contain One or more `#+TBLFM: FORMULAS` lines, where `FORMULAS` can contain any
any character, can follow an org table. character, can follow an org table.
<a id="Elements"></a> <a id="Elements"></a>
@ -370,8 +362,8 @@ any character, can follow an org table.
Elements cannot contain any other element. Elements cannot contain any other element.
Only [keywords](#Keywords) whose name belongs to Only [keywords](#Keywords) whose name belongs to
`org-element-document-properties`, [verse blocks](#Blocks) , [paragraphs](#Paragraphs) and `org-element-document-properties`, [verse blocks](#Blocks) ,
[table rows](#Table_Rows) can contain objects. [paragraphs](#Paragraphs) and [table rows](#Table_Rows) can contain objects.
<a id="Babel_Call"></a> <a id="Babel_Call"></a>
@ -395,33 +387,33 @@ Like [greater blocks](#Greater_Blocks), pattern for blocks is:
NAME cannot contain any whitespace character. NAME cannot contain any whitespace character.
If NAME is &ldquo;COMMENT&rdquo;, it will be a &ldquo;comment block&rdquo;. If it is 1. If NAME is `COMMENT`, it will be a **comment block**.
&ldquo;EXAMPLE&rdquo;, it will be an &ldquo;example block&rdquo;. If it is &ldquo;EXPORT&rdquo;, it 2. If it is `EXAMPLE`, it will be an **example block**.
will be an &ldquo;export block&rdquo;. If it is &ldquo;SRC&rdquo;, it will be a &ldquo;source 3. If it is `EXPORT`, it will be an **export block**.
block&rdquo;. If it is &ldquo;VERSE&rdquo;, it will be a &ldquo;verse block&rdquo;. 4. If it is `SRC`, it will be a **source block**.
5. If it is `VERSE`, it will be a **verse block**.
DATA can contain any character but a new line. It can be ommitted, DATA can contain any character but a new line. It can be ommitted, unless the
unless the block is either a &ldquo;source block&rdquo; or an &ldquo;export block&rdquo;. block is either a **source block** or an **export block**.
In the latter case, it should be constituted of a single word. In the latter case, it should be constituted of a single word.
In the former case, it must follow the pattern &ldquo;LANGUAGE SWITCHES In the former case, it must follow the pattern `LANGUAGE SWITCHES ARGUMENTS`,
ARGUMENTS&rdquo;, where SWITCHES and ARGUMENTS are optional. where SWITCHES and ARGUMENTS are optional.
LANGUAGE cannot contain any whitespace character. LANGUAGE cannot contain any whitespace character.
SWITCHES is made of any number of &ldquo;SWITCH&rdquo; patterns, separated by SWITCHES is made of any number of `SWITCH` patterns, separated by blank lines.
blank lines.
A SWITCH pattern is either &ldquo;-l &rdquo;FORMAT&ldquo;&rdquo;, where FORMAT can contain A SWITCH pattern is either `-l FORMAT`, where FORMAT can contain any character
any character but a double quote and a new line, &ldquo;-S&rdquo; or &ldquo;+S&rdquo;, but a double quote and a new line, `-S` or `+S`, where S stands for a single
where S stands for a single letter. letter.
ARGUMENTS can contain any character but a new line. ARGUMENTS can contain any character but a new line.
CONTENTS can contain any character, including new lines. Though it CONTENTS can contain any character, including new lines. Though it will only
will only contain Org objects if the block is a verse block. contain Org objects if the block is a verse block. Otherwise, CONTENTS will not
Otherwise, CONTENTS will not be parsed. be parsed.
<a id="Clock,_Diary_Sexp_and_Planning"></a> <a id="Clock,_Diary_Sexp_and_Planning"></a>
@ -432,41 +424,39 @@ A clock follows either of the patterns below:
CLOCK: INACTIVE-TIMESTAMP CLOCK: INACTIVE-TIMESTAMP
CLOCK: INACTIVE-TIMESTAMP-RANGE DURATION CLOCK: INACTIVE-TIMESTAMP-RANGE DURATION
INACTIVE-TIMESTAMP, resp. INACTIVE-TIMESTAMP-RANGE, is an inactive, INACTIVE-TIMESTAMP, resp. INACTIVE-TIMESTAMP-RANGE, is an inactive, resp.
resp. inactive range, [timestamp](#Timestamp) object. inactive range, [timestamp](#Timestamp) object.
DURATION follows the pattern: DURATION follows the pattern:
=> HH:MM => HH:MM
HH is a number containing any number of digits. MM is a two digit HH is a number containing any number of digits. MM is a two digit numbers.
numbers.
A diary sexp is a line starting at column 0 with &ldquo;%%(&rdquo; string. It A diary sexp is a line starting at column 0 with `%%(` string. It can then
can then contain any character besides a new line. contain any character besides a new line.
A planning is an element with the following pattern: A planning is an element with the following pattern:
HEADLINE HEADLINE
PLANNING PLANNING
where HEADLINE is a [headline](#Headlines_and_Sections) element and PLANNING is a line filled where HEADLINE is a [headline](#Headlines_and_Sections) element and PLANNING is
with INFO parts, where each of them follows the pattern: a line filled with INFO parts, where each of them follows the pattern:
KEYWORD: TIMESTAMP KEYWORD: TIMESTAMP
KEYWORD is either &ldquo;DEADLINE&rdquo;, &ldquo;SCHEDULED&rdquo; or &ldquo;CLOSED&rdquo;. TIMESTAMP KEYWORD is either `DEADLINE`, `SCHEDULED` or `CLOSED`. TIMESTAMP is a
is a [timestamp](#Timestamp) object. [timestamp](#Timestamp) object.
In particular, no blank line is allowed between PLANNING and In particular, no blank line is allowed between PLANNING and HEADLINE.
HEADLINE.
<a id="Comments"></a> <a id="Comments"></a>
## Comments ## Comments
A &ldquo;comment line&rdquo; starts with a hash signe and a whitespace A **comment line** starts with a hash signe and a whitespace character or an end
character or an end of line. of line.
Comments can contain any number of consecutive comment lines. Comments can contain any number of consecutive comment lines.
@ -474,18 +464,17 @@ Comments can contain any number of consecutive comment lines.
## Fixed Width Areas ## Fixed Width Areas
A &ldquo;fixed-width line&rdquo; start with a colon character and a whitespace A **fixed-width line** start with a colon character and a whitespace or an end
or an end of line. of line.
Fixed width areas can contain any number of consecutive fixed-width Fixed width areas can contain any number of consecutive fixed-width lines.
lines.
<a id="Horizontal_Rules"></a> <a id="Horizontal_Rules"></a>
## Horizontal Rules ## Horizontal Rules
A horizontal rule is a line made of at least 5 consecutive hyphens. A horizontal rule is a line made of at least 5 consecutive hyphens. It can be
It can be indented. indented.
<a id="Keywords"></a> <a id="Keywords"></a>
@ -495,13 +484,12 @@ Keywords follow the syntax:
#+KEY: VALUE #+KEY: VALUE
KEY can contain any non-whitespace character, but it cannot be KEY can contain any non-whitespace character, but it cannot be equal to `CALL`
equal to &ldquo;CALL&rdquo; or any affiliated keyword. or any affiliated keyword.
VALUE can contain any character excepted a new line. VALUE can contain any character excepted a new line.
If KEY belongs to `org-element-document-properties`, VALUE can If KEY belongs to `org-element-document-properties`, VALUE can contain objects.
contain objects.
<a id="LaTeX_Environments"></a> <a id="LaTeX_Environments"></a>
@ -513,14 +501,14 @@ Pattern for LaTeX environments is:
NAME is constituted of alpha-numeric or asterisk characters. NAME is constituted of alpha-numeric or asterisk characters.
CONTENTS can contain anything but the &ldquo;\end{NAME}&rdquo; string. CONTENTS can contain anything but the `\end{NAME}` string.
<a id="Node_Properties"></a> <a id="Node_Properties"></a>
## Node Properties ## Node Properties
Node properties can only exist in [property drawers](#Property_Drawers). Their pattern Node properties can only exist in [property drawers](#Property_Drawers). Their
is any of the following pattern is any of the following
:NAME: VALUE :NAME: VALUE
@ -530,8 +518,8 @@ is any of the following
:NAME+: :NAME+:
NAME can contain any non-whitespace character but cannot end with NAME can contain any non-whitespace character but cannot end with a plus sign.
a plus sign. It cannot be the empty string. It cannot be the empty string.
VALUE can contain anything but a newline character. VALUE can contain anything but a newline character.
@ -539,8 +527,8 @@ VALUE can contain anything but a newline character.
## Paragraphs ## Paragraphs
Paragraphs are the default element, which means that any Paragraphs are the default element, which means that any unrecognized context is
unrecognized context is a paragraph. a paragraph.
Empty lines and other elements end paragraphs. Empty lines and other elements end paragraphs.
@ -550,11 +538,11 @@ Paragraphs can contain every type of object.
## Table Rows ## Table Rows
A table rows is either constituted of a vertical bar and any number A table rows is either constituted of a vertical bar and any number of [table
of [table cells](#Table_Cells) or a vertical bar followed by a hyphen. cells](#Table_Cells) or a vertical bar followed by a hyphen.
In the first case the table row has the &ldquo;standard&rdquo; type. In the In the first case the table row has the **standard** type. In the second case,
second case, it has the &ldquo;rule&rdquo; type. it has the **rule** type.
Table rows can only exist in [tables](#Tables). Table rows can only exist in [tables](#Tables).
@ -564,19 +552,18 @@ Table rows can only exist in [tables](#Tables).
Objects can only be found in the following locations: Objects can only be found in the following locations:
- [affiliated keywords](#Affiliated_keywords) defined in `org-element-parsed-keywords`, - [affiliated keywords](#Affiliated_keywords) defined in
`org-element-parsed-keywords`,
- [document properties](#Keywords), - [document properties](#Keywords),
- [headline](#Headlines_and_Sections) titles, - [headline](#Headlines_and_Sections) titles,
- [inlinetask](#Inlinetasks) titles, - [inlinetask](#Inlinetasks) titles,
- [item](#Plain_Lists_and_Items) tags, - [item](#Plain_Lists_and_Items) tags,
- [paragraphs](#Paragraphs), - [paragraphs](#Paragraphs),
- [table cells](#Table_Cells), - [table cells](#Table_Cells),
- [table rows](#Table_Rows), which can only contain table cell - [table rows](#Table_Rows), which can only contain table cell objects,
objects,
- [verse blocks](#Blocks). - [verse blocks](#Blocks).
Most objects cannot contain objects. Those which can will be Most objects cannot contain objects. Those which can will be specified.
specified.
<a id="Entities_and_LaTeX_Fragments"></a> <a id="Entities_and_LaTeX_Fragments"></a>
@ -589,8 +576,8 @@ An entity follows the pattern:
where NAME has a valid association in either `org-entities` or where NAME has a valid association in either `org-entities` or
`org-entities-user`. `org-entities-user`.
POST is the end of line, &ldquo;{}&rdquo; string, or a non-alphabetical POST is the end of line, `{}` string, or a non-alphabetical character. It isn't
character. It isn&rsquo;t separated from NAME by a whitespace character. separated from NAME by a whitespace character.
A LaTeX fragment can follow multiple patterns: A LaTeX fragment can follow multiple patterns:
@ -601,48 +588,43 @@ A LaTeX fragment can follow multiple patterns:
PRE$CHAR$POST PRE$CHAR$POST
PRE$BORDER1 BODY BORDER2$POST PRE$BORDER1 BODY BORDER2$POST
NAME contains alphabetical characters only and must not have an NAME contains alphabetical characters only and must not have an association in
association in either `org-entities` or `org-entities-user`. either **org-entities** or **org-entities-user**.
BRACKETS is optional, and is not separated from NAME with white BRACKETS is optional, and is not separated from NAME with white spaces. It may
spaces. It may contain any number of the following patterns: contain any number of the following patterns:
[CONTENTS1] [CONTENTS1]
{CONTENTS2} {CONTENTS2}
where CONTENTS1 can contain any characters excepted &ldquo;{&rdquo; &ldquo;}&rdquo;, &ldquo;[&rdquo; where CONTENTS1 can contain any characters excepted `{` `}`, `[` `]` and newline
&ldquo;]&rdquo; and newline and CONTENTS2 can contain any character excepted and CONTENTS2 can contain any character excepted `{`, `}` and newline.
&ldquo;{&rdquo;, &ldquo;}&rdquo; and newline.
CONTENTS can contain any character but cannot contain &ldquo;\\)&rdquo; in the CONTENTS can contain any character but cannot contain `\\)` in the second
second template or &ldquo;\\]&rdquo; in the third one. template or `\\]` in the third one.
PRE is either the beginning of line or a character different from PRE is either the beginning of line or a character different from `$`.
`$`.
CHAR is a non-whitespace character different from `.`, `,`, `?`, CHAR is a non-whitespace character different from `.`, `,`, `?`, `;`, `'` or a
`;`, `'` or a double quote. double quote.
POST is any punctuation (including parentheses and quotes) or space POST is any punctuation (including parentheses and quotes) or space character,
character, or the end of line. or the end of line.
BORDER1 is a non-whitespace character different from `.`, `,`, `;` BORDER1 is a non-whitespace character different from `.`, `,`, `;` and `$`.
and `$`.
BODY can contain any character excepted `$`, and may not span over BODY can contain any character excepted `$`, and may not span over more than 3
more than 3 lines. lines.
BORDER2 is any non-whitespace character different from `,`, `.` and BORDER2 is any non-whitespace character different from `,`, `.` and `$`.
`$`.
--- ---
> It would introduce incompatibilities with previous Org versions, > It would introduce incompatibilities with previous Org versions, but support
> but support for `$...$` (and for symmetry, `$$...$$`) constructs > for `$...$` (and for symmetry, `$$...$$`) constructs ought to be removed.
> ought to be removed.
> >
> They are slow to parse, fragile, redundant and imply false > They are slow to parse, fragile, redundant and imply false positives. &#x2014;
> positives. &#x2014; ngz > ngz
<a id="Export_Snippets"></a> <a id="Export_Snippets"></a>
@ -654,7 +636,7 @@ Patter for export snippets is:
NAME can contain any alpha-numeric character and hyphens. NAME can contain any alpha-numeric character and hyphens.
VALUE can contain anything but &ldquo;@@&rdquo; string. VALUE can contain anything but `@@` string.
<a id="Footnote_References"></a> <a id="Footnote_References"></a>
@ -666,16 +648,15 @@ There are four patterns for footnote references:
[fn:LABEL:DEFINITION] [fn:LABEL:DEFINITION]
[fn::DEFINITION] [fn::DEFINITION]
LABEL can contain any word constituent character, hyphens and LABEL can contain any word constituent character, hyphens and underscores.
underscores.
DEFINITION can contain any character. Though opening and closing DEFINITION can contain any character. Though opening and closing square brackets
square brackets must be balanced in it. It can contain any object must be balanced in it. It can contain any object encountered in a paragraph,
encountered in a paragraph, even other footnote references. even other footnote references.
If the reference follows the second pattern, it is called an If the reference follows the second pattern, it is called an **inline
&ldquo;inline footnote&rdquo;. If it follows the third one, i.e. if LABEL is footnote**. If it follows the third one, i.e. if LABEL is omitted, it is an
omitted, it is an &ldquo;anonymous footnote&rdquo;. **anonymous footnote**.
<a id="Inline_Babel_Calls_and_Source_Blocks"></a> <a id="Inline_Babel_Calls_and_Source_Blocks"></a>
@ -686,11 +667,11 @@ Inline Babel calls follow any of the following patterns:
call_NAME(ARGUMENTS) call_NAME(ARGUMENTS)
call_NAME[HEADER](ARGUMENTS)[HEADER] call_NAME[HEADER](ARGUMENTS)[HEADER]
NAME can contain any character besides `(`, `)` and &ldquo;\n&rdquo;. NAME can contain any character besides `(`, `)` and `\n`.
HEADER can contain any character besides `]` and &ldquo;\n&rdquo;. HEADER can contain any character besides `]` and `\n`.
ARGUMENTS can contain any character besides `)` and &ldquo;\n&rdquo;. ARGUMENTS can contain any character besides `)` and `\n`.
Inline source blocks follow any of the following patterns: Inline source blocks follow any of the following patterns:
@ -699,14 +680,14 @@ Inline source blocks follow any of the following patterns:
LANG can contain any non-whitespace character. LANG can contain any non-whitespace character.
OPTIONS and BODY can contain any character but &ldquo;\n&rdquo;. OPTIONS and BODY can contain any character but `\n`.
<a id="Line_Breaks"></a> <a id="Line_Breaks"></a>
## Line Breaks ## Line Breaks
A line break consists in &ldquo;\\\SPACE&rdquo; pattern at the end of an A line break consists in `\\\SPACE` pattern at the end of an otherwise non-empty
otherwise non-empty line. line.
SPACE can contain any number of tabs and spaces, including 0. SPACE can contain any number of tabs and spaces, including 0.
@ -723,25 +704,27 @@ There are 4 major types of links:
PRE1 and POST1, when they exist, are non alphanumeric characters. PRE1 and POST1, when they exist, are non alphanumeric characters.
RADIO is a string matched by some [radio target](#Targets_and_Radio_Targets). It may contain RADIO is a string matched by some [radio target](#Targets_and_Radio_Targets). It
[entities](#Entities_and_LaTeX_Fragments), [latex fragments](#Entities_and_LaTeX_Fragments), [subscript](#Subscript_and_Superscript) and [superscript](#Subscript_and_Superscript). may contain [entities](#Entities_and_LaTeX_Fragments), [latex
fragments](#Entities_and_LaTeX_Fragments),
[subscript](#Subscript_and_Superscript) and
[superscript](#Subscript_and_Superscript).
PROTOCOL is a string among `org-link-types`. PROTOCOL is a string among `org-link-types`.
PATH can contain any character but `]`, `<`, `>` and `\n`. PATH can contain any character but `]`, `<`, `>` and `\n`.
PRE2 and POST2, when they exist, are non word constituent PRE2 and POST2, when they exist, are non word constituent characters.
characters.
PATH2 can contain any non-whitespace character excepted `(`, `)`, PATH2 can contain any non-whitespace character excepted `(`, `)`, `<` and `>`.
`<` and `>`. It must end with a word-constituent character, or any It must end with a word-constituent character, or any non-whitespace
non-whitespace non-punctuation character followed by `/`. non-punctuation character followed by `/`.
DESCRIPTION must be enclosed within square brackets. It can DESCRIPTION must be enclosed within square brackets. It can contain any
contain any character but square brackets. It can contain any character but square brackets. It can contain any object found in a paragraph
object found in a paragraph excepted a [footnote reference](#Footnote_References), a [radio excepted a [footnote reference](#Footnote_References), a [radio
target](#Targets_and_Radio_Targets) and a [line break](#Line_Breaks). It cannot contain another link either, target](#Targets_and_Radio_Targets) and a [line break](#Line_Breaks). It cannot
unless it is a plain or angular link. contain another link either, unless it is a plain or angular link.
DESCRIPTION is optional. DESCRIPTION is optional.
@ -761,8 +744,8 @@ PATH4 can contain any character besides square brackets.
ID is constituted of hexadecimal numbers separated with hyphens. ID is constituted of hexadecimal numbers separated with hyphens.
PATH4, CUSTOM-ID, CODEREF and FUZZY can contain any character PATH4, CUSTOM-ID, CODEREF and FUZZY can contain any character besides square
besides square brackets. brackets.
<a id="Macros"></a> <a id="Macros"></a>
@ -772,12 +755,12 @@ Macros follow the pattern:
{{{NAME(ARGUMENTS)}}} {{{NAME(ARGUMENTS)}}}
NAME must start with a letter and can be followed by any number of NAME must start with a letter and can be followed by any number of alpha-numeric
alpha-numeric characters, hyphens and underscores. characters, hyphens and underscores.
ARGUMENTS can contain anything but &ldquo;}}}&rdquo; string. Values within ARGUMENTS can contain anything but `}}}` string. Values within ARGUMENTS are
ARGUMENTS are separated by commas. Non-separating commas have to separated by commas. Non-separating commas have to be escaped with a backslash
be escaped with a backslash character. character.
<a id="Targets_and_Radio_Targets"></a> <a id="Targets_and_Radio_Targets"></a>
@ -787,18 +770,19 @@ Radio targets follow the pattern:
<<<CONTENTS>>> <<<CONTENTS>>>
CONTENTS can be any character besides `<`, `>` and &ldquo;\n&rdquo;. It cannot CONTENTS can be any character besides `<`, `>` and `\n`. It cannot start or end
start or end with a whitespace character. As far as objects go, it with a whitespace character. As far as objects go, it can contain [text
can contain [text markup](#Emphasis_Markers), [entities](#Entities_and_LaTeX_Fragments), [latex fragments](#Entities_and_LaTeX_Fragments), [subscript](#Subscript_and_Superscript) and markup](#Emphasis_Markers), [entities](#Entities_and_LaTeX_Fragments), [latex
fragments](#Entities_and_LaTeX_Fragments),
[subscript](#Subscript_and_Superscript) and
[superscript](#Subscript_and_Superscript) only. [superscript](#Subscript_and_Superscript) only.
Targets follow the pattern: Targets follow the pattern:
<<TARGET>> <<TARGET>>
TARGET can contain any character besides `<`, `>` and &ldquo;\n&rdquo;. It TARGET can contain any character besides `<`, `>` and `\n`. It cannot start or
cannot start or end with a whitespace character. It cannot contain end with a whitespace character. It cannot contain any object.
any object.
<a id="Statistics_Cookies"></a> <a id="Statistics_Cookies"></a>
@ -825,9 +809,9 @@ Pattern for superscript is:
CHAR is any non-whitespace character. CHAR is any non-whitespace character.
SCRIPT can be `*` or an expression enclosed in parenthesis SCRIPT can be `*` or an expression enclosed in parenthesis (respectively curly
(respectively curly brackets), possibly containing balanced brackets), possibly containing balanced parenthesis (respectively curly
parenthesis (respectively curly brackets). brackets).
SCRIPT can also follow the pattern: SCRIPT can also follow the pattern:
@ -835,8 +819,8 @@ SCRIPT can also follow the pattern:
SIGN is either a plus sign, a minus sign, or an empty string. SIGN is either a plus sign, a minus sign, or an empty string.
CHARS is any number of alpha-numeric characters, commas, CHARS is any number of alpha-numeric characters, commas, backslashes and dots,
backslashes and dots, or an empty string. or an empty string.
FINAL is an alpha-numeric character. FINAL is an alpha-numeric character.
@ -852,11 +836,10 @@ Table cells follow the pattern:
CONTENTS can contain any character excepted a vertical bar. CONTENTS can contain any character excepted a vertical bar.
SPACES contains any number of space characters, including zero. It SPACES contains any number of space characters, including zero. It can be used
can be used to align properly the table. to align properly the table.
The final bar may be replaced with a newline character for the last The final bar may be replaced with a newline character for the last cell in row.
cell in row.
<a id="Timestamp"></a> <a id="Timestamp"></a>
@ -878,29 +861,28 @@ DATE follows the pattern:
YYYY-MM-DD DAYNAME YYYY-MM-DD DAYNAME
`Y`, `M` and `D` are digits. DAYNAME can contain any non `Y`, `M` and `D` are digits. DAYNAME can contain any non whitespace-character
whitespace-character besides `+`, `-`, `]`, `>`, a digit or `\n`. besides `+`, `-`, `]`, `>`, a digit or `\n`.
TIME follows the pattern `H:MM`. `H` can be one or two digit long TIME follows the pattern `H:MM`. `H` can be one or two digit long and can start
and can start with 0. with 0.
REPEATER-OR-DELAY follows the pattern: REPEATER-OR-DELAY follows the pattern:
MARK VALUE UNIT MARK VALUE UNIT
MARK is `+` (cumulate type), `++` (catch-up type) or `.+` (restart MARK is `+` (cumulate type), `++` (catch-up type) or `.+` (restart type) for a
type) for a repeater, and `-` (all type) or `--` (first type) for repeater, and `-` (all type) or `--` (first type) for warning delays.
warning delays.
VALUE is a number. VALUE is a number.
UNIT is a character among `h` (hour), `d` (day), `w` (week), `m` UNIT is a character among `h` (hour), `d` (day), `w` (week), `m` (month), `y`
(month), `y` (year). (year).
MARK, VALUE and UNIT are not separated by whitespace characters. MARK, VALUE and UNIT are not separated by whitespace characters.
There can be two REPEATER-OR-DELAY in the timestamp: one as There can be two REPEATER-OR-DELAY in the timestamp: one as a repeater and one
a repeater and one as a warning delay. as a warning delay.
<a id="Emphasis_Markers"></a> <a id="Emphasis_Markers"></a>
@ -910,32 +892,30 @@ Text markup follows the pattern:
PRE MARKER CONTENTS MARKER POST PRE MARKER CONTENTS MARKER POST
PRE is a whitespace character, `(`, `{` `'` or a double quote. It PRE is a whitespace character, `(`, `{` `'` or a double quote. It can also be a
can also be a beginning of line. beginning of line.
MARKER is a character among `*` (bold), `=` (verbatim), `/` MARKER is a character among `*` (bold), `=` (verbatim), `/` (italic), `+`
(italic), `+` (strike-through), `_` (underline), `~` (code). (strike-through), `_` (underline), `~` (code).
CONTENTS is a string following the pattern: CONTENTS is a string following the pattern:
BORDER BODY BORDER BORDER BODY BORDER
BORDER can be any non-whitespace character excepted `,`, `'` or BORDER can be any non-whitespace character excepted `,`, `'` or a double quote.
a double quote.
BODY can contain contain any character but may not span over more BODY can contain contain any character but may not span over more than 3 lines.
than 3 lines.
BORDER and BODY are not separated by whitespaces. BORDER and BODY are not separated by whitespaces.
CONTENTS can contain any object encountered in a paragraph when CONTENTS can contain any object encountered in a paragraph when markup is
markup is &ldquo;bold&rdquo;, &ldquo;italic&rdquo;, &ldquo;strike-through&rdquo; or &ldquo;underline&rdquo;. **bold**, **italic**, **strike-through** or **underline**.
POST is a whitespace character, `-`, `.`, `,`, `:`, `!`, `?`, `'`, POST is a whitespace character, `-`, `.`, `,`, `:`, `!`, `?`, `'`, `)`, `}` or a
`)`, `}` or a double quote. It can also be an end of line. double quote. It can also be an end of line.
PRE, MARKER, CONTENTS, MARKER and POST are not separated by PRE, MARKER, CONTENTS, MARKER and POST are not separated by whitespace
whitespace characters. characters.
--- ---
@ -944,19 +924,19 @@ whitespace characters.
> >
> This should really be simplified. > This should really be simplified.
> >
> Also, CONTENTS should be anything within code and verbatim > Also, CONTENTS should be anything within code and verbatim emphasis, by
> emphasis, by definition. &#x2014; ngz > definition. &#x2014; ngz
# Footnotes # Footnotes
<sup><a id="fn.1" href="#fnr.1">1</a></sup> In particular, the parser requires stars at column 0 to be <sup><a id="fn.1" href="#fnr.1">1</a></sup> In particular, the parser requires
quoted by a comma when they do not define a headline. stars at column 0 to be quoted by a comma when they do not define a headline.
<sup><a id="fn.2" href="#fnr.2">2</a></sup> It also means that only headlines and sections can be <sup><a id="fn.2" href="#fnr.2">2</a></sup> It also means that only headlines
recognized just by looking at the beginning of the line. Planning and sections can be recognized just by looking at the beginning of the line.
lines and property drawers can be recognized by looking at one or two Planning lines and property drawers can be recognized by looking at one or two
lines above. lines above.
As a consequence, using `org-element-at-point` or As a consequence, using `org-element-at-point` or `org-element-context` will
`org-element-context` will move up to the parent headline, and parse move up to the parent headline, and parse top-down from there until context
top-down from there until context around original location is found. around original location is found.