dev/org-export-reference.org

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