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