dev/org-export-reference.org

   1 #+TITLE:      Org Export Reference Documentation
   2 #+AUTHOR:     Nicolas Goaziou
   3 #+EMAIL:      mail@nicolasgoaziou.fr
   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, properties offered by the
  19 [[#communication][communication channel]] during export, the [[#filter-system][filter system]] internals and
  20 [[#toolbox][tools]] provided by the exporter.  Eventually, expected [[#interactive][interactive
  21 functions]] aimed at end-users are explained in the last part of this
  22 document.
  23
  24
  25 * Defining a Back-End
  26   :PROPERTIES:
  27   :CUSTOM_ID: back-end
  28   :END:
  29
  30   A back-end is defined with ~org-export-define-backend~ function.  It
  31   requires two mandatory arguments: the back-end name and its
  32   translation table, an alist that associates element and object types
  33   to translator functions.  According to the documentation:
  34
  35   #+BEGIN_QUOTE
  36   These functions should return a string without any trailing space,
  37   or nil.  They must accept three arguments: the object or element
  38   itself, its contents or nil when it isn't recursive and the property
  39   list used as a communication channel.
  40
  41   Contents, when not nil, are stripped from any global indentation
  42   (although the relative one is preserved).  They also always end with
  43   a single newline character.
  44
  45   If, for a given type, no function is found, that element or object
  46   type will simply be ignored, along with any blank line or white
  47   space at its end.  The same will happen if the function returns the
  48   nil value.  If that function returns the empty string, the type will
  49   be ignored, but the blank lines or white spaces will be kept.
  50
  51   In addition to element and object types, one function can be
  52   associated to the ~template~ symbol and another one to the
  53   ~plain-text~ symbol.
  54
  55   The former returns the final transcoded string, and can be used to
  56   add a preamble and a postamble to document's body.  It must accept
  57   two arguments: the transcoded string and the property list
  58   containing export options.
  59
  60   The latter, when defined, is to be called on every text not
  61   recognized as an element or an object.  It must accept two
  62   arguments: the text string and the information channel.  It is an
  63   appropriate place to protect special chars relative to the back-end.
  64   #+END_QUOTE
  65
  66   Optionally, the function can set-up back-end specific properties (like
  67   values from specific buffer keywords) accessible from every translator
  68   function with the ~:options-alist~ keyword.  See
  69   ~org-export-options-alist~ for details on the structure of the value.
  70
  71   As an example, the following excerpt from ~latex~ back-end
  72   definition introduces three new buffer keywords (and their
  73   headline's property counterpart), and redefine ~DATE~ default value:
  74
  75   #+BEGIN_SRC emacs-lisp
  76   (org-export-define-backend 'latex
  77     ...
  78     :options-alist '((:date "DATE" nil "\\today" t)
  79                      (:date-format nil nil org-latex-date-timestamp-format)
  80                      (:latex-class "LATEX_CLASS" nil org-latex-default-class t)
  81                      (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
  82                      (:latex-header-extra "LATEX_HEADER" nil nil newline)
  83                      (:latex-hyperref-p nil "texht" org-latex-with-hyperref t)))
  84   #+END_SRC
  85
  86   Eventually ~org-export-define-backend~ allows to define back-ends
  87   specific filters.  Refer to [[#filter-system][The Filter System]] section for more
  88   information.
  89
  90   If the new back-end shares most properties with another one, use
  91   ~org-export-define-derived-backend~ to simplify the creation
  92   process.  In the example below, we implement a new back-end which
  93   behaves like ~latex~ except for headlines and the template.
  94
  95   #+BEGIN_SRC emacs-lisp
  96     (org-export-define-derived-backend 'my-latex 'latex
  97       :translate-alist '((headline . my-latex-headline-translator)
  98                          (template . my-latex-template)))
  99   #+END_SRC
 100
 101   Back-ends defined with either function can be registered in the export
 102   dispatcher using special keyword =:menu-entry=.  See defuns docstrings
 103   for more information.
 104
 105   Eventually, you can create an anonymous back-end with
 106   ~org-export-create-backend~.  It can inherit from an existing
 107   back-end or define everything from scratch.
 108
 109   Such a back-end doesn't appear in any user-facing menu, however.  It
 110   is meant to be used as an argument for ~org-export-with-backend~ and
 111   ~org-export-data-with-backend~, for exporting rules with a limited
 112   scope.
 113
 114   For example, entries in a table of contents usually link to headings
 115   in the document.  As a consequence, targets, footnote references,
 116   and external links may be ignored from the table of contents.  As an
 117   example, the HTML export back-end prunes various link-like types
 118   from table of contents' entries -- here ~toc-entry~ -- with the
 119   following code:
 120
 121   #+BEGIN_SRC emacs-lisp
 122     (org-export-data-with-backend
 123      toc-entry
 124      (org-export-create-backend
 125       :parent 'html
 126       :transcoders `((footnote-reference . ,#'ignore)
 127                      (link . ,(lambda (l c i)
 128                                 (or c
 129                                     (org-export-data
 130                                      (org-element-property :raw-link l)
 131                                      i))))
 132                      (radio-target . ,(lambda (_r c _i) c))
 133                      (target . ,#'ignore)))
 134      info)
 135   #+END_SRC
 136
 137   Since this is a common anonymous back-end, the above is readily
 138   available calling ~org-export-toc-entry-backend~.
 139
 140 * The Communication Channel
 141   :PROPERTIES:
 142   :CUSTOM_ID: communication
 143   :END:
 144
 145   During export process, every function has access to a number of
 146   properties.  They are of two types:
 147
 148   1. Environment options are collected once at the very beginning of
 149      the process, out of the original buffer and configuration.
 150      Collecting them is handled by ~org-export-get-environment~
 151      function.
 152
 153      Most environment options are defined through the
 154      ~org-export-options-alist~ variable.
 155
 156   2. Tree properties are extracted directly from the parsed tree, just
 157      before export, by ~org-export-collect-tree-properties~.
 158
 159   This is the full list of properties available during transcode
 160   process, with their category (=option= or =tree=) and their value
 161   type.
 162
 163 ** ~:author~
 164
 165    Author's name.
 166
 167    - category :: option
 168    - type :: string
 169
 170 ** ~:back-end~
 171
 172    Current back-end used for transcoding.
 173
 174    - category :: tree
 175    - type :: structure
 176
 177 ** ~:creator~
 178
 179    String to write as creation information.
 180
 181    - category :: option
 182    - type :: string
 183
 184 ** ~:date~
 185
 186    String to use as date.
 187
 188    - category :: option
 189    - type :: string
 190
 191 ** ~:description~
 192
 193    Description text for the current data.
 194
 195    - category :: option
 196    - type :: string
 197
 198 ** ~:email~
 199
 200    Author's email.
 201
 202    - category :: option
 203    - type :: string
 204
 205 ** ~:exclude-tags~
 206
 207    Tags for exclusion of sub-trees from export process.
 208
 209    - category :: option
 210    - type :: list of strings
 211
 212 ** ~:export-options~
 213
 214    List of export options available for current process.
 215
 216    - category :: none
 217    - type :: list of symbols, among ~subtree~, ~body-only~ and
 218              ~visible-only~.
 219
 220 ** ~:exported-data~
 221
 222    Hash table used to memoize results from [[#data][~org-export-data~]].
 223
 224    - category :: tree
 225    - type :: hash table
 226
 227 ** ~:filetags~
 228
 229    List of global tags for buffer.  Used by [[#get-tags][~org-export-get-tags~]] to
 230    get tags with inheritance.
 231
 232    - category :: option
 233    - type :: list of strings
 234
 235 ** ~:headline-levels~
 236    :PROPERTIES:
 237    :CUSTOM_ID: headline-levels
 238    :END:
 239
 240    Maximum level being exported as an headline.  Comparison is done
 241    with the relative level of headlines in the parse tree, not
 242    necessarily with their actual level.
 243
 244    - category :: option
 245    - type :: integer
 246
 247 ** ~:headline-numbering~
 248
 249    Alist between headlines' beginning position and their numbering, as
 250    a list of numbers – cf. [[#get-headline-number][~org-export-get-headline-number~]].
 251
 252    - category :: tree
 253    - type :: alist (INTEGER . LIST)
 254
 255 ** ~:headline-offset~
 256
 257    Difference between relative and real level of headlines in the
 258    parse tree.  For example, a value of -1 means a level 2 headline
 259    should be considered as level 1 —
 260    cf. [[#get-relative-level][~org-export-get-relative-level~]].
 261
 262    - category :: tree
 263    - type :: integer
 264
 265 ** ~:ignore-list~
 266
 267    List of elements and objects that will be unconditionally ignored
 268    during export.
 269
 270    - category :: option
 271    - type :: list of elements
 272
 273 ** ~:id-alist~
 274
 275    Alist between ID strings and destination file's path, relative to
 276    current directory.
 277
 278    - category :: option
 279    - type :: alist (STRING . STRING)
 280
 281 ** ~:input-buffer~
 282
 283    Original buffer name.
 284
 285    - category :: option
 286    - type :: string
 287
 288 ** ~:input-file~
 289
 290    Full path to input file, if any.
 291
 292    - category :: option
 293    - type :: string or nil
 294
 295 ** ~:keywords~
 296
 297    List of keywords attached to data.
 298
 299    - category :: option
 300    - type :: string
 301
 302 ** ~:language~
 303
 304    Default language used for translations.
 305
 306    - category :: option
 307    - type :: string
 308
 309 ** ~:output-file~
 310
 311    Full path to output file, if any.
 312
 313    - category :: option
 314    - type :: string or nil
 315
 316 ** ~:parse-tree~
 317
 318    Whole parse tree, available at any time during transcoding.
 319
 320    - category :: option
 321    - type :: list (as returned by ~org-element-parse-buffer~)
 322
 323 ** ~:preserve-breaks~
 324
 325    Non-nil means transcoding should preserve all line breaks.
 326
 327    - category :: option
 328    - type :: symbol (nil, t)
 329
 330 ** ~:section-numbers~
 331
 332    Non-nil means transcoding should add section numbers to headlines.
 333
 334    - category :: option
 335    - type :: symbol (nil, t)
 336
 337 ** ~:select-tags~
 338    :PROPERTIES:
 339    :CUSTOM_ID: select-tags
 340    :END:
 341
 342    List of tags enforcing inclusion of sub-trees in transcoding.  When
 343    such a tag is present, sub-trees without it are /de facto/ excluded
 344    from the process.  See [[#use-select-tags][~:use-select-tags~]].
 345
 346    - category :: option
 347    - type :: list of strings
 348
 349 ** ~:time-stamp-file~
 350
 351    Non-nil means transcoding should insert a time stamp in the output.
 352
 353    - category :: option
 354    - type :: symbol (nil, t)
 355
 356 ** ~:translate-alist~
 357
 358    Alist between element and object types and transcoding functions
 359    relative to the current back-end.  Special keys ~template~ and
 360    ~plain-text~ are also possible.
 361
 362    - category :: option
 363    - type :: alist (SYMBOL . FUNCTION)
 364
 365 ** ~:use-select-tags~
 366    :PROPERTIES:
 367    :CUSTOM_ID: use-select-tags
 368    :END:
 369
 370    When non-nil, a select tags has been found in the parse tree.
 371    Thus, any headline without one will be filtered out.  See
 372    [[#select-tags][~:select-tags~]].
 373
 374    - category :: tree
 375    - type :: integer or nil
 376
 377 ** ~:with-archived-trees~
 378
 379    Non-nil when archived sub-trees should also be transcoded.  If it
 380    is set to the ~headline~ symbol, only the archived headline's name
 381    is retained.
 382
 383    - category :: option
 384    - type :: symbol (nil, t, ~headline~)
 385
 386 ** ~:with-author~
 387
 388    Non-nil means author's name should be included in the output.
 389
 390    - category :: option
 391    - type :: symbol (nil, t)
 392
 393 ** ~:with-clocks~
 394
 395    Non-nil means clock keywords should be exported.
 396
 397    - category :: option
 398    - type :: symbol (nil, t)
 399
 400 ** ~:with-creator~
 401
 402    Non-nil means a creation sentence should be inserted at the end of
 403    the transcoded string.  If the value is ~comment~, it should be
 404    commented.
 405
 406    - category :: option
 407    - type :: symbol (~comment~, nil, t)
 408
 409 ** ~:with-date~
 410
 411    Non nil means output should contain a date.
 412
 413    - category :: option
 414    - type :: symbol (nil, t)
 415
 416 ** ~:with-drawers~
 417
 418    Non-nil means drawers should be exported.  If its value is a list
 419    of names, only drawers with such names will be transcoded.
 420
 421    - category :: option
 422    - type :: symbol (nil, t) or list of strings
 423
 424 ** ~:with-email~
 425
 426    Non-nil means output should contain author's email.
 427
 428    - category :: option
 429    - type :: symbol (nil, t)
 430
 431 ** ~:with-emphasize~
 432
 433    Non-nil means emphasized text should be interpreted.
 434
 435    - category :: option
 436    - type :: symbol (nil, t)
 437
 438 ** ~:with-fixed-width~
 439
 440    Non-nil if transcoder should interpret strings starting with
 441    a colon as a fixed-with — verbatim — area.
 442
 443    - category :: option
 444    - type :: symbol (nil, t)
 445
 446 ** ~:with-footnotes~
 447
 448    Non-nil if transcoder should interpret footnotes.
 449
 450    - category :: option
 451    - type :: symbol (nil, t)
 452
 453 ** ~:with-latex~
 454
 455    Non-nil means ~latex-environment~ elements and ~latex-fragment~
 456    objects should appear in export output.  When this property is set
 457    to ~verbatim~, they will be left as-is.
 458
 459    - category :: option
 460    - type :: symbol (~verbatim~, nil, t)
 461
 462 ** ~:with-planning~
 463
 464    Non-nil means transcoding should include planning info.
 465
 466    - category :: option
 467    - type :: symbol (nil, t)
 468
 469 ** ~:with-priority~
 470
 471    Non-nil means transcoding should include priority cookies.
 472
 473    - category :: option
 474    - type :: symbol (nil, t)
 475
 476 ** ~:with-smart-quotes~
 477
 478    Non-nil means activate smart quotes during export.
 479
 480    - category :: option
 481    - type :: symbol (nil ,t)
 482
 483 ** ~:with-special-strings~
 484
 485    Non-nil means transcoding should interpret special strings in plain
 486    text.
 487
 488    - category :: option
 489    - type :: symbol (nil, t)
 490
 491 ** ~:with-sub-superscript~
 492
 493    Non-nil means transcoding should interpret subscript and
 494    superscript.  With a value of ~{}~, only interpret those using
 495    curly brackets.
 496
 497    - category :: option
 498    - type :: symbol (nil, ~{}~, t)
 499
 500 ** ~:with-tables~
 501
 502    Non-nil means transcoding should interpret tables.
 503
 504    - category :: option
 505    - type :: symbol (nil, t)
 506
 507 ** ~:with-tags~
 508
 509    Non-nil means transcoding should keep tags in headlines.
 510    A ~not-in-toc~ value will remove them from the table of contents,
 511    if any, nonetheless.
 512
 513    - category :: option
 514    - type :: symbol (nil, t, ~not-in-toc~)
 515
 516 ** ~:with-tasks~
 517
 518    Non-nil means transcoding should include headlines with a TODO
 519    keyword.  A ~todo~ value will only include headlines with a TODO
 520    type keyword while a ~done~ value will do the contrary.  If a list
 521    of strings is provided, only tasks with keywords belonging to that
 522    list will be kept.
 523
 524    - category :: option
 525    - type :: symbol (t, ~todo~, ~done~, nil) or list of strings
 526
 527 ** ~:with-timestamps~
 528
 529    Non-nil means transcoding should include time stamps.  Special
 530    value ~active~ (resp. ~inactive~) ask to export only active
 531    (resp. inactive) timestamps.  Otherwise, completely remove them.
 532
 533    - category :: option
 534    - type :: symbol: (~active~, ~inactive~, t, nil)
 535
 536 ** ~:with-toc~
 537
 538    Non-nil means that a table of contents has to be added to the
 539    output.  An integer value limits its depth.
 540
 541    - category :: option
 542    - type :: symbol (nil, t or integer)
 543
 544 ** ~:with-todo-keywords~
 545
 546    Non-nil means transcoding should include TODO keywords.
 547
 548    - category :: option
 549    - type :: symbol (nil, t)
 550
 551 * The Filter System
 552   :PROPERTIES:
 553   :CUSTOM_ID: filter-system
 554   :END:
 555
 556   Filters sets are lists of functions.  They allow to alter parse tree
 557   before export and to post-process output of each transcoded object
 558   or element.
 559
 560   Each function in a set must accept three arguments: a string (or
 561   a parse tree as a special case), a symbol representing the current
 562   back-end, and the communication channel, as a plist.
 563
 564   As an exception, functions in options filter only accept two
 565   arguments: the property list containing the export options and the
 566   back-end, as a symbol.
 567
 568   From the developer side, filters sets can be installed using
 569   ~:filters-alist~ keyword while defining the back-end with
 570   ~org-export-define-derived-backend~.  Each association has a key
 571   among the following symbols and a function or a list of functions as
 572   value:
 573
 574   - ~:filter-babel-call~
 575   - ~:filter-bold~
 576   - ~:filter-center-block~
 577   - ~:filter-clock~
 578   - ~:filter-code~
 579   - ~:filter-drawer~
 580   - ~:filter-dynamic-block~
 581   - ~:filter-entity~
 582   - ~:filter-example-block~
 583   - ~:filter-export-block~
 584   - ~:filter-export-snippet~
 585   - ~:filter-final-output~
 586   - ~:filter-fixed-width~
 587   - ~:filter-footnote-definition~
 588   - ~:filter-footnote-reference~
 589   - ~:filter-headline~
 590   - ~:filter-horizontal-rule~
 591   - ~:filter-inline-babel-call~
 592   - ~:filter-inline-src-block~
 593   - ~:filter-inlinetask~
 594   - ~:filter-italic~
 595   - ~:filter-item~
 596   - ~:filter-keyword~
 597   - ~:filter-latex-environment~
 598   - ~:filter-latex-fragment~
 599   - ~:filter-line-break~
 600   - ~:filter-link~
 601   - ~:filter-node-property~
 602   - ~:filter-options~
 603   - ~:filter-paragraph~
 604   - ~:filter-parse-tree~
 605   - ~:filter-plain-list~
 606   - ~:filter-plain-text~
 607   - ~:filter-planning~
 608   - ~:filter-property-drawer~
 609   - ~:filter-quote-block~
 610   - ~:filter-quote-section~
 611   - ~:filter-radio-target~
 612   - ~:filter-section~
 613   - ~:filter-special-block~
 614   - ~:filter-src-block~
 615   - ~:filter-strike-through~
 616   - ~:filter-statistics-cookie~
 617   - ~:filter-subscript~
 618   - ~:filter-superscript~
 619   - ~:filter-table~
 620   - ~:filter-table-cell~
 621   - ~:filter-table-row~
 622   - ~:filter-target~
 623   - ~:filter-timestamp~
 624   - ~:filter-underline~
 625   - ~:filter-verbatim~
 626   - ~:filter-verse-block~
 627
 628
 629   For example, ~ascii~ back-end implements a filter that makes sure
 630   headlines end with two blank lines:
 631
 632   #+BEGIN_SRC emacs-lisp
 633   (org-export-define-backend 'ascii
 634     ...
 635     :filters-alist '((:filter-headline . org-ascii-filter-headline-blank-lines)
 636                      (:filter-section . org-ascii-filter-headline-blank-lines)))
 637
 638   (defun org-ascii-filter-section-blank-lines (headline back-end info)
 639     "Filter controlling number of blank lines after a section."
 640     (let ((blanks (make-string 2 ?\n)))
 641       (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" blanks headline)))
 642   #+END_SRC
 643
 644 * The Toolbox
 645   :PROPERTIES:
 646   :CUSTOM_ID: toolbox
 647   :END:
 648
 649   A whole set of tools is available to help build new exporters.  Any
 650   function general enough to have its use across a couple of back-ends
 651   may be added here.
 652
 653   Many of them are high-level access to properties from the
 654   communication channel.  As such, they should be preferred to
 655   straight access to communication channel, when possible.
 656
 657 ** ~org-export-activate-smart-quotes~
 658    :PROPERTIES:
 659    :CUSTOM_ID: activate-smart-quotes
 660    :END:
 661
 662    Transform quotes and apostrophes into their "smart" counterpart in
 663    a given string.
 664
 665    It should be used after a check against ~:with-smart-quotes~ value
 666    in communication channel.
 667
 668    Since this function needs the original string, it may be useful to
 669    apply others transformations (i.e. characters protection) on a copy
 670    of that string and provide the pristine original string as the
 671    optional argument.
 672
 673    For example, in ~html~ back-end, it is necessary to protect "<",
 674    ">" and "&" characters before calling this function.  Here's an
 675    excerpt of its ~plain-text~ transcoder:
 676
 677    #+BEGIN_SRC emacs-lisp
 678    (let ((output text))
 679      ;; Protect following characters: <, >, &.
 680      (setq output (org-html-encode-plain-text output))
 681      ;; Handle smart quotes.  Be sure to provide original string since
 682      ;; OUTPUT may have been modified.
 683      (when (plist-get info :with-smart-quotes)
 684        (setq output (org-export-activate-smart-quotes output :html info text)))
 685      ...
 686      ;; Return value.
 687      output)
 688    #+END_SRC
 689
 690 ** ~org-export-collect-figures~
 691    :PROPERTIES:
 692    :CUSTOM_ID: collect-figures
 693    :END:
 694
 695    Return a list of all exportable figures in parse tree.
 696
 697    Used to build a table of figures.
 698
 699    See also: [[#collect-headlines][~org-export-collect-headlines~]],
 700    [[#collect-tables][~org-export-collect-tables~]], [[#collect-listings][~org-export-collect-listings~]].
 701
 702 ** ~org-export-collect-footnote-definitions~
 703    :PROPERTIES:
 704    :CUSTOM_ID: collect-footnote-definitions
 705    :END:
 706
 707    List actually used footnotes definitions in order to add footnote
 708    listings throughout the transcoded data.
 709
 710    Feed it with the whole parse tree to get the full footnote listing.
 711    Feed it with the current headline to get partial footnote listing
 712    relative to that headline.
 713
 714    Number, label, if any, and definition are provided.
 715
 716    See also: [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
 717    [[#get-footnote-definition][~org-export-get-footnote-definition~]],
 718    [[#get-footnote-number][~org-export-get-footnote-number~]].
 719
 720 ** ~org-export-collect-headlines~
 721    :PROPERTIES:
 722    :CUSTOM_ID: collect-headlines
 723    :END:
 724
 725    Return a list of all exportable headlines, possibly limited to
 726    a certain depth.
 727
 728    Used to build a table of contents, e.g., when a "#+TOC: headlines
 729    2" keyword value pair is specified.
 730
 731    See also: [[#collect-tables][~org-export-collect-tables~]],
 732    [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]],
 733    [[#excluded-from-toc-p][~org-export-excluded-from-toc-p~]].
 734
 735 ** ~org-export-collect-listings~
 736    :PROPERTIES:
 737    :CUSTOM_ID: collect-listings
 738    :END:
 739
 740    Return a list of all exportable source blocks with a caption or
 741    a name in parse tree.
 742
 743    Used to build a table of listings, e.g., when a "#+TOC: listings"
 744    keyword value pair is specified.
 745
 746    See also: [[#collect-headlines][~org-export-collect-headlines~]],
 747    [[#collect-tables][~org-export-collect-tables~]], [[#collect-figures][~org-export-collect-figures~]].
 748
 749 ** ~org-export-collect-tables~
 750    :PROPERTIES:
 751    :CUSTOM_ID: collect-tables
 752    :END:
 753
 754    Return a list of all exportable tables with a caption or a name in
 755    parse tree.
 756
 757    Used to build a table of tables, e.g., when a "#+TOC: tables"
 758    keyword value pair is specified.
 759
 760    See also: [[#collect-headlines][~org-export-collect-headlines~]],
 761    [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]].
 762
 763 ** ~org-export-data~
 764    :PROPERTIES:
 765    :CUSTOM_ID: data
 766    :END:
 767
 768    Transcode a given element, object, secondary string or string using
 769    current back-end.
 770
 771    It is used primarily to transcode secondary strings, like ~:title~.
 772    For example ~beamer~ back-end uses the following:
 773
 774    #+BEGIN_SRC emacs-lisp
 775    (defun org-beamer-template (contents info)
 776      (let ((title (org-export-data (plist-get info :title) info)))
 777        ...))
 778    #+END_SRC
 779
 780 ** ~org-export-data-with-backend~
 781    :PROPERTIES:
 782    :CUSTOM_ID: data-with-backend
 783    :END:
 784
 785    Recursively convert some data (an element, an object, a secondary
 786    string or a string) using another backend.
 787
 788    See also: [[#with-backend][~org-export-with-backend~]],
 789    [[#toc-entry-backend][~org-export-toc-entry-backend~]].
 790
 791 ** ~org-export-excluded-from-toc-p~
 792 :PROPERTIES:
 793 :CUSTOM_ID: excluded-from-toc-p
 794 :END:
 795
 796 Non-nil if a headline must not appear in a table of contents.
 797
 798 See also : [[#collect-headlines][~org-export-collect-headlines~]].
 799
 800 ** ~org-export-file-uri~
 801    :PROPERTIES:
 802    :CUSTOM_ID: file-uri
 803    :END:
 804
 805    Return URI associated to a given filename.
 806
 807 ** ~org-export-first-sibling-p~
 808    :PROPERTIES:
 809    :CUSTOM_ID: first-sibling-p
 810    :END:
 811
 812    Non-nil if an element or object is the first of its siblings.
 813
 814    It may be used to know when to start a list if headline's relative
 815    level is below the one specified in [[#headline-levels][~:headline-levels~]] property.
 816
 817    See also: [[#get-relative-level][~org-export-get-relative-level~]],
 818    [[#number-to-roman][~org-export-number-to-roman~]], [[#last-sibling-p][~org-export-last-sibling-p~]].
 819
 820 ** ~org-export-footnote-first-reference-p~
 821    :PROPERTIES:
 822    :CUSTOM_ID: footnote-first-reference-p
 823    :END:
 824
 825    Non-nil when a footnote reference if the first reference relative
 826    to its definition.
 827
 828    Used when a back-end needs to attach the footnote definition only
 829    to the first occurrence of the corresponding label.
 830
 831    Its scope can be arbitrary narrowed, e.g., to a headline.
 832
 833    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
 834    [[#get-footnote-definition][~org-export-get-footnote-definition~]],
 835    [[#get-footnote-number][~org-export-get-footnote-number~]].
 836
 837 ** ~org-export-format-code~
 838    :PROPERTIES:
 839    :CUSTOM_ID: format-code
 840    :END:
 841
 842    Helper function to format source code.  It applies a given function
 843    on each line of the code, passing current line number and
 844    associated code reference label, if any, as arguments.
 845
 846    See also: [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]],
 847    [[#unravel-code][~org-export-unravel-code~]].
 848
 849 ** ~org-export-format-code-default~
 850    :PROPERTIES:
 851    :CUSTOM_ID: format-code-default
 852    :END:
 853
 854    Return contents of a =src-block= or =example-block= element in
 855    a format suited for raw text or verbatim output.  More
 856    specifically, it takes care of line numbering and labels
 857    integration depending of element's switches, but no formatting is
 858    otherwise applied to source code.
 859
 860    See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
 861
 862 ** ~org-export-get-alt-title~
 863    :PROPERTIES:
 864    :CUSTOM_ID: get-alt-title
 865    :END:
 866
 867    Return the alternative title for a given headline as a secondary
 868    string.  If no such title is found, it will return its main title.
 869
 870    This function is useful when building a table of contents.
 871
 872 ** ~org-export-get-caption~
 873    :PROPERTIES:
 874    :CUSTOM_ID: get-caption
 875    :END:
 876
 877    Return the caption of a given element, as a secondary string.  With
 878    an optional argument, return the short caption instead.
 879
 880    As an example, ~ascii~ back-end, when creating a list of listings,
 881    uses the following:
 882
 883    #+BEGIN_SRC emacs-lisp
 884    (defun org-ascii--list-listings (keyword info)
 885      (let ((title (org-ascii--translate "List of Listings" info)))
 886        (concat title "\n"
 887                ...
 888                (mapconcat
 889                 (lambda (src-block)
 890                   ...
 891                   ;; Use short name in priority, if available.
 892                   (let ((caption (or (org-export-get-caption src-block t)
 893                                      (org-export-get-caption src-block))))
 894                     (org-export-data caption info)
 895                     ...))
 896                 (org-export-collect-listings info) "\n"))))
 897    #+END_SRC
 898
 899    See also: [[#read-attribute][~org-export-read-attribute~]].
 900
 901 ** ~org-export-get-category~
 902    :PROPERTIES:
 903    :CUSTOM_ID: get-category
 904    :END:
 905
 906    Return category associated to a given element or object.  Unlike to
 907    the ~:category~ property from headlines and inlinetasks, this
 908    function handles inheritance and ~CATEGORY~ keywords.  Therefore,
 909    it should be the preferred way to retrieve a category during
 910    export.
 911
 912    See also: [[#get-node-property][~org-export-get-node-property~]].
 913
 914 ** ~org-export-get-coderef-format~
 915    :PROPERTIES:
 916    :CUSTOM_ID: get-coderef-format
 917    :END:
 918
 919    Return an appropriate format string for code reference links.
 920
 921    See also: [[#resolve-coderef][~org-export-resolve-coderef~]].
 922
 923 ** ~org-export-get-date~
 924    :PROPERTIES:
 925    :CUSTOM_ID: get-date
 926    :END:
 927
 928    Returns a date, as a string or a secondary string.  It handles
 929    ~org-export-date-timestamp-format~.
 930
 931    Note that ~:with-date~ property in [[#communication][communication channel]] should be
 932    checked prior to use this, as shown in the following example
 933    extracted from ~ox-latex.el~:
 934
 935    #+BEGIN_SRC emacs-lisp :exports code
 936    (let ((date (and (plist-get info :with-date) (org-export-get-date info))))
 937      (format "\\date{%s}\n" (org-export-data date info)))
 938    #+END_SRC
 939
 940 ** ~org-export-get-footnote-definition~
 941    :PROPERTIES:
 942    :CUSTOM_ID: get-footnote-definition
 943    :END:
 944
 945    Retrieve the footnote definition relative to a given footnote
 946    reference.
 947
 948    If the footnote definition in inline, it is returned as a secondary
 949    string.  Otherwise, it is full Org data.
 950
 951    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
 952    [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
 953    [[#get-footnote-number][~org-export-get-footnote-number~]].
 954
 955 ** ~org-export-get-footnote-number~
 956    :PROPERTIES:
 957    :CUSTOM_ID: get-footnote-number
 958    :END:
 959
 960    Return the ordinal attached to a footnote reference or definition.
 961
 962    Its scope can be arbitrary narrowed, e.g., to get the numbering
 963    relative to a headline.
 964
 965    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
 966    [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
 967    [[#get-footnote-definition][~org-export-get-footnote-definition~]].
 968
 969 ** ~org-export-get-headline-number~
 970    :PROPERTIES:
 971    :CUSTOM_ID: get-headline-number
 972    :END:
 973
 974    Return the section number of an headline, as a list of integers.
 975
 976    See also: [[#headline-numbered-p][~org-export-headline-numbered-p~]],
 977    [[#number-to-roman][~org-export-number-to-roman~]].
 978
 979 ** ~org-export-get-loc~
 980    :PROPERTIES:
 981    :CUSTOM_ID: get-loc
 982    :END:
 983
 984    Return count of accumulated lines of code from previous
 985    line-numbered =example-block= and =src-block= elements, according
 986    to current element's switches.
 987
 988    In other words, the first line of code in the current block is
 989    supposed to be numbered as the returned value plus one, assuming
 990    its ~:number-lines~ properties is non-nil.
 991
 992    See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
 993
 994 ** ~org-export-get-next-element~
 995    :PROPERTIES:
 996    :CUSTOM_ID: get-next-element
 997    :END:
 998
 999    Return element (resp. object or string) after an element
1000    (resp. object), or nil.
1001
1002    See also: [[#get-parent][~org-export-get-parent~]],
1003    [[#get-parent-headline][~org-export-get-parent-headline~]],
1004    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1005    [[#get-previous-element][~org-export-get-previous-element~]].
1006
1007 ** ~org-export-get-node-property~
1008    :PROPERTIES:
1009    :CUSTOM_ID: get-node-property
1010    :END:
1011
1012    Return the node property associated to an element or object.  If
1013    the element is an headline, this is equivalent to reading the
1014    property with ~org-element-property~.
1015
1016    Though, this function can optionally handle inheritance.
1017
1018    See also: [[#get-category][~org-export-get-category~]].
1019
1020 ** ~org-export-get-ordinal~
1021    :PROPERTIES:
1022    :CUSTOM_ID: get-ordinal
1023    :END:
1024
1025    Associate a sequence number to any object or element.  It is meant
1026    to be used to build captions.
1027
1028    Also, it could be applied on a fuzzy link's destination, since such
1029    links are expected to be replaced with the sequence number of their
1030    destination, provided they have no description.
1031
1032    Taken from ~ascii~ back-end, the following example shows how fuzzy
1033    links could be handled :
1034
1035    #+BEGIN_SRC emacs-lisp :exports code
1036    (let ((type (org-element-property :type link)))
1037      (cond
1038       ...
1039       ;; Do not apply a special syntax on fuzzy links pointing to targets.
1040       ((string= type "fuzzy")
1041        (let ((destination (org-export-resolve-fuzzy-link link info)))
1042          ;; If link has a description, use it.
1043          (if (org-string-nw-p desc) desc
1044            (when destination
1045              (let ((number (org-export-get-ordinal destination info)))
1046                (when number
1047                  (if (atom number) (number-to-string number)
1048                    (mapconcat 'number-to-string number "."))))))))
1049       ...))
1050    #+END_SRC
1051
1052    See also : [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]]
1053
1054 ** ~org-export-get-parent~
1055    :PROPERTIES:
1056    :CUSTOM_ID: get-parent
1057    :END:
1058
1059    Return closest element containing current element or object, if
1060    any.  Return nil otherwise.
1061
1062    See also: [[#get-next-element][~org-export-get-next-element~]],
1063    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1064    [[#get-parent-headline][~org-export-get-parent-headline~]],
1065    [[#get-previous-element][~org-export-get-previous-element~]].
1066
1067 ** ~org-export-get-parent-element~
1068    :PROPERTIES:
1069    :CUSTOM_ID: get-parent-paragraph
1070    :END:
1071
1072    Return the first element containing provided object, if any.
1073    Return nil otherwise.
1074
1075    See also: [[#get-parent][~org-export-get-parent~]],
1076    [[#get-parent-headline][~org-export-get-parent-headline~]],
1077    [[#get-previous-element][~org-export-get-previous-element~]], [[#get-next-element][~org-export-get-next-element~]].
1078
1079 ** ~org-export-get-parent-headline~
1080    :PROPERTIES:
1081    :CUSTOM_ID: get-parent-headline
1082    :END:
1083
1084    Return the headline containing provided element or object, if any.
1085    Return nil otherwise.
1086
1087    See also: [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1088    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1089    [[#get-previous-element][~org-export-get-previous-element~]].
1090
1091 ** ~org-export-get-previous-element~
1092    :PROPERTIES:
1093    :CUSTOM_ID: get-previous-element
1094    :END:
1095
1096    Return element (resp. object or string) before an element
1097    (resp. object), or nil.
1098
1099    See also: [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1100    [[#get-parent-headline][~org-export-get-parent-headline~]],
1101    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]].
1102
1103 ** ~org-export-get-reference~
1104    :PROPERTIES:
1105    :CUSTOM_ID: get-reference
1106    :END:
1107
1108    Return unique reference associated to an element or an object, as
1109    a string.
1110
1111    Since it consists of alphanumerical characters only, it can be used
1112    as internal references for back-ends needing them.
1113
1114    For example, =ox-latex.el= uses it to translate radio targets into
1115    ~\label{}~ and links to radio targets into ~\hyperref{}~:
1116
1117    #+BEGIN_SRC emacs-lisp
1118    (defun org-latex-radio-target (radio-target text info)
1119      (format "\\label{%s}%s" (org-export-get-reference radio-target info) text))
1120
1121    (defun org-latex-link (link desc info)
1122      (let ((type (org-element-property :type link)))
1123        (cond
1124         ...
1125         ((string= type "radio")
1126          (let ((destination (org-export-resolve-radio-link link info)))
1127            (if (not destination) desc
1128              (format "\\hyperref[%s]{%s}"
1129                      (org-export-get-reference destination info)
1130                      desc))))
1131         ...)))
1132    #+END_SRC
1133
1134    See also: [[#inline-image-p][~org-export-inline-image-p~]],
1135    [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]],
1136    [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1137
1138 ** ~org-export-get-relative-level~
1139    :PROPERTIES:
1140    :CUSTOM_ID: get-relative-level
1141    :END:
1142
1143    Return headline level, relatively to the lower headline level in
1144    the parsed tree.  It is meant to be used over ~:level~ headline's
1145    property.
1146
1147    See also:[[#first-sibling-p][~org-export-first-sibling-p~]],
1148     [[#get-headline-number][~org-export-get-headline-number~]],[[#headline-numbered-p][~org-export-headline-numbered-p~]],
1149     [[#last-sibling-p][~org-export-last-sibling-p~]].
1150
1151 ** ~org-export-get-table-cell-at~
1152    :PROPERTIES:
1153    :CUSTOM_ID: get-table-cell-at
1154    :END:
1155
1156    Return exportable cell object at a given position, or nil.  Hence,
1157    position ~(0 . 0)~ will always point to the first exportable cell
1158    in the table.
1159
1160    See also: [[#table-cell-address][~org-export-table-cell-address~]],
1161    [[#table-dimensions][~org-export-table-dimensions~]].
1162
1163 ** ~org-export-get-tags~
1164    :PROPERTIES:
1165    :CUSTOM_ID: get-tags
1166    :END:
1167
1168    Return list of exportable tags attached to a given headline or
1169    inlinetask element.  With an optional argument, tags are inherited
1170    from parent headlines and ~FILETAGS~ keywords.
1171
1172    In particular, it removes select tags and exclude tags. The
1173    function also accepts an arbitrary list of tags for further
1174    cleaning.
1175
1176    For example, ~latex~ back-end uses the following snippet in the
1177    inlinetask transcode function.
1178
1179    #+BEGIN_SRC emacs-lisp
1180    (let ((title (org-export-data (org-element-property :title inlinetask) info))
1181       (todo (and (plist-get info :with-todo-keywords)
1182                  (let ((todo (org-element-property :todo-keyword inlinetask)))
1183                    (and todo (org-export-data todo info)))))
1184       (todo-type (org-element-property :todo-type inlinetask))
1185       (tags (and (plist-get info :with-tags)
1186                  (org-export-get-tags inlinetask info)))
1187       (priority (and (plist-get info :with-priority)
1188                      (org-element-property :priority inlinetask))))
1189   ...)
1190    #+END_SRC
1191
1192 ** ~org-export-headline-numbered-p~
1193    :PROPERTIES:
1194    :CUSTOM_ID: headline-numbered-p
1195    :END:
1196
1197    Non nil when a given headline should be numbered.
1198
1199    See also: [[#get-headline-number][~org-export-get-headline-number~]],
1200    [[#get-relative-level][~org-export-get-relative-level~]].
1201
1202 ** ~org-export-inline-image-p~
1203    :PROPERTIES:
1204    :CUSTOM_ID: inline-image-p
1205    :END:
1206
1207    Non-nil when the link provided should be considered as an inline
1208    image.  Note that it always return nil when the link has
1209    a description.
1210
1211    It accepts an optional set of rules in order to tweak the
1212    definition of an inline image, which is, by default, any link
1213    targeting a local file whose extension is either "png", "jpeg",
1214    "jpg", "gif", "tiff", "tif", "xbm", "xpm", "pbm", "pgm" or "ppm".
1215
1216    A set of rules consists in an alist whose key is a type of link, as
1217    a string, and whose value is a regexp matching link's path.  As an
1218    example, ~html~ back-end uses the following rules:
1219
1220    #+BEGIN_SRC emacs-lisp
1221    '(("file" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1222      ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1223      ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'"))
1224    #+END_SRC
1225
1226    See also: [[#get-reference][~org-export-get-reference~]],
1227    [[#get-coderef-format][~org-export-get-coderef-format~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]].
1228
1229 ** ~org-export-last-sibling-p~
1230    :PROPERTIES:
1231    :CUSTOM_ID: last-sibling-p
1232    :END:
1233
1234    Non-nil if an element or object is the last of its siblings.
1235
1236    It may be used to know when to close a list if headline's relative
1237    level is below the one specified in [[#headline-levels][~:headline-levels~]] property.
1238
1239    See also: [[#get-relative-level][~org-export-get-relative-level~]],
1240    [[#number-to-roman][~org-export-number-to-roman~]], [[#first-sibling-p][~org-export-first-sibling-p~]].
1241
1242 ** ~org-export-number-to-roman~
1243    :PROPERTIES:
1244    :CUSTOM_ID: number-to-roman
1245    :END:
1246
1247    Convert numbers to roman numbers. It can be used to provide roman
1248    numbering for headlines and numbered lists.
1249
1250    See also: [[#get-headline-number][~org-export-get-headline-number~]].
1251
1252 ** ~org-export-read-attribute~
1253    :PROPERTIES:
1254    :CUSTOM_ID: read-attribute
1255    :END:
1256
1257    Read a property from a given element as a plist.  It can be used to
1258    normalize affiliated keywords' syntax.  For example, the following
1259    affiliated keywords:
1260
1261    #+BEGIN_SRC org
1262    ,#+ATTR_HTML: :width 10 :height 5
1263    ,#+ATTR_HTML: :file filename.ext
1264    #+END_SRC
1265
1266    would be returned as:
1267
1268    #+BEGIN_SRC emacs-lisp
1269    '(:width "10" :height "5" :file "filename.ext")
1270    #+END_SRC
1271
1272    See also: [[#get-caption][~org-export-get-caption~]].
1273
1274 ** ~org-export-resolve-coderef~
1275    :PROPERTIES:
1276    :CUSTOM_ID: resolve-coderef
1277    :END:
1278
1279    Search for a code reference within ~src-block~ and ~example-block~
1280    elements.  Return corresponding --possibly accumulated-- line
1281    number, or reference itself, depending on container's switches.
1282
1283    See also : [[#get-coderef-format][~org-export-get-coderef-format~]],
1284    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1285    [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1286
1287 ** ~org-export-resolve-fuzzy-link~
1288    :PROPERTIES:
1289    :CUSTOM_ID: resolve-fuzzy-link
1290    :END:
1291
1292    Search destination of a fuzzy link — i.e. it has a ~fuzzy~ ~:type~
1293    attribute – within the parsed tree, and return that element or
1294    object.
1295
1296    See also: [[#get-ordinal][~org-export-get-ordinal~]], [[#resolve-coderef][~org-export-resolve-coderef~]],
1297    [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1298    [[#get-reference][~org-export-get-reference~]].
1299
1300 ** ~org-export-resolve-id-link~
1301    :PROPERTIES:
1302    :CUSTOM_ID: resolve-id-link
1303    :END:
1304
1305    Search headline targeted by an id link --- i.e. it has a ~id~ or
1306    ~custom-id~ ~:type~ attribute --- within the parse tree.  Return
1307    the matching headline in the tree, the name of the external file,
1308    as a string.
1309
1310    See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1311    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1312    [[#get-reference][~org-export-get-reference~]].
1313
1314 ** ~org-export-resolve-radio-link~
1315    :PROPERTIES:
1316    :CUSTOM_ID: resolve-radio-link
1317    :END:
1318
1319    Return first radio target object matching a radio link --- that is
1320    with a ~radio~ ~:type~ attribute --- in the parse tree, or nil.
1321
1322    Typically, target's contents are exported through ~org-export-data~
1323    and used as link description, as in the following excerpt from
1324    =ox-latex.el=:
1325
1326    #+BEGIN_SRC emacs-lisp
1327    (defun org-latex-link (link desc info)
1328      (let* ((type (org-element-property :type link))
1329             ...)
1330        (cond
1331         ...
1332         ((string= type "radio")
1333          (let ((destination (org-export-resolve-radio-link link info)))
1334            (when destination
1335              (format "\\hyperref[%s]{%s}"
1336                      (org-export-get-reference destination info)
1337                      (org-export-data (org-element-contents destination) info)))))
1338         ...)))
1339    #+END_SRC
1340
1341    See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1342    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1343    [[#get-reference][~org-export-get-reference~]].
1344
1345 ** ~org-export-table-cell-address~
1346    :PROPERTIES:
1347    :CUSTOM_ID: table-cell-address
1348    :END:
1349
1350    Return row and column of a given cell object.  Positions are
1351    0-indexed and only exportable rows and columns are considered.  The
1352    function returns nil if called on a non-exportable cell.
1353
1354    See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
1355    [[#table-dimensions][~org-export-table-dimensions~]].
1356
1357 ** ~org-export-table-cell-alignment~
1358    :PROPERTIES:
1359    :CUSTOM_ID: table-cell-alignment
1360    :END:
1361
1362    Return expected alignment for the contents of a given cell object.
1363    It can be either ~left~, ~right~ or ~center~.
1364
1365    See also: [[#table-cell-borders][~org-export-table-cell-borders~]],
1366    [[#table-cell-width][~org-export-table-cell-width~]].
1367
1368 ** ~org-export-table-cell-borders~
1369    :PROPERTIES:
1370    :CUSTOM_ID: table-cell-borders
1371    :END:
1372
1373    Indicate expected borders for a given cell object.  When non-nil,
1374    return value is a list of symbols among ~top~, ~bottom~, ~above~,
1375    ~below~, ~left~ and ~right~.
1376
1377    Special values ~top~ and ~bottom~ only happen for cells in,
1378    respectively, the first and the last exportable rows.
1379
1380    See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
1381    [[#table-cell-width][~org-export-table-cell-width~]].
1382
1383 ** ~org-export-table-cell-ends-colgroup-p~
1384    :PROPERTIES:
1385    :CUSTOM_ID: table-cell-ends-colgroup-p
1386    :END:
1387
1388    Non-nil when a table cell object ends a column group.
1389
1390    See also: [[#table-cell-starts-colgroup-p][~org-export-table-cell-starts-colgroup-p~]].
1391
1392 ** ~org-export-table-cell-starts-colgroup-p~
1393    :PROPERTIES:
1394    :CUSTOM_ID: table-cell-starts-colgroup-p
1395    :END:
1396
1397    Non-nil when a table cell object starts a column group.
1398
1399    See also: [[#table-cell-ends-colgroup-p][~org-export-table-cell-ends-colgroup-p~]].
1400
1401 ** ~org-export-table-cell-width~
1402    :PROPERTIES:
1403    :CUSTOM_ID: table-cell-width
1404    :END:
1405
1406    Return expected width for contents of a given cell object.
1407
1408    Only width specified explicitly through meta-data is considered.
1409    If no such information can be found, return nil instead.
1410
1411    Some back-end may still need to know the actual width of exported
1412    cell's contents in order to compute column's width.  In that case,
1413    every cell in the column must be transcoded in order to find the
1414    widest one.  The snippet below, extracted from =ox-ascii.el=
1415    illustrates a possible implementation.
1416
1417    #+BEGIN_SRC emacs-lisp
1418    (or (org-export-table-cell-width table-cell info)
1419        (let* ((max-width 0)
1420               (table (org-export-get-parent-table table-cell info))
1421               (specialp (org-export-table-has-special-column-p table))
1422               (col (cdr (org-export-table-cell-address table-cell info))))
1423          (org-element-map
1424           table 'table-row
1425           (lambda (row)
1426             ;; For each exportable row, get the cell at column COL and
1427             ;; transcode its contents.  Then compare its length with
1428             ;; MAX-WIDTH and keep the greater of two.
1429             (setq max-width
1430                   (max (length
1431                         (org-export-data
1432                          (org-element-contents
1433                           (elt (if specialp (car (org-element-contents row))
1434                                  (org-element-contents row))
1435                                col))
1436                          info))
1437                        max-width)))
1438           info)
1439          max-width))
1440    #+END_SRC
1441
1442    See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
1443    [[#table-cell-borders][~org-export-table-cell-borders~]].
1444
1445 ** ~org-export-table-dimensions~
1446    :PROPERTIES:
1447    :CUSTOM_ID: table-dimensions
1448    :END:
1449
1450    Return the number of exportable rows and columns in a given table.
1451
1452    See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
1453    [[#table-cell-address][~org-export-table-cell-address~]].
1454
1455 ** ~org-export-table-has-header-p~
1456    :PROPERTIES:
1457    :CUSTOM_ID: table-has-header-p
1458    :END:
1459
1460    Non-nil when table has at least two row groups.
1461
1462    See also: [[#table-has-special-column-p][~org-export-table-has-special-column-p~]],
1463    [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
1464
1465 ** ~org-export-table-has-special-column-p~
1466    :PROPERTIES:
1467    :CUSTOM_ID: table-has-special-column-p
1468    :END:
1469
1470    Non-nil when first column in the table only contains meta-data.
1471
1472    See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1473    [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
1474
1475 ** ~org-export-table-row-ends-header-p~
1476    :PROPERTIES:
1477    :CUSTOM_ID: table-row-ends-header-p
1478    :END:
1479
1480    Non-nil when a table row element ends table's header.
1481
1482    See also: [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1483    [[#table-row-group][~org-export-table-row-group~]],
1484    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1485    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]],
1486    [[#table-row-in-header-p][~org-export-table-row-in-header-p~]].
1487
1488 ** ~org-export-table-row-ends-rowgroup-p~
1489    :PROPERTIES:
1490    :CUSTOM_ID: table-row-ends-rowgroup-p
1491    :END:
1492
1493    Non-nil when a a table row element ends a rowgroup, header
1494    included.
1495
1496    See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1497    [[#table-row-group][~org-export-table-row-group~]],
1498    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1499    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1500
1501 ** ~org-export-table-row-group~
1502    :PROPERTIES:
1503    :CUSTOM_ID: table-row-group
1504    :END:
1505
1506    Return row group number for a given table row element.
1507
1508    See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1509    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1510    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1511    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1512
1513 ** ~org-export-table-row-in-header-p~
1514    :PROPERTIES:
1515    :CUSTOM_ID: table-row-in-header-p
1516    :END:
1517
1518    Non-nil if a given table row element belongs to table's header.
1519    Always nil if the table contains no header or the row is
1520    a separator.
1521
1522    See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1523    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1524    [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]].
1525
1526
1527 ** ~org-export-table-row-is-special-p~
1528    :PROPERTIES:
1529    :CUSTOM_ID: table-row-is-special-p
1530    :END:
1531
1532    Non-nil if a given table row element only contains meta-data.
1533
1534    See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1535    [[#table-has-special-column-p][~org-export-table-has-special-column-p~]].
1536
1537 ** ~org-export-table-row-starts-header-p~
1538    :PROPERTIES:
1539    :CUSTOM_ID: table-row-starts-header-p
1540    :END:
1541
1542    Non-nil when a table row element starts table's header.
1543
1544    See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1545    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1546    [[#table-row-group][~org-export-table-row-group~]],
1547    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]],
1548    [[#table-row-in-header-p][~org-export-table-row-in-header-p~]].
1549
1550 ** ~org-export-table-row-starts-rowgroup-p~
1551    :PROPERTIES:
1552    :CUSTOM_ID: table-row-starts-rowgroup-p
1553    :END:
1554
1555    Non-nil when a table row element starts a rowgroup, header
1556    included.
1557
1558    See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1559    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1560    [[#table-row-group][~org-export-table-row-group~]],
1561    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]].
1562
1563 ** ~org-export-toc-entry-backend~
1564 :PROPERTIES:
1565 :CUSTOM_ID: toc-entry-backend
1566 :END:
1567
1568 Generate an anonymous export back-end appropriate for entries in table
1569 of contents.
1570
1571 See also: [[#data-with-backend][~org-export-data-with-backend~]].
1572
1573 ** ~org-export-translate~
1574
1575    Translate a string, i.e. "Table of Contents", according to language
1576    specification.
1577
1578    Refer to ~org-export-dictionary~ variable for the list of all
1579    supported strings.
1580
1581 ** ~org-export-unravel-code~
1582    :PROPERTIES:
1583    :CUSTOM_ID: unravel-code
1584    :END:
1585
1586    Clean source code from an =example-block= or a =src-block= element
1587    and extract code references out of it.
1588
1589    Its purpose is to allow to transform raw source code first and then
1590    integrate line numbers or references back into the final output.
1591    That final task can be achieved with the help of
1592    ~org-export-format-code~ function.
1593
1594    See also: [[#format-code][~org-export-format-code~]],
1595    [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]].
1596
1597 ** ~org-export-with-backend~
1598    :PROPERTIES:
1599    :CUSTOM_ID: with-backend
1600    :END:
1601
1602    Export an element or object using locally another back-end.
1603
1604    In a derived back-end, it may be used as a fall-back function once
1605    all specific cases have been handled.  Thus, ~beamer~ back-end,
1606    derived from ~latex~, takes care of every internal link type and
1607    delegates everything else to its parent back-end:
1608
1609    #+BEGIN_SRC emacs-lisp
1610    (let ((type (org-element-property :type link))
1611          (path (org-element-property :path link)))
1612      (cond
1613       ;; Handle every internal link type, but be careful to ignore "id"
1614       ;; type links pointing to external files.
1615       ((equal type "radio") ...)
1616       ((and (member type '("custom-id" "fuzzy" "id"))
1617             (let ((destination (if (string= type "fuzzy")
1618                                    (org-export-resolve-fuzzy-link link info)
1619                                  (org-export-resolve-id-link link info))))
1620               (pcase (org-element-type destination)
1621                 (`headline ...)
1622                 (`target ...)))))
1623       ;; Otherwise, use `latex' back-end.
1624       (t (org-export-with-backend 'latex link contents info))))
1625    #+END_SRC
1626
1627    See also: [[#data-with-backend][~org-export-data-with-backend~]].
1628
1629 ** ~org-timestamp-translate~
1630    :PROPERTIES:
1631    :CUSTOM_ID: timestamp-translate
1632    :END:
1633
1634    Translate a timestamp object according to
1635    ~org-time-stamp-custom-formats~, which see.
1636
1637    It should be used whenever exported timestamps are expected to
1638    comply to user-defined display.  As an example, in the following
1639    excerpt from, =ox-html.el=, the timestamp object is first turned
1640    into a custom string:
1641
1642    #+BEGIN_SRC emacs-lisp
1643    (defun org-html-timestamp (timestamp contents info)
1644      "Transcode a TIMESTAMP object from Org to HTML.
1645    CONTENTS is nil.  INFO is a plist holding contextual
1646    information."
1647      (let ((value (org-html-plain-text
1648                    (org-timestamp-translate timestamp) info)))
1649        (format "<span class=\"timestamp-wrapper\"><span class=\"timestamp\">%s</span></span>"
1650                (replace-regexp-in-string "--" "&ndash;" value))))
1651    #+END_SRC
1652
1653 * Interactive functions
1654   :PROPERTIES:
1655   :CUSTOM_ID: interactive
1656   :END:
1657
1658   Once the back-end is complete, interactive functions have to be
1659   offered for the user to use it.  Depending on the desired output,
1660   three functions are provided to help in this task, along with
1661   a wrapper function allowing to make export asynchronous.
1662
1663   Hence, ~org-export-to-buffer~ may be used if the expected output is
1664   a temporary buffer whereas ~org-export-to-file~ will be used when
1665   exporting to a file.  In the latter case,
1666   ~org-export-output-file-name~ can be useful to guess the name of the
1667   output file --- though, don't use it in an external process, since
1668   it will ask the user for a file name when guessing fails.  At the
1669   lowest level, ~org-export-as~ returns the output as a string.
1670
1671   While it is suggested to have a look at their respective docstring,
1672   the following examples illustrate how to combine all these
1673   functions:
1674
1675   1. Export to a temporary buffer:
1676
1677      #+BEGIN_SRC emacs-lisp
1678      ;;;###autoload
1679      (defun org-latex-export-as-latex
1680      (&optional async subtreep visible-only body-only ext-plist)
1681        (interactive)
1682        (org-export-to-buffer 'latex "*Org LATEX Export*"
1683          async subtreep visible-only body-only ext-plist (lambda () (LaTeX-mode))))
1684      #+END_SRC
1685
1686   2. Export to a file:
1687
1688      #+BEGIN_SRC emacs-lisp
1689      ;;;###autoload
1690      (defun org-latex-export-to-latex
1691        (&optional async subtreep visible-only body-only ext-plist)
1692        (interactive)
1693        (let ((outfile (org-export-output-file-name ".tex" subtreep)))
1694          (org-export-to-file 'latex outfile
1695            async subtreep visible-only body-only ext-plist)))
1696      #+END_SRC
1697
1698   It may also be interesting to provide a publishing function for the
1699   back-end.  Such function must accept three arguments: a plist
1700   containing properties relative to the project being exported, the
1701   name of the current file being published and the publishing
1702   directory.  It often is a simple wrapper around ~org-publish-org-to~
1703   function defined in =ox-publish.el=, as shown in the following
1704   example:
1705
1706   #+BEGIN_SRC emacs-lisp
1707   (defun org-html-publish-to-html (plist filename pub-dir)
1708     (org-publish-org-to 'html filename ".html" plist pub-dir))
1709   #+END_SRC
1710
1711
1712 # Local Variables:
1713 # sentence-end-double-space: t
1714 # End: