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