dev/org-export-reference.org

   1 #+TITLE:      Org Export Reference Documentation
   2 #+AUTHOR:     Nicolas Goaziou
   3 #+EMAIL:      n.goaziou AT gmail DOT com
   4 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   6 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   7 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) NEW(n)
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 [[file:../index.org][{Back to Worg's index}]]
  13
  14 This document is aimed at back-end developers for the generic export
  15 engine =org-export.el=.  It assumes a good understanding of Org
  16 syntax --- as specified by /Org Elements/ --- from the reader.
  17
  18 It covers [[#back-end][back-end creation]] process, all [[#attributes][attributes]] associated to each
  19 element or object type, properties offered by the [[#communication][communication
  20 channel]] during export, the [[#filter-system][filter system]] internals and [[#toolbox][tools]] provided
  21 by the exporter.  Eventually, expected [[#interactive][interactive functions]] aimed at
  22 end-users are explained in the last part of this document.
  23
  24
  25 * Defining a Back-End
  26
  27   A back-end is defined with ~org-export-define-backend~ macro.  It
  28   requires two mandatory arguments: the back-end name and its
  29   translation table, an alist that associates element and object types
  30   to translator functions.  According to the macro doc-string:
  31
  32   #+BEGIN_QUOTE
  33   These functions should return a string without any trailing space,
  34   or nil.  They must accept three arguments: the object or element
  35   itself, its contents or nil when it isn't recursive and the property
  36   list used as a communication channel.
  37
  38   Contents, when not nil, are stripped from any global indentation
  39   (although the relative one is preserved).  They also always end with
  40   a single newline character.
  41
  42   If, for a given type, no function is found, that element or object
  43   type will simply be ignored, along with any blank line or white
  44   space at its end.  The same will happen if the function returns the
  45   nil value.  If that function returns the empty string, the type will
  46   be ignored, but the blank lines or white spaces will be kept.
  47
  48   In addition to element and object types, one function can be
  49   associated to the ~template~ symbol and another one to the
  50   ~plain-text~ symbol.
  51
  52   The former returns the final transcoded string, and can be used to
  53   add a preamble and a postamble to document's body.  It must accept
  54   two arguments: the transcoded string and the property list
  55   containing export options.
  56
  57   The latter, when defined, is to be called on every text not
  58   recognized as an element or an object.  It must accept two
  59   arguments: the text string and the information channel.  It is an
  60   appropriate place to protect special chars relative to the back-end.
  61   #+END_QUOTE
  62
  63   Optionally, the macro can set-up back-end specific properties (like
  64   values from specific buffer keywords) accessible from every
  65   translator function with the ~:options-alist~ keyword.  See
  66   ~org-export-options-alist~ for details on the structure of the
  67   value.
  68
  69   As an example, the following excerpt from ~latex~ back-end
  70   definition introduces three new buffer keywords (and their
  71   headline's property counterpart), and redefine ~DATE~ default value:
  72
  73   #+BEGIN_SRC emacs-lisp
  74   (org-export-define-backend latex
  75     ...
  76     :options-alist ((:date "DATE" nil "\\today" t)
  77                     (:date-format nil nil org-latex-date-timestamp-format)
  78                     (:latex-class "LATEX_CLASS" nil org-latex-default-class t)
  79                     (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
  80                     (:latex-header-extra "LATEX_HEADER" nil nil newline)
  81                     (:latex-hyperref-p nil "texht" org-latex-with-hyperref t)))
  82   #+END_SRC
  83
  84   It is also possible, with ~:export-block~ keyword, to associate
  85   given block names to the ~export-block~ type.  Such blocks can
  86   contain raw code that will be directly inserted in the output, as
  87   long as the corresponding translator function says so.
  88
  89   In the following example, in the ~html~ back-end, =HTML= blocks are
  90   export blocks.  The associated translator function inserts their
  91   contents as-is, and ignores any other export block.
  92
  93   #+BEGIN_SRC emacs-lisp
  94   (org-export-define-backend html
  95     (...
  96      (export-block . org-html-export-block)
  97      ... )
  98     :export-block "HTML")
  99
 100   (defun org-html-export-block (export-block contents info)
 101     "Transcode a EXPORT-BLOCK element from Org to HTML.
 102   CONTENTS is nil.  INFO is a plist used as a communication
 103   channel."
 104     (when (string= (org-element-property :type export-block) "HTML")
 105       (org-element-property :value export-block)))
 106   #+END_SRC
 107
 108   Eventually ~org-export-define-backend~ allows to define back-ends
 109   specific filters.  Refer to [[#filter-system][The Filter System]] section for more
 110   information.
 111
 112   If the new back-end shares most properties with another one,
 113   ~org-export-define-derived-backend~ macro can be used to simplify
 114   the process.  In the example below, we implement a new back-end
 115   which behaves like ~latex~ excepted for headlines and the template.
 116
 117   #+BEGIN_SRC emacs-lisp
 118   (org-export-define-derived-backend my-latex latex
 119     :translate-alist ((headline . my-latex-headline-translator)
 120                       (template . my-latex-template)))
 121   #+END_SRC
 122
 123   Back-ends defined with either function can be registered in the
 124   export dispatcher using special keyword =:menu-entry=.  See macros
 125   docstrings for more information.
 126
 127 * Elements Attributes
 128   :PROPERTIES:
 129   :CUSTOM_ID: attributes
 130   :END:
 131
 132   Element attributes are accessed with ~org-element-property~
 133   function.  Other accessors relative to elements are
 134   ~org-element-type~ and ~org-element-contents~.
 135
 136   Each greater element, element and object has a fixed set of
 137   properties attached to it.  Among them, four are shared by all
 138   types: ~:begin~ and ~:end~, which refer to the beginning and ending
 139   buffer positions of the considered element or object, ~:post-blank~,
 140   which holds the number of blank lines, or white spaces, at its end
 141   and ~:parent~ which refers to the element or object containing it.
 142
 143   Greater elements, elements and objects containing objects will have
 144   ~:contents-begin~ and ~:contents-end~ properties to delimit
 145   contents.  Greater elements and elements accepting affiliated
 146   keywords will also have a ~:post-affiliated~ property, referring to
 147   the buffer position after any affiliated keyword, when applicable.
 148
 149   In addition to these properties, each element can optionally get
 150   some more from affiliated keywords, namely: ~:attr_ascii~,
 151   ~:attr_docbook~, ~:attr_html~, ~:attr_latex~, ~:attr_odt~,
 152   ~:caption~, ~:header~, ~:name~, ~:plot~, and ~:results~.
 153
 154   At the lowest level, a ~:parent~ property is also attached to any
 155   string, as a text property.
 156
 157   Other properties, specific to each element or object, are listed
 158   below.
 159
 160 ** Babel Call
 161
 162    Element.
 163
 164    - ~:info~ :: Information about function being called, as returned
 165                 by ~ob-babel-lob-get-info~ (string).
 166 ** Bold
 167
 168    Recursive object.
 169
 170    No specific property.
 171
 172 ** Center Block
 173
 174    Greater element.
 175
 176    - ~:hiddenp~ :: Non-nil if the block is hidden (boolean).
 177
 178 ** Clock
 179
 180    Element.
 181
 182    - ~:duration~ :: Clock duration for a closed clock, or nil (string
 183                     or nil).
 184    - ~:status~ :: Status of current clock (symbol: ~closed~ or
 185                   ~running~).
 186    - ~:value~ :: Timestamp associated to clock keyword (timestamp
 187                  object).
 188
 189 ** Code
 190
 191    Object.
 192
 193    - ~:value~ :: Contents (string).
 194
 195 ** Comment
 196
 197    Element.
 198
 199    - ~:value~ :: Comments, with pound signs (string).
 200
 201 ** Comment Block
 202
 203    Element.
 204
 205    - ~:value~ :: Comments, without block's boundaries (string).
 206    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
 207
 208 ** Diary Sexp
 209
 210    Element.
 211
 212    - ~:value~ :: Full Sexp (string).
 213
 214 ** Drawer
 215
 216    Greater element.
 217
 218    - ~:drawer-name~ :: Drawer's name (string).
 219    - ~:hiddenp~ :: Non-nil if the drawer is hidden (boolean).
 220
 221    /Note relative to export:/ The idea behind drawers is that they are
 222    transparent export-wise.  By default, they should return their
 223    contents without additional decorations.
 224
 225 ** Dynamic Block
 226
 227    Greater element.
 228
 229    - ~:arguments~ :: Block's parameters (string).
 230    - ~:block-name~ :: Block's name (string).
 231    - ~:drawer-name~ :: Drawer's name (string).
 232    - ~:hiddenp~ :: Non-nil if the block is hidden (boolean).
 233
 234 ** Entity
 235
 236    Object.
 237
 238    - ~:ascii~ :: Entity's ASCII representation (string).
 239    - ~:html~ :: Entity's HTML representation (string).
 240    - ~:latex~ :: Entity's LaTeX representation (string).
 241    - ~:latex-math-p~ :: Non-nil if entity's LaTeX representation
 242         should be in math mode (boolean).
 243    - ~:latin1~ :: Entity's Latin-1 encoding representation (string).
 244    - ~:name~ :: Entity's name, without backslash nor brackets
 245                 (string).
 246    - ~:use-brackets-p~ :: Non-nil if entity is written with optional
 247         brackets in original buffer (boolean).
 248    - ~:utf-8~ :: Entity's UTF-8 encoding representation (string).
 249
 250 ** Example Block
 251
 252    Element.
 253
 254    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
 255    - ~:label-fmt~ :: Format string used to write labels in current
 256                      block, if different from
 257                      ~org-coderef-label-format~ (string or nil).
 258    - ~:language~ :: Language of the code in the block, if specified
 259                     (string or nil).
 260    - ~:number-lines~ :: Non-nil if code lines should be numbered.
 261         A ~new~ value starts numbering from 1 wheareas ~continued~
 262         resume numbering from previous numbered block (symbol: ~new~,
 263         ~continued~ or nil).
 264    - ~:options~ :: Block's options located on the block's opening line
 265                    (string).
 266    - ~:parameters~ :: Optional header arguments (string or nil).
 267    - ~:preserve-indent~ :: Non-nil when indentation within the block
 268         mustn't be modified upon export (boolean).
 269    - ~:retain-labels~ :: Non-nil if labels should be kept visible upon
 270         export (boolean).
 271    - ~:switches~ :: Optional switches for code block export (string or
 272                     nil).
 273    - ~:use-labels~ :: Non-nil if links to labels contained in the
 274                       block should display the label instead of the
 275                       line number (boolean).
 276    - ~:value~ :: Contents (string).
 277
 278 ** Export Block
 279
 280    Element.
 281
 282    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
 283    - ~:type~ :: Related back-end's name (string).
 284    - ~:value~ :: Contents (string).
 285
 286 ** Export Snippet
 287
 288    Object.
 289
 290    - ~:back-end~ :: Relative back-end's name (string).
 291    - ~:value~ :: Export code (string).
 292
 293 ** Fixed Width
 294
 295    Element.
 296
 297    - ~:value~ :: Contents, with colons (string).
 298
 299 ** Footnote Definition
 300
 301    Greater element.
 302
 303    - ~:label~ :: Label used for references (string).
 304
 305 ** Footnote Reference
 306
 307    Object.
 308
 309    - ~:inline-definition~ :: Footnote's definition, when inlined
 310         (secondary string or nil).
 311    - ~:label~ :: Footnote's label, if any (string or nil).
 312    - ~:raw-definition~ :: Uninterpreted footnote's definition, when
 313         inlined (string or nil).
 314    - ~:type~ :: Determine whether reference has its definition inline,
 315                 or not (symbol: ~inline~, ~standard~).
 316
 317 ** Headline
 318
 319    Greater element.
 320
 321    In addition to the following list, any property specified in
 322    a property drawer attached to the headline will be accessible as an
 323    attribute (with underscores replaced with hyphens and a lowercase
 324    name, i.e. ~:custom-id~).
 325
 326    - ~:archivedp~ :: Non-nil if the headline has an archive tag
 327                      (boolean).
 328    - ~:closed~ :: Headline's CLOSED reference, if any (timestamp
 329                   object or nil)
 330    - ~:commentedp~ :: Non-nil if the headline has a comment keyword
 331                       (boolean).
 332    - ~:deadline~ :: Headline's DEADLINE reference, if any (timestamp
 333                     object or nil).
 334    - ~:footnote-section-p~ :: Non-nil if the headline is a footnote
 335         section (boolean).
 336    - ~:hiddenp~ :: Non-nil if the headline is hidden (boolean).
 337    - ~:level~ :: Reduced level of the headline (integer).
 338    - ~:pre-blank~ :: Number of blank lines between the headline and
 339                      the first non-blank line of its contents
 340                      (integer).
 341    - ~:priority~ :: Headline's priority, as a character (integer).
 342    - ~:quotedp~ :: Non-nil if the headline contains a quote keyword
 343                    (boolean).
 344    - ~:raw-value~ :: Raw headline's text, without the stars and the
 345                      tags (string).
 346    - ~:scheduled~ :: Headline's SCHEDULED reference, if any (timestamp
 347                      object or nil).
 348    - ~:tags~ :: Headline's tags, if any, without the archive
 349                 tag. (list of strings).
 350    - ~:title~ :: Parsed headline's text, without the stars and the
 351                  tags (secondary string).
 352    - ~:todo-keyword~ :: Headline's TODO keyword without quote and
 353         comment strings, if any (string or nil).
 354    - ~:todo-type~ :: Type of headline's TODO keyword, if any (symbol:
 355                      ~done~, ~todo~).
 356
 357 ** Horizontal Rule
 358
 359    Element.
 360
 361    No specific property.
 362
 363 ** Inline Babel Call
 364
 365    Object.
 366
 367    - ~:info~ :: Information about function called, as returned by
 368                 ~org-babel-lob-get-info~ (list).
 369
 370    /Note relative to export:/ Since Babel related blocks are expanded
 371    before parsing, these can safely be ignored by back-ends.
 372
 373 ** Inline Src Block
 374
 375    Object.
 376
 377    - ~:language~ :: Language of the code in the block (string).
 378    - ~:parameters~ :: Optional header arguments (string or nil).
 379    - ~:value~ :: Source code (string).
 380
 381 ** Inlinetask
 382
 383    Greater element.
 384
 385    In addition to the following list, any property specified in
 386    a property drawer attached to the headline will be accessible as an
 387    attribute (with underscores replaced with hyphens and a lowercase
 388    name, i.e. ~:custom-id~).
 389
 390    - ~:closed~ :: Inlinetask's CLOSED reference, if any (timestamp
 391                   object or nil)
 392    - ~:deadline~ :: Inlinetask's DEADLINE reference, if any (timestamp
 393                     object or nil).
 394    - ~:hiddenp~ :: Non-nil if the headline is hidden (boolean).
 395    - ~:level~ :: Reduced level of the inlinetask (integer).
 396    - ~:priority~ :: Headline's priority, as a character (integer).
 397    - ~:raw-value~ :: Raw inlinetask's text, without the stars and the
 398                      tags (string).
 399    - ~:scheduled~ :: Inlinetask's SCHEDULED reference, if any
 400                      (timestamp object or nil).
 401    - ~:tags~ :: Inlinetask's tags, if any (list of strings).
 402    - ~:title~ :: Parsed inlinetask's text, without the stars and the
 403                  tags (secondary string).
 404    - ~:todo-keyword~ :: Inlinetask's TODO keyword, if any (string or
 405         nil).
 406    - ~:todo-type~ :: Type of inlinetask's TODO keyword, if any
 407                      (symbol: ~done~, ~todo~).
 408
 409 ** Italic
 410
 411    Recursive object.
 412
 413    No specific property.
 414
 415 ** Item
 416
 417    Greater element.
 418
 419    - ~:bullet~ :: Item's bullet (string).
 420    - ~:checkbox~ :: Item's check-box, if any (symbol: ~on~, ~off~,
 421                     ~trans~, nil).
 422    - ~:counter~ :: Item's counter, if any.  Literal counters become
 423                    ordinals (integer).
 424    - ~:raw-tag~ :: Uninterpreted item's tag, if any (string or nil).
 425    - ~:tag~ :: Parsed item's tag, if any (secondary string or nil).
 426    - ~:hiddenp~ :: Non-nil if item is hidden (boolean).
 427    - ~:structure~ :: Full list's structure, as returned by
 428                      ~org-list-struct~ (alist).
 429
 430 ** Keyword
 431
 432    Element.
 433
 434    - ~:key~ :: Keyword's name (string).
 435    - ~:value~ :: Keyword's value (string).
 436
 437    /Note relative to export:/ Each back-end should, as far as
 438    possible, support a number of common keywords.  These include:
 439
 440    - Back-end relative keyword (i.e. "LATEX" for =e-latex=), which
 441      should always return its value as-is.
 442
 443    - "TARGET" keyword, which should always return a nil value.
 444
 445    - "TOC" keyword.  It accepts four common values: "headlines",
 446      "tables", "figures", "listings".  Also, "headlines" value can
 447      have an optional numeric argument to specify depth of the
 448      contents.
 449
 450      See [[#collect-headlines][~org-export-collect-headlines~]], [[#collect-tables][~org-export-collect-tables~]],
 451      [[#collect-figures][~org-export-collect-figures~]] and [[#collect-listings][~org-export-collect-listings~]].
 452
 453    - "INDEX" keyword.
 454
 455 ** LaTeX Environment
 456
 457    Element.
 458
 459    - ~:begin~ :: Buffer position at first affiliated keyword or at the
 460                  beginning of the first line of environment (integer).
 461    - ~:end~ :: Buffer position at the first non-blank line after last
 462                line of the environment, or buffer's end (integer).
 463    - ~:post-blank~ :: Number of blank lines between last environment's
 464                       line and next non-blank line or buffer's end
 465                       (integer).
 466    - ~:value~ :: LaTeX code (string).
 467
 468 ** LaTeX Fragment
 469
 470    Object.
 471
 472    - ~:value~ :: LaTeX code (string).
 473
 474 ** Line Break
 475
 476    Element.
 477
 478    No specific property.
 479
 480 ** Link
 481
 482    Recursive object.
 483
 484    - ~:application~ :: Name of application requested to open the link
 485                        in Emacs (string or nil). It only applies to
 486                        "file" type links.
 487    - ~:path~ :: Identifier for link's destination.  It is usually the
 488                 link part with type, if specified, removed (string).
 489    - ~:raw-link~ :: Uninterpreted link part (string).
 490    - ~:search-option~ :: Additional information for file location
 491         (string or nil). It only applies to "file" type links.
 492    - ~:type~ :: Link's type.  Possible types (string) are:
 493      - ~coderef~ :: Line in some source code,
 494      - ~custom-id~ :: Specific headline's custom-id,
 495      - ~file~ :: External file,
 496      - ~fuzzy~ :: Target, target keyword, a named element or an
 497                   headline in the current parse tree,
 498      - ~id~ :: Specific headline's id,
 499      - ~radio~ :: Radio-target.
 500      It can also be any ~org-link-types~ element.
 501
 502
 503    /Notes relative to export:/
 504
 505    - A fuzzy link leading to a target keyword should be ignored during
 506      export: it's an invisible target.
 507
 508    - A fuzzy link with no description should display the
 509      cross-reference number of its target.  This number can be:
 510
 511      - If link's destination is a target object within a footnote, it
 512        will be footnote's number.
 513
 514      - If link's destination is a target object in a list, it will be
 515        an item number.
 516
 517      - If link leads to a named element, it will be the sequence number
 518        of that element among named elements of the same type.
 519
 520      - Otherwise, it will be the number of the headline containing
 521        link's destination.
 522
 523      See [[#get-ordinal][~org-export-get-ordinal~]] function.
 524
 525 ** Macro
 526
 527    Object.
 528
 529    - ~:args~ :: Arguments passed to the macro (list of strings).
 530    - ~:key~ :: Macro's name (string).
 531    - ~:value~ :: Replacement text (string).
 532
 533    /Note relative to export:/ Macro expansion takes place before
 534    buffer parsing. As such, export back-ends don't have to handle:
 535    they'll never see them.
 536
 537 ** Paragraph
 538
 539    Element containing objects.
 540
 541    No specific property.
 542
 543 ** Plain List
 544
 545    Greater element.
 546
 547    - ~:structure~ :: Full list's structure, as returned by
 548                      ~org-list-struct~ (alist).
 549    - ~:type~ :: List's type (symbol: ~descriptive~, ~ordered~,
 550                 ~unordered~).
 551
 552 ** Planning
 553
 554    Element.
 555
 556    - ~:closed~ :: Timestamp associated to closed keyword, if any
 557                   (timestamp object or nil).
 558    - ~:deadline~ :: Timestamp associated to deadline keyword, if any
 559                     (timestamp object or nil).
 560    - ~:scheduled~ :: Timestamp associated to scheduled keyword, if any
 561                      (timestamp object or nil).
 562
 563 ** Property Drawer
 564
 565    Element.
 566
 567    - ~:hiddenp~ :: Non-nil if drawer is hidden (boolean).
 568    - ~:properties~ :: Properties defined in the drawer (alist).
 569
 570 ** Quote Block
 571
 572    Greater element.
 573
 574    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
 575
 576 ** Quote Section
 577
 578    Element.
 579
 580    - ~:value~ :: Quoted text (string).
 581
 582 ** Radio Target
 583
 584    Recursive object.
 585
 586    - ~:raw-value~ :: Uninterpreted contents (string).
 587
 588 ** Section
 589
 590    Greater element.
 591
 592    No specific property.
 593
 594 ** Special Block
 595
 596    Greater element.
 597
 598    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
 599    - ~:type~ :: Block's name (string).
 600
 601 ** Src Block
 602
 603    Element.
 604
 605    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
 606    - ~:label-fmt~ :: Format string used to write labels in current
 607                      block, if different from
 608                      ~org-coderef-label-format~ (string or nil).
 609    - ~:language~ :: Language of the code in the block, if specified
 610                     (string or nil).
 611    - ~:number-lines~ :: Non-nil if code lines should be numbered.
 612         A ~new~ value starts numbering from 1 wheareas ~continued~
 613         resume numbering from previous numbered block (symbol: ~new~,
 614         ~continued~ or nil).
 615    - ~:parameters~ :: Optional header arguments (string or nil).
 616    - ~:preserve-indent~ :: Non-nil when indentation within the block
 617         mustn't be modified upon export (boolean).
 618    - ~:retain-labels~ :: Non-nil if labels should be kept visible upon
 619         export (boolean).
 620    - ~:switches~ :: Optional switches for code block export (string or
 621                     nil).
 622    - ~:use-labels~ :: Non-nil if links to labels contained in the
 623                       block should display the label instead of the
 624                       line number (boolean).
 625    - ~:value~ :: Source code (string).
 626
 627 ** Statistics Cookie
 628
 629    Object.
 630
 631    - ~:value~ :: Full cookie (string).
 632
 633 ** Strike Through
 634
 635    Recursive object.
 636
 637    No specific property.
 638
 639 ** Subscript
 640
 641    Recursive object.
 642
 643    - ~:use-brackets-p~ :: Non-nil if contents are enclosed in curly
 644         brackets (t, nil).
 645
 646 ** Superscript
 647
 648    Recursive object.
 649
 650    - ~:use-brackets-p~ :: Non-nil if contents are enclosed in curly
 651         brackets (t, nil).
 652
 653 ** Table
 654
 655    Greater element.
 656
 657    - ~:tblfm~ :: Formulas associated to the table, if any (string or
 658                  nil).
 659    - ~:type~ :: Table's origin (symbol: ~table.el~, ~org~).
 660    - ~:value~ :: Raw ~table.el~ table or nil (string or nil).
 661
 662 ** Table Cell
 663
 664    Recursive object.
 665
 666    No specific property.
 667
 668 ** Table Row
 669
 670    Element containing objects.
 671
 672    - ~:type~ :: Row's type (symbol: ~standard~, ~rule~).
 673
 674 ** Target
 675
 676    Object.
 677
 678    - ~:value~ :: Target's ID (string).
 679
 680
 681    Notes relatives to export:
 682
 683    - Target should become an anchor, if back-end permits it.
 684    - Target's ID shouldn't be visible on export.
 685
 686 ** Timestamp
 687
 688    Object.
 689
 690    - ~:day-end~ :: Day part from timestamp end.  If no ending date is
 691                    defined, it defaults to start day part (integer).
 692    - ~:day-start~ :: Day part from timestamp start (integer).
 693    - ~:hour-start~ :: Hour part from timestamp end. If no ending date
 694                       is defined, it defaults to start hour part, if
 695                       any (integer or nil).
 696    - ~:hour-start~ :: Hour part from timestamp start, if specified
 697                       (integer or nil).
 698    - ~:minute-start~ :: Minute part from timestamp end. If no ending
 699         date is defined, it defaults to start minute part, if any
 700         (integer or nil).
 701    - ~:minute-start~ :: Minute part from timestamp start, if specified
 702         (integer or nil).
 703    - ~:month-end~ :: Month part from timestamp end.  If no ending date
 704                      is defined, it defaults to start month part
 705                      (integer).
 706    - ~:month-start~ :: Month part from timestamp start (integer).
 707    - ~:raw-value~ :: Raw timestamp (string).
 708    - ~:repeater-type~ :: Type of repeater, if any (symbol: ~catch-up~,
 709         ~restart~, ~cumulate~ or nil)
 710    - ~:repeater-unit~ :: Unit of shift, if a repeater is defined
 711         (symbol: ~year~, ~month~, ~week~, ~day~, ~hour~ or nil).
 712    - ~:repeater-value~ :: Value of shift, if a repeater is defined
 713         (integer or nil).
 714    - ~:type~ :: Type of timestamp (symbol: ~active~, ~active-range~,
 715                 ~diary~, ~inactive~, ~inactive-range~).
 716    - ~:year-end~ :: Year part from timestamp end.  If no ending date
 717                     is defined, it defaults to start year part
 718                     (integer).
 719    - ~:year-start~ :: Year part from timestamp start (integer).
 720
 721    Note relative to export: =org.el= provides tools to work on
 722    timestamps objects.  In particular, back-ends usually make use of
 723    ~org-timestamp-translate~ function.  Thus, in =ox-html.el=, the
 724    timestamp object is first translated:
 725
 726    #+BEGIN_SRC emacs-lisp
 727    (defun org-html-timestamp (timestamp contents info)
 728      "Transcode a TIMESTAMP object from Org to HTML.
 729    CONTENTS is nil.  INFO is a plist holding contextual
 730    information."
 731      (let ((value (org-html-plain-text
 732                    (org-timestamp-translate timestamp) info)))
 733        (format "<span class=\"timestamp-wrapper\"><span class=\"timestamp\">%s</span></span>"
 734                (replace-regexp-in-string "--" "&ndash;" value))))
 735    #+END_SRC
 736
 737 ** Underline
 738
 739    Recursive object.
 740
 741    No specific property.
 742
 743 ** Verbatim
 744
 745    Object.
 746
 747    - ~:value~ :: Contents (string).
 748
 749 ** Verse Block
 750
 751    Element containing objects.
 752
 753    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
 754
 755 * The Communication Channel
 756   :PROPERTIES:
 757   :CUSTOM_ID: communication
 758   :END:
 759
 760   This is the full list of properties available during transcode
 761   process, with their category (~option~ or ~tree~) and their value
 762   type.
 763
 764 ** ~:author~
 765
 766    Author's name.
 767
 768    - category :: option
 769    - type :: string
 770
 771 ** ~:back-end~
 772
 773    Current back-end used for transcoding.
 774
 775    - category :: tree
 776    - type :: symbol
 777
 778 ** ~:creator~
 779
 780    String to write as creation information.
 781
 782    - category :: option
 783    - type :: string
 784
 785 ** ~:date~
 786
 787    String to use as date.
 788
 789    - category :: option
 790    - type :: string
 791
 792 ** ~:description~
 793
 794    Description text for the current data.
 795
 796    - category :: option
 797    - type :: string
 798
 799 ** ~:email~
 800
 801    Author's email.
 802
 803    - category :: option
 804    - type :: string
 805
 806 ** ~:exclude-tags~
 807
 808    Tags for exclusion of sub-trees from export process.
 809
 810    - category :: option
 811    - type :: list of strings
 812
 813 ** ~:exported-data~
 814
 815    Hash table used to memoize results from [[#data][~org-export-data~]].
 816
 817    - category :: tree
 818    - type :: hash table
 819
 820 ** ~:filetags~
 821
 822    List of global tags for buffer.  Used by [[#get-tags][~org-export-get-tags~]] to
 823    get tags with inheritance.
 824
 825    - category :: option
 826    - type :: list of strings
 827
 828 ** ~:footnote-definition-alist~
 829
 830    Alist between footnote labels and their definition, as parsed data.
 831    Only non-inline footnotes are represented in this alist.  Also,
 832    every definition isn't guaranteed to be referenced in the parse
 833    tree.  The purpose of this property is to preserve definitions from
 834    oblivion – i.e. when the parse tree comes from a part of the
 835    original buffer –, it isn't meant for direct use in a back-end.  To
 836    retrieve a definition relative to a reference, use
 837    [[#get-footnote-definition][~org-export-get-footnote-definition~]] instead.
 838
 839    - category :: option
 840    - type :: alist (STRING . LIST)
 841
 842 ** ~:headline-levels~
 843    :PROPERTIES:
 844    :CUSTOM_ID: headline-levels
 845    :END:
 846
 847    Maximum level being exported as an headline.  Comparison is done
 848    with the relative level of headlines in the parse tree, not
 849    necessarily with their actual level.
 850
 851    - category :: option
 852    - type :: integer
 853
 854 ** ~:headline-numbering~
 855
 856    Alist between headlines' beginning position and their numbering, as
 857    a list of numbers – cf. [[#get-headline-number][~org-export-get-headline-number~]].
 858
 859    - category :: tree
 860    - type :: alist (INTEGER . LIST)
 861
 862 ** ~:headline-offset~
 863
 864    Difference between relative and real level of headlines in the
 865    parse tree.  For example, a value of -1 means a level 2 headline
 866    should be considered as level 1 —
 867    cf. [[#get-relative-level][~org-export-get-relative-level~]].
 868
 869    - category :: tree
 870    - type :: integer
 871
 872 ** ~:ignore-list~
 873
 874    List of elements and objects that will be unconditionally ignored
 875    during export.
 876
 877    - category :: option
 878    - type :: list of elements
 879
 880 ** ~:id-alist~
 881
 882    Alist between ID strings and destination file's path, relative to
 883    current directory.
 884
 885    - category :: option
 886    - type :: alist (STRING . STRING)
 887
 888 ** ~:input-file~
 889
 890    Full path to input file, if any.
 891
 892    - category :: option
 893    - type :: string or nil
 894
 895 ** ~:keywords~
 896
 897    List of keywords attached to data.
 898
 899    - category :: option
 900    - type :: string
 901
 902 ** ~:language~
 903
 904    Default language used for translations.
 905
 906    - category :: option
 907    - type :: string
 908
 909 ** ~:parse-tree~
 910
 911    Whole parse tree, available at any time during transcoding.
 912
 913    - category :: option
 914    - type :: list (as returned by ~org-element-parse-buffer~)
 915
 916 ** ~:preserve-breaks~
 917
 918    Non-nil means transcoding should preserve all line breaks.
 919
 920    - category :: option
 921    - type :: symbol (nil, t)
 922
 923 ** ~:section-numbers~
 924
 925    Non-nil means transcoding should add section numbers to headlines.
 926
 927    - category :: option
 928    - type :: symbol (nil, t)
 929
 930 ** ~:select-tags~
 931    :PROPERTIES:
 932    :CUSTOM_ID: select-tags
 933    :END:
 934
 935    List of tags enforcing inclusion of sub-trees in transcoding.  When
 936    such a tag is present, sub-trees without it are /de facto/ excluded
 937    from the process.  See [[#use-select-tags][~:use-select-tags~]].
 938
 939    - category :: option
 940    - type :: list of strings
 941
 942 ** ~:time-stamp-file~
 943
 944    Non-nil means transcoding should insert a time stamp in the output.
 945
 946    - category :: option
 947    - type :: symbol (nil, t)
 948
 949 ** ~:translate-alist~
 950
 951    Alist between element and object types and transcoding functions
 952    relative to the current back-end.  Special keys ~template~ and
 953    ~plain-text~ are also possible.
 954
 955    - category :: option
 956    - type :: alist (SYMBOL . FUNCTION)
 957
 958 ** ~:use-select-tags~
 959    :PROPERTIES:
 960    :CUSTOM_ID: use-select-tags
 961    :END:
 962
 963    When non-nil, a select tags has been found in the parse tree.
 964    Thus, any headline without one will be filtered out.  See
 965    [[#select-tags][~:select-tags~]].
 966
 967    - category :: tree
 968    - type :: interger or nil
 969
 970 ** ~:with-archived-trees~
 971
 972    Non-nil when archived sub-trees should also be transcoded.  If it
 973    is set to the ~headline~ symbol, only the archived headline's name
 974    is retained.
 975
 976    - category :: option
 977    - type :: symbol (nil, t, ~headline~)
 978
 979 ** ~:with-author~
 980
 981    Non-nil means author's name should be included in the output.
 982
 983    - category :: option
 984    - type :: symbol (nil, t)
 985
 986 ** ~:with-clocks~
 987
 988    Non-nil means clock keywords should be exported.
 989
 990    - category :: option
 991    - type :: symbol (nil, t)
 992
 993 ** ~:with-creator~
 994
 995    Non-nil means a creation sentence should be inserted at the end of
 996    the transcoded string.  If the value is ~comment~, it should be
 997    commented.
 998
 999    - category :: option
1000    - type :: symbol (~comment~, nil, t)
1001
1002 ** ~:with-date~
1003
1004    Non nil means output should contain a date.
1005
1006    - category :: option
1007    - type :: symbol (nil, t)
1008
1009 ** ~:with-drawers~
1010
1011    Non-nil means drawers should be exported.  If its value is a list
1012    of names, only drawers with such names will be transcoded.
1013
1014    - category :: option
1015    - type :: symbol (nil, t) or list of strings
1016
1017 ** ~:with-email~
1018
1019    Non-nil means output should contain author's email.
1020
1021    - category :: option
1022    - type :: symbol (nil, t)
1023
1024 ** ~:with-emphasize~
1025
1026    Non-nil means emphasized text should be interpreted.
1027
1028    - category :: option
1029    - type :: symbol (nil, t)
1030
1031 ** ~:with-fixed-width~
1032
1033    Non-nil if transcoder should interpret strings starting with
1034    a colon as a fixed-with — verbatim — area.
1035
1036    - category :: option
1037    - type :: symbol (nil, t)
1038
1039 ** ~:with-footnotes~
1040
1041    Non-nil if transcoder should interpret footnotes.
1042
1043    - category :: option
1044    - type :: symbol (nil, t)
1045
1046 ** ~:with-latex~
1047
1048    Non-nil means ~latex-environment~ elements and ~latex-fragment~
1049    objects should appear in export output.  When this property is set
1050    to ~verbatim~, they will be left as-is.
1051
1052    - category :: option
1053    - type :: symbol (~verbatim~, nil, t)
1054
1055 ** ~:with-plannings~
1056
1057    Non-nil means transcoding should include planning info.
1058
1059    - category :: option
1060    - type :: symbol (nil, t)
1061
1062 ** ~:with-priority~
1063
1064    Non-nil means transcoding should include priority cookies.
1065
1066    - category :: option
1067    - type :: symbol (nil, t)
1068
1069 ** ~:with-smart-quotes~
1070
1071    Non-nil means activate smart quotes during export.
1072
1073    - category :: option
1074    - type :: symbol (nil ,t)
1075
1076 ** ~:with-special-strings~
1077
1078    Non-nil means transcoding should interpret special strings in plain
1079    text.
1080
1081    - category :: option
1082    - type :: symbol (nil, t)
1083
1084 ** ~:with-sub-superscript~
1085
1086    Non-nil means transcoding should interpret subscript and
1087    superscript.  With a value of ~{}~, only interpret those using
1088    curly brackets.
1089
1090    - category :: option
1091    - type :: symbol (nil, ~{}~, t)
1092
1093 ** ~:with-tables~
1094
1095    Non-nil means transcoding should interpret tables.
1096
1097    - category :: option
1098    - type :: symbol (nil, t)
1099
1100 ** ~:with-tags~
1101
1102    Non-nil means transcoding should keep tags in headlines.
1103    A ~not-in-toc~ value will remove them from the table of contents,
1104    if any, nonetheless.
1105
1106    - category :: option
1107    - type :: symbol (nil, t, ~not-in-toc~)
1108
1109 ** ~:with-tasks~
1110
1111    Non-nil means transcoding should include headlines with a TODO
1112    keyword.  A ~todo~ value will only include headlines with a TODO
1113    type keyword while a ~done~ value will do the contrary.  If a list
1114    of strings is provided, only tasks with keywords belonging to that
1115    list will be kept.
1116
1117    - category :: option
1118    - type :: symbol (t, ~todo~, ~done~, nil) or list of strings
1119
1120 ** ~:with-timestamps~
1121
1122    Non-nil means transcoding should include time stamps.  Special
1123    value ~active~ (resp. ~inactive~) ask to export only active
1124    (resp. inactive) timestamps.  Otherwise, completely remove them.
1125
1126    - category :: option
1127    - type :: symbol: (~active~, ~inactive~, t, nil)
1128
1129 ** ~:with-toc~
1130
1131    Non-nil means that a table of contents has to be added to the
1132    output.  An integer value limits its depth.
1133
1134    - category :: option
1135    - type :: symbol (nil, t or integer)
1136
1137 ** ~:with-todo-keywords~
1138
1139    Non-nil means transcoding should include TODO keywords.
1140
1141    - category :: option
1142    - type :: symbol (nil, t)
1143
1144 * The Filter System
1145   :PROPERTIES:
1146   :CUSTOM_ID: filter-system
1147   :END:
1148
1149   Filters sets are lists of functions.  They allow to pre-process
1150   parse tree before export and to post-process output of each
1151   transcoded object or element.
1152
1153   Each function in a set must accept three arguments: a string (or
1154   a parse tree as a special case), a symbol representing the current
1155   back-end, and the communication channel, as a plist.
1156
1157   As an exception, functions in options filter only accept two
1158   arguments: the property list containing the export options and the
1159   back-end, as a symbol.
1160
1161   From the developer side, filters sets can be installed using
1162   ~:filters-alist~ keyword while defining the back-end with
1163   ~org-export-define-derived-backend~.  Each association has a key
1164   among the following symbols and a function or a list of functions as
1165   value:
1166
1167   - ~:filter-babel-call~
1168   - ~:filter-bold~
1169   - ~:filter-center-block~
1170   - ~:filter-clock~
1171   - ~:filter-code~
1172   - ~:filter-comment~
1173   - ~:filter-comment-block~
1174   - ~:filter-drawer~
1175   - ~:filter-dynamic-block~
1176   - ~:filter-entity~
1177   - ~:filter-example-block~
1178   - ~:filter-export-block~
1179   - ~:filter-export-snippet~
1180   - ~:filter-final-output~
1181   - ~:filter-fixed-width~
1182   - ~:filter-footnote-definition~
1183   - ~:filter-footnote-reference~
1184   - ~:filter-headline~
1185   - ~:filter-horizontal-rule~
1186   - ~:filter-inline-babel-call~
1187   - ~:filter-inline-src-block~
1188   - ~:filter-inlinetask~
1189   - ~:filter-italic~
1190   - ~:filter-item~
1191   - ~:filter-keyword~
1192   - ~:filter-latex-environment~
1193   - ~:filter-latex-fragment~
1194   - ~:filter-line-break~
1195   - ~:filter-link~
1196   - ~:filter-macro~
1197   - ~:filter-node-property~
1198   - ~:filter-options~
1199   - ~:filter-paragraph~
1200   - ~:filter-parse-tree~
1201   - ~:filter-plain-list~
1202   - ~:filter-plain-text~
1203   - ~:filter-planning~
1204   - ~:filter-property-drawer~
1205   - ~:filter-quote-block~
1206   - ~:filter-quote-section~
1207   - ~:filter-radio-target~
1208   - ~:filter-section~
1209   - ~:filter-special-block~
1210   - ~:filter-src-block~
1211   - ~:filter-strike-through~
1212   - ~:filter-statistics-cookie~
1213   - ~:filter-subscript~
1214   - ~:filter-superscript~
1215   - ~:filter-table~
1216   - ~:filter-table-cell~
1217   - ~:filter-table-row~
1218   - ~:filter-target~
1219   - ~:filter-timestamp~
1220   - ~:filter-underline~
1221   - ~:filter-verbatim~
1222   - ~:filter-verse-block~
1223
1224
1225   For example, ~ascii~ back-end implements a filter that makes sure
1226   headlines end with two blank lines:
1227
1228   #+BEGIN_SRC emacs-lisp
1229   (org-export-define-backend ascii
1230     ...
1231     :filters-alist ((:filter-headline . org-ascii-filter-headline-blank-lines)
1232                     (:filter-section . org-ascii-filter-headline-blank-lines)))
1233
1234   (defun org-ascii-filter-section-blank-lines (headline back-end info)
1235     "Filter controlling number of blank lines after a section."
1236     (let ((blanks (make-string 2 ?\n)))
1237       (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" blanks headline)))
1238   #+END_SRC
1239
1240 * The Toolbox
1241   :PROPERTIES:
1242   :CUSTOM_ID: toolbox
1243   :END:
1244
1245   A whole set of tools is available to help build new exporters.  Any
1246   function general enough to have its use across a couple of back-ends
1247   may be added here.
1248
1249   Many of them are high-level access to properties from the
1250   communication channel.  As such, they should be preferred to
1251   straight access to communication channel, when possible.
1252
1253 ** ~org-element-adopt-element~
1254    :PROPERTIES:
1255    :CUSTOM_ID: adopt-element
1256    :END:
1257
1258    Add an element to the contents of another element.
1259
1260    See also: [[#set-element][~org-element-set-element~]]
1261
1262 ** ~org-element-set-element~
1263    :PROPERTIES:
1264    :CUSTOM_ID: set-element
1265    :END:
1266
1267    Replace an element with another in the parse tree.
1268
1269    See also: [[#adopt-element][~org-element-adopt-element~]].
1270
1271 ** ~org-export-activate-smart-quotes~
1272    :PROPERTIES:
1273    :CUSTOM_ID: activate-smart-quotes
1274    :END:
1275
1276    Transform quotes and apostrophes into their "smart" counterpart in
1277    a given string.
1278
1279    It should be used after a check against ~:with-smart-quotes~ value
1280    in communication channel.
1281
1282    Since this function needs the original string, it may be useful to
1283    apply others transformations (i.e. characters protection) on a copy
1284    of that string and provide the pristine original string as the
1285    optional argument.
1286
1287    For example, in ~html~ back-end, it is necessary to protect "<",
1288    ">" and "&" characters before calling this function.  Here's an
1289    excerpt of its ~plain-text~ transcoder:
1290
1291    #+BEGIN_SRC emacs-lisp
1292    (let ((output text))
1293      ;; Protect following characters: <, >, &.
1294      (setq output (org-html-encode-plain-text output))
1295      ;; Handle smart quotes.  Be sure to provide original string since
1296      ;; OUTPUT may have been modified.
1297      (when (plist-get info :with-smart-quotes)
1298        (setq output (org-export-activate-smart-quotes output :html info text)))
1299      ...
1300      ;; Return value.
1301      output)
1302    #+END_SRC
1303
1304 ** ~org-export-collect-figures~
1305    :PROPERTIES:
1306    :CUSTOM_ID: collect-figures
1307    :END:
1308
1309    Return a list of all exportable figures in parse tree.
1310
1311    Used to build a table of figures.
1312
1313    See also: [[#collect-headlines][~org-export-collect-headlines~]],
1314    [[#collect-tables][~org-export-collect-tables~]], [[#collect-listings][~org-export-collect-listings~]].
1315
1316 ** ~org-export-collect-footnote-definitions~
1317    :PROPERTIES:
1318    :CUSTOM_ID: collect-footnote-definitions
1319    :END:
1320
1321    List actually used footnotes definitions in order to add footnote
1322    listings throughout the transcoded data.
1323
1324    Feed it with the whole parse tree to get the full footnote listing.
1325    Feed it with the current headline to get partial footnote listing
1326    relative to that headline.
1327
1328    Number, label, if any, and definition are provided.
1329
1330    See also: [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
1331    [[#get-footnote-definition][~org-export-get-footnote-definition~]],
1332    [[#get-footnote-number][~org-export-get-footnote-number~]].
1333
1334 ** ~org-export-collect-headlines~
1335    :PROPERTIES:
1336    :CUSTOM_ID: collect-headlines
1337    :END:
1338
1339    Return a list of all exportable headlines, possibly limited to
1340    a certain depth.
1341
1342    Used to build a table of contents.
1343
1344    See also: [[#collect-tables][~org-export-collect-tables~]],
1345    [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]].
1346
1347 ** ~org-export-collect-listings~
1348    :PROPERTIES:
1349    :CUSTOM_ID: collect-listings
1350    :END:
1351
1352    Return a list of all exportable source blocks with a caption or
1353    a name in parse tree.
1354
1355    Used to build a table of listings.
1356
1357    See also: [[#collect-headlines][~org-export-collect-headlines~]],
1358    [[#collect-tables][~org-export-collect-tables~]], [[#collect-figures][~org-export-collect-figures~]].
1359 ** ~org-export-collect-tables~
1360    :PROPERTIES:
1361    :CUSTOM_ID: collect-tables
1362    :END:
1363
1364    Return a list of all exportable tables with a caption or a name in
1365    parse tree.
1366
1367    Used to build a table of tables.
1368
1369    See also: [[#collect-headlines][~org-export-collect-headlines~]],
1370    [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]].
1371
1372 ** ~org-export-data~
1373    :PROPERTIES:
1374    :CUSTOM_ID: data
1375    :END:
1376
1377    Transcode a given element, object, secondary string or string using
1378    current back-end.
1379
1380    It is used primarily to transcode secondary strings, like ~:title~.
1381    For example ~beamer~ back-end uses the following:
1382
1383    #+BEGIN_SRC emacs-lisp
1384    (defun org-beamer-template (contents info)
1385      (let ((title (org-export-data (plist-get info :title) info)))
1386        ...))
1387    #+END_SRC
1388
1389 ** ~org-export-data-with-backend~
1390    :PROPERTIES:
1391    :CUSTOM_ID: data-with-backend
1392    :END:
1393
1394    Recursively convert some data (an element, an object, a secondary
1395    string or a string) using another backend.
1396
1397    See also: [[#with-backend][~org-export-with-backend~]],
1398    [[#data-with-translations][~org-export-data-with-translations~]]
1399
1400 ** ~org-export-data-with-translations~
1401    :PROPERTIES:
1402    :CUSTOM_ID: data-with-translations
1403    :END:
1404
1405    Recursively convert some data (an element, an object, a secondary
1406    string or a string) using a given translation table, which
1407    basically acts as an anonymous back-end.
1408
1409    See also: [[#with-backend][~org-export-with-backend~]],
1410    [[#data-with-backend][~org-export-data-with-backend~]]
1411
1412 ** ~org-export-first-sibling-p~
1413    :PROPERTIES:
1414    :CUSTOM_ID: first-sibling-p
1415    :END:
1416
1417    Non-nil if an headline is the first of its siblings.
1418
1419    Used to know when to start a list if headline's relative level is
1420    below the one specified in [[#headline-levels][~:headline-levels~]] property.
1421
1422    See also: [[#get-relative-level][~org-export-get-relative-level~]],
1423    [[#number-to-roman][~org-export-number-to-roman~]], [[#last-sibling-p][~org-export-last-sibling-p~]].
1424
1425 ** ~org-export-footnote-first-reference-p~
1426    :PROPERTIES:
1427    :CUSTOM_ID: footnote-first-reference-p
1428    :END:
1429
1430    Non-nil when a footnote reference if the first reference relative
1431    to its definition.
1432
1433    Used when a back-end needs to attach the footnote definition only
1434    to the first occurrence of the corresponding label.
1435
1436    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
1437    [[#get-footnote-definition][~org-export-get-footnote-definition~]],
1438    [[#get-footnote-number][~org-export-get-footnote-number~]].
1439
1440 ** ~org-export-format-code-default~
1441    :PROPERTIES:
1442    :CUSTOM_ID: format-code-default
1443    :END:
1444
1445    Return contents of a =src-block= or =example-block= element in
1446    a format suited for raw text or verbatim output.  More
1447    specifically, it takes care of line numbering and labels
1448    integration depending of element's switches, but no formatting is
1449    otherwise applied to source code.
1450
1451    See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
1452
1453 ** ~org-export-format-code~
1454    :PROPERTIES:
1455    :CUSTOM_ID: format-code
1456    :END:
1457
1458    Helper function to format source code.  It applies a given function
1459    on each line of the code, passing current line number and
1460    associated code reference label, if any, as arguments.
1461
1462    See also: [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]],
1463    [[#unravel-code][~org-export-unravel-code~]].
1464
1465 ** ~org-export-get-caption~
1466    :PROPERTIES:
1467    :CUSTOM_ID: get-caption
1468    :END:
1469
1470    Return the caption of a given element, as a secondary string.  With
1471    an optional argument, return the short caption instead.
1472
1473    As an example, ~ascii~ back-end, when creating a list of listings,
1474    uses the following:
1475
1476    #+BEGIN_SRC emacs-lisp
1477    (defun org-ascii--list-listings (keyword info)
1478      (let ((title (org-ascii--translate "List of Listings" info)))
1479        (concat title "\n"
1480                ...
1481                (mapconcat
1482                 (lambda (src-block)
1483                   ...
1484                   ;; Use short name in priority, if available.
1485                   (let ((caption (or (org-export-get-caption src-block t)
1486                                      (org-export-get-caption src-block))))
1487                     (org-export-data caption info)
1488                     ...))
1489                 (org-export-collect-listings info) "\n"))))
1490    #+END_SRC
1491
1492    See also: [[#read-attribute][~org-export-read-attribute~]].
1493
1494 ** ~org-export-get-category~
1495    :PROPERTIES:
1496    :CUSTOM_ID: get-category
1497    :END:
1498
1499    Return category associated to a given element or object.  Unlike to
1500    the ~:category~ property from headlines and inlinetasks, this
1501    function handles inheritance and ~CATEGORY~ keywords.  Therefore,
1502    it should be the preferred way to retrieve a category during
1503    export.
1504
1505    See also: [[#get-node-property][~org-export-get-node-property~]].
1506
1507 ** ~org-export-get-coderef-format~
1508    :PROPERTIES:
1509    :CUSTOM_ID: get-coderef-format
1510    :END:
1511
1512    Return an appropriate format string for code reference links.
1513
1514    See also: [[#resolve-coderef][~org-export-resolve-coderef~]].
1515
1516 ** ~org-export-get-footnote-definition~
1517    :PROPERTIES:
1518    :CUSTOM_ID: get-footnote-definition
1519    :END:
1520
1521    Retrieve the footnote definition relative to a given footnote
1522    reference.
1523
1524    If the footnote definition in inline, it is returned as a secondary
1525    string.  Otherwise, it is full Org data.
1526
1527    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
1528    [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
1529    [[#get-footnote-number][~org-export-get-footnote-number~]].
1530
1531 ** ~org-export-get-footnote-number~
1532    :PROPERTIES:
1533    :CUSTOM_ID: get-footnote-number
1534    :END:
1535
1536    Return the ordinal attached to a footnote reference or definition.
1537
1538    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
1539    [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
1540    [[#get-footnote-definition][~org-export-get-footnote-definition~]].
1541
1542 ** ~org-export-get-genealogy~
1543    :PROPERTIES:
1544    :CUSTOM_ID: get-genealogy
1545    :END:
1546
1547    Return flat list of current object or element's parents from
1548    closest to farthest, along with their contents.
1549
1550    See also: [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1551    [[#get-parent-headline][~org-export-get-parent-headline~]],
1552    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1553    [[#get-previous-element][~org-export-get-previous-element~]].
1554
1555 ** ~org-export-get-headline-number~
1556    :PROPERTIES:
1557    :CUSTOM_ID: get-headline-number
1558    :END:
1559
1560    Return the section number of an headline, as a list of integers.
1561
1562    See also: [[#headline-numbered-p][~org-export-headline-numbered-p~]],
1563    [[#number-to-roman][~org-export-number-to-roman~]].
1564
1565 ** ~org-export-get-loc~
1566    :PROPERTIES:
1567    :CUSTOM_ID: get-loc
1568    :END:
1569
1570    Return count of accumulated lines of code from previous
1571    line-numbered =example-block= and =src-block= elements, according
1572    to current element's switches.
1573
1574    In other words, the first line of code in the current block is
1575    supposed to be numbered as the returned value plus one, assuming
1576    its ~:number-lines~ properties is non-nil.
1577
1578    See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
1579
1580 ** ~org-export-get-next-element~
1581    :PROPERTIES:
1582    :CUSTOM_ID: get-next-element
1583    :END:
1584
1585    Return element (resp. object or string) after an element
1586    (resp. object), or nil.
1587
1588    See also: [[#get-genealogy][~org-export-get-genealogy~]], [[#get-parent][~org-export-get-parent~]],
1589    [[#get-parent-headline][~org-export-get-parent-headline~]],
1590    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1591    [[#get-previous-element][~org-export-get-previous-element~]].
1592
1593 ** ~org-export-get-node-property~
1594    :PROPERTIES:
1595    :CUSTOM_ID: get-node-property
1596    :END:
1597
1598    Return the node property associated to an element or object.  If
1599    the element is an headline, this is equivalent to reading the
1600    property with ~org-element-property~.
1601
1602    Though, this function can optionally handle inheritance.
1603
1604    See also: [[#get-category][~org-export-get-category~]].
1605
1606 ** ~org-export-get-ordinal~
1607    :PROPERTIES:
1608    :CUSTOM_ID: get-ordinal
1609    :END:
1610
1611    Associate a sequence number to any object or element.  It is meant
1612    to be used to build captions.
1613
1614    Also, it could be applied on a fuzzy link's destination, since such
1615    links are expected to be replaced with the sequence number of their
1616    destination, provided they have no description.
1617
1618    Taken from ~ascii~ back-end, the following example shows how fuzzy
1619    links could be handled :
1620
1621    #+BEGIN_SRC emacs-lisp :exports code
1622    (let ((type (org-element-property :type link)))
1623      (cond
1624       ...
1625       ;; Do not apply a special syntax on fuzzy links pointing to targets.
1626       ((string= type "fuzzy")
1627        (let ((destination (org-export-resolve-fuzzy-link link info)))
1628          ;; Ignore invisible "#+TARGET: path".
1629          (unless (eq (org-element-type destination) 'keyword)
1630            ;; If link has a description, use it.
1631            (if (org-string-nw-p desc) desc
1632              (when destination
1633                (let ((number (org-export-get-ordinal destination info)))
1634                  (when number
1635                    (if (atom number) (number-to-string number)
1636                      (mapconcat 'number-to-string number ".")))))))))
1637       ...))
1638    #+END_SRC
1639
1640    See also : [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]]
1641
1642 ** ~org-export-get-parent-element~
1643    :PROPERTIES:
1644    :CUSTOM_ID: get-parent-paragraph
1645    :END:
1646
1647    Return the first element containing provided object, if any.
1648    Return nil otherwise.
1649
1650    See also: [[#get-genealogy][~org-export-get-genealogy~]], [[#get-parent][~org-export-get-parent~]],
1651    [[#get-parent-headline][~org-export-get-parent-headline~]],
1652    [[#get-previous-element][~org-export-get-previous-element~]], [[#get-next-element][~org-export-get-next-element~]].
1653
1654 ** ~org-export-get-parent-headline~
1655    :PROPERTIES:
1656    :CUSTOM_ID: get-parent-headline
1657    :END:
1658
1659    Return the headline containing provided element or object, if any.
1660    Return nil otherwise.
1661
1662    See also: [[#get-genealogy][~org-export-get-genealogy~]],
1663    [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1664    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1665    [[#get-previous-element][~org-export-get-previous-element~]].
1666
1667 ** ~org-export-get-parent~
1668    :PROPERTIES:
1669    :CUSTOM_ID: get-parent
1670    :END:
1671
1672    Return closest element containing current element or object, if
1673    any.  Return nil otherwise.
1674
1675    See also: [[#get-genealogy][~org-export-get-genealogy~]],
1676    [[#get-next-element][~org-export-get-next-element~]], [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1677    [[#get-parent-headline][~org-export-get-parent-headline~]],
1678    [[#get-previous-element][~org-export-get-previous-element~]].
1679
1680 ** ~org-export-get-previous-element~
1681    :PROPERTIES:
1682    :CUSTOM_ID: get-previous-element
1683    :END:
1684
1685    Return element (resp. object or string) before an element
1686    (resp. object), or nil.
1687
1688    See also: [[#get-genealogy][~org-export-get-genealogy~]],
1689    [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1690    [[#get-parent-headline][~org-export-get-parent-headline~]],
1691    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]].
1692
1693 ** ~org-export-get-relative-level~
1694    :PROPERTIES:
1695    :CUSTOM_ID: get-relative-level
1696    :END:
1697
1698    Return headline level, relatively to the lower headline level in
1699    the parsed tree.  It is meant to be used over ~:level~ headline's
1700    property.
1701
1702    See also:[[#first-sibling-p][~org-export-first-sibling-p~]],
1703     [[#get-headline-number][~org-export-get-headline-number~]],[[#headline-numbered-p][~org-export-headline-numbered-p~]],
1704     [[#last-sibling-p][~org-export-last-sibling-p~]].
1705
1706 ** ~org-export-get-table-cell-at~
1707    :PROPERTIES:
1708    :CUSTOM_ID: get-table-cell-at
1709    :END:
1710
1711    Return exportable cell object at a given position, or nil.  Hence,
1712    position ~(0 . 0)~ will always point to the first exportable cell
1713    in the table.
1714
1715    See also: [[#table-cell-address][~org-export-table-cell-address~]],
1716    [[#table-dimensions][~org-export-table-dimensions~]].
1717
1718 ** ~org-export-get-tags~
1719    :PROPERTIES:
1720    :CUSTOM_ID: get-tags
1721    :END:
1722
1723    Return list of exportable tags attached to a given headline or
1724    inlinetask element.  With an optional argument, tags are inherited
1725    from parent headlines and ~FILETAGS~ keywords.
1726
1727    In particular, it removes select tags and exclude tags. The
1728    function also accepts an arbitrary list of tags for further
1729    cleaning.
1730
1731    For example, ~latex~ back-end uses the following snippet in the
1732    inlinetask transcode function.
1733
1734    #+BEGIN_SRC emacs-lisp
1735    (let ((title (org-export-data (org-element-property :title inlinetask) info))
1736       (todo (and (plist-get info :with-todo-keywords)
1737                  (let ((todo (org-element-property :todo-keyword inlinetask)))
1738                    (and todo (org-export-data todo info)))))
1739       (todo-type (org-element-property :todo-type inlinetask))
1740       (tags (and (plist-get info :with-tags)
1741                  (org-export-get-tags inlinetask info)))
1742       (priority (and (plist-get info :with-priority)
1743                      (org-element-property :priority inlinetask))))
1744   ...)
1745    #+END_SRC
1746
1747 ** ~org-export-headline-numbered-p~
1748    :PROPERTIES:
1749    :CUSTOM_ID: headline-numbered-p
1750    :END:
1751
1752    Non nil when a given headline should be numbered.
1753
1754    See also: [[#get-headline-number][~org-export-get-headline-number~]],
1755    [[#get-relative-level][~org-export-get-relative-level~]].
1756
1757 ** ~org-export-inline-image-p~
1758    :PROPERTIES:
1759    :CUSTOM_ID: inline-image-p
1760    :END:
1761
1762    Non-nil when the link provided should be considered as an inline
1763    image.  Note that it always return nil when the link has
1764    a description.
1765
1766    It accepts an optional set of rules in order to tweak the
1767    definition of an inline image, which is, by default, any link
1768    targetting a local file whose extension is either "png", "jpeg",
1769    "jpg", "gif", "tiff", "tif", "xbm", "xpm", "pbm", "pgm" or "ppm".
1770
1771    A set of rules consists in an alist whose key is a type of link, as
1772    a string, and whose value is a regexp matching link's path.  As an
1773    example, ~html~ back-end uses the following rules:
1774
1775    #+BEGIN_SRC emacs-lisp
1776    '(("file" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1777      ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1778      ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'"))
1779    #+END_SRC
1780
1781    See also: [[#solidify-link-text][~org-export-solidify-link-text~]],
1782    [[#get-coderef-format][~org-export-get-coderef-format~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]].
1783
1784 ** ~org-export-last-sibling-p~
1785    :PROPERTIES:
1786    :CUSTOM_ID: last-sibling-p
1787    :END:
1788
1789    Non-nil if an headline is the last of its siblings.
1790
1791    Used to know when to close a list if headline's relative level is
1792    below the one specified in [[#headline-levels][~:headline-levels~]] property.
1793
1794    See also: [[#get-relative-level][~org-export-get-relative-level~]],
1795    [[#number-to-roman][~org-export-number-to-roman~]], [[#first-sibling-p][~org-export-first-sibling-p~]].
1796
1797 ** ~org-export-number-to-roman~
1798    :PROPERTIES:
1799    :CUSTOM_ID: number-to-roman
1800    :END:
1801
1802    Convert numbers to roman numbers. It can be used to provide roman
1803    numbering for headlines and numbered lists.
1804
1805    See also: [[#get-headline-number][~org-export-get-headline-number~]].
1806
1807 ** ~org-export-read-attribute~
1808    :PROPERTIES:
1809    :CUSTOM_ID: read-attribute
1810    :END:
1811
1812    Read a property from a given element as a plist.  It can be used to
1813    normalize affiliated keywords' syntax.  For example, the following
1814    affiliated keywords:
1815
1816    #+BEGIN_SRC org
1817    ,#+ATTR_HTML: :width 10 :height 5
1818    ,#+ATTR_HTML: :file "filename.ext"
1819    #+END_SRC
1820
1821    would be returned as:
1822
1823    #+BEGIN_SRC emacs-lisp
1824    '(:width 10 :height 5 :file "filename.ext")
1825    #+END_SRC
1826
1827    See also: [[#get-caption][~org-export-get-caption~]].
1828
1829 ** ~org-export-resolve-coderef~
1830    :PROPERTIES:
1831    :CUSTOM_ID: resolve-coderef
1832    :END:
1833
1834    Search for a code reference within ~src-block~ and ~example-block~
1835    elements.  Return corresponding --possibly accumulated-- line
1836    number, or reference itself, depending on container's switches.
1837
1838    See also : [[#get-coderef-format][~org-export-get-coderef-format~]],
1839    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1840    [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1841
1842 ** ~org-export-resolve-fuzzy-link~
1843    :PROPERTIES:
1844    :CUSTOM_ID: resolve-fuzzy-link
1845    :END:
1846
1847    Search destination of a fuzzy link — i.e. it has a ~fuzzy~ ~:type~
1848    attribute – within the parsed tree, and return that element,
1849    object, or nil.
1850
1851    See also: [[#get-ordinal][~org-export-get-ordinal~]], [[#resolve-coderef][~org-export-resolve-coderef~]],
1852    [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1853    [[#solidify-link-text][~org-export-solidify-link-text~]].
1854
1855 ** ~org-export-resolve-id-link~
1856    :PROPERTIES:
1857    :CUSTOM_ID: resolve-id-link
1858    :END:
1859
1860    Search headline targetted by an id link --- i.e. it has a ~id~ or
1861    ~custom-id~ ~:type~ attribute --- within the parse tree.  Return
1862    the matching headline in the tree, the name of the external file,
1863    as a string, or nil.
1864
1865    See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1866    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1867    [[#solidify-link-text][~org-export-solidify-link-text~]].
1868
1869 ** ~org-export-resolve-radio-link~
1870    :PROPERTIES:
1871    :CUSTOM_ID: resolve-radio-link
1872    :END:
1873
1874    Return first radio target object matching a radio link --- that is
1875    with a ~radio~ ~:type~ attribute --- in the parse tree, or nil.
1876
1877    Typically, target's contents are exported through ~org-export-data~
1878    and used as link description, as in the following excerpt from
1879    =ox-latex.el=:
1880
1881    #+BEGIN_SRC emacs-lisp
1882    (defun org-latex-link (link desc info)
1883      (let* ((type (org-element-property :type link))
1884             ...)
1885        (cond
1886         ...
1887         ((string= type "radio")
1888          (let ((destination (org-export-resolve-radio-link link info)))
1889            (when destination
1890              (format "\\hyperref[%s]{%s}"
1891                      (org-export-solidify-link-text path)
1892                      (org-export-data (org-element-contents destination) info)))))
1893         ...)))
1894    #+END_SRC
1895
1896    See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1897    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1898    [[#solidify-link-text][~org-export-solidify-link-text~]].
1899
1900 ** ~org-export-solidify-link-text~
1901    :PROPERTIES:
1902    :CUSTOM_ID: solidify-link-text
1903    :END:
1904
1905    Normalize a string, replacing most non-standard characters with
1906    hyphens.
1907
1908    Used to turn targets names into safer versions for links.
1909
1910    See also: [[#inline-image-p][~org-export-inline-image-p~]],
1911    [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]],
1912    [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1913
1914 ** ~org-export-table-cell-address~
1915    :PROPERTIES:
1916    :CUSTOM_ID: table-cell-address
1917    :END:
1918
1919    Return row and column of a given cell object.  Positions are
1920    0-indexed and only exportable rows and columns are considered.  The
1921    function returns nil if called on a non-exportable cell.
1922
1923    See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
1924    [[#table-dimensions][~org-export-table-dimensions~]].
1925
1926 ** ~org-export-table-cell-alignment~
1927    :PROPERTIES:
1928    :CUSTOM_ID: table-cell-alignment
1929    :END:
1930
1931    Return expected alignment for the contents of a given cell object.
1932    It can be either ~left~, ~right~ or ~center~.
1933
1934    See also: [[#table-cell-borders][~org-export-table-cell-borders~]],
1935    [[#table-cell-width][~org-export-table-cell-width~]].
1936
1937 ** ~org-export-table-cell-borders~
1938    :PROPERTIES:
1939    :CUSTOM_ID: table-cell-borders
1940    :END:
1941
1942    Indicate expected borders for a given cell object.  When non-nil,
1943    return value is a list of symbols among ~top~, ~bottom~, ~above~,
1944    ~below~, ~left~ and ~right~.
1945
1946    Special values ~top~ and ~bottom~ only happen for cells in,
1947    respectively, the first and the last exportable rows.
1948
1949    See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
1950    [[#table-cell-width][~org-export-table-cell-width~]].
1951
1952 ** ~org-export-table-cell-ends-colgroup-p~
1953    :PROPERTIES:
1954    :CUSTOM_ID: table-cell-ends-colgroup-p
1955    :END:
1956
1957    Non-nil when a table cell object ends a column group.
1958
1959    See also: [[#table-cell-starts-colgroup-p][~org-export-table-cell-starts-colgroup-p~]].
1960
1961 ** ~org-export-table-cell-starts-colgroup-p~
1962    :PROPERTIES:
1963    :CUSTOM_ID: table-cell-starts-colgroup-p
1964    :END:
1965
1966    Non-nil when a table cell object starts a column group.
1967
1968    See also: [[#table-cell-ends-colgroup-p][~org-export-table-cell-ends-colgroup-p~]].
1969
1970 ** ~org-export-table-cell-width~
1971    :PROPERTIES:
1972    :CUSTOM_ID: table-cell-width
1973    :END:
1974
1975    Return expected width for contents of a given cell object.
1976
1977    Only width specified explicitely through meta-data is considered.
1978    If no such information can be found, return nil instead.
1979
1980    Some back-end may still need to know the actual width of exported
1981    cell's contents in order to compute column's width.  In that case,
1982    every cell in the column must be transcoded in order to find the
1983    widest one.  The snippet below, extracted from =ox-ascii.el=
1984    illustrates a possible implementation.
1985
1986    #+BEGIN_SRC emacs-lisp
1987    (or (org-export-table-cell-width table-cell info)
1988        (let* ((max-width 0)
1989               (table (org-export-get-parent-table table-cell info))
1990               (specialp (org-export-table-has-special-column-p table))
1991               (col (cdr (org-export-table-cell-address table-cell info))))
1992          (org-element-map
1993           table 'table-row
1994           (lambda (row)
1995             ;; For each exportable row, get the cell at column COL and
1996             ;; transcode its contents.  Then compare its length with
1997             ;; MAX-WIDTH and keep the greater of two.
1998             (setq max-width
1999                   (max (length
2000                         (org-export-data
2001                          (org-element-contents
2002                           (elt (if specialp (car (org-element-contents row))
2003                                  (org-element-contents row))
2004                                col))
2005                          info))
2006                        max-width)))
2007           info)
2008          max-width))
2009    #+END_SRC
2010
2011    See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
2012    [[#table-cell-borders][~org-export-table-cell-borders~]].
2013
2014 ** ~org-export-table-dimensions~
2015    :PROPERTIES:
2016    :CUSTOM_ID: table-dimensions
2017    :END:
2018
2019    Return the number of exportable rows and columns in a given table.
2020
2021    See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
2022    [[#table-cell-address][~org-export-table-cell-address~]].
2023
2024 ** ~org-export-table-has-header-p~
2025    :PROPERTIES:
2026    :CUSTOM_ID: table-has-header-p
2027    :END:
2028
2029    Non-nil when table has at least two row groups.
2030
2031    See also: [[#table-has-special-column-p][~org-export-table-has-special-column-p~]],
2032    [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
2033
2034 ** ~org-export-table-has-special-column-p~
2035    :PROPERTIES:
2036    :CUSTOM_ID: table-has-special-column-p
2037    :END:
2038
2039    Non-nil when first column in the table only contains meta-data.
2040
2041    See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
2042    [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
2043
2044 ** ~org-export-table-row-ends-header-p~
2045    :PROPERTIES:
2046    :CUSTOM_ID: table-row-ends-header-p
2047    :END:
2048
2049    Non-nil when a table row element ends table's header.
2050
2051    See also: [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
2052    [[#table-row-group][~org-export-table-row-group~]],
2053    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
2054    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
2055
2056 ** ~org-export-table-row-ends-rowgroup-p~
2057    :PROPERTIES:
2058    :CUSTOM_ID: table-row-ends-rowgroup-p
2059    :END:
2060
2061    Non-nil when a a table row element ends a rowgroup, header
2062    included.
2063
2064    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
2065    [[#table-row-group][~org-export-table-row-group~]],
2066    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
2067    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
2068
2069 ** ~org-export-table-row-group~
2070    :PROPERTIES:
2071    :CUSTOM_ID: table-row-group
2072    :END:
2073
2074    Return row group number for a given table row element.
2075
2076    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
2077    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
2078    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
2079    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
2080
2081 ** ~org-export-table-row-is-special-p~
2082    :PROPERTIES:
2083    :CUSTOM_ID: table-row-is-special-p
2084    :END:
2085
2086    Non-nil a given table row element only contains meta-data.
2087
2088    See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
2089    [[#table-has-special-column-p][~org-export-table-has-special-column-p~]].
2090
2091 ** ~org-export-table-row-starts-header-p~
2092    :PROPERTIES:
2093    :CUSTOM_ID: table-row-starts-header-p
2094    :END:
2095
2096    Non-nil when a table row element starts table's header.
2097
2098    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
2099    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
2100    [[#table-row-group][~org-export-table-row-group~]],
2101    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
2102
2103 ** ~org-export-table-row-starts-rowgroup-p~
2104    :PROPERTIES:
2105    :CUSTOM_ID: table-row-starts-rowgroup-p
2106    :END:
2107
2108    Non-nil when a table row element starts a rowgroup, header
2109    included.
2110
2111    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
2112    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
2113    [[#table-row-group][~org-export-table-row-group~]],
2114    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]].
2115
2116 ** ~org-export-translate~
2117
2118    Translate a string, i.e. "Table of Contents", according to language
2119    specification.
2120
2121    Refer to ~org-export-dictionary~ variable for the list of all
2122    supported strings.
2123
2124 ** ~org-export-unravel-code~
2125    :PROPERTIES:
2126    :CUSTOM_ID: unravel-code
2127    :END:
2128
2129    Clean source code from an =example-block= or a =src-block= element
2130    and extract code references out of it.
2131
2132    Its purpose is to allow to transform raw source code first and then
2133    integrate line numbers or references back into the final output.
2134    That final task can be achieved with the help of
2135    ~org-export-format-code~ function.
2136
2137    See also: [[#format-code][~org-export-format-code~]],
2138    [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]].
2139
2140 ** ~org-export-with-backend~
2141    :PROPERTIES:
2142    :CUSTOM_ID: with-backend
2143    :END:
2144
2145    Export an element or object using locally another back-end.
2146
2147    In a derived back-end, it may be used as a fall-back function once
2148    all specific cases have been handled.  Thus, ~beamer~ back-end,
2149    derived from ~latex~, takes care of every internal link type and
2150    delagates everything else to its parent back-end:
2151
2152    #+BEGIN_SRC emacs-lisp
2153    (let ((type (org-element-property :type link))
2154          (path (org-element-property :path link)))
2155      (cond
2156       ;; Handle every internal link type, but be careful to ignore "id"
2157       ;; type links pointing to external files.
2158       ((equal type "radio") ...)
2159       ((and (member type '("custom-id" "fuzzy" "id"))
2160             (let ((destination (if (string= type "fuzzy")
2161                                    (org-export-resolve-fuzzy-link link info)
2162                                  (org-export-resolve-id-link link info))))
2163               (case (org-element-type destination)
2164                 (headline ...)
2165                 (target ...)))))
2166       ;; Otherwise, use `latex' back-end.
2167       (t (org-export-with-backend 'latex link contents info))))
2168    #+END_SRC
2169
2170    See also: [[#data-with-backend][~org-export-data-with-backend~]],
2171    [[#data-with-translations][~org-export-data-with-translations~]]
2172
2173 * Interactive functions
2174   :PROPERTIES:
2175   :CUSTOM_ID: interactive
2176   :END:
2177
2178   Once the back-end is complete, interactive functions have to be
2179   offered for the user to use it.  Depending on the desired output,
2180   three functions are provided to help in this task, along with
2181   a wrapper function allowing to make export asynchronous.
2182
2183   Hence, ~org-export-to-buffer~ may be used if the expected output is
2184   a temporary buffer whereas ~org-export-to-file~ will be used when
2185   exporting to a file.  In the latter case,
2186   ~org-export-output-file-name~ can be useful to guess the name of the
2187   output file --- though, don't use it in an external process, since
2188   it will ask the user for a file name when guessing fails.  At the
2189   lowest level, ~org-export-as~ returns the output as a string.  It
2190   may be used in conjunction with ~org-export-async-start~ in order to
2191   export asynchronously to a temporary buffer, since buffer creation
2192   cannot happen in the external process.
2193
2194   When exporting in background, the output is expected to be displayed
2195   in the Export Stack.  The function ~org-export-add-to-stack~ helps
2196   doing so.
2197
2198   While it is suggested to have a look at their respective docstring,
2199   the following examples illustrate how to combine all these
2200   functions:
2201
2202   1. Export to a temporary buffer:
2203
2204      #+BEGIN_SRC emacs-lisp
2205      ;;;###autoload
2206      (defun org-latex-export-as-latex
2207      (&optional async subtreep visible-only body-only ext-plist)
2208        (interactive)
2209        (if async
2210            (org-export-async-start
2211                (lambda (output)
2212                  (with-current-buffer (get-buffer-create "*Org E-LATEX Export*")
2213                    (erase-buffer)
2214                    (insert output)
2215                    (goto-char (point-min))
2216                    (LaTeX-mode)
2217                    (org-export-add-to-stack (current-buffer) 'latex)))
2218              `(org-export-as 'latex ,subtreep ,visible-only ,body-only ',ext-plist))
2219          (let ((outbuf (org-export-to-buffer 'latex "*Org E-LATEX Export*"
2220                                       subtreep visible-only body-only ext-plist)))
2221            (with-current-buffer outbuf (LaTeX-mode))
2222            (when org-export-show-temporary-export-buffer
2223              (switch-to-buffer-other-window outbuf)))))
2224      #+END_SRC
2225
2226   2. Export to a file:
2227
2228      #+BEGIN_SRC emacs-lisp
2229      ;;;###autoload
2230      (defun org-latex-export-to-latex
2231        (&optional async subtreep visible-only body-only ext-plist)
2232        (interactive)
2233        (let ((outfile (org-export-output-file-name ".tex" subtreep)))
2234          (if async
2235              (org-export-async-start
2236                  (lambda (f) (org-export-add-to-stack f 'latex))
2237                `(expand-file-name
2238                  (org-export-to-file
2239                   'latex ,outfile ,subtreep ,visible-only ,body-only ',ext-plist)))
2240            (org-export-to-file
2241             'latex outfile subtreep visible-only body-only ext-plist))))
2242      #+END_SRC
2243
2244   It may also be interesting to provide a publishing function for the
2245   back-end.  Such function must accept three arguments: a plist
2246   containing properties relative to the project being exported, the
2247   name of the current file being published and the publishing
2248   directory.  It often is a simple wrapper around ~org-publish-org-to~
2249   function defined in =ox-publish.el=, as shown in the following
2250   example:
2251
2252   #+BEGIN_SRC emacs-lisp
2253   (defun org-html-publish-to-html (plist filename pub-dir)
2254     (org-publish-org-to 'html filename ".html" plist pub-dir))
2255   #+END_SRC
2256
2257
2258 # Local Variables:
2259 # sentence-end-double-space: t
2260 # End: