1a855424a0aeca52ed83457646a03f4725c25ddd
[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.
22
23
24 * Defining a Back-End
25
26   A back-end is defined with ~org-export-define-backend~ macro.  It
27   requires two mandatory arguments: the back-end name and its
28   translation table, an alist that associates element and object types
29   to translator functions.  According to the macro doc-string:
30
31   #+BEGIN_QUOTE
32   These functions should return a string without any trailing space,
33   or nil.  They must accept three arguments: the object or element
34   itself, its contents or nil when it isn't recursive and the property
35   list used as a communication channel.
36
37   Contents, when not nil, are stripped from any global indentation
38   (although the relative one is preserved).  They also always end with
39   a single newline character.
40
41   If, for a given type, no function is found, that element or object
42   type will simply be ignored, along with any blank line or white
43   space at its end.  The same will happen if the function returns the
44   nil value.  If that function returns the empty string, the type will
45   be ignored, but the blank lines or white spaces will be kept.
46
47   In addition to element and object types, one function can be
48   associated to the ~template~ symbol and another one to the
49   ~plain-text~ symbol.
50
51   The former returns the final transcoded string, and can be used to
52   add a preamble and a postamble to document's body.  It must accept
53   two arguments: the transcoded string and the property list
54   containing export options.
55
56   The latter, when defined, is to be called on every text not
57   recognized as an element or an object.  It must accept two
58   arguments: the text string and the information channel.  It is an
59   appropriate place to protect special chars relative to the back-end.
60   #+END_QUOTE
61
62   Optionally, the macro can set-up back-end specific properties (like
63   values from specific buffer keywords) accessible from every
64   translator function with the ~:options-alist~ keyword.  See
65   ~org-export-options-alist~ for details on the structure of the
66   value.
67
68   As an example, the following excerpt from =e-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 e-latex
74     ...
75     :options-alist ((:date "DATE" nil org-e-latex-date-format t)
76                     (:latex-class "LATEX_CLASS" nil org-e-latex-default-class t)
77                     (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
78                     (:latex-header-extra "LATEX_HEADER" nil nil newline)))
79   #+END_SRC
80
81   It is also possible, with ~:export-block~ keyword, to associate
82   given block names to the ~export-block~ type.  Such blocks can
83   contain raw code that will be directly inserted in the output, as
84   long as the corresponding translator function says so.
85
86   In the following example, in the ~e-html~ back-end, =HTML= blocks
87   are export blocks.  The associated translator function inserts their
88   contents as-is, and ignores any other export block.
89
90   #+BEGIN_SRC emacs-lisp
91   (org-export-define-backend e-html
92     (...
93      (export-block . org-e-html-export-block)
94      ... )
95     :export-block "HTML")
96
97   (defun org-e-html-export-block (export-block contents info)
98     "Transcode a EXPORT-BLOCK element from Org to HTML.
99   CONTENTS is nil.  INFO is a plist used as a communication
100   channel."
101     (when (string= (org-element-property :type export-block) "HTML")
102       (org-element-property :value export-block)))
103   #+END_SRC
104
105   Eventually ~org-export-define-backend~ allows to define back-ends
106   specific filters.  Refer to [[#filter-system][The Filter System]] section for more
107   information.
108
109   If the new back-end shares most properties with another one,
110   ~org-export-define-derived-backend~ macro can be used to simplify
111   the process.  In the example below, we implement a new back-end
112   which behaves like =e-latex= excepted for headlines and the
113   template.
114
115   #+BEGIN_SRC emacs-lisp
116   (org-export-define-derived-backend my-latex e-latex
117     :translate-alist ((headline . custom-headline-translator)
118                       (template . custom-template)))
119   #+END_SRC
120
121   Back-ends defined with either function can be registered in the
122   export dispatcher using special keyword =:menu-entry= (and also
123   =:sub-menu-entry= for a derived back-end).  See macros 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 containing objects and recursive objects
143   will also have ~:contents-begin~ and ~:contents-end~ properties to
144   delimit contents.
145
146   In addition to these properties, each element can optionally get
147   some more from affiliated keywords, namely: ~:attr_ascii~,
148   ~:attr_docbook~, ~:attr_html~, ~:attr_latex~, ~:attr_odt~,
149   ~:caption~, ~:header~, ~:name~, ~:plot~, and ~:results~.
150
151   At the lowest level, a ~:parent~ property is also attached to any
152   string, as a text property.
153
154   Other properties, specific to each element or object, are listed
155   below.
156
157 ** Babel Call
158
159    Element.
160
161    - ~:info~ :: Information about function being called, as returned
162                 by ~ob-babel-lob-get-info~ (string).
163 ** Bold
164
165    Recursive object.
166
167    No specific property.
168
169 ** Center Block
170
171    Greater element.
172
173    - ~:hiddenp~ :: Non-nil if the block is hidden (boolean).
174
175 ** Clock
176
177    Element.
178
179    - ~:status~ :: Status of current clock (symbol: ~closed~ or
180                   ~running~).
181    - ~:value~ :: Timestamp associated to clock keyword (string).
182    - ~:time~ :: Clock duration for a closed clock, or nil (string or
183                 nil).
184
185 ** Code
186
187    Object.
188
189    - ~:value~ :: Contents (string).
190
191 ** Comment
192
193    Element.
194
195    - ~:value~ :: Comments, with pound signs (string).
196
197 ** Comment Block
198
199    Element.
200
201    - ~:value~ :: Comments, without block's boundaries (string).
202    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
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    - ~:hiddenp~ :: Non-nil if the drawer is hidden (boolean).
216
217    /Note relative to export:/ The idea behind drawers is that they are
218    transparent export-wise.  By default, they should return their
219    contents only.
220
221 ** Dynamic Block
222
223    Greater element.
224
225    - ~:arguments~ :: Block's parameters (string).
226    - ~:block-name~ :: Block's name (string).
227    - ~:drawer-name~ :: Drawer's name (string).
228    - ~:hiddenp~ :: Non-nil if the block is hidden (boolean).
229
230 ** Entity
231
232    Object.
233
234    - ~:ascii~ :: Entity's ASCII representation (string).
235    - ~:html~ :: Entity's HTML representation (string).
236    - ~:latex~ :: Entity's LaTeX representation (string).
237    - ~:latex-math-p~ :: Non-nil if entity's LaTeX representation
238         should be in math mode (boolean).
239    - ~:latin1~ :: Entity's Latin-1 encoding representation (string).
240    - ~:name~ :: Entity's name, without backslash nor brackets
241                 (string).
242    - ~:use-brackets-p~ :: Non-nil if entity is written with optional
243         brackets in original buffer (boolean).
244    - ~:utf-8~ :: Entity's UTF-8 encoding representation (string).
245
246 ** Example Block
247
248    Element.
249
250    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
251    - ~:label-fmt~ :: Format string used to write labels in current
252                      block, if different from
253                      ~org-coderef-label-format~ (string or nil).
254    - ~:language~ :: Language of the code in the block, if specified
255                     (string or nil).
256    - ~:number-lines~ :: Non-nil if code lines should be numbered.
257         A ~new~ value starts numbering from 1 wheareas ~continued~
258         resume numbering from previous numbered block (symbol: ~new~,
259         ~continued~ or nil).
260    - ~:options~ :: Block's options located on the block's opening line
261                    (string).
262    - ~:parameters~ :: Optional header arguments (string or nil).
263    - ~:preserve-indent~ :: Non-nil when indentation within the block
264         mustn't be modified upon export (boolean).
265    - ~:retain-labels~ :: Non-nil if labels should be kept visible upon
266         export (boolean).
267    - ~:switches~ :: Optional switches for code block export (string or
268                     nil).
269    - ~:use-labels~ :: Non-nil if links to labels contained in the
270                       block should display the label instead of the
271                       line number (boolean).
272    - ~:value~ :: Contents (string).
273
274 ** Export Block
275
276    Element.
277
278    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
279    - ~:type~ :: Related back-end's name (string).
280    - ~:value~ :: Contents (string).
281
282 ** Export Snippet
283
284    Object.
285
286    - ~:back-end~ :: Relative back-end's name (string).
287    - ~:value~ :: Export code (string).
288
289 ** Fixed Width
290
291    Element.
292
293    - ~:value~ :: Contents, with colons (string).
294
295 ** Footnote Definition
296
297    Greater element.
298
299    - ~:label~ :: Label used for references (string).
300
301 ** Footnote Reference
302
303    Object.
304
305    - ~:inline-definition~ :: Footnote's definition, when inlined
306         (secondary string or nil).
307    - ~:label~ :: Footnote's label, if any (string or nil).
308    - ~:raw-definition~ :: Uninterpreted footnote's definition, when
309         inlined (string or nil).
310    - ~:type~ :: Determine whether reference has its definition inline,
311                 or not (symbol: ~inline~, ~standard~).
312
313 ** Headline
314
315    Greater element.
316
317    In addition to the following list, any property specified in
318    a property drawer attached to the headline will be accessible as an
319    attribute (with underscores replaced with hyphens and a lowercase
320    name, i.e. ~:custom-id~).
321    
322    - ~:archivedp~ :: Non-nil if the headline has an archive tag
323                      (boolean).
324    - ~:category~ :: Headline's category (string).
325    - ~:clock~ :: Headline's CLOCK reference, if any (string or nil).
326    - ~:commentedp~ :: Non-nil if the headline has a comment keyword
327                       (boolean).
328    - ~:deadline~ :: Headline's DEADLINE reference, if any (string or
329                     nil).
330    - ~:footnote-section-p~ :: Non-nil if the headline is a footnote
331         section (boolean).
332    - ~:hiddenp~ :: Non-nil if the headline is hidden (boolean).
333    - ~:level~ :: Reduced level of the headline (integer).
334    - ~:pre-blank~ :: Number of blank lines between the headline and
335                      the first non-blank line of its contents
336                      (integer).
337    - ~:priority~ :: Headline's priority, as a character (integer).
338    - ~:quotedp~ :: Non-nil if the headline contains a quote keyword
339                    (boolean).
340    - ~:raw-value~ :: Raw headline's text, without the stars and the
341                      tags (string).
342    - ~:scheduled~ :: Headline's SCHEDULED reference, if any (string or
343                      nil).
344    - ~:tags~ :: Headline's tags, if any, without the archive
345                 tag. (list of strings).
346    - ~:timestamp~ :: Headline's TIMESTAMP reference, if any (string or
347                      nil).
348    - ~:title~ :: Parsed headline's text, without the stars and the
349                  tags (secondary string).
350    - ~:todo-keyword~ :: Headline's TODO keyword without quote and
351         comment strings, if any (string or nil).
352    - ~:todo-type~ :: Type of headline's TODO keyword, if any (symbol:
353                      ~done~, ~todo~).
354
355 ** Horizontal Rule
356
357    Element.
358
359    No specific property.
360
361 ** Inline Babel Call
362
363    Object.
364
365    - ~:info~ :: Information about function called, as returned by
366                 ~org-babel-lob-get-info~ (list).
367
368    /Note relative to export:/ Since Babel related blocks are expanded
369    before parsing, these can safely be ignored by back-ends.
370
371 ** Inline Src Block
372
373    Object.
374
375    - ~:language~ :: Language of the code in the block (string).
376    - ~:parameters~ :: Optional header arguments (string or nil).
377    - ~:value~ :: Source code (string).
378
379 ** Inlinetask
380
381    Greater element.
382    
383    In addition to the following list, any property specified in
384    a property drawer attached to the headline will be accessible as an
385    attribute (with underscores replaced with hyphens and a lowercase
386    name, i.e. ~:custom-id~).
387
388    - ~:clock~ :: Inlinetask's CLOCK reference, if any (string or nil).
389    - ~:deadline~ :: Inlinetask's DEADLINE reference, if any (string or
390                     nil).
391    - ~:hiddenp~ :: Non-nil if the headline is hidden (boolean).
392    - ~:level~ :: Reduced level of the inlinetask (integer).
393    - ~:priority~ :: Headline's priority, as a character (integer).
394    - ~:raw-value~ :: Raw inlinetask's text, without the stars and the
395                      tags (string).
396    - ~:scheduled~ :: Inlinetask's SCHEDULED reference, if any (string
397                      or nil).
398    - ~:tags~ :: Inlinetask's tags, if any (list of strings).
399    - ~:timestamp~ :: Inlinetask's TIMESTAMP reference, if any (string
400                      or nil).
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                   (string or nil).
557    - ~:deadline~ :: Timestamp associated to deadline keyword, if any
558                     (string or nil).
559    - ~:scheduled~ :: Timestamp associated to scheduled keyword, if any
560                      (string 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    - ~:range-end~ :: Timestamp ending the date range, if any (string
690                      or nil).
691    - ~:type~ :: Type of timestamp (symbol: ~active~, ~active-range~,
692                 ~diary~, ~inactive~, ~inactive-range~).
693    - ~:value~ :: Timestamp (string).
694
695 ** Underline
696
697    Recursive object.
698
699    No specific property.
700
701 ** Verbatim
702
703    Object.
704
705    - ~:value~ :: Contents (string).
706
707 ** Verse Block
708
709    Element containing objects.
710
711    - ~:hiddenp~ :: Non-nil if block is hidden (boolean).
712
713 * The Communication Channel
714   :PROPERTIES:
715   :CUSTOM_ID: communication
716   :END:
717
718   This is the full list of properties available during transcode
719   process, with their category (~option~ or ~tree~) and their value
720   type.
721
722 ** ~:author~
723
724    Author's name.
725     
726    - category :: option
727    - type :: string
728
729 ** ~:back-end~
730
731    Current back-end used for transcoding.
732
733    - category :: tree
734    - type :: symbol
735
736 ** ~:creator~
737
738    String to write as creation information.
739
740    - category :: option
741    - type :: string
742
743 ** ~:date~
744
745    String to use as date.
746
747    - category :: option
748    - type :: string
749
750 ** ~:description~
751
752    Description text for the current data.
753
754    - category :: option
755    - type :: string
756
757 ** ~:email~
758
759    Author's email.
760
761    - category :: option
762    - type :: string
763
764 ** ~:exclude-tags~
765
766    Tags for exclusion of sub-trees from export process.
767
768    - category :: option
769    - type :: list of strings
770
771 ** ~:exported-data~
772
773    Hash table used to memoize results from [[#data][~org-export-data~]].
774
775    - category :: tree
776    - type :: hash table
777
778 ** ~:footnote-definition-alist~
779
780    /Alist/ between footnote labels and their definition, as parsed
781    data.  Only non-inline footnotes are represented in this /alist/.
782    Also, every definition isn't guaranteed to be referenced in the
783    parse tree.  The purpose of this property is to preserve
784    definitions from oblivion – i.e. when the parse tree comes from
785    a part of the original buffer –, it isn't meant for direct use in
786    a back-end.  To retrieve a definition relative to a reference, use
787    [[#get-footnote-definition][~org-export-get-footnote-definition~]] instead.
788
789    - category :: option
790    - type :: alist (STRING . LIST)
791
792 ** ~:headline-levels~
793    :PROPERTIES:
794    :CUSTOM_ID: headline-levels
795    :END:
796
797    Maximum level being exported as an headline.  Comparison is done
798    with the relative level of headlines in the parse tree, not
799    necessarily with their actual level.
800
801    - category :: option
802    - type :: integer
803
804 ** ~:headline-numbering~
805
806    Alist between headlines' beginning position and their numbering, as
807    a list of numbers – cf. [[#get-headline-number][~org-export-get-headline-number~]].
808
809    - category :: tree
810    - type :: alist (INTEGER . LIST)
811
812 ** ~:headline-offset~
813
814    Difference between relative and real level of headlines in the
815    parse tree.  For example, a value of -1 means a level 2 headline
816    should be considered as level 1 —
817    cf. [[#get-relative-level][~org-export-get-relative-level~]].
818
819    - category :: tree
820    - type :: integer
821
822 ** ~:ignore-list~
823
824    List of elements and objects that will be unconditionally ignored
825    during export.
826
827    - category :: option
828    - type :: list of elements
829
830 ** ~:id-alist~
831
832    Alist between ID strings and destination file's path, relative to
833    current directory.
834
835    - category :: option
836    - type :: alist (STRING . STRING)
837
838 ** ~:input-file~
839
840    Full path to input file, if any.
841
842    - category :: option
843    - type :: string or nil
844
845 ** ~:keywords~
846
847    List of keywords attached to data.
848
849    - category :: option
850    - type :: string
851
852 ** ~:language~
853
854    Default language used for translations.
855
856    - category :: option
857    - type :: string
858
859 ** ~:parse-tree~
860
861    Whole parse tree, available at any time during transcoding.
862
863    - category :: option
864    - type :: list (as returned by ~org-element-parse-buffer~)
865
866 ** ~:preserve-breaks~
867
868    Non-nil means transcoding should preserve all line breaks.
869
870    - category :: option
871    - type :: symbol (nil, t)
872
873 ** ~:section-numbers~
874
875    Non-nil means transcoding should add section numbers to headlines.
876
877    - category :: option
878    - type :: symbol (nil, t)
879
880 ** ~:select-tags~
881    :PROPERTIES:
882    :CUSTOM_ID: select-tags
883    :END:
884
885    List of tags enforcing inclusion of sub-trees in transcoding.  When
886    such a tag is present, sub-trees without it are /de facto/ excluded
887    from the process.  See [[#use-select-tags][~:use-select-tags~]].
888
889    - category :: option
890    - type :: list of strings
891
892 ** ~:target-list~
893
894    List of targets raw names encountered in the parse tree.  This is
895    used to partly resolve "fuzzy" links —
896    cf. [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]].
897
898    - category :: tree
899    - type :: list of strings
900
901 ** ~:time-stamp-file~
902
903    Non-nil means transcoding should insert a time stamp in the output.
904
905    - category :: option
906    - type :: symbol (nil, t)
907
908 ** ~:translate-alist~
909
910    Alist between element and object types and transcoding functions
911    relative to the current back-end.  Special keys ~template~ and
912    ~plain-text~ are also possible.
913
914    - category :: option
915    - type :: alist (SYMBOL . FUNCTION)
916
917 ** ~:use-select-tags~
918    :PROPERTIES:
919    :CUSTOM_ID: use-select-tags
920    :END:
921
922    When non-nil, a select tags has been found in the parse tree.
923    Thus, any headline without one will be filtered out.  See
924    [[#select-tags][~:select-tags~]].
925
926    - category :: tree
927    - type :: interger or nil
928
929 ** ~:with-archived-trees~
930
931    Non-nil when archived sub-trees should also be transcoded.  If it
932    is set to the ~headline~ symbol, only the archived headline's name
933    is retained.
934
935    - category :: option
936    - type :: symbol (nil, t, ~headline~)
937
938 ** ~:with-author~
939
940    Non-nil means author's name should be included in the output.
941
942    - category :: option
943    - type :: symbol (nil, t)
944
945 ** ~:with-clocks~
946
947    Non-nil means clock keywords should be exported.
948
949    - category :: option
950    - type :: symbol (nil, t)
951
952 ** ~:with-creator~
953
954    Non-nil means a creation sentence should be inserted at the end of
955    the transcoded string.  If the value is ~comment~, it should be
956    commented.
957
958    - category :: option
959    - type :: symbol (~comment~, nil, t)
960
961 ** ~:with-drawers~
962
963    Non-nil means drawers should be exported.  If its value is a list
964    of names, only drawers with such names will be transcoded.
965
966    - category :: option
967    - type :: symbol (nil, t) or list of strings
968
969 ** ~:with-email~
970
971    Non-nil means output should contain author's email.
972
973    - category :: option
974    - type :: symbol (nil, t)
975
976 ** ~:with-emphasize~
977
978    Non-nil means emphasized text should be interpreted.
979
980    - category :: option
981    - type :: symbol (nil, t)
982
983 ** ~:with-fixed-width~
984
985    Non-nil if transcoder should interpret strings starting with
986    a colon as a fixed-with — verbatim — area.
987
988    - category :: option
989    - type :: symbol (nil, t)
990
991 ** ~:with-footnotes~
992
993    Non-nil if transcoder should interpret footnotes.
994
995    - category :: option
996    - type :: symbol (nil, t)
997
998 ** ~:with-plannings~
999
1000    Non-nil means transcoding should include planning info.
1001
1002    - category :: option
1003    - type :: symbol (nil, t)
1004
1005 ** ~:with-priority~
1006
1007    Non-nil means transcoding should include priority cookies.
1008
1009    - category :: option
1010    - type :: symbol (nil, t)
1011
1012 ** ~:with-smart-quotes~
1013
1014    Non-nil means activate smart quotes during export.
1015
1016    - category :: option
1017    - type :: symbol (nil ,t)
1018
1019 ** ~:with-special-strings~
1020
1021    Non-nil means transcoding should interpret special strings in plain
1022    text.
1023
1024    - category :: option
1025    - type :: symbol (nil, t)
1026
1027 ** ~:with-sub-superscript~
1028
1029    Non-nil means transcoding should interpret subscript and
1030    superscript.  With a value of ~{}~, only interpret those using
1031    curly brackets.
1032
1033    - category :: option
1034    - type :: symbol (nil, ~{}~, t)
1035
1036 ** ~:with-tables~
1037
1038    Non-nil means transcoding should interpret tables.
1039
1040    - category :: option
1041    - type :: symbol (nil, t)
1042
1043 ** ~:with-tags~
1044
1045    Non-nil means transcoding should keep tags in headlines.
1046    A ~not-in-toc~ value will remove them from the table of contents,
1047    if any, nonetheless.
1048
1049    - category :: option
1050    - type :: symbol (nil, t, ~not-in-toc~)
1051
1052 ** ~:with-tasks~
1053
1054    Non-nil means transcoding should include headlines with a TODO
1055    keyword.  A ~todo~ value will only include headlines with a TODO
1056    type keyword while a ~done~ value will do the contrary.  If a list
1057    of strings is provided, only tasks with keywords belonging to that
1058    list will be kept.
1059
1060    - category :: option
1061    - type :: symbol (t, ~todo~, ~done~, nil) or list of strings
1062
1063 ** ~:with-timestamps~
1064
1065    Non-nil means transcoding should include time stamps.  Special
1066    value ~active~ (resp. ~inactive~) ask to export only active
1067    (resp. inactive) timestamps.  Otherwise, completely remove them.
1068
1069    - category :: option
1070    - type :: symbol: (~active~, ~inactive~, t, nil)
1071
1072 ** ~:with-toc~
1073
1074    Non-nil means that a table of contents has to be added to the
1075    output.  An integer value limits its depth.
1076
1077    - category :: option
1078    - type :: symbol (nil, t or integer)
1079
1080 ** ~:with-todo-keywords~
1081
1082    Non-nil means transcoding should include TODO keywords.
1083
1084    - category :: option
1085    - type :: symbol (nil, t)
1086
1087 * The Filter System
1088   :PROPERTIES:
1089   :CUSTOM_ID: filter-system
1090   :END:
1091
1092   Filters sets are lists of functions.  They allow to pre-process
1093   parse tree before export and to post-process output of each
1094   transcoded object or element.
1095
1096   Each function in a set must accept three arguments: a string (or
1097   a parse tree as a special case), a symbol representing the current
1098   back-end, and the communication channel, as a plist.
1099
1100   From the developer side, filters sets can be installed using
1101   ~:filters-alist~ keyword while defining the back-end with
1102   ~org-export-define-derived-backend~.  Each association has a key
1103   among the following symbols and a function or a list of functions as
1104   value:
1105
1106   - ~:filter-babel-call~
1107   - ~:filter-bold~
1108   - ~:filter-center-block~
1109   - ~:filter-clock~
1110   - ~:filter-code~
1111   - ~:filter-comment~
1112   - ~:filter-comment-block~
1113   - ~:filter-drawer~
1114   - ~:filter-dynamic-block~
1115   - ~:filter-entity~
1116   - ~:filter-example-block~
1117   - ~:filter-export-block~
1118   - ~:filter-export-snippet~
1119   - ~:filter-final-output~
1120   - ~:filter-fixed-width~
1121   - ~:filter-footnote-definition~
1122   - ~:filter-footnote-reference~
1123   - ~:filter-headline~
1124   - ~:filter-horizontal-rule~
1125   - ~:filter-inline-babel-call~
1126   - ~:filter-inline-src-block~
1127   - ~:filter-inlinetask~
1128   - ~:filter-italic~
1129   - ~:filter-item~
1130   - ~:filter-keyword~
1131   - ~:filter-latex-environment~
1132   - ~:filter-latex-fragment~
1133   - ~:filter-line-break~
1134   - ~:filter-link~
1135   - ~:filter-macro~
1136   - ~:filter-paragraph~
1137   - ~:filter-parse-tree~
1138   - ~:filter-plain-list~
1139   - ~:filter-plain-text~
1140   - ~:filter-planning~
1141   - ~:filter-property-drawer~
1142   - ~:filter-quote-block~
1143   - ~:filter-quote-section~
1144   - ~:filter-radio-target~
1145   - ~:filter-section~
1146   - ~:filter-special-block~
1147   - ~:filter-src-block~
1148   - ~:filter-strike-through~
1149   - ~:filter-statistics-cookie~
1150   - ~:filter-subscript~
1151   - ~:filter-superscript~
1152   - ~:filter-table~
1153   - ~:filter-table-cell~
1154   - ~:filter-table-row~
1155   - ~:filter-target~
1156   - ~:filter-timestamp~
1157   - ~:filter-underline~
1158   - ~:filter-verbatim~
1159   - ~:filter-verse-block~
1160
1161
1162   For example, =e-ascii= back-end implements a filter that makes sure
1163   headlines end with two blank lines:
1164
1165   #+BEGIN_SRC emacs-lisp
1166   (org-export-define-backend e-ascii
1167     ...
1168     :filters-alist ((:filter-headline . org-e-ascii-filter-headline-blank-lines)
1169                     (:filter-section . org-e-ascii-filter-headline-blank-lines)))
1170
1171   (defun org-e-ascii-filter-section-blank-lines (headline back-end info)
1172     "Filter controlling number of blank lines after a section."
1173     (if (not (eq back-end 'e-ascii)) headline
1174       (let ((blanks (make-string 2 ?\n)))
1175         (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" blanks headline))))
1176   #+END_SRC
1177
1178 * The Toolbox
1179   :PROPERTIES:
1180   :CUSTOM_ID: toolbox
1181   :END:
1182
1183   A whole set of tools is available to help build new exporters.  Any
1184   function general enough to have its use across a couple of back-ends
1185   may be added here.
1186
1187   Many of them are high-level access to properties from the
1188   communication channel.  As such, they should be preferred to
1189   straight access to communication channel, when possible.
1190
1191 ** ~org-element-adopt-element~
1192    :PROPERTIES:
1193    :CUSTOM_ID: adopt-element
1194    :END:
1195
1196    Add an element to the contents of another element.
1197
1198    See also: [[#set-element][~org-element-set-element~]]
1199
1200 ** ~org-element-set-element~
1201    :PROPERTIES:
1202    :CUSTOM_ID: set-element
1203    :END:
1204
1205    Replace an element with another in the parse tree.
1206
1207    See also: [[#adopt-element][~org-element-adopt-element~]].
1208
1209 ** ~org-export-activate-smart-quotes~
1210    :PROPERTIES:
1211    :CUSTOM_ID: activate-smart-quotes
1212    :END:
1213
1214    Transform quotes and apostrophes into their "smart" counterpart in
1215    a given string.
1216
1217    It should be used after a check against ~:with-smart-quotes~ value
1218    in communication channel.
1219
1220    Since this function needs the original string, it may be useful to
1221    apply others transformations (i.e. characters protection) on a copy
1222    of that string and provide the pristine original string as the
1223    optional argument.
1224
1225    For example, in ~e-html~ back-end, it is necessary to protect "<",
1226    ">" and "&" characters before calling this function.  Here's an
1227    excerpt of the ~plain-text~ transcoder:
1228
1229    #+BEGIN_SRC emacs-lisp
1230    (let ((output text))
1231      ;; Protect following characters: <, >, &.
1232      (setq output (org-e-html-encode-plain-text output))
1233      ;; Handle smart quotes.  Be sure to provide original string since
1234      ;; OUTPUT may have been modified.
1235      (when (plist-get info :with-smart-quotes)
1236        (setq output (org-export-activate-smart-quotes output :html info text)))
1237      ...
1238      ;; Return value.
1239      output)
1240    #+END_SRC
1241
1242 ** ~org-export-collect-figures~
1243    :PROPERTIES:
1244    :CUSTOM_ID: collect-figures
1245    :END:
1246
1247    Return a list of all exportable figures in parse tree.
1248
1249    Used to build a table of figures.
1250    
1251    See also: [[#collect-headlines][~org-export-collect-headlines~]],
1252    [[#collect-tables][~org-export-collect-tables~]], [[#collect-listings][~org-export-collect-listings~]].
1253
1254 ** ~org-export-collect-footnote-definitions~
1255    :PROPERTIES:
1256    :CUSTOM_ID: collect-footnote-definitions
1257    :END:
1258
1259    List actually used footnotes definitions in order to add footnote
1260    listings throughout the transcoded data.
1261
1262    Feed it with the whole parse tree to get the full footnote listing.
1263    Feed it with the current headline to get partial footnote listing
1264    relative to that headline.
1265
1266    Number, label, if any, and definition are provided.
1267
1268    See also: [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
1269    [[#get-footnote-definition][~org-export-get-footnote-definition~]],
1270    [[#get-footnote-number][~org-export-get-footnote-number~]].
1271
1272 ** ~org-export-collect-headlines~
1273    :PROPERTIES:
1274    :CUSTOM_ID: collect-headlines
1275    :END:
1276
1277    Return a list of all exportable headlines, possibly limited to
1278    a certain depth.
1279
1280    Used to build a table of contents.
1281
1282    See also: [[#collect-tables][~org-export-collect-tables~]],
1283    [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]].
1284
1285 ** ~org-export-collect-listings~
1286    :PROPERTIES:
1287    :CUSTOM_ID: collect-listings
1288    :END:
1289
1290    Return a list of all exportable source blocks with a caption or
1291    a name in parse tree.
1292
1293    Used to build a table of listings.
1294
1295    See also: [[#collect-headlines][~org-export-collect-headlines~]],
1296    [[#collect-tables][~org-export-collect-tables~]], [[#collect-figures][~org-export-collect-figures~]].
1297 ** ~org-export-collect-tables~
1298    :PROPERTIES:
1299    :CUSTOM_ID: collect-tables
1300    :END:
1301
1302    Return a list of all exportable tables with a caption or a name in
1303    parse tree.
1304
1305    Used to build a table of tables.
1306
1307    See also: [[#collect-headlines][~org-export-collect-headlines~]],
1308    [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]].
1309
1310 ** ~org-export-data~
1311    :PROPERTIES:
1312    :CUSTOM_ID: data
1313    :END:
1314
1315    Transcode a given element, object, secondary string or string using
1316    current back-end.
1317
1318    It is used primarily to transcode secondary strings, like ~:title~.
1319    For example =e-beamer= back-end uses the following:
1320
1321    #+BEGIN_SRC emacs-lisp
1322    (defun org-e-beamer-template (contents info)
1323      (let ((title (org-export-data (plist-get info :title) info)))
1324        ...))
1325    #+END_SRC
1326
1327 ** ~org-export-first-sibling-p~
1328    :PROPERTIES:
1329    :CUSTOM_ID: first-sibling-p
1330    :END:
1331
1332    Non-nil if an headline is the first of its siblings.
1333
1334    Used to know when to start a list if headline's relative level is
1335    below the one specified in [[#headline-levels][~:headline-levels~]] property.
1336
1337    See also: [[#get-relative-level][~org-export-get-relative-level~]],
1338    [[#number-to-roman][~org-export-number-to-roman~]], [[#last-sibling-p][~org-export-last-sibling-p~]].
1339
1340 ** ~org-export-footnote-first-reference-p~
1341    :PROPERTIES:
1342    :CUSTOM_ID: footnote-first-reference-p
1343    :END:
1344
1345    Non-nil when a footnote reference if the first reference relative
1346    to its definition.
1347
1348    Used when a back-end needs to attach the footnote definition only
1349    to the first occurrence of the corresponding label.
1350
1351    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
1352    [[#get-footnote-definition][~org-export-get-footnote-definition~]],
1353    [[#get-footnote-number][~org-export-get-footnote-number~]].
1354
1355 ** ~org-export-format-code-default~
1356    :PROPERTIES:
1357    :CUSTOM_ID: format-code-default
1358    :END:
1359
1360    Return contents of a =src-block= or =example-block= element in
1361    a format suited for raw text or verbatim output.  More
1362    specifically, it takes care of line numbering and labels
1363    integration depending of element's switches, but no formatting is
1364    otherwise applied to source code.
1365
1366    See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
1367
1368 ** ~org-export-format-code~
1369    :PROPERTIES:
1370    :CUSTOM_ID: format-code
1371    :END:
1372
1373    Helper function to format source code.  It applies a given function
1374    on each line of the code, passing current line number and
1375    associated code reference label, if any, as arguments.
1376
1377    See also: [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]],
1378    [[#unravel-code][~org-export-unravel-code~]].
1379
1380 ** ~org-export-get-caption~
1381    :PROPERTIES:
1382    :CUSTOM_ID: get-caption
1383    :END:
1384
1385    Return the caption of a given element, as a secondary string.  With
1386    an optional argument, return the short caption instead.
1387
1388    As an example, =e-ascii= back-end, when creating a list of
1389    listings, uses the following:
1390
1391    #+BEGIN_SRC emacs-lisp
1392    (defun org-e-ascii--list-listings (keyword info)
1393      (let ((title (org-e-ascii--translate "List of Listings" info)))
1394        (concat title "\n"
1395                ...
1396                (mapconcat
1397                 (lambda (src-block)
1398                   ...
1399                   ;; Use short name in priority, if available.
1400                   (let ((caption (or (org-export-get-caption src-block t)
1401                                      (org-export-get-caption src-block))))
1402                     (org-export-data caption info)
1403                     ...))
1404                 (org-export-collect-listings info) "\n"))))
1405    #+END_SRC
1406
1407    See also: [[#read-attribute][~org-export-read-attribute~]].
1408
1409 ** ~org-export-get-coderef-format~
1410    :PROPERTIES:
1411    :CUSTOM_ID: get-coderef-format
1412    :END:
1413
1414    Return an appropriate format string for code reference links.
1415
1416    See also: [[#resolve-coderef][~org-export-resolve-coderef~]].
1417
1418 ** ~org-export-get-footnote-definition~
1419    :PROPERTIES:
1420    :CUSTOM_ID: get-footnote-definition
1421    :END:
1422
1423    Retrieve the footnote definition relative to a given footnote
1424    reference.
1425
1426    If the footnote definition in inline, it is returned as a secondary
1427    string.  Otherwise, it is full Org data.
1428
1429    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
1430    [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
1431    [[#get-footnote-number][~org-export-get-footnote-number~]].
1432
1433 ** ~org-export-get-footnote-number~
1434    :PROPERTIES:
1435    :CUSTOM_ID: get-footnote-number
1436    :END:
1437
1438    Return the ordinal attached to a footnote reference or definition.
1439
1440    See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
1441    [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
1442    [[#get-footnote-definition][~org-export-get-footnote-definition~]].
1443
1444 ** ~org-export-get-genealogy~
1445    :PROPERTIES:
1446    :CUSTOM_ID: get-genealogy
1447    :END:
1448
1449    Return flat list of current object or element's parents from
1450    closest to farthest, along with their contents.
1451
1452    See also: [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1453    [[#get-parent-headline][~org-export-get-parent-headline~]],
1454    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1455    [[#get-previous-element][~org-export-get-previous-element~]].
1456
1457 ** ~org-export-get-headline-number~
1458    :PROPERTIES:
1459    :CUSTOM_ID: get-headline-number
1460    :END:
1461
1462    Return the section number of an headline, as a list of integers.
1463
1464    See also: [[#headline-numbered-p][~org-export-headline-numbered-p~]],
1465    [[#number-to-roman][~org-export-number-to-roman~]].
1466
1467 ** ~org-export-get-loc~
1468    :PROPERTIES:
1469    :CUSTOM_ID: get-loc
1470    :END:
1471
1472    Return count of accumulated lines of code from previous
1473    line-numbered =example-block= and =src-block= elements, according
1474    to current element's switches.
1475
1476    In other words, the first line of code in the current block is
1477    supposed to be numbered as the returned value plus one, assuming
1478    its ~:number-lines~ properties is non-nil.
1479
1480    See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
1481
1482 ** ~org-export-get-next-element~
1483    :PROPERTIES:
1484    :CUSTOM_ID: get-next-element
1485    :END:
1486
1487    Return element (resp. object or string) after an element
1488    (resp. object), or nil.
1489
1490    See also: [[#get-genealogy][~org-export-get-genealogy~]], [[#get-parent][~org-export-get-parent~]],
1491    [[#get-parent-headline][~org-export-get-parent-headline~]],
1492    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1493    [[#get-previous-element][~org-export-get-previous-element~]].
1494
1495 ** ~org-export-get-ordinal~
1496    :PROPERTIES:
1497    :CUSTOM_ID: get-ordinal
1498    :END:
1499
1500    Associate a sequence number to any object or element.  It is meant
1501    to be used to build captions.
1502
1503    Also, it could be applied on a fuzzy link's destination, since such
1504    links are expected to be replaced with the sequence number of their
1505    destination, provided they have no description.
1506
1507    Taken from =e-ascii= back-end, the following example shows how
1508    fuzzy links could be handled :
1509
1510    #+BEGIN_SRC emacs-lisp :exports code
1511    (let ((type (org-element-property :type link)))
1512      (cond
1513       ...
1514       ;; Do not apply a special syntax on fuzzy links pointing to targets.
1515       ((string= type "fuzzy")
1516        (let ((destination (org-export-resolve-fuzzy-link link info)))
1517          ;; Ignore invisible "#+TARGET: path".
1518          (unless (eq (org-element-type destination) 'keyword)
1519            ;; If link has a description, use it.
1520            (if (org-string-nw-p desc) desc
1521              (when destination
1522                (let ((number (org-export-get-ordinal destination info)))
1523                  (when number
1524                    (if (atom number) (number-to-string number)
1525                      (mapconcat 'number-to-string number ".")))))))))
1526       ...))
1527    #+END_SRC
1528
1529    See also : [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]]
1530
1531 ** ~org-export-get-parent-element~
1532    :PROPERTIES:
1533    :CUSTOM_ID: get-parent-paragraph
1534    :END:
1535
1536    Return the first element containing provided object, if any.
1537    Return nil otherwise.
1538
1539    See also: [[#get-genealogy][~org-export-get-genealogy~]], [[#get-parent][~org-export-get-parent~]],
1540    [[#get-parent-headline][~org-export-get-parent-headline~]],
1541    [[#get-previous-element][~org-export-get-previous-element~]], [[#get-next-element][~org-export-get-next-element~]].
1542
1543 ** ~org-export-get-parent-headline~
1544    :PROPERTIES:
1545    :CUSTOM_ID: get-parent-headline
1546    :END:
1547
1548    Return the headline containing provided element or object, if any.
1549    Return nil otherwise.
1550
1551    See also: [[#get-genealogy][~org-export-get-genealogy~]],
1552    [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1553    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1554    [[#get-previous-element][~org-export-get-previous-element~]].
1555
1556 ** ~org-export-get-parent~
1557    :PROPERTIES:
1558    :CUSTOM_ID: get-parent
1559    :END:
1560
1561    Return closest element containing current element or object, if
1562    any.  Return nil otherwise.
1563
1564    See also: [[#get-genealogy][~org-export-get-genealogy~]],
1565    [[#get-next-element][~org-export-get-next-element~]], [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1566    [[#get-parent-headline][~org-export-get-parent-headline~]],
1567    [[#get-previous-element][~org-export-get-previous-element~]].
1568
1569 ** ~org-export-get-previous-element~
1570    :PROPERTIES:
1571    :CUSTOM_ID: get-previous-element
1572    :END:
1573
1574    Return element (resp. object or string) before an element
1575    (resp. object), or nil.
1576
1577    See also: [[#get-genealogy][~org-export-get-genealogy~]],
1578    [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1579    [[#get-parent-headline][~org-export-get-parent-headline~]],
1580    [[#get-parent-paragraph][~org-export-get-parent-paragraph~]].
1581
1582 ** ~org-export-get-relative-level~
1583    :PROPERTIES:
1584    :CUSTOM_ID: get-relative-level
1585    :END:
1586
1587    Return headline level, relatively to the lower headline level in
1588    the parsed tree.  It is meant to be used over ~:level~ headline's
1589    property.
1590
1591    See also:[[#first-sibling-p][~org-export-first-sibling-p~]],
1592     [[#get-headline-number][~org-export-get-headline-number~]],[[#headline-numbered-p][~org-export-headline-numbered-p~]],
1593     [[#last-sibling-p][~org-export-last-sibling-p~]].
1594
1595 ** ~org-export-get-table-cell-at~
1596    :PROPERTIES:
1597    :CUSTOM_ID: get-table-cell-at
1598    :END:
1599
1600    Return exportable cell object at a given position, or nil.  Hence,
1601    position ~(0 . 0)~ will always point to the first exportable cell
1602    in the table.
1603
1604    See also: [[#table-cell-address][~org-export-table-cell-address~]],
1605    [[#table-dimensions][~org-export-table-dimensions~]].
1606
1607 ** ~org-export-get-tags~
1608    :PROPERTIES:
1609    :CUSTOM_ID: get-tags
1610    :END:
1611
1612    Return list of exportable tags attached to a given headline or
1613    inlinetask element.
1614
1615    In particular, it removes select tags and exclude tags. The
1616    function also accepts an arbitrary list of tags for further
1617    cleaning.
1618
1619    For example, =e-latex= back-end uses the following snippet in the
1620    inlinetask transcode function.
1621
1622    #+BEGIN_SRC emacs-lisp
1623    (let ((title (org-export-data (org-element-property :title inlinetask) info))
1624       (todo (and (plist-get info :with-todo-keywords)
1625                  (let ((todo (org-element-property :todo-keyword inlinetask)))
1626                    (and todo (org-export-data todo info)))))
1627       (todo-type (org-element-property :todo-type inlinetask))
1628       (tags (and (plist-get info :with-tags)
1629                  (org-export-get-tags inlinetask info)))
1630       (priority (and (plist-get info :with-priority)
1631                      (org-element-property :priority inlinetask))))
1632   ...)
1633    #+END_SRC
1634
1635 ** ~org-export-headline-numbered-p~
1636    :PROPERTIES:
1637    :CUSTOM_ID: headline-numbered-p
1638    :END:
1639
1640    Non nil when a given headline should be numbered.
1641
1642    See also: [[#get-headline-number][~org-export-get-headline-number~]],
1643    [[#get-relative-level][~org-export-get-relative-level~]].
1644
1645 ** ~org-export-inline-image-p~
1646    :PROPERTIES:
1647    :CUSTOM_ID: inline-image-p
1648    :END:
1649
1650    Non-nil when the link provided should be considered as an inline
1651    image.  Note that it always return nil when the link has
1652    a description.
1653
1654    It accepts an optional set of rules in order to tweak the
1655    definition of an inline image, which is, by default, any link
1656    targetting a local file whose extension is either "png", "jpeg",
1657    "jpg", "gif", "tiff", "tif", "xbm", "xpm", "pbm", "pgm" or "ppm".
1658
1659    A set of rules consists in an alist whose key is a type of link, as
1660    a string, and whose value is a regexp matching link's path.  As an
1661    example, =e-html= back-end uses the following rules:
1662
1663    #+BEGIN_SRC emacs-lisp
1664    '(("file" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1665      ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1666      ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'"))
1667    #+END_SRC
1668
1669    See also: [[#solidify-link-text][~org-export-solidify-link-text~]],
1670    [[#get-coderef-format][~org-export-get-coderef-format~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]].
1671
1672 ** ~org-export-last-sibling-p~
1673    :PROPERTIES:
1674    :CUSTOM_ID: last-sibling-p
1675    :END:
1676
1677    Non-nil if an headline is the last of its siblings.
1678
1679    Used to know when to close a list if headline's relative level is
1680    below the one specified in [[#headline-levels][~:headline-levels~]] property.
1681
1682    See also: [[#get-relative-level][~org-export-get-relative-level~]],
1683    [[#number-to-roman][~org-export-number-to-roman~]], [[#first-sibling-p][~org-export-first-sibling-p~]].
1684
1685 ** ~org-export-number-to-roman~
1686    :PROPERTIES:
1687    :CUSTOM_ID: number-to-roman
1688    :END:
1689
1690    Convert numbers to roman numbers. It can be used to provide roman
1691    numbering for headlines and numbered lists.
1692
1693    See also: [[#get-headline-number][~org-export-get-headline-number~]].
1694
1695 ** ~org-export-read-attribute~
1696    :PROPERTIES:
1697    :CUSTOM_ID: read-attribute
1698    :END:
1699
1700    Read a property from a given element as a plist.  It can be used to
1701    normalize affiliated keywords' syntax.  For example, the following
1702    affiliated keywords:
1703
1704    #+BEGIN_SRC org
1705    ,#+ATTR_HTML: :width 10 :height 5
1706    ,#+ATTR_HTML: :file "filename.ext"
1707    #+END_SRC
1708
1709    would be returned as:
1710
1711    #+BEGIN_SRC emacs-lisp
1712    '(:width 10 :height 5 :file "filename.ext")
1713    #+END_SRC
1714
1715    See also: [[#get-caption][~org-export-get-caption~]].
1716
1717 ** ~org-export-resolve-coderef~
1718    :PROPERTIES:
1719    :CUSTOM_ID: resolve-coderef
1720    :END:
1721
1722    Search for a code reference within ~src-block~ and ~example-block~
1723    elements.  Return corresponding --possibly accumulated-- line
1724    number, or reference itself, depending on container's switches.
1725
1726    See also : [[#get-coderef-format][~org-export-get-coderef-format~]],
1727    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1728    [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1729
1730 ** ~org-export-resolve-fuzzy-link~
1731    :PROPERTIES:
1732    :CUSTOM_ID: resolve-fuzzy-link
1733    :END:
1734
1735    Search destination of a fuzzy link — i.e. it has a ~fuzzy~ ~:type~
1736    attribute – within the parsed tree, and return that element,
1737    object, or nil.
1738
1739    See also: [[#get-ordinal][~org-export-get-ordinal~]], [[#resolve-coderef][~org-export-resolve-coderef~]],
1740    [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1741    [[#solidify-link-text][~org-export-solidify-link-text~]].
1742
1743 ** ~org-export-resolve-id-link~
1744    :PROPERTIES:
1745    :CUSTOM_ID: resolve-id-link
1746    :END:
1747
1748    Search headline targetted by an id link --- i.e. it has a ~id~ or
1749    ~custom-id~ ~:type~ attribute --- within the parse tree.  Return
1750    the matching headline in the tree, the name of the external file,
1751    as a string, or nil.
1752
1753    See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1754    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1755    [[#solidify-link-text][~org-export-solidify-link-text~]].
1756
1757 ** ~org-export-resolve-radio-link~
1758    :PROPERTIES:
1759    :CUSTOM_ID: resolve-radio-link
1760    :END:
1761
1762    Return first radio target object matching a radio link --- that is
1763    with a ~radio~ ~:type~ attribute --- in the parse tree, or nil.
1764
1765    Typically, target's contents are exported through ~org-export-data~
1766    and used as link description, as in the following excerpt from
1767    =org-e-latex.el=:
1768
1769    #+BEGIN_SRC emacs-lisp
1770    (defun org-e-latex-link (link desc info)
1771      (let* ((type (org-element-property :type link))
1772             ...)
1773        (cond
1774         ...
1775         ((string= type "radio")
1776          (let ((destination (org-export-resolve-radio-link link info)))
1777            (when destination
1778              (format "\\hyperref[%s]{%s}"
1779                      (org-export-solidify-link-text path)
1780                      (org-export-data (org-element-contents destination) info)))))
1781         ...)))
1782    #+END_SRC
1783
1784    See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1785    [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1786    [[#solidify-link-text][~org-export-solidify-link-text~]].
1787
1788 ** ~org-export-solidify-link-text~
1789    :PROPERTIES:
1790    :CUSTOM_ID: solidify-link-text
1791    :END:
1792
1793    Normalize a string, replacing most non-standard characters with
1794    hyphens.
1795
1796    Used to turn targets names into safer versions for links.
1797
1798    See also: [[#inline-image-p][~org-export-inline-image-p~]],
1799    [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]],
1800    [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1801
1802 ** ~org-export-table-cell-address~
1803    :PROPERTIES:
1804    :CUSTOM_ID: table-cell-address
1805    :END:
1806
1807    Return row and column of a given cell object.  Positions are
1808    0-indexed and only exportable rows and columns are considered.  The
1809    function returns nil if called on a non-exportable cell.
1810
1811    See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
1812    [[#table-dimensions][~org-export-table-dimensions~]].
1813
1814 ** ~org-export-table-cell-alignment~
1815    :PROPERTIES:
1816    :CUSTOM_ID: table-cell-alignment
1817    :END:
1818
1819    Return expected alignment for the contents of a given cell object.
1820    It can be either ~left~, ~right~ or ~center~.
1821
1822    See also: [[#table-cell-borders][~org-export-table-cell-borders~]],
1823    [[#table-cell-width][~org-export-table-cell-width~]].
1824
1825 ** ~org-export-table-cell-borders~
1826    :PROPERTIES:
1827    :CUSTOM_ID: table-cell-borders
1828    :END:
1829
1830    Indicate expected borders for a given cell object.  When non-nil,
1831    return value is a list of symbols among ~top~, ~bottom~, ~above~,
1832    ~below~, ~left~ and ~right~.
1833
1834    Special values ~top~ and ~bottom~ only happen for cells in,
1835    respectively, the first and the last exportable rows.
1836
1837    See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
1838    [[#table-cell-width][~org-export-table-cell-width~]].
1839
1840 ** ~org-export-table-cell-ends-colgroup-p~
1841    :PROPERTIES:
1842    :CUSTOM_ID: table-cell-ends-colgroup-p
1843    :END:
1844
1845    Non-nil when a table cell object ends a column group.
1846
1847    See also: [[#table-cell-starts-colgroup-p][~org-export-table-cell-starts-colgroup-p~]].
1848
1849 ** ~org-export-table-cell-starts-colgroup-p~
1850    :PROPERTIES:
1851    :CUSTOM_ID: table-cell-starts-colgroup-p
1852    :END:
1853
1854    Non-nil when a table cell object starts a column group.
1855
1856    See also: [[#table-cell-ends-colgroup-p][~org-export-table-cell-ends-colgroup-p~]].
1857
1858 ** ~org-export-table-cell-width~
1859    :PROPERTIES:
1860    :CUSTOM_ID: table-cell-width
1861    :END:
1862
1863    Return expected width for contents of a given cell object.
1864
1865    Only width specified explicitely through meta-data is considered.
1866    If no such information can be found, return nil instead.
1867
1868    Some back-end may still need to know the actual width of exported
1869    cell's contents in order to compute column's width.  In that case,
1870    every cell in the column must be transcoded in order to find the
1871    widest one.  The snippet below, extracted from =org-e-ascii.el=
1872    illustrates a possible implementation.
1873
1874    #+BEGIN_SRC emacs-lisp
1875    (or (org-export-table-cell-width table-cell info)
1876        (let* ((max-width 0)
1877               (table (org-export-get-parent-table table-cell info))
1878               (specialp (org-export-table-has-special-column-p table))
1879               (col (cdr (org-export-table-cell-address table-cell info))))
1880          (org-element-map
1881           table 'table-row
1882           (lambda (row)
1883             ;; For each exportable row, get the cell at column COL and
1884             ;; transcode its contents.  Then compare its length with
1885             ;; MAX-WIDTH and keep the greater of two.
1886             (setq max-width
1887                   (max (length
1888                         (org-export-data
1889                          (org-element-contents
1890                           (elt (if specialp (car (org-element-contents row))
1891                                  (org-element-contents row))
1892                                col))
1893                          info))
1894                        max-width)))
1895           info)
1896          max-width))
1897    #+END_SRC
1898
1899    See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
1900    [[#table-cell-borders][~org-export-table-cell-borders~]].
1901
1902 ** ~org-export-table-dimensions~
1903    :PROPERTIES:
1904    :CUSTOM_ID: table-dimensions
1905    :END:
1906
1907    Return the number of exportable rows and columns in a given table.
1908
1909    See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
1910    [[#table-cell-address][~org-export-table-cell-address~]].
1911
1912 ** ~org-export-table-has-header-p~
1913    :PROPERTIES:
1914    :CUSTOM_ID: table-has-header-p
1915    :END:
1916
1917    Non-nil when table has at least two row groups.
1918
1919    See also: [[#table-has-special-column-p][~org-export-table-has-special-column-p~]],
1920    [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
1921
1922 ** ~org-export-table-has-special-column-p~
1923    :PROPERTIES:
1924    :CUSTOM_ID: table-has-special-column-p
1925    :END:
1926
1927    Non-nil when first column in the table only contains meta-data.
1928
1929    See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1930    [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
1931
1932 ** ~org-export-table-row-ends-header-p~
1933    :PROPERTIES:
1934    :CUSTOM_ID: table-row-ends-header-p
1935    :END:
1936
1937    Non-nil when a table row element ends table's header.
1938
1939    See also: [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1940    [[#table-row-group][~org-export-table-row-group~]],
1941    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1942    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1943
1944 ** ~org-export-table-row-ends-rowgroup-p~
1945    :PROPERTIES:
1946    :CUSTOM_ID: table-row-ends-rowgroup-p
1947    :END:
1948
1949    Non-nil when a a table row element ends a rowgroup, header
1950    included.
1951
1952    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
1953    [[#table-row-group][~org-export-table-row-group~]],
1954    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1955    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1956
1957 ** ~org-export-table-row-group~
1958    :PROPERTIES:
1959    :CUSTOM_ID: table-row-group
1960    :END:
1961
1962    Return row group number for a given table row element.
1963
1964    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
1965    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1966    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1967    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1968
1969 ** ~org-export-table-row-is-special-p~
1970    :PROPERTIES:
1971    :CUSTOM_ID: table-row-is-special-p
1972    :END:
1973
1974    Non-nil a given table row element only contains meta-data.
1975
1976    See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1977    [[#table-has-special-column-p][~org-export-table-has-special-column-p~]].
1978
1979 ** ~org-export-table-row-starts-header-p~
1980    :PROPERTIES:
1981    :CUSTOM_ID: table-row-starts-header-p
1982    :END:
1983
1984    Non-nil when a table row element starts table's header.
1985
1986    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
1987    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1988    [[#table-row-group][~org-export-table-row-group~]],
1989    [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1990
1991 ** ~org-export-table-row-starts-rowgroup-p~
1992    :PROPERTIES:
1993    :CUSTOM_ID: table-row-starts-rowgroup-p
1994    :END:
1995
1996    Non-nil when a table row element starts a rowgroup, header
1997    included.
1998
1999    See also: [[#table-cell-starts-ends-header-p][~org-export-table-row-ends-header-p~]],
2000    [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
2001    [[#table-row-group][~org-export-table-row-group~]],
2002    [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]].
2003
2004 ** ~org-export-translate~
2005
2006    Translate a string, i.e. "Table of Contents", according to language
2007    specification.
2008
2009    Refer to ~org-export-dictionary~ variable for the list of all
2010    supported strings.
2011
2012 ** ~org-export-unravel-code~
2013    :PROPERTIES:
2014    :CUSTOM_ID: unravel-code
2015    :END:
2016
2017    Clean source code from an =example-block= or a =src-block= element
2018    and extract code references out of it.
2019
2020    Its purpose is to allow to transform raw source code first and then
2021    integrate line numbers or references back into the final output.
2022    That final task can be achieved with the help of
2023    ~org-export-format-code~ function.
2024
2025    See also: [[#format-code][~org-export-format-code~]],
2026    [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]].
2027
2028
2029 # Local Variables:
2030 # sentence-end-double-space: t
2031 # End: