1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070#+TITLE: Org Syntax (draft)
#+AUTHOR: Nicolas Goaziou
#+OPTIONS: toc:t ':t author:nil
#+LANGUAGE: en
#+CATEGORY: worg
#+BIND: sentence-end-double-space t
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-free[fn:1][fn: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.
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 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.
* Headlines and Sections
:PROPERTIES:
:CUSTOM_ID: Headlines_and_Sections
:END:
A headline is defined as:
#+BEGIN_EXAMPLE
STARS KEYWORD PRIORITY TITLE TAGS
#+END_EXAMPLE
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.
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.
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:
#+BEGIN_EXAMPLE
,*
,** DONE
,*** Some e-mail
,**** TODO [#A] COMMENT Title :tag:a2%:
#+END_EXAMPLE
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 "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 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:
#+BEGIN_EXAMPLE
An introduction.
,* A Headline
Some text.
,** Sub-Topic 1
,** Sub-Topic 2
,*** Additional entry
#+END_EXAMPLE
Its internal structure could be summarized as:
#+BEGIN_EXAMPLE
(document
(section)
(headline
(section)
(headline)
(headline
(headline))))
#+END_EXAMPLE
* Affiliated Keywords
:PROPERTIES:
:CUSTOM_ID: Affiliated_keywords
:END:
With the exception of comment, clocks, headlines, inlinetasks,
items, node properties, planning, property drawers, sections, and
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.
Affiliated keywords are built upon one of the following patterns:
#+BEGIN_EXAMPLE
,#+KEY: VALUE
,#+KEY[OPTIONAL]: VALUE
,#+ATTR_BACKEND: VALUE
#+END_EXAMPLE
KEY is either "CAPTION", "HEADER", "NAME", "PLOT" or "RESULTS"
string.
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.
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.
* Greater Elements
:PROPERTIES:
:CUSTOM_ID: Greater_Elements
:END:
Unless specified otherwise, greater elements can contain directly
any other element or greater element except:
- elements of their own type,
- node properties, which can only be found in property drawers,
- items, which can only be found in plain lists.
** Greater Blocks
:PROPERTIES:
:CUSTOM_ID: Greater_Blocks
:END:
Greater blocks consist in the following pattern:
#+BEGIN_EXAMPLE
,#+BEGIN_NAME PARAMETERS
CONTENTS
,#+END_NAME
#+END_EXAMPLE
NAME can contain any non-whitespace character.
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 the block is neither a center block, a quote block or a block
element, 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.
** Drawers and Property Drawers
:PROPERTIES:
:CUSTOM_ID: Drawers
:END:
Pattern for drawers is:
#+BEGIN_EXAMPLE
:NAME:
CONTENTS
:END:
#+END_EXAMPLE
NAME can contain word-constituent characters, hyphens and
underscores.
CONTENTS can contain any element but another drawer.
** Dynamic Blocks
:PROPERTIES:
:CUSTOM_ID: Dynamic_Blocks
:END:
Pattern for dynamic blocks is:
#+BEGIN_EXAMPLE
,#+BEGIN: NAME PARAMETERS
CONTENTS
,#+END:
#+END_EXAMPLE
NAME cannot contain any whitespace character.
PARAMETERS can contain any character and can be omitted.
** Footnote Definitions
:PROPERTIES:
:CUSTOM_ID: Footnote_Definitions
:END:
Pattern for footnote definitions is:
#+BEGIN_EXAMPLE
[fn:LABEL] CONTENTS
#+END_EXAMPLE
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.
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
:PROPERTIES:
:CUSTOM_ID: Inlinetasks
:END:
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.
Inlinetasks are recognized only after =org-inlinetask= library is
loaded.
** Plain Lists and Items
:PROPERTIES:
:CUSTOM_ID: Plain_Lists_and_Items
:END:
Items are defined by a line starting with the following pattern:
"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.
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.
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.
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.
For example, consider the following excerpt of an Org document:
#+BEGIN_EXAMPLE
1. item 1
2. [X] item 2
- some tag :: item 2.1
#+END_EXAMPLE
Its internal structure is as follows:
#+BEGIN_EXAMPLE
(ordered-plain-list
(item)
(item
(descriptive-plain-list
(item))))
#+END_EXAMPLE
** Property Drawers
:PROPERTIES:
:CUSTOM_ID: Property_Drawers
:END:
Property drawers are a special type of drawer containing properties
attached to a headline. They are located right after a headline
and its planning information.
#+BEGIN_EXAMPLE
HEADLINE
PROPERTYDRAWER
HEADLINE
PLANNING
PROPERTYDRAWER
#+END_EXAMPLE
PROPERTYDRAWER follows the pattern
#+BEGIN_EXAMPLE
:PROPERTIES:
CONTENTS
:END:
#+END_EXAMPLE
where CONTENTS consists of zero or more node properties.
** Tables
:PROPERTIES:
:CUSTOM_ID: Tables
:END:
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.
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.
One or more "#+TBLFM: FORMULAS" lines, where "FORMULAS" can contain
any character, can follow an org table.
* Elements
:PROPERTIES:
:CUSTOM_ID: Elements
:END:
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.
** Babel Call
:PROPERTIES:
:CUSTOM_ID: Babel_Call
:END:
Pattern for babel calls is:
#+BEGIN_EXAMPLE
,#+CALL: VALUE
#+END_EXAMPLE
VALUE is optional. It can contain any character but a new line.
** Blocks
:PROPERTIES:
:CUSTOM_ID: Blocks
:END:
Like greater blocks, pattern for blocks is:
#+BEGIN_EXAMPLE
,#+BEGIN_NAME DATA
CONTENTS
,#+END_NAME
#+END_EXAMPLE
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".
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.
LANGUAGE cannot contain any whitespace character.
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.
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.
** Clock, Diary Sexp and Planning
:PROPERTIES:
:CUSTOM_ID: Clock,_Diary_Sexp_and_Planning
:END:
A clock follows either of the patterns below:
#+BEGIN_EXAMPLE
CLOCK: INACTIVE-TIMESTAMP
CLOCK: INACTIVE-TIMESTAMP-RANGE DURATION
#+END_EXAMPLE
INACTIVE-TIMESTAMP, resp. INACTIVE-TIMESTAMP-RANGE, is an inactive,
resp. inactive range, timestamp object.
DURATION follows the pattern:
#+BEGIN_EXAMPLE
=> HH:MM
#+END_EXAMPLE
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 planning is an element with the following pattern:
#+BEGIN_EXAMPLE
HEADLINE
PLANNING
#+END_EXAMPLE
where HEADLINE is a headline element and PLANNING is a line filled
with INFO parts, where each of them follows the pattern:
#+BEGIN_EXAMPLE
KEYWORD: TIMESTAMP
#+END_EXAMPLE
KEYWORD is either "DEADLINE", "SCHEDULED" or "CLOSED". TIMESTAMP
is a timestamp object.
In particular, no blank line is allowed between PLANNING and
HEADLINE.
** Comments
:PROPERTIES:
:CUSTOM_ID: Comments
:END:
A "comment line" starts with zero or more whitespace characters,
followed by a hash sign and a whitespace character or an end of
line.
Comments consist of one or more consecutive comment lines.
** Fixed Width Areas
:PROPERTIES:
:CUSTOM_ID: Fixed_Width_Areas
:END:
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.
** Horizontal Rules
:PROPERTIES:
:CUSTOM_ID: Horizontal_Rules
:END:
A horizontal rule is a line made of at least 5 consecutive hyphens.
It can be indented.
** Keywords
:PROPERTIES:
:CUSTOM_ID: Keywords
:END:
Keywords follow the syntax:
#+BEGIN_EXAMPLE
,#+KEY: VALUE
#+END_EXAMPLE
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.
** LaTeX Environments
:PROPERTIES:
:CUSTOM_ID: LaTeX_Environments
:END:
Pattern for LaTeX environments is:
#+BEGIN_EXAMPLE
\begin{NAME} CONTENTS \end{NAME}
#+END_EXAMPLE
NAME is constituted of alpha-numeric or asterisk characters.
CONTENTS can contain anything but the "\end{NAME}" string.
** Node Properties
:PROPERTIES:
:CUSTOM_ID: Node_Properties
:END:
Node properties can only exist in property drawers. Their pattern
is any of the following
#+BEGIN_EXAMPLE
:NAME: VALUE
:NAME+: VALUE
:NAME:
:NAME+:
#+END_EXAMPLE
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.
** Paragraphs
:PROPERTIES:
:CUSTOM_ID: Paragraphs
:END:
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.
** Table Rows
:PROPERTIES:
:CUSTOM_ID: Table_Rows
:END:
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 "standard" type. In the
second case, it has the "rule" type.
Table rows can only exist in tables.
* Objects
:PROPERTIES:
:CUSTOM_ID: Objects
:END:
Objects can only be found in the following locations:
- affiliated keywords defined in ~org-element-parsed-keywords~,
- document properties,
- headline titles,
- inlinetask titles,
- item tags,
- paragraphs,
- table cells,
- table rows, which can only contain table cell
objects,
- verse blocks.
Most objects cannot contain objects. Those which can will be
specified.
** Entities and LaTeX Fragments
:PROPERTIES:
:CUSTOM_ID: Entities_and_LaTeX_Fragments
:END:
An entity follows the pattern:
#+BEGIN_EXAMPLE
\NAME POST
#+END_EXAMPLE
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.
A LaTeX fragment can follow multiple patterns:
#+BEGIN_EXAMPLE
\NAME BRACKETS
\(CONTENTS\)
\[CONTENTS\]
$$CONTENTS$$
PRE$CHAR$POST
PRE$BORDER1 BODY BORDER2$POST
#+END_EXAMPLE
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:
#+BEGIN_EXAMPLE
[CONTENTS1]
{CONTENTS2}
#+END_EXAMPLE
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.
PRE is either the beginning of line or a character different from
~$~.
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.
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
~$~.
#+ATTR_ASCII: :width 5
-----
#+BEGIN_QUOTE
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
#+END_QUOTE
** Export Snippets
:PROPERTIES:
:CUSTOM_ID: Export_Snippets
:END:
Patter for export snippets is:
#+BEGIN_EXAMPLE
@@NAME:VALUE@@
#+END_EXAMPLE
NAME can contain any alpha-numeric character and hyphens.
VALUE can contain anything but "@@" string.
** Footnote References
:PROPERTIES:
:CUSTOM_ID: Footnote_References
:END:
There are four patterns for footnote references:
#+BEGIN_EXAMPLE
[fn:LABEL]
[fn:LABEL:DEFINITION]
[fn::DEFINITION]
#+END_EXAMPLE
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 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".
** Inline Babel Calls and Source Blocks
:PROPERTIES:
:CUSTOM_ID: Inline_Babel_Calls_and_Source_Blocks
:END:
Inline Babel calls follow any of the following patterns:
#+BEGIN_EXAMPLE
call_NAME(ARGUMENTS)
call_NAME[HEADER](ARGUMENTS)[HEADER]
#+END_EXAMPLE
NAME can contain any character besides ~(~, ~)~ and "\n".
HEADER can contain any character besides ~]~ and "\n".
ARGUMENTS can contain any character besides ~)~ and "\n".
Inline source blocks follow any of the following patterns:
#+BEGIN_EXAMPLE
src_LANG{BODY}
src_LANG[OPTIONS]{BODY}
#+END_EXAMPLE
LANG can contain any non-whitespace character.
OPTIONS and BODY can contain any character but "\n".
** Line Breaks
:PROPERTIES:
:CUSTOM_ID: Line_Breaks
:END:
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.
** Links
:PROPERTIES:
:CUSTOM_ID: Links
:END:
There are 4 major types of links:
#+BEGIN_EXAMPLE
PRE1 RADIO POST1 ("radio" link)
<PROTOCOL:PATH> ("angle" link)
PRE2 PROTOCOL:PATH2 POST2 ("plain" link)
[[PATH3]DESCRIPTION] ("regular" link)
#+END_EXAMPLE
PRE1 and POST1, when they exist, are non alphanumeric characters.
RADIO is a string matched by some radio target. It may contain
entities, latex fragments, 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.
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, a radio
target and a line break. It cannot contain another link either,
unless it is a plain or angular link.
DESCRIPTION is optional.
PATH3 is built according to the following patterns:
#+BEGIN_EXAMPLE
FILENAME ("file" type)
PROTOCOL:PATH4 ("PROTOCOL" type)
PROTOCOL://PATH4 ("PROTOCOL" type)
id:ID ("id" type)
#CUSTOM-ID ("custom-id" type)
(CODEREF) ("coderef" type)
FUZZY ("fuzzy" type)
#+END_EXAMPLE
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.
** Macros
:PROPERTIES:
:CUSTOM_ID: Macros
:END:
Macros follow the pattern:
#+BEGIN_EXAMPLE
{{{NAME(ARGUMENTS)}}}
#+END_EXAMPLE
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.
** Targets and Radio Targets
:PROPERTIES:
:CUSTOM_ID: Targets_and_Radio_Targets
:END:
Radio targets follow the pattern:
#+BEGIN_EXAMPLE
<<<CONTENTS>>>
#+END_EXAMPLE
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, entities, latex fragments, subscript and
superscript only.
Targets follow the pattern:
#+BEGIN_EXAMPLE
<<TARGET>>
#+END_EXAMPLE
TARGET can contain any character besides ~<~, ~>~ and "\n". It
cannot start or end with a whitespace character. It cannot contain
any object.
** Statistics Cookies
:PROPERTIES:
:CUSTOM_ID: Statistics_Cookies
:END:
Statistics cookies follow either pattern:
#+BEGIN_EXAMPLE
[PERCENT%]
[NUM1/NUM2]
#+END_EXAMPLE
PERCENT, NUM1 and NUM2 are numbers or the empty string.
** Subscript and Superscript
:PROPERTIES:
:CUSTOM_ID: Subscript_and_Superscript
:END:
Pattern for subscript is:
#+BEGIN_EXAMPLE
CHAR_SCRIPT
#+END_EXAMPLE
Pattern for superscript is:
#+BEGIN_EXAMPLE
CHAR^SCRIPT
#+END_EXAMPLE
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 also follow the pattern:
#+BEGIN_EXAMPLE
SIGN CHARS FINAL
#+END_EXAMPLE
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.
FINAL is an alpha-numeric character.
There is no white space between SIGN, CHARS and FINAL.
** Table Cells
:PROPERTIES:
:CUSTOM_ID: Table_Cells
:END:
Table cells follow the pattern:
#+BEGIN_EXAMPLE
CONTENTS SPACES|
#+END_EXAMPLE
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.
The final bar may be replaced with a newline character for the last
cell in row.
** Timestamps
:PROPERTIES:
:CUSTOM_ID: Timestamp
:END:
There are seven possible patterns for timestamps:
#+BEGIN_EXAMPLE
<%%(SEXP)> (diary)
<DATE TIME REPEATER-OR-DELAY> (active)
[DATE TIME REPEATER-OR-DELAY] (inactive)
<DATE TIME REPEATER-OR-DELAY>--<DATE TIME REPEATER-OR-DELAY> (active range)
<DATE TIME-TIME REPEATER-OR-DELAY> (active range)
[DATE TIME REPEATER-OR-DELAY]--[DATE TIME REPEATER-OR-DELAY] (inactive range)
[DATE TIME-TIME REPEATER-OR-DELAY] (inactive range)
#+END_EXAMPLE
SEXP can contain any character excepted ~>~ and ~\n~.
DATE follows the pattern:
#+BEGIN_EXAMPLE
YYYY-MM-DD DAYNAME
#+END_EXAMPLE
~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.
REPEATER-OR-DELAY follows the pattern:
#+BEGIN_EXAMPLE
MARK VALUE UNIT
#+END_EXAMPLE
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).
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.
** Text Markup
:PROPERTIES:
:CUSTOM_ID: Emphasis_Markers
:END:
Text markup follows the pattern:
#+BEGIN_EXAMPLE
PRE MARKER CONTENTS MARKER POST
#+END_EXAMPLE
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).
CONTENTS is a string following the pattern:
#+BEGIN_EXAMPLE
BORDER BODY BORDER
#+END_EXAMPLE
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.
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".
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.
#+ATTR_ASCII: :width 5
-----
#+BEGIN_QUOTE
All of this is wrong if ~org-emphasis-regexp-components~ or
~org-emphasis-alist~ are modified.
This should really be simplified.
Also, CONTENTS should be anything within code and verbatim
emphasis, by definition. --- ngz
#+END_QUOTE
* Footnotes
[fn:1] In particular, the parser requires stars at column 0 to be
quoted by a comma when they do not define a headline.
[fn: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.
# Local Variables:
# sentence-end-double-space: t
# End: