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