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