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