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