59855612b7b983785e7c24579c4f4304e7d80ae0
[worg.git] / dev / org-syntax.org
1 #+TITLE: Org Syntax (draft)
2 #+AUTHOR: Nicolas Goaziou
3 #+OPTIONS: toc:t ':t author:nil
4 #+LANGUAGE: en
5 #+CATEGORY: worg
6 #+BIND: sentence-end-double-space t
7
8 This document describes and comments Org syntax as it is currently
9 read by its parser (Org Elements) and, therefore, by the export
10 framework.  It also includes a few comments on that syntax.
11
12 A core concept in this syntax is that only headlines and sections are
13 context-free[fn:1][fn:2].  Every other syntactical part only exists
14 within specific environments.
15
16 Three categories are used to classify these environments: "Greater
17 elements", "elements", and "objects", from the broadest scope to the
18 narrowest.  The word "element" is used for both Greater and non-Greater
19 elements, the context should make that clear.
20
21 The paragraph is the unit of measurement.  An element defines
22 syntactical parts that are at the same level as a paragraph,
23 i.e. which cannot contain or be included in a paragraph.  An object is
24 a part that could be included in an element.  Greater elements are all
25 parts that can contain an element.
26
27 Empty lines belong to the largest element ending before them.  For
28 example, in a list, empty lines between items belong are part of the
29 item before them, but empty lines at the end of a list belong to the
30 plain list element.
31
32 Unless specified otherwise, case is not significant.
33
34 * Headlines and Sections
35   :PROPERTIES:
36   :CUSTOM_ID: Headlines_and_Sections
37   :END:
38
39   A headline is defined as:
40
41   #+BEGIN_EXAMPLE
42   STARS KEYWORD PRIORITY TITLE TAGS
43   #+END_EXAMPLE
44
45   STARS is a string starting at column 0, containing at least one
46   asterisk (and up to ~org-inlinetask-min-level~ if =org-inlinetask=
47   library is loaded) and ended by a space character.  The number of
48   asterisks is used to define the level of the headline.  It's the
49   sole compulsory part of a headline.
50
51   KEYWORD is a TODO keyword, which has to belong to the list defined
52   in ~org-todo-keywords-1~.  Case is significant.
53
54   PRIORITY is a priority cookie, i.e. a single letter preceded by
55   a hash sign # and enclosed within square brackets.
56
57   TITLE can be made of any character but a new line.  Though, it will
58   match after every other part have been matched.
59     
60   TAGS is made of words containing any alpha-numeric character,
61   underscore, at sign, hash sign or percent sign, and separated with
62   colons.
63     
64   Examples of valid headlines include:
65
66   #+BEGIN_EXAMPLE
67   ,*
68
69   ,** DONE
70
71   ,*** Some e-mail
72
73   ,**** TODO [#A] COMMENT Title :tag:a2%:
74   #+END_EXAMPLE
75     
76   If the first word appearing in the title is ~org-comment-string~,
77   the headline will be considered as "commented".  If that first word
78   is ~org-quote-string~, it will be considered as "quoted".  In both
79   situations, case is significant.
80
81   If its title is ~org-footnote-section~, it will be considered as
82   a "footnote section".  Case is significant.
83
84   If ~org-archive-tag~ is one of its tags, it will be considered as
85   "archived".  Case is significant.
86
87   A headline contains directly one section (optionally), followed by
88   any number of deeper level headlines.
89
90   A section contains directly any greater element or element.  Only
91   a headline can contain a section.  As an exception, text before the
92   first headline in the document also belongs to a section.
93
94   If a quoted headline contains a section, the latter will be
95   considered as a "quote section".
96
97   As an example, consider the following document:
98
99   #+BEGIN_SRC org
100   An introduction.
101   
102   ,* A Headline 
103   
104     Some text.
105   
106   ,** Sub-Topic 1
107   
108   ,** Sub-Topic 2
109   
110   ,*** Additional entry 
111   
112   ,** QUOTE Another Sub-Topic
113   
114      Some other text.
115   #+END_SRC
116
117   Its internal structure could be summarized as:
118
119   #+BEGIN_EXAMPLE
120   (document
121    (section)
122    (headline
123     (section)
124     (headline)
125     (headline
126      (headline))
127     (headline
128      (quote-section))))
129   #+END_EXAMPLE
130   
131 * Affiliated Keywords
132   :PROPERTIES:
133   :CUSTOM_ID: Affiliated_keywords
134   :END:
135
136   With the exception of [[#Inlinetasks][inlinetasks]], [[#Plain_Lists_and_Items][items]], [[#Clock,_Diary_Sexp_and_Planning][planning]], [[#Clock,_Diary_Sexp_and_Planning][clocks]], [[#Node_Properties][node
137   properties]] and [[#Table_Rows][table rows]], every other element type can be assigned
138   attributes.
139
140   This is done by adding specific keywords, named "affiliated
141   keywords", just above the element considered, no blank line
142   allowed.
143
144   Affiliated keywords are built upon one of the following patterns:
145   "#+KEY: VALUE", "#+KEY[OPTIONAL]: VALUE" or "#+ATTR_BACKEND: VALUE".
146
147   KEY is either "CAPTION", "HEADER", "NAME", "PLOT" or "RESULTS"
148   string.
149
150   BACKEND is a string constituted of alpha-numeric characters, hyphens
151   or underscores.
152
153   OPTIONAL and VALUE can contain any character but a new line.  Only
154   "CAPTION" and "RESULTS" keywords can have an optional value.
155
156   An affiliated keyword can appear more than once if KEY is either
157   "CAPTION" or "HEADER" or if its pattern is "#+ATTR_BACKEND: VALUE".
158
159   "CAPTION", "AUTHOR", "DATE" and "TITLE" keywords can contain objects
160   in their value and their optional value, if applicable.
161
162 * Greater Elements
163   :PROPERTIES:
164   :CUSTOM_ID: Greater_Elements
165   :END:
166
167   Unless specified otherwise, greater elements can contain directly
168   any other element or greater element excepted:
169
170   - elements of their own type,
171   - [[#Node_Properties][node properties]], which can only be found in [[#Drawers_and_Property_Drawers][property drawers]],
172   - [[#Plain_Lists_and_Items][items]], which can only be found in [[#Plain_Lists_and_Items][plain lists]].
173
174 ** Greater Blocks
175    :PROPERTIES:
176    :CUSTOM_ID: Greater_Blocks
177    :END:
178
179    Greater blocks consist in the following pattern:
180
181    #+BEGIN_EXAMPLE
182    ,#+BEGIN_NAME PARAMETERS
183    CONTENTS
184    ,#+END_NAME
185    #+END_EXAMPLE
186
187    NAME can contain any non-whitespace character.
188
189    PARAMETERS can contain any character other than new line, and can
190    be omitted.
191
192    If NAME is "CENTER", it will be a "center block".  If it is
193    "QUOTE", it will be a "quote block".
194
195    If the block is neither a center block, a quote block or a [[#Blocks][block
196    element]], it will be a "special block".
197
198    CONTENTS can contain any element, except : a line =#+END_NAME= on
199    its own.  Also lines beginning with STARS must be quoted by
200    a comma.
201
202 ** Drawers and Property Drawers
203    :PROPERTIES:
204    :CUSTOM_ID: Drawers_and_Property_Drawers
205    :END:
206
207    Pattern for drawers is:
208
209    #+BEGIN_EXAMPLE
210    :NAME:
211    CONTENTS
212    :END:
213    #+END_EXAMPLE
214
215    NAME has to either be "PROPERTIES" or belong to ~org-drawers~ list.
216
217    If NAME is "PROPERTIES", the drawer will become a "property
218    drawer".
219
220    In a property drawers, CONTENTS can only contain [[#Node_Properties][node property]]
221    elements.  Otherwise it can contain any element but another drawer
222    or property drawer.
223
224    #+ATTR_ASCII: :width 5
225    -----
226
227    It would be nice if users hadn't to register drawers names before
228    using them in ~org-drawers~ (or through the ~#+DRAWERS:~ keyword).
229    Anything starting with ~^[ \t]*:\w+:[ \t]$~ and ending with
230    ~^[ \t]*:END:[ \t]$~ could be considered as a drawer.  --- ngz
231
232 ** Dynamic Blocks
233    :PROPERTIES:
234    :CUSTOM_ID: Dynamic_Blocks
235    :END:
236
237    Pattern for dynamic blocks is:
238
239    #+BEGIN_EXAMPLE
240    ,#+BEGIN: NAME PARAMETERS
241    CONTENTS
242    ,#+END:
243    #+END_EXAMPLE
244
245    NAME cannot contain any whitespace character.
246
247    PARAMETERS can contain any character and can be omitted.
248
249 ** Footnote Definitions
250    :PROPERTIES:
251    :CUSTOM_ID: Footnote_Definitions
252    :END:
253
254    Pattern for footnote definitions is:
255
256    #+BEGIN_EXAMPLE
257    [LABEL] CONTENTS
258    #+END_EXAMPLE
259
260    It must start at column 0.
261
262    LABEL is either a number or follows the pattern "fn:WORD", where
263    word can contain any word-constituent character, hyphens and
264    underscore characters.
265
266    CONTENTS can contain any element excepted another footnote
267    definition.  It ends at the next footnote definition, the next
268    headline, two consecutive empty lines or the end of buffer.
269
270 ** Inlinetasks
271    :PROPERTIES:
272    :CUSTOM_ID: Inlinetasks
273    :END:
274
275    Inlinetasks are defined by ~org-inlinetask-min-level~ contiguous
276    asterisk characters starting at column 0, followed by a whitespace
277    character.
278
279    Optionally, inlinetasks can be ended with a string constituted of
280    ~org-inlinetask-min-level~ contiguous asterisk characters starting
281    at column 0, followed by a space and the "END" string.
282
283    Inlinetasks are recognized only after =org-inlinetask= library is
284    loaded.
285
286 ** Plain Lists and Items
287    :PROPERTIES:
288    :CUSTOM_ID: Plain_Lists_and_Items
289    :END:
290
291    Items are defined by a line starting with the following pattern:
292    "BULLET COUNTER-SET CHECK-BOX TAG", in which only BULLET is
293    mandatory.
294
295    BULLET is either an asterisk, a hyphen, a plus sign character or
296    follows either the pattern "COUNTER." or "COUNTER)".  In any case,
297    BULLET is follwed by a whitespace character or line ending.
298
299    COUNTER can be a number or a single letter.
300
301    COUNTER-SET follows the pattern [@COUNTER].
302
303    CHECK-BOX is either a single whitespace character, a "X" character
304    or a hyphen, enclosed within square brackets.
305
306    TAG follows "TAG-TEXT ::" pattern, where TAG-TEXT can contain any
307    character but a new line.
308
309    An item ends before the next item, the first line less or equally
310    indented than its starting line, or two consecutive empty lines.
311    Indentation of lines within other greater elements do not count,
312    neither do inlinetasks boundaries.
313
314    A plain list is a set of consecutive items of the same indentation.
315    It can only directly contain items.
316
317    If first item in a plain list has a counter in its bullet, the
318    plain list will be an "ordered plain-list".  If it contains a tag,
319    it will be a "descriptive list".  Otherwise, it will be an
320    "unordered list".  List types are mutually exclusive.
321
322    For example, consider the following excerpt of an Org document:
323
324    #+BEGIN_EXAMPLE
325    1. item 1
326    2. [X] item 2
327       - some tag :: item 2.1
328    #+END_EXAMPLE
329
330    Its internal structure is as follows:
331
332    #+BEGIN_EXAMPLE
333    (ordered-plain-list
334     (item)
335     (item
336      (descriptive-plain-list
337       (item))))
338    #+END_EXAMPLE
339
340 ** Tables
341    :PROPERTIES:
342    :CUSTOM_ID: Tables
343    :END:
344
345    Tables start at lines beginning with either a vertical bar or the
346    "+-" string followed by plus or minus signs only, assuming they are
347    not preceded with lines of the same type.  These lines can be
348    indented.
349
350    A table starting with a vertical bar has "org" type.  Otherwise it
351    has "table.el" type.
352
353    Org tables end at the first line not starting with a vertical bar.
354    Table.el tables end at the first line not starting with either
355    a vertical line or a plus sign.  Such lines can be indented.
356
357    An org table can only contain table rows.  A table.el table does
358    not contain anything.
359
360    One or more "#+TBLFM: FORMULAS" lines, where "FORMULAS" can contain
361    any character, can follow an org table.
362
363 * Elements
364   :PROPERTIES:
365   :CUSTOM_ID: Elements
366   :END:
367
368   Elements cannot contain any other element.
369
370   Only [[#Keywords][keywords]] whose name belongs to
371   ~org-element-document-properties~, [[#Blocks][verse blocks]] , [[#Paragraphs][paragraphs]] and
372   [[#Table_Rows][table rows]] can contain objects.
373
374 ** Babel Call
375    :PROPERTIES:
376    :CUSTOM_ID: Babel_Call
377    :END:
378
379    Pattern for babel calls is:
380
381    #+BEGIN_EXAMPLE
382    ,#+CALL: VALUE
383    #+END_EXAMPLE
384
385    VALUE is optional.  It can contain any character but a new line.
386
387 ** Blocks
388    :PROPERTIES:
389    :CUSTOM_ID: Blocks
390    :END:
391
392    Like [[#Greater_Blocks][greater blocks]], pattern for blocks is:
393
394    #+BEGIN_EXAMPLE
395    ,#+BEGIN_NAME DATA
396    CONTENTS
397    ,#+END_NAME
398    #+END_EXAMPLE
399
400    NAME cannot contain any whitespace character.
401
402    If NAME is "COMMENT", it will be a "comment block".  If it is
403    "EXAMPLE", it will be an "example block".  If it is "SRC", it will
404    be a "source block".  If it is "VERSE", it will be a "verse block".
405
406    If NAME is a string matching the name of any export back-end
407    loaded, the block will be an "export block".
408
409    DATA can contain any character but a new line.  It can be ommitted,
410    unless the block is a "source block".  In this case, it must follow
411    the pattern "LANGUAGE SWITCHES ARGUMENTS", where SWITCHES and
412    ARGUMENTS are optional.
413
414    LANGUAGE cannot contain any whitespace character.
415
416    SWITCHES is made of any number of "SWITCH" patterns, separated by
417    blank lines.
418
419    A SWITCH pattern is either "-l "FORMAT"", where FORMAT can contain
420    any character but a double quote and a new line, "-S" or "+S",
421    where S stands for a single letter.
422
423    ARGUMENTS can contain any character but a new line.
424
425    CONTENTS can contain any character, including new lines.  Though it
426    will only contain Org objects if the block is a verse block.
427    Otherwise, contents will not be parsed.
428
429 ** Clock, Diary Sexp and Planning
430    :PROPERTIES:
431    :CUSTOM_ID: Clock,_Diary_Sexp_and_Planning
432    :END:
433
434    A clock follows the pattern:
435    
436    #+BEGIN_EXAMPLE
437    CLOCK: TIMESTAMP DURATION
438    #+END_EXAMPLE
439
440    Both TIMESTAMP and DURATION are optional.
441
442    TIMESTAMP is a [[#Timestamp][timestamp]] object.
443
444    DURATION follows the pattern:
445
446    #+BEGIN_EXAMPLE
447    => HH:MM
448    #+END_EXAMPLE
449
450    HH is a number containing any number of digits.  MM is a two digit
451    numbers.
452
453    A diary sexp is a line starting at column 0 with "%%(" string.  It
454    can then contain any character besides a new line.
455
456    A planning is a line filled with more at most three INFO parts,
457    where each INFO part follows the pattern:
458
459    #+BEGIN_EXAMPLE
460    KEYWORD: TIMESTAMP
461    #+END_EXAMPLE
462
463    KEYWORD is a string among ~org-deadline-string~,
464    ~org-scheduled-string~ and ~org-closed-string~.  TIMESTAMP is is
465    a [[#Timestamp][timestamp]] object.
466
467    Even though a planning element can exist anywhere in a section or
468    a greater element, it will only affect the headline containing the
469    section if it is put on the line following that headline.
470
471 ** Comments
472    :PROPERTIES:
473    :CUSTOM_ID: Comments
474    :END:
475
476    A "comment line" starts with a hash signe and a whitespace
477    character or an end of line.
478
479    Comments can contain any number of consecutive comment lines.
480
481 ** Fixed Width Areas
482    :PROPERTIES:
483    :CUSTOM_ID: Fixed_Width_Areas
484    :END:
485
486    A "fixed-width line" start with a colon character and a whitespace
487    or an end of line.
488
489    Fixed width areas can contain any number of consecutive fixed-width
490    lines.
491
492 ** Horizontal Rules
493    :PROPERTIES:
494    :CUSTOM_ID: Horizontal_Rules
495    :END:
496
497    A horizontal rule is a line made of at least 5 consecutive hyphens.
498    It can be indented.
499
500 ** Keywords
501    :PROPERTIES:
502    :CUSTOM_ID: Keywords
503    :END:
504
505    Keywords follow the syntax:
506
507    #+BEGIN_EXAMPLE
508    ,#+KEY: VALUE
509    #+END_EXAMPLE
510
511    KEY can contain any non-whitespace character, but it cannot be
512    equal to "CALL" or any affiliated keyword.
513
514    VALUE can contain any character excepted a new line.
515
516    If KEY belongs to ~org-element-document-properties~, VALUE can
517    contain objects.
518
519 ** LaTeX Environments
520    :PROPERTIES:
521    :CUSTOM_ID: LaTeX_Environments
522    :END:
523
524    Pattern for LaTeX environments is:
525
526    #+BEGIN_EXAMPLE
527    \begin{NAME}ARGUMENTS
528    CONTENTS
529    \end{NAME}
530    #+END_EXAMPLE
531
532    NAME is constituted of alpha-numeric characters and may end with an
533    asterisk.
534
535    ARGUMENTS is is any number (including zero) of ARGUMENT constructs
536    like ~[DATA]~ or ~{DATA}~.  DATA can contain any character excepted
537    a new line or the one ending ARGUMENT.
538
539    CONTENTS can contain anything but the "\end{NAME}" string.
540
541 ** Node Properties
542    :PROPERTIES:
543    :CUSTOM_ID: Node_Properties
544    :END:
545
546    Patter for node properties is:
547
548    #+BEGIN_EXAMPLE
549    :PROPERTY: VALUE
550    #+END_EXAMPLE
551
552    PROPERTY can contain any non-whitespace character.  VALUE can
553    contain any character but a new line.
554
555    Node properties can only exist in a [[#Drawers_and_Property_Drawers][property drawers]].
556
557 ** Paragraphs
558    :PROPERTIES:
559    :CUSTOM_ID: Paragraphs
560    :END:
561
562    Paragraphs are the default element, which means that any
563    unrecognized context is a paragraph.
564
565    Empty lines and other elements end paragraphs.
566
567    Paragraphs can contain every type of object.
568
569 ** Table Rows
570    :PROPERTIES:
571    :CUSTOM_ID: Table_Rows
572    :END:
573
574    A table rows is either constituted of a vertical bar and any number
575    of [[#Table_Cells][table cells]] or a vertical bar followed by a hyphen.
576
577    In the first case the table row has the "standard" type.  In the
578    second case, it has the "rule" type.
579
580    Table rows can only exist in [[#Tables][tables]].
581
582 * Objects
583   :PROPERTIES:
584   :CUSTOM_ID: Objects
585   :END:
586
587   Objects can only be found in the following locations:
588
589   - [[#Affiliated_keywords][affiliated keywords]] defined in ~org-element-parsed-keywords~,
590   - [[#Keywords][document properties]],
591   - [[#Headlines_and_Sections][headline]] titles,
592   - [[#Inlinetasks][inlinetask]] titles,
593   - [[#Plain_Lists_and_Items][item]] tags,
594   - [[#Paragraphs][paragraphs]],
595   - [[#Table_Cells][table cells]],
596   - [[#Table_Rows][table rows]], which can only contain table cell
597     objects,
598   - [[#Blocks][verse blocks]].
599     
600   Most objects cannot contain objects.  Those which can will be
601   specified.
602
603 ** Entities and LaTeX Fragments
604    :PROPERTIES:
605    :CUSTOM_ID: Entities_and_LaTeX_Fragments
606    :END:
607
608    An entity follows the pattern:
609
610    #+BEGIN_EXAMPLE
611    \NAME POST
612    #+END_EXAMPLE
613
614    where NAME has a valid association in either ~org-entities~ or
615    ~org-entities-user~.
616
617    POST is the end of line, "{}" string, or a non-alphabetical
618    character.  It isn't separated from NAME by a whitespace character.
619
620    A LaTeX fragment can follow multiple patterns:
621
622    #+BEGIN_EXAMPLE
623    \NAME POST
624    \(CONTENTS\)
625    \[CONTENTS\]
626    $$CONTENTS$$
627    PRE$CHAR$POST
628    PRE$BORDER1 BODY BORDER2$
629    #+END_EXAMPLE
630
631    NAME contains alphabetical characters only and must not have an
632    association in either ~org-entities~ or ~org-entities-user~.
633
634    POST is the same as for entities.
635
636    CONTENTS can contain any character but cannot contain "\)" in the
637    second template or "\]" in the third one.
638
639    PRE is either the beginning of line or a character different from
640    ~$~.
641
642    CHAR is a non-whitespace character different from ~.~, ~,~, ~?~,
643    ~;~, ~'~ or a double quote.
644
645    POST is any of ~-~, ~.~, ~,~, ~?~, ~;~, ~:~, ~'~, a double quote,
646    a whitespace character and the end of line.
647
648    BORDER1 is a non-whitespace character different from ~.~, ~;~, ~.~
649    and ~$~.
650
651    BODY can contain any character excepted ~$~, and may not span over
652    more than 3 lines.
653
654    BORDER2 is any non-whitespace character different from ~,~, ~.~ and
655    ~$~.
656
657    #+ATTR_ASCII: :width 5
658    -----
659
660    #+BEGIN_QUOTE
661    It would introduce incompatibilities with previous Org versions,
662    but support for ~$...$~ (and for symmetry, ~$$...$$~) constructs
663    ought to be removed.
664
665    They are slow to parse, fragile, redundant and imply false
666    positives.  --- ngz
667    #+END_QUOTE
668
669 ** Export Snippets
670    :PROPERTIES:
671    :CUSTOM_ID: Export_Snippets
672    :END:
673
674    Patter for export snippets is:
675
676    #+BEGIN_EXAMPLE
677    @@NAME:VALUE@@
678    #+END_EXAMPLE
679
680    NAME can contain any alpha-numeric character and hyphens.
681
682    VALUE can contain anything but "@@" string.
683
684 ** Footnote References
685    :PROPERTIES:
686    :CUSTOM_ID: Footnote_References
687    :END:
688
689    There are four patterns for footnote references:
690
691    #+BEGIN_EXAMPLE
692    [MARK]
693    [fn:LABEL]
694    [fn:LABEL:DEFINITION]
695    [fn::DEFINITION]
696    #+END_EXAMPLE
697
698    MARK is a number.
699
700    LABEL can contain any word constituent character, hyphens and
701    underscores.
702
703    DEFINITION can contain any character.  Though opening and closing
704    square brackets must be balanced in it.  It can contain any object
705    encountered in a paragraph, even other footnote references.
706
707    If the reference follows the third pattern, it is called an "inline
708    footnote".  If it follows the fourth one, i.e. if LABEL is omitted,
709    it is an "anonymous footnote".
710
711 ** Inline Babel Calls and Source Blocks
712    :PROPERTIES:
713    :CUSTOM_ID: Inline_Babel_Calls_and_Source_Blocks
714    :END:
715
716    Inline Babel calls follow any of the following patterns:
717
718    #+BEGIN_EXAMPLE
719    call_NAME(ARGUMENTS)
720    call_NAME[HEADER](ARGUMENTS)[HEADER]
721    #+END_EXAMPLE
722
723    NAME can contain any character besides ~(~, ~)~ and "\n".
724
725    HEADER can contain any character besides ~]~ and "\n".
726
727    ARGUMENTS can contain any character besides ~)~ and "\n".
728
729    Inline source blocks follow any of the following patterns:
730    
731    #+BEGIN_EXAMPLE
732    src_LANG{BODY}
733    src_LANG[OPTIONS]{BODY}
734    #+END_EXAMPLE
735
736    LANG can contain any non-whitespace character.
737
738    OPTIONS and BODY can contain any character but "\n".
739
740 ** Line Breaks
741    :PROPERTIES:
742    :CUSTOM_ID: Line_Breaks
743    :END:
744
745    A line break consists in "\\SPACE" pattern at the end of an
746    otherwise non-empty line.
747
748    SPACE can contain any number of tabs and spaces, including 0.
749
750 ** Links
751    :PROPERTIES:
752    :CUSTOM_ID: Links
753    :END:
754
755    There are 4 major types of links:
756
757    #+BEGIN_EXAMPLE
758    RADIO                     ("radio" link)
759    <PROTOCOL:PATH>           ("angle" link)
760    PRE PROTOCOL:PATH2 POST   ("plain" link)
761    [[PATH3]DESCRIPTION]      ("regular" link)
762    #+END_EXAMPLE
763
764    RADIO is a string matched by some [[#Targets_and_Radio_Targets][radio target]].  It can contain
765    [[#Entities_and_LaTeX_Fragments][entities]], [[#Entities_and_LaTeX_Fragments][latex fragments]], [[#Subscript_and_Superscript][subscript]] and [[#Subscript_and_Superscript][superscript]] only.
766
767    PROTOCOL is a string among ~org-link-types~.
768
769    PATH can contain any character but ~]~, ~<~, ~>~ and ~\n~.
770
771    PRE and POST are non word constituent.  They can be, respectively,
772    the beginning or the end of a line.
773
774    PATH2 can contain any non-whitespace character excepted ~(~, ~)~,
775    ~<~ and ~>~.  It must end with a word-constituent character, or any
776    non-whitespace non-punctuation character followed by ~/~.
777
778    DESCRIPTION must be enclosed within square brackets.  It can
779    contain any character but square brackets.  Object-wise, it can
780    contain any object found in a paragraph excepted a [[#Footnote_References][footnote
781    reference]], a [[#Targets_and_Radio_Targets][radio target]] and a [[#Line_Breaks][line break]].  It cannot contain
782    another link either, unless it is a plain link.
783
784    DESCRIPTION is optional.
785
786    PATH3 is built according to the following patterns:
787
788    #+BEGIN_EXAMPLE
789    FILENAME           ("file" type)
790    PROTOCOL:PATH4     ("PROTOCOL" type)
791    id:ID              ("id" type)
792    #CUSTOM-ID         ("custom-id" type)
793    (CODEREF)          ("coderef" type)
794    FUZZY              ("fuzzy" type)
795    #+END_EXAMPLE
796
797    FILENAME is a file name, either absolute or relative.
798
799    PATH4 can contain any character besides square brackets.
800
801    ID is constituted of hexadecimal numbers separated with hyphens.
802
803    PATH4, CUSTOM-ID, CODEREF and FUZZY can contain any character
804    besides square brackets.
805
806    #+ATTR_ASCII: :width 5
807    -----
808
809    #+BEGIN_QUOTE
810    I suggest to remove angle links.  If one needs spaces in PATH, she
811    can use standard link syntax instead.
812
813    I also suggest to remove ~org-link-types~ dependency in PROTOCOL
814    and match ~[a-zA-Z]~ instead, for portability.  --- ngz
815    #+END_QUOTE
816
817 ** Macros
818    :PROPERTIES:
819    :CUSTOM_ID: Macros
820    :END:
821
822    Macros follow the pattern:
823
824    #+BEGIN_EXAMPLE
825    {{{NAME(ARGUMENTS)}}}
826    #+END_EXAMPLE
827
828    NAME must start with a letter and can be followed by any number of
829    alpha-numeric characters, hyphens and underscores.
830
831    ARGUMENTS can contain anything but "}}}" string.  Values within
832    ARGUMENTS are separated by commas.  Non-separating commas have to
833    be escaped with a backslash character.
834
835 ** Targets and Radio Targets
836    :PROPERTIES:
837    :CUSTOM_ID: Targets_and_Radio_Targets
838    :END:
839
840    Radio targets follow the pattern:
841
842    #+BEGIN_EXAMPLE
843    <<<CONTENTS>>>
844    #+END_EXAMPLE
845
846    CONTENTS can be any character besides ~<~, ~>~ and "\n".  As far as
847    objects go, it can contain [[#Entities_and_LaTeX_Fragments][entities]], [[#Entities_and_LaTeX_Fragments][latex fragments]], [[#Subscript_and_Superscript][subscript]] and
848    [[#Subscript_and_Superscript][superscript]] only.
849
850    Targets follow the pattern:
851
852    #+BEGIN_EXAMPLE
853    <<TARGET>>
854    #+END_EXAMPLE
855
856    TARGET can contain any character besides ~<~, ~>~ and "\n".  It
857    cannot contain any object.
858
859 ** Statistics Cookies
860    :PROPERTIES:
861    :CUSTOM_ID: Statistics_Cookies
862    :END:
863
864    Statistics cookies follow either pattern:
865
866    #+BEGIN_EXAMPLE
867    [PERCENT%]
868    [NUM1/NUM2]
869    #+END_EXAMPLE
870
871    PERCENT, NUM1 and NUM2 are numbers or the empty string.
872
873 ** Subscript and Superscript
874    :PROPERTIES:
875    :CUSTOM_ID: Subscript_and_Superscript
876    :END:
877
878    Pattern for subscript is:
879
880    #+BEGIN_EXAMPLE
881    CHAR_SCRIPT
882    #+END_EXAMPLE
883
884    Pattern for superscript is:
885
886    #+BEGIN_EXAMPLE
887    CHAR^SCRIPT
888    #+END_EXAMPLE
889
890    CHAR is any non-whitespace character.
891
892    SCRIPT can be ~*~, a string made of word-constituent characters
893    maybe preceded by a plus or a minus sign, an expression enclosed in
894    parenthesis (resp. curly brackets) containing balanced parenthesis
895    (resp. curly brackets).
896
897 ** Table Cells
898    :PROPERTIES:
899    :CUSTOM_ID: Table_Cells
900    :END:
901
902    Table cells follow the pattern:
903
904    #+BEGIN_EXAMPLE
905    CONTENTS|
906    #+END_EXAMPLE
907
908    CONTENTS can contain any character excepted a vertical bar.
909
910 ** Timestamps
911    :PROPERTIES:
912    :CUSTOM_ID: Timestamp
913    :END:
914
915    There are seven possible patterns for timestamps:
916    
917    #+BEGIN_EXAMPLE
918    <%%(SEXP)>                                   (diary)
919    <DATE TIME REPEATER-OR-DELAY>                                  (active)
920    [DATE TIME REPEATER-OR-DELAY]                                  (inactive)
921    <DATE TIME REPEATER-OR-DELAY>--<DATE TIME REPEATER-OR-DELAY>   (active range)
922    <DATE TIME-TIME REPEATER-OR-DELAY>                             (active range)
923    [DATE TIME REPEATER-OR-DELAY]--[DATE TIME REPEATER-OR-DELAY]   (inactive range)
924    [DATE TIME-TIME REPEATER-OR-DELAY]                             (inactive range)
925    #+END_EXAMPLE
926
927    SEXP can contain any character excepted ~>~ and ~\n~.
928
929    DATE follows the pattern:
930
931    #+BEGIN_EXAMPLE
932    YYYY-MM-DD DAYNAME
933    #+END_EXAMPLE
934
935    Y, M and D are digits.  DAYNAME can contain any non
936    whitespace-character besides ~+~, ~-~, ~]~, ~>~, a digit or ~\n~.
937
938    TIME follows the pattern =H:MM~.  H can be one or two digit long
939    and can start with 0.
940
941    REPEATER-OR-DELAY follows the pattern:
942
943    #+BEGIN_EXAMPLE
944    MARK VALUE UNIT
945    #+END_EXAMPLE
946
947    MARK is ~+~ (cumulate type), ~++~ (catch-up type) or ~.+~ (restart
948    type) for a repeater, and ~-~ (all type) or ~--~ (first type) for
949    warning delays.
950
951    VALUE is a number.
952
953    UNIT is a character among ~h~ (hour), ~d~ (day), ~w~ (week), ~m~
954    (month), ~y~ (year).
955
956    MARK, VALUE and UNIT are not separated by whitespace characters.
957
958    There can be two REPEATER-OR-DELAY in the timestamp: one as
959    a repeater and one as a warning delay.
960
961 ** Text Markup
962    :PROPERTIES:
963    :CUSTOM_ID: Emphasis_Markers
964    :END:
965
966    Text markup follows the pattern:
967
968    #+BEGIN_EXAMPLE
969    PRE MARKER CONTENTS MARKER POST
970    #+END_EXAMPLE
971
972    PRE is a whitespace character, ~(~, ~{~ ~'~ or a double quote.  It
973    can also be a beginning of line.
974
975    MARKER is a character among ~*~ (bold), ~=~ (verbatim), ~/~
976    (italic), ~+~ (strike-through), ~_~ (underline), ~~~ (code).
977
978    CONTENTS is a string following the pattern:
979
980    #+BEGIN_EXAMPLE
981    BORDER BODY BORDER
982    #+END_EXAMPLE
983
984    BORDER can be any non-whitespace character excepted ~,~, ~'~ or
985    a double quote.
986
987    BODY can contain contain any character but may not span over more
988    than 3 lines.
989
990    BORDER and BODY are not separated by whitespaces.
991
992    CONTENTS can contain any object encountered in a paragraph when
993    markup is "bold", "italic", "strike-through" or "underline".
994
995    POST is a whitespace character, ~-~, ~.~, ~,~, ~:~, ~!~, ~?~, ~'~,
996    ~)~, ~}~ or a double quote.  It can also be an end of line.
997
998    PRE, MARKER, CONTENTS, MARKER and POST are not separated by
999    whitespace characters.
1000
1001    #+ATTR_ASCII: :width 5
1002    -----
1003    
1004    #+BEGIN_QUOTE
1005    All of this is wrong if ~org-emphasis-regexp-components~ or
1006    ~org-emphasis-alist~ are modified.
1007
1008    This should really be simplified and made persistent (i.e. no
1009    defcustom allowed).  Otherwise, portability and parsing are
1010    jokes.
1011
1012    Also, CONTENTS should be anything within code and verbatim
1013    emphasis, by definition.  --- ngz
1014    #+END_QUOTE
1015
1016 * Footnotes
1017
1018 [fn:1] In particular, the parser requires stars at column 0 to be
1019 quoted by a comma when they do not define a headline.
1020
1021 [fn:2] It also means that only headlines and sections can be
1022 recognized just by looking at the beginning of the line.
1023
1024 As a consequence, using ~org-element-at-point~ or
1025 ~org-element-context~ will move up to the parent headline, and parse
1026 top-down from there until context around is found.
1027
1028
1029 # Local Variables:
1030 # sentence-end-double-space: t
1031 # End: