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