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