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