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