org-export: Fix smart quotes with isolated quotes
[org-mode.git] / contrib / lisp / org-export.el
1 ;;; org-export.el --- Generic Export Engine For Org
2
3 ;; Copyright (C) 2012  Free Software Foundation, Inc.
4
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7
8 ;; This program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation, either version 3 of the License, or
11 ;; (at your option) any later version.
12
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 ;; GNU General Public License for more details.
17
18 ;; You should have received a copy of the GNU General Public License
19 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
20
21 ;;; Commentary:
22 ;;
23 ;; This library implements a generic export engine for Org, built on
24 ;; its syntactical parser: Org Elements.
25 ;;
26 ;; Besides that parser, the generic exporter is made of three distinct
27 ;; parts:
28 ;;
29 ;; - The communication channel consists in a property list, which is
30 ;;   created and updated during the process.  Its use is to offer
31 ;;   every piece of information, would it be about initial environment
32 ;;   or contextual data, all in a single place.  The exhaustive list
33 ;;   of properties is given in "The Communication Channel" section of
34 ;;   this file.
35 ;;
36 ;; - The transcoder walks the parse tree, ignores or treat as plain
37 ;;   text elements and objects according to export options, and
38 ;;   eventually calls back-end specific functions to do the real
39 ;;   transcoding, concatenating their return value along the way.
40 ;;
41 ;; - The filter system is activated at the very beginning and the very
42 ;;   end of the export process, and each time an element or an object
43 ;;   has been converted.  It is the entry point to fine-tune standard
44 ;;   output from back-end transcoders.  See "The Filter System"
45 ;;   section for more information.
46 ;;
47 ;; The core function is `org-export-as'.  It returns the transcoded
48 ;; buffer as a string.
49 ;;
50 ;; An export back-end is defined with `org-export-define-backend',
51 ;; which sets one mandatory variable: his translation table.  Its name
52 ;; is always `org-BACKEND-translate-alist' where BACKEND stands for
53 ;; the name chosen for the back-end.  Its value is an alist whose keys
54 ;; are elements and objects types and values translator functions.
55 ;; See function's docstring for more information about translators.
56 ;;
57 ;; Optionally, `org-export-define-backend' can also support specific
58 ;; buffer keywords, OPTION keyword's items and filters.  Also refer to
59 ;; function documentation for more information.
60 ;;
61 ;; If the new back-end shares most properties with another one,
62 ;; `org-export-define-derived-backend' can be used to simplify the
63 ;; process.
64 ;;
65 ;; Any back-end can define its own variables.  Among them, those
66 ;; customizable should belong to the `org-export-BACKEND' group.
67 ;;
68 ;; Tools for common tasks across back-ends are implemented in the
69 ;; penultimate part of this file.  A dispatcher for standard back-ends
70 ;; is provided in the last one.
71
72 ;;; Code:
73
74 (eval-when-compile (require 'cl))
75 (require 'org-element)
76
77 (declare-function org-e-publish "org-e-publish" (project &optional force))
78 (declare-function org-e-publish-all "org-e-publish" (&optional force))
79 (declare-function org-e-publish-current-file "org-e-publish" (&optional force))
80 (declare-function org-e-publish-current-project "org-e-publish"
81                   (&optional force))
82 (declare-function org-export-blocks-preprocess "ob-exp")
83
84 (defvar org-e-publish-project-alist)
85 (defvar org-table-number-fraction)
86 (defvar org-table-number-regexp)
87
88
89 \f
90 ;;; Internal Variables
91 ;;
92 ;; Among internal variables, the most important is
93 ;; `org-export-options-alist'.  This variable define the global export
94 ;; options, shared between every exporter, and how they are acquired.
95
96 (defconst org-export-max-depth 19
97   "Maximum nesting depth for headlines, counting from 0.")
98
99 (defconst org-export-options-alist
100   '((:author "AUTHOR" nil user-full-name t)
101     (:creator "CREATOR" nil org-export-creator-string)
102     (:date "DATE" nil nil t)
103     (:description "DESCRIPTION" nil nil newline)
104     (:email "EMAIL" nil user-mail-address t)
105     (:exclude-tags "EXCLUDE_TAGS" nil org-export-exclude-tags split)
106     (:headline-levels nil "H" org-export-headline-levels)
107     (:keywords "KEYWORDS" nil nil space)
108     (:language "LANGUAGE" nil org-export-default-language t)
109     (:preserve-breaks nil "\\n" org-export-preserve-breaks)
110     (:section-numbers nil "num" org-export-with-section-numbers)
111     (:select-tags "SELECT_TAGS" nil org-export-select-tags split)
112     (:time-stamp-file nil "timestamp" org-export-time-stamp-file)
113     (:title "TITLE" nil nil space)
114     (:with-archived-trees nil "arch" org-export-with-archived-trees)
115     (:with-author nil "author" org-export-with-author)
116     (:with-clocks nil "c" org-export-with-clocks)
117     (:with-creator nil "creator" org-export-with-creator)
118     (:with-drawers nil "d" org-export-with-drawers)
119     (:with-email nil "email" org-export-with-email)
120     (:with-emphasize nil "*" org-export-with-emphasize)
121     (:with-entities nil "e" org-export-with-entities)
122     (:with-fixed-width nil ":" org-export-with-fixed-width)
123     (:with-footnotes nil "f" org-export-with-footnotes)
124     (:with-inlinetasks nil "inline" org-export-with-inlinetasks)
125     (:with-plannings nil "p" org-export-with-planning)
126     (:with-priority nil "pri" org-export-with-priority)
127     (:with-smart-quotes nil "'" org-export-with-smart-quotes)
128     (:with-special-strings nil "-" org-export-with-special-strings)
129     (:with-statistics-cookies nil "stat" org-export-with-statistics-cookies)
130     (:with-sub-superscript nil "^" org-export-with-sub-superscripts)
131     (:with-toc nil "toc" org-export-with-toc)
132     (:with-tables nil "|" org-export-with-tables)
133     (:with-tags nil "tags" org-export-with-tags)
134     (:with-tasks nil "tasks" org-export-with-tasks)
135     (:with-timestamps nil "<" org-export-with-timestamps)
136     (:with-todo-keywords nil "todo" org-export-with-todo-keywords))
137   "Alist between export properties and ways to set them.
138
139 The CAR of the alist is the property name, and the CDR is a list
140 like (KEYWORD OPTION DEFAULT BEHAVIOUR) where:
141
142 KEYWORD is a string representing a buffer keyword, or nil.  Each
143   property defined this way can also be set, during subtree
144   export, through an headline property named after the keyword
145   with the \"EXPORT_\" prefix (i.e. DATE keyword and EXPORT_DATE
146   property).
147 OPTION is a string that could be found in an #+OPTIONS: line.
148 DEFAULT is the default value for the property.
149 BEHAVIOUR determine how Org should handle multiple keywords for
150   the same property.  It is a symbol among:
151   nil       Keep old value and discard the new one.
152   t         Replace old value with the new one.
153   `space'   Concatenate the values, separating them with a space.
154   `newline' Concatenate the values, separating them with
155             a newline.
156   `split'   Split values at white spaces, and cons them to the
157             previous list.
158
159 KEYWORD and OPTION have precedence over DEFAULT.
160
161 All these properties should be back-end agnostic.  Back-end
162 specific properties are set through `org-export-define-backend'.
163 Properties redefined there have precedence over these.")
164
165 (defconst org-export-special-keywords '("SETUP_FILE" "OPTIONS")
166   "List of in-buffer keywords that require special treatment.
167 These keywords are not directly associated to a property.  The
168 way they are handled must be hard-coded into
169 `org-export--get-inbuffer-options' function.")
170
171 (defconst org-export-filters-alist
172   '((:filter-bold . org-export-filter-bold-functions)
173     (:filter-babel-call . org-export-filter-babel-call-functions)
174     (:filter-center-block . org-export-filter-center-block-functions)
175     (:filter-clock . org-export-filter-clock-functions)
176     (:filter-code . org-export-filter-code-functions)
177     (:filter-comment . org-export-filter-comment-functions)
178     (:filter-comment-block . org-export-filter-comment-block-functions)
179     (:filter-diary-sexp . org-export-filter-diary-sexp-functions)
180     (:filter-drawer . org-export-filter-drawer-functions)
181     (:filter-dynamic-block . org-export-filter-dynamic-block-functions)
182     (:filter-entity . org-export-filter-entity-functions)
183     (:filter-example-block . org-export-filter-example-block-functions)
184     (:filter-export-block . org-export-filter-export-block-functions)
185     (:filter-export-snippet . org-export-filter-export-snippet-functions)
186     (:filter-final-output . org-export-filter-final-output-functions)
187     (:filter-fixed-width . org-export-filter-fixed-width-functions)
188     (:filter-footnote-definition . org-export-filter-footnote-definition-functions)
189     (:filter-footnote-reference . org-export-filter-footnote-reference-functions)
190     (:filter-headline . org-export-filter-headline-functions)
191     (:filter-horizontal-rule . org-export-filter-horizontal-rule-functions)
192     (:filter-inline-babel-call . org-export-filter-inline-babel-call-functions)
193     (:filter-inline-src-block . org-export-filter-inline-src-block-functions)
194     (:filter-inlinetask . org-export-filter-inlinetask-functions)
195     (:filter-italic . org-export-filter-italic-functions)
196     (:filter-item . org-export-filter-item-functions)
197     (:filter-keyword . org-export-filter-keyword-functions)
198     (:filter-latex-environment . org-export-filter-latex-environment-functions)
199     (:filter-latex-fragment . org-export-filter-latex-fragment-functions)
200     (:filter-line-break . org-export-filter-line-break-functions)
201     (:filter-link . org-export-filter-link-functions)
202     (:filter-macro . org-export-filter-macro-functions)
203     (:filter-node-property . org-export-filter-node-property-functions)
204     (:filter-paragraph . org-export-filter-paragraph-functions)
205     (:filter-parse-tree . org-export-filter-parse-tree-functions)
206     (:filter-plain-list . org-export-filter-plain-list-functions)
207     (:filter-plain-text . org-export-filter-plain-text-functions)
208     (:filter-planning . org-export-filter-planning-functions)
209     (:filter-property-drawer . org-export-filter-property-drawer-functions)
210     (:filter-quote-block . org-export-filter-quote-block-functions)
211     (:filter-quote-section . org-export-filter-quote-section-functions)
212     (:filter-radio-target . org-export-filter-radio-target-functions)
213     (:filter-section . org-export-filter-section-functions)
214     (:filter-special-block . org-export-filter-special-block-functions)
215     (:filter-src-block . org-export-filter-src-block-functions)
216     (:filter-statistics-cookie . org-export-filter-statistics-cookie-functions)
217     (:filter-strike-through . org-export-filter-strike-through-functions)
218     (:filter-subscript . org-export-filter-subscript-functions)
219     (:filter-superscript . org-export-filter-superscript-functions)
220     (:filter-table . org-export-filter-table-functions)
221     (:filter-table-cell . org-export-filter-table-cell-functions)
222     (:filter-table-row . org-export-filter-table-row-functions)
223     (:filter-target . org-export-filter-target-functions)
224     (:filter-timestamp . org-export-filter-timestamp-functions)
225     (:filter-underline . org-export-filter-underline-functions)
226     (:filter-verbatim . org-export-filter-verbatim-functions)
227     (:filter-verse-block . org-export-filter-verse-block-functions))
228   "Alist between filters properties and initial values.
229
230 The key of each association is a property name accessible through
231 the communication channel.  Its value is a configurable global
232 variable defining initial filters.
233
234 This list is meant to install user specified filters.  Back-end
235 developers may install their own filters using
236 `org-export-define-backend'.  Filters defined there will always
237 be prepended to the current list, so they always get applied
238 first.")
239
240 (defconst org-export-default-inline-image-rule
241   `(("file" .
242      ,(format "\\.%s\\'"
243               (regexp-opt
244                '("png" "jpeg" "jpg" "gif" "tiff" "tif" "xbm"
245                  "xpm" "pbm" "pgm" "ppm") t))))
246   "Default rule for link matching an inline image.
247 This rule applies to links with no description.  By default, it
248 will be considered as an inline image if it targets a local file
249 whose extension is either \"png\", \"jpeg\", \"jpg\", \"gif\",
250 \"tiff\", \"tif\", \"xbm\", \"xpm\", \"pbm\", \"pgm\" or \"ppm\".
251 See `org-export-inline-image-p' for more information about
252 rules.")
253
254
255 \f
256 ;;; User-configurable Variables
257 ;;
258 ;; Configuration for the masses.
259 ;;
260 ;; They should never be accessed directly, as their value is to be
261 ;; stored in a property list (cf. `org-export-options-alist').
262 ;; Back-ends will read their value from there instead.
263
264 (defgroup org-export nil
265   "Options for exporting Org mode files."
266   :tag "Org Export"
267   :group 'org)
268
269 (defgroup org-export-general nil
270   "General options for export engine."
271   :tag "Org Export General"
272   :group 'org-export)
273
274 (defcustom org-export-with-archived-trees 'headline
275   "Whether sub-trees with the ARCHIVE tag should be exported.
276
277 This can have three different values:
278 nil         Do not export, pretend this tree is not present.
279 t           Do export the entire tree.
280 `headline'  Only export the headline, but skip the tree below it.
281
282 This option can also be set with the #+OPTIONS line,
283 e.g. \"arch:nil\"."
284   :group 'org-export-general
285   :type '(choice
286           (const :tag "Not at all" nil)
287           (const :tag "Headline only" 'headline)
288           (const :tag "Entirely" t)))
289
290 (defcustom org-export-with-author t
291   "Non-nil means insert author name into the exported file.
292 This option can also be set with the #+OPTIONS line,
293 e.g. \"author:nil\"."
294   :group 'org-export-general
295   :type 'boolean)
296
297 (defcustom org-export-with-clocks nil
298   "Non-nil means export CLOCK keywords.
299 This option can also be set with the #+OPTIONS line,
300 e.g. \"c:t\"."
301   :group 'org-export-general
302   :type 'boolean)
303
304 (defcustom org-export-with-creator 'comment
305   "Non-nil means the postamble should contain a creator sentence.
306
307 The sentence can be set in `org-export-creator-string' and
308 defaults to \"Generated by Org mode XX in Emacs XXX.\".
309
310 If the value is `comment' insert it as a comment."
311   :group 'org-export-general
312   :type '(choice
313           (const :tag "No creator sentence" nil)
314           (const :tag "Sentence as a comment" 'comment)
315           (const :tag "Insert the sentence" t)))
316
317 (defcustom org-export-creator-string
318   (format "Generated by Org mode %s in Emacs %s."
319           (if (fboundp 'org-version) (org-version) "(Unknown)")
320           emacs-version)
321   "String to insert at the end of the generated document."
322   :group 'org-export-general
323   :type '(string :tag "Creator string"))
324
325 (defcustom org-export-with-drawers t
326   "Non-nil means export contents of standard drawers.
327
328 When t, all drawers are exported.  This may also be a list of
329 drawer names to export.  This variable doesn't apply to
330 properties drawers.
331
332 This option can also be set with the #+OPTIONS line,
333 e.g. \"d:nil\"."
334   :group 'org-export-general
335   :type '(choice
336           (const :tag "All drawers" t)
337           (const :tag "None" nil)
338           (repeat :tag "Selected drawers"
339                   (string :tag "Drawer name"))))
340
341 (defcustom org-export-with-email nil
342   "Non-nil means insert author email into the exported file.
343 This option can also be set with the #+OPTIONS line,
344 e.g. \"email:t\"."
345   :group 'org-export-general
346   :type 'boolean)
347
348 (defcustom org-export-with-emphasize t
349   "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
350
351 If the export target supports emphasizing text, the word will be
352 typeset in bold, italic, or underlined, respectively.  Not all
353 export backends support this.
354
355 This option can also be set with the #+OPTIONS line, e.g. \"*:nil\"."
356   :group 'org-export-general
357   :type 'boolean)
358
359 (defcustom org-export-exclude-tags '("noexport")
360   "Tags that exclude a tree from export.
361
362 All trees carrying any of these tags will be excluded from
363 export.  This is without condition, so even subtrees inside that
364 carry one of the `org-export-select-tags' will be removed.
365
366 This option can also be set with the #+EXCLUDE_TAGS: keyword."
367   :group 'org-export-general
368   :type '(repeat (string :tag "Tag")))
369
370 (defcustom org-export-with-fixed-width t
371   "Non-nil means lines starting with \":\" will be in fixed width font.
372
373 This can be used to have pre-formatted text, fragments of code
374 etc.  For example:
375   : ;; Some Lisp examples
376   : (while (defc cnt)
377   :   (ding))
378 will be looking just like this in also HTML.  See also the QUOTE
379 keyword.  Not all export backends support this.
380
381 This option can also be set with the #+OPTIONS line, e.g. \"::nil\"."
382   :group 'org-export-translation
383   :type 'boolean)
384
385 (defcustom org-export-with-footnotes t
386   "Non-nil means Org footnotes should be exported.
387 This option can also be set with the #+OPTIONS line,
388 e.g. \"f:nil\"."
389   :group 'org-export-general
390   :type 'boolean)
391
392 (defcustom org-export-headline-levels 3
393   "The last level which is still exported as a headline.
394
395 Inferior levels will produce itemize lists when exported.
396
397 This option can also be set with the #+OPTIONS line, e.g. \"H:2\"."
398   :group 'org-export-general
399   :type 'integer)
400
401 (defcustom org-export-default-language "en"
402   "The default language for export and clocktable translations, as a string.
403 This may have an association in
404 `org-clock-clocktable-language-setup'."
405   :group 'org-export-general
406   :type '(string :tag "Language"))
407
408 (defcustom org-export-preserve-breaks nil
409   "Non-nil means preserve all line breaks when exporting.
410
411 Normally, in HTML output paragraphs will be reformatted.
412
413 This option can also be set with the #+OPTIONS line,
414 e.g. \"\\n:t\"."
415   :group 'org-export-general
416   :type 'boolean)
417
418 (defcustom org-export-with-entities t
419   "Non-nil means interpret entities when exporting.
420
421 For example, HTML export converts \\alpha to &alpha; and \\AA to
422 &Aring;.
423
424 For a list of supported names, see the constant `org-entities'
425 and the user option `org-entities-user'.
426
427 This option can also be set with the #+OPTIONS line,
428 e.g. \"e:nil\"."
429   :group 'org-export-general
430   :type 'boolean)
431
432 (defcustom org-export-with-inlinetasks t
433   "Non-nil means inlinetasks should be exported.
434 This option can also be set with the #+OPTIONS line,
435 e.g. \"inline:nil\"."
436   :group 'org-export-general
437   :type 'boolean)
438
439 (defcustom org-export-with-planning nil
440   "Non-nil means include planning info in export.
441 This option can also be set with the #+OPTIONS: line,
442 e.g. \"p:t\"."
443   :group 'org-export-general
444   :type 'boolean)
445
446 (defcustom org-export-with-priority nil
447   "Non-nil means include priority cookies in export.
448 This option can also be set with the #+OPTIONS line,
449 e.g. \"pri:t\"."
450   :group 'org-export-general
451   :type 'boolean)
452
453 (defcustom org-export-with-section-numbers t
454   "Non-nil means add section numbers to headlines when exporting.
455
456 When set to an integer n, numbering will only happen for
457 headlines whose relative level is higher or equal to n.
458
459 This option can also be set with the #+OPTIONS line,
460 e.g. \"num:t\"."
461   :group 'org-export-general
462   :type 'boolean)
463
464 (defcustom org-export-select-tags '("export")
465   "Tags that select a tree for export.
466
467 If any such tag is found in a buffer, all trees that do not carry
468 one of these tags will be ignored during export.  Inside trees
469 that are selected like this, you can still deselect a subtree by
470 tagging it with one of the `org-export-exclude-tags'.
471
472 This option can also be set with the #+SELECT_TAGS: keyword."
473   :group 'org-export-general
474   :type '(repeat (string :tag "Tag")))
475
476 (defcustom org-export-with-smart-quotes nil
477   "Non-nil means activate smart quotes during export.
478 This option can also be set with the #+OPTIONS: line,
479 e.g. \"':t\"."
480   :group 'org-export-general
481   :type 'boolean)
482
483 (defcustom org-export-with-special-strings t
484   "Non-nil means interpret \"\\-\", \"--\" and \"---\" for export.
485
486 When this option is turned on, these strings will be exported as:
487
488    Org     HTML     LaTeX    UTF-8
489   -----+----------+--------+-------
490    \\-    &shy;      \\-
491    --    &ndash;    --         –
492    ---   &mdash;    ---        —
493    ...   &hellip;   \\ldots     …
494
495 This option can also be set with the #+OPTIONS line,
496 e.g. \"-:nil\"."
497   :group 'org-export-general
498   :type 'boolean)
499
500 (defcustom org-export-with-statistics-cookies t
501   "Non-nil means include statistics cookies in export.
502 This option can also be set with the #+OPTIONS: line,
503 e.g. \"stat:nil\""
504   :group 'org-export-general
505   :type 'boolean)
506
507 (defcustom org-export-with-sub-superscripts t
508   "Non-nil means interpret \"_\" and \"^\" for export.
509
510 When this option is turned on, you can use TeX-like syntax for
511 sub- and superscripts.  Several characters after \"_\" or \"^\"
512 will be considered as a single item - so grouping with {} is
513 normally not needed.  For example, the following things will be
514 parsed as single sub- or superscripts.
515
516  10^24   or   10^tau     several digits will be considered 1 item.
517  10^-12  or   10^-tau    a leading sign with digits or a word
518  x^2-y^3                 will be read as x^2 - y^3, because items are
519                          terminated by almost any nonword/nondigit char.
520  x_{i^2} or   x^(2-i)    braces or parenthesis do grouping.
521
522 Still, ambiguity is possible - so when in doubt use {} to enclose
523 the sub/superscript.  If you set this variable to the symbol
524 `{}', the braces are *required* in order to trigger
525 interpretations as sub/superscript.  This can be helpful in
526 documents that need \"_\" frequently in plain text.
527
528 This option can also be set with the #+OPTIONS line,
529 e.g. \"^:nil\"."
530   :group 'org-export-general
531   :type '(choice
532           (const :tag "Interpret them" t)
533           (const :tag "Curly brackets only" {})
534           (const :tag "Do not interpret them" nil)))
535
536 (defcustom org-export-with-toc t
537   "Non-nil means create a table of contents in exported files.
538
539 The TOC contains headlines with levels up
540 to`org-export-headline-levels'.  When an integer, include levels
541 up to N in the toc, this may then be different from
542 `org-export-headline-levels', but it will not be allowed to be
543 larger than the number of headline levels.  When nil, no table of
544 contents is made.
545
546 This option can also be set with the #+OPTIONS line,
547 e.g. \"toc:nil\" or \"toc:3\"."
548   :group 'org-export-general
549   :type '(choice
550           (const :tag "No Table of Contents" nil)
551           (const :tag "Full Table of Contents" t)
552           (integer :tag "TOC to level")))
553
554 (defcustom org-export-with-tables t
555   "If non-nil, lines starting with \"|\" define a table.
556 For example:
557
558   | Name        | Address  | Birthday  |
559   |-------------+----------+-----------|
560   | Arthur Dent | England  | 29.2.2100 |
561
562 This option can also be set with the #+OPTIONS line, e.g. \"|:nil\"."
563   :group 'org-export-general
564   :type 'boolean)
565
566 (defcustom org-export-with-tags t
567   "If nil, do not export tags, just remove them from headlines.
568
569 If this is the symbol `not-in-toc', tags will be removed from
570 table of contents entries, but still be shown in the headlines of
571 the document.
572
573 This option can also be set with the #+OPTIONS line,
574 e.g. \"tags:nil\"."
575   :group 'org-export-general
576   :type '(choice
577           (const :tag "Off" nil)
578           (const :tag "Not in TOC" not-in-toc)
579           (const :tag "On" t)))
580
581 (defcustom org-export-with-tasks t
582   "Non-nil means include TODO items for export.
583 This may have the following values:
584 t                    include tasks independent of state.
585 todo                 include only tasks that are not yet done.
586 done                 include only tasks that are already done.
587 nil                  remove all tasks before export
588 list of keywords     keep only tasks with these keywords"
589   :group 'org-export-general
590   :type '(choice
591           (const :tag "All tasks" t)
592           (const :tag "No tasks" nil)
593           (const :tag "Not-done tasks" todo)
594           (const :tag "Only done tasks" done)
595           (repeat :tag "Specific TODO keywords"
596                   (string :tag "Keyword"))))
597
598 (defcustom org-export-time-stamp-file t
599   "Non-nil means insert a time stamp into the exported file.
600 The time stamp shows when the file was created.
601
602 This option can also be set with the #+OPTIONS line,
603 e.g. \"timestamp:nil\"."
604   :group 'org-export-general
605   :type 'boolean)
606
607 (defcustom org-export-with-timestamps t
608   "Non nil means allow timestamps in export.
609
610 It can be set to `active', `inactive', t or nil, in order to
611 export, respectively, only active timestamps, only inactive ones,
612 all of them or none.
613
614 This option can also be set with the #+OPTIONS line, e.g.
615 \"<:nil\"."
616   :group 'org-export-general
617   :type '(choice
618           (const :tag "All timestamps" t)
619           (const :tag "Only active timestamps" active)
620           (const :tag "Only inactive timestamps" inactive)
621           (const :tag "No timestamp" nil)))
622
623 (defcustom org-export-with-todo-keywords t
624   "Non-nil means include TODO keywords in export.
625 When nil, remove all these keywords from the export."
626   :group 'org-export-general
627   :type 'boolean)
628
629 (defcustom org-export-allow-BIND 'confirm
630   "Non-nil means allow #+BIND to define local variable values for export.
631 This is a potential security risk, which is why the user must
632 confirm the use of these lines."
633   :group 'org-export-general
634   :type '(choice
635           (const :tag "Never" nil)
636           (const :tag "Always" t)
637           (const :tag "Ask a confirmation for each file" confirm)))
638
639 (defcustom org-export-snippet-translation-alist nil
640   "Alist between export snippets back-ends and exporter back-ends.
641
642 This variable allows to provide shortcuts for export snippets.
643
644 For example, with a value of '\(\(\"h\" . \"e-html\"\)\), the
645 HTML back-end will recognize the contents of \"@@h:<b>@@\" as
646 HTML code while every other back-end will ignore it."
647   :group 'org-export-general
648   :type '(repeat
649           (cons
650            (string :tag "Shortcut")
651            (string :tag "Back-end"))))
652
653 (defcustom org-export-coding-system nil
654   "Coding system for the exported file."
655   :group 'org-export-general
656   :type 'coding-system)
657
658 (defcustom org-export-copy-to-kill-ring t
659   "Non-nil means exported stuff will also be pushed onto the kill ring."
660   :group 'org-export-general
661   :type 'boolean)
662
663 (defcustom org-export-initial-scope 'buffer
664   "The initial scope when exporting with `org-export-dispatch'.
665 This variable can be either set to `buffer' or `subtree'."
666   :group 'org-export-general
667   :type '(choice
668           (const :tag "Export current buffer" 'buffer)
669           (const :tag "Export current subtree" 'subtree)))
670
671 (defcustom org-export-show-temporary-export-buffer t
672   "Non-nil means show buffer after exporting to temp buffer.
673 When Org exports to a file, the buffer visiting that file is ever
674 shown, but remains buried.  However, when exporting to
675 a temporary buffer, that buffer is popped up in a second window.
676 When this variable is nil, the buffer remains buried also in
677 these cases."
678   :group 'org-export-general
679   :type 'boolean)
680
681 (defcustom org-export-dispatch-use-expert-ui nil
682   "Non-nil means using a non-intrusive `org-export-dispatch'.
683 In that case, no help buffer is displayed.  Though, an indicator
684 for current export scope is added to the prompt (\"b\" when
685 output is restricted to body only, \"s\" when it is restricted to
686 the current subtree, \"v\" when only visible elements are
687 considered for export and \"f\" when publishing functions should
688 be passed the FORCE argument).  Also, \[?] allows to switch back
689 to standard mode."
690   :group 'org-export-general
691   :type 'boolean)
692
693
694 \f
695 ;;; Defining New Back-ends
696 ;;
697 ;; `org-export-define-backend' is the standard way to define an export
698 ;; back-end.  It allows to specify translators, filters, buffer
699 ;; options and a menu entry.  If the new back-end shares translators
700 ;; with another back-end, `org-export-define-derived-backend' may be
701 ;; used instead.
702 ;;
703 ;; Eventually `org-export-barf-if-invalid-backend' returns an error
704 ;; when a given back-end hasn't been registered yet.
705
706 (defmacro org-export-define-backend (backend translators &rest body)
707   "Define a new back-end BACKEND.
708
709 TRANSLATORS is an alist between object or element types and
710 functions handling them.
711
712 These functions should return a string without any trailing
713 space, or nil.  They must accept three arguments: the object or
714 element itself, its contents or nil when it isn't recursive and
715 the property list used as a communication channel.
716
717 Contents, when not nil, are stripped from any global indentation
718 \(although the relative one is preserved).  They also always end
719 with a single newline character.
720
721 If, for a given type, no function is found, that element or
722 object type will simply be ignored, along with any blank line or
723 white space at its end.  The same will happen if the function
724 returns the nil value.  If that function returns the empty
725 string, the type will be ignored, but the blank lines or white
726 spaces will be kept.
727
728 In addition to element and object types, one function can be
729 associated to the `template' symbol and another one to the
730 `plain-text' symbol.
731
732 The former returns the final transcoded string, and can be used
733 to add a preamble and a postamble to document's body.  It must
734 accept two arguments: the transcoded string and the property list
735 containing export options.
736
737 The latter, when defined, is to be called on every text not
738 recognized as an element or an object.  It must accept two
739 arguments: the text string and the information channel.  It is an
740 appropriate place to protect special chars relative to the
741 back-end.
742
743 BODY can start with pre-defined keyword arguments.  The following
744 keywords are understood:
745
746   :export-block
747
748     String, or list of strings, representing block names that
749     will not be parsed.  This is used to specify blocks that will
750     contain raw code specific to the back-end.  These blocks
751     still have to be handled by the relative `export-block' type
752     translator.
753
754   :filters-alist
755
756     Alist between filters and function, or list of functions,
757     specific to the back-end.  See `org-export-filters-alist' for
758     a list of all allowed filters.  Filters defined here
759     shouldn't make a back-end test, as it may prevent back-ends
760     derived from this one to behave properly.
761
762   :menu-entry
763
764     Menu entry for the export dispatcher.  It should be a list
765     like:
766
767       \(KEY DESCRIPTION ACTION-OR-MENU)
768
769     where :
770
771       KEY is a free character selecting the back-end.
772       DESCRIPTION is a string naming the back-end.
773       ACTION-OR-MENU is either a function or an alist.
774
775       If it is an action, it will be called with three arguments:
776       SUBTREEP, VISIBLE-ONLY and BODY-ONLY.  See `org-export-as'
777       for further explanations.
778
779       If it is an alist, associations should follow the
780       pattern:
781
782         \(KEY DESCRIPTION ACTION)
783
784       where KEY, DESCRIPTION and ACTION are described above.
785
786     Valid values include:
787
788       \(?m \"My Special Back-end\" my-special-export-function)
789
790       or
791
792       \(?l \"Export to LaTeX\"
793            \((?b \"TEX (buffer)\" org-e-latex-export-as-latex)
794             \(?l \"TEX (file)\" org-e-latex-export-to-latex)
795             \(?p \"PDF file\" org-e-latex-export-to-pdf)
796             \(?o \"PDF file and open\"
797                 \(lambda (subtree visible body-only)
798                    \(org-open-file
799                      \(org-e-latex-export-to-pdf subtree visible body-only))))))
800
801   :options-alist
802
803     Alist between back-end specific properties introduced in
804     communication channel and how their value are acquired.  See
805     `org-export-options-alist' for more information about
806     structure of the values."
807   (declare (debug (&define name sexp [&rest [keywordp sexp]] defbody))
808            (indent 1))
809   (let (export-block filters menu-entry options)
810     (while (keywordp (car body))
811       (case (pop body)
812         (:export-block (let ((names (pop body)))
813                          (setq export-block
814                                (if (consp names) (mapcar 'upcase names)
815                                  (list (upcase names))))))
816         (:filters-alist (setq filters (pop body)))
817         (:menu-entry (setq menu-entry (pop body)))
818         (:options-alist (setq options (pop body)))
819         (t (pop body))))
820     `(progn
821        ;; Define translators.
822        (defvar ,(intern (format "org-%s-translate-alist" backend)) ',translators
823          "Alist between element or object types and translators.")
824        ;; Define options.
825        ,(when options
826           `(defconst ,(intern (format "org-%s-options-alist" backend)) ',options
827              ,(format "Alist between %s export properties and ways to set them.
828 See `org-export-options-alist' for more information on the
829 structure of the values."
830                       backend)))
831        ;; Define filters.
832        ,(when filters
833           `(defconst ,(intern (format "org-%s-filters-alist" backend)) ',filters
834              "Alist between filters keywords and back-end specific filters.
835 See `org-export-filters-alist' for more information."))
836        ;; Tell parser to not parse EXPORT-BLOCK blocks.
837        ,(when export-block
838           `(mapc
839             (lambda (name)
840               (add-to-list 'org-element-block-name-alist
841                            `(,name . org-element-export-block-parser)))
842             ',export-block))
843        ;; Add an entry for back-end in `org-export-dispatch'.
844        ,(when menu-entry
845           `(unless (assq (car ',menu-entry) org-export-dispatch-menu-entries)
846              (add-to-list 'org-export-dispatch-menu-entries ',menu-entry)))
847        ;; Splice in the body, if any.
848        ,@body)))
849
850 (defmacro org-export-define-derived-backend (child parent &rest body)
851   "Create a new back-end as a variant of an existing one.
852
853 CHILD is the name of the derived back-end.  PARENT is the name of
854 the parent back-end.
855
856 BODY can start with pre-defined keyword arguments.  The following
857 keywords are understood:
858
859   :export-block
860
861     String, or list of strings, representing block names that
862     will not be parsed.  This is used to specify blocks that will
863     contain raw code specific to the back-end.  These blocks
864     still have to be handled by the relative `export-block' type
865     translator.
866
867   :filters-alist
868
869     Alist of filters that will overwrite or complete filters
870     defined in PARENT back-end.  See `org-export-filters-alist'
871     for a list of allowed filters.
872
873   :menu-entry
874
875     Menu entry for the export dispatcher.  See
876     `org-export-define-backend' for more information about the
877     expected value.
878
879   :options-alist
880
881     Alist of back-end specific properties that will overwrite or
882     complete those defined in PARENT back-end.  Refer to
883     `org-export-options-alist' for more information about
884     structure of the values.
885
886   :sub-menu-entry
887
888     Append entries to an existing menu in the export dispatcher.
889     The associated value should be a list whose CAR is the
890     character selecting the menu to expand and CDR a list of
891     entries following the pattern:
892
893       \(KEY DESCRIPTION ACTION)
894
895     where KEY is a free character triggering the action,
896     DESCRIPTION is a string defining the action, and ACTION is
897     a function that will be called with three arguments:
898     SUBTREEP, VISIBLE-ONLY and BODY-ONLY.  See `org-export-as'
899     for further explanations.
900
901     Valid values include:
902
903       \(?l (?P \"As PDF file (Beamer)\" org-e-beamer-export-to-pdf)
904           \(?O \"As PDF file and open (Beamer)\"
905               \(lambda (s v b)
906                 \(org-open-file (org-e-beamer-export-to-pdf s v b)))))
907
908   :translate-alist
909
910     Alist of element and object types and transcoders that will
911     overwrite or complete transcode table from PARENT back-end.
912     Refer to `org-export-define-backend' for detailed information
913     about transcoders.
914
915 As an example, here is how one could define \"my-latex\" back-end
916 as a variant of `e-latex' back-end with a custom template
917 function:
918
919   \(org-export-define-derived-backend my-latex e-latex
920      :translate-alist ((template . my-latex-template-fun)))
921
922 The back-end could then be called with, for example:
923
924   \(org-export-to-buffer 'my-latex \"*Test my-latex*\")"
925   (declare (debug (&define name sexp [&rest [keywordp sexp]] def-body))
926            (indent 2))
927   (let (export-block filters menu-entry options sub-menu-entry translate)
928     (while (keywordp (car body))
929       (case (pop body)
930         (:export-block (let ((names (pop body)))
931                          (setq export-block
932                                (if (consp names) (mapcar 'upcase names)
933                                  (list (upcase names))))))
934         (:filters-alist (setq filters (pop body)))
935         (:menu-entry (setq menu-entry (pop body)))
936         (:options-alist (setq options (pop body)))
937         (:sub-menu-entry (setq sub-menu-entry (pop body)))
938         (:translate-alist (setq translate (pop body)))
939         (t (pop body))))
940     `(progn
941        ;; Tell parser to not parse EXPORT-BLOCK blocks.
942        ,(when export-block
943           `(mapc
944             (lambda (name)
945               (add-to-list 'org-element-block-name-alist
946                            `(,name . org-element-export-block-parser)))
947             ',export-block))
948        ;; Define filters.
949        ,(let ((parent-filters (intern (format "org-%s-filters-alist" parent))))
950           (when (or (boundp parent-filters) filters)
951             `(defconst ,(intern (format "org-%s-filters-alist" child))
952                ',(append filters
953                          (and (boundp parent-filters)
954                               (copy-sequence (symbol-value parent-filters))))
955                "Alist between filters keywords and back-end specific filters.
956 See `org-export-filters-alist' for more information.")))
957        ;; Define options.
958        ,(let ((parent-options (intern (format "org-%s-options-alist" parent))))
959           (when (or (boundp parent-options) options)
960             `(defconst ,(intern (format "org-%s-options-alist" child))
961                ',(append options
962                          (and (boundp parent-options)
963                               (copy-sequence (symbol-value parent-options))))
964                ,(format "Alist between %s export properties and ways to set them.
965 See `org-export-options-alist' for more information on the
966 structure of the values."
967                         child))))
968        ;; Define translators.
969        (defvar ,(intern (format "org-%s-translate-alist" child))
970          ',(append translate
971                    (copy-sequence
972                     (symbol-value
973                      (intern (format "org-%s-translate-alist" parent)))))
974          "Alist between element or object types and translators.")
975        ;; Add an entry for back-end in `org-export-dispatch'.
976        ,(when menu-entry
977           `(unless (assq (car ',menu-entry) org-export-dispatch-menu-entries)
978              (add-to-list 'org-export-dispatch-menu-entries ',menu-entry)))
979        ,(when sub-menu-entry
980           (let ((menu (nth 2 (assq (car sub-menu-entry)
981                                    org-export-dispatch-menu-entries))))
982             (when menu `(nconc ',menu
983                                ',(org-remove-if (lambda (e) (member e menu))
984                                                 (cdr sub-menu-entry))))))
985        ;; Splice in the body, if any.
986        ,@body)))
987
988 (defun org-export-barf-if-invalid-backend (backend)
989   "Signal an error if BACKEND isn't defined."
990   (unless (boundp (intern (format "org-%s-translate-alist" backend)))
991     (error "Unknown \"%s\" back-end: Aborting export" backend)))
992
993
994 \f
995 ;;; The Communication Channel
996 ;;
997 ;; During export process, every function has access to a number of
998 ;; properties.  They are of two types:
999 ;;
1000 ;; 1. Environment options are collected once at the very beginning of
1001 ;;    the process, out of the original buffer and configuration.
1002 ;;    Collecting them is handled by `org-export-get-environment'
1003 ;;    function.
1004 ;;
1005 ;;    Most environment options are defined through the
1006 ;;    `org-export-options-alist' variable.
1007 ;;
1008 ;; 2. Tree properties are extracted directly from the parsed tree,
1009 ;;    just before export, by `org-export-collect-tree-properties'.
1010 ;;
1011 ;; Here is the full list of properties available during transcode
1012 ;; process, with their category and their value type.
1013 ;;
1014 ;; + `:author' :: Author's name.
1015 ;;   - category :: option
1016 ;;   - type :: string
1017 ;;
1018 ;; + `:back-end' :: Current back-end used for transcoding.
1019 ;;   - category :: tree
1020 ;;   - type :: symbol
1021 ;;
1022 ;; + `:creator' :: String to write as creation information.
1023 ;;   - category :: option
1024 ;;   - type :: string
1025 ;;
1026 ;; + `:date' :: String to use as date.
1027 ;;   - category :: option
1028 ;;   - type :: string
1029 ;;
1030 ;; + `:description' :: Description text for the current data.
1031 ;;   - category :: option
1032 ;;   - type :: string
1033 ;;
1034 ;; + `:email' :: Author's email.
1035 ;;   - category :: option
1036 ;;   - type :: string
1037 ;;
1038 ;; + `:exclude-tags' :: Tags for exclusion of subtrees from export
1039 ;;      process.
1040 ;;   - category :: option
1041 ;;   - type :: list of strings
1042 ;;
1043 ;; + `:exported-data' :: Hash table used for memoizing
1044 ;;     `org-export-data'.
1045 ;;   - category :: tree
1046 ;;   - type :: hash table
1047 ;;
1048 ;; + `:footnote-definition-alist' :: Alist between footnote labels and
1049 ;;     their definition, as parsed data.  Only non-inlined footnotes
1050 ;;     are represented in this alist.  Also, every definition isn't
1051 ;;     guaranteed to be referenced in the parse tree.  The purpose of
1052 ;;     this property is to preserve definitions from oblivion
1053 ;;     (i.e. when the parse tree comes from a part of the original
1054 ;;     buffer), it isn't meant for direct use in a back-end.  To
1055 ;;     retrieve a definition relative to a reference, use
1056 ;;     `org-export-get-footnote-definition' instead.
1057 ;;   - category :: option
1058 ;;   - type :: alist (STRING . LIST)
1059 ;;
1060 ;; + `:headline-levels' :: Maximum level being exported as an
1061 ;;      headline.  Comparison is done with the relative level of
1062 ;;      headlines in the parse tree, not necessarily with their
1063 ;;      actual level.
1064 ;;   - category :: option
1065 ;;   - type :: integer
1066 ;;
1067 ;; + `:headline-offset' :: Difference between relative and real level
1068 ;;      of headlines in the parse tree.  For example, a value of -1
1069 ;;      means a level 2 headline should be considered as level
1070 ;;      1 (cf. `org-export-get-relative-level').
1071 ;;   - category :: tree
1072 ;;   - type :: integer
1073 ;;
1074 ;; + `:headline-numbering' :: Alist between headlines and their
1075 ;;      numbering, as a list of numbers
1076 ;;      (cf. `org-export-get-headline-number').
1077 ;;   - category :: tree
1078 ;;   - type :: alist (INTEGER . LIST)
1079 ;;
1080 ;; + `:id-alist' :: Alist between ID strings and destination file's
1081 ;;      path, relative to current directory.  It is used by
1082 ;;      `org-export-resolve-id-link' to resolve ID links targeting an
1083 ;;      external file.
1084 ;;   - category :: option
1085 ;;   - type :: alist (STRING . STRING)
1086 ;;
1087 ;; + `:ignore-list' :: List of elements and objects that should be
1088 ;;      ignored during export.
1089 ;;   - category :: tree
1090 ;;   - type :: list of elements and objects
1091 ;;
1092 ;; + `:input-file' :: Full path to input file, if any.
1093 ;;   - category :: option
1094 ;;   - type :: string or nil
1095 ;;
1096 ;; + `:keywords' :: List of keywords attached to data.
1097 ;;   - category :: option
1098 ;;   - type :: string
1099 ;;
1100 ;; + `:language' :: Default language used for translations.
1101 ;;   - category :: option
1102 ;;   - type :: string
1103 ;;
1104 ;; + `:parse-tree' :: Whole parse tree, available at any time during
1105 ;;      transcoding.
1106 ;;   - category :: option
1107 ;;   - type :: list (as returned by `org-element-parse-buffer')
1108 ;;
1109 ;; + `:preserve-breaks' :: Non-nil means transcoding should preserve
1110 ;;      all line breaks.
1111 ;;   - category :: option
1112 ;;   - type :: symbol (nil, t)
1113 ;;
1114 ;; + `:section-numbers' :: Non-nil means transcoding should add
1115 ;;      section numbers to headlines.
1116 ;;   - category :: option
1117 ;;   - type :: symbol (nil, t)
1118 ;;
1119 ;; + `:select-tags' :: List of tags enforcing inclusion of sub-trees
1120 ;;      in transcoding.  When such a tag is present, subtrees without
1121 ;;      it are de facto excluded from the process.  See
1122 ;;      `use-select-tags'.
1123 ;;   - category :: option
1124 ;;   - type :: list of strings
1125 ;;
1126 ;; + `:target-list' :: List of targets encountered in the parse tree.
1127 ;;      This is used to partly resolve "fuzzy" links
1128 ;;      (cf. `org-export-resolve-fuzzy-link').
1129 ;;   - category :: tree
1130 ;;   - type :: list of strings
1131 ;;
1132 ;; + `:time-stamp-file' :: Non-nil means transcoding should insert
1133 ;;      a time stamp in the output.
1134 ;;   - category :: option
1135 ;;   - type :: symbol (nil, t)
1136 ;;
1137 ;; + `:translate-alist' :: Alist between element and object types and
1138 ;;      transcoding functions relative to the current back-end.
1139 ;;      Special keys `template' and `plain-text' are also possible.
1140 ;;   - category :: option
1141 ;;   - type :: alist (SYMBOL . FUNCTION)
1142 ;;
1143 ;; + `:with-archived-trees' :: Non-nil when archived subtrees should
1144 ;;      also be transcoded.  If it is set to the `headline' symbol,
1145 ;;      only the archived headline's name is retained.
1146 ;;   - category :: option
1147 ;;   - type :: symbol (nil, t, `headline')
1148 ;;
1149 ;; + `:with-author' :: Non-nil means author's name should be included
1150 ;;      in the output.
1151 ;;   - category :: option
1152 ;;   - type :: symbol (nil, t)
1153 ;;
1154 ;; + `:with-clocks' :: Non-nild means clock keywords should be exported.
1155 ;;   - category :: option
1156 ;;   - type :: symbol (nil, t)
1157 ;;
1158 ;; + `:with-creator' :: Non-nild means a creation sentence should be
1159 ;;      inserted at the end of the transcoded string.  If the value
1160 ;;      is `comment', it should be commented.
1161 ;;   - category :: option
1162 ;;   - type :: symbol (`comment', nil, t)
1163 ;;
1164 ;; + `:with-drawers' :: Non-nil means drawers should be exported.  If
1165 ;;      its value is a list of names, only drawers with such names
1166 ;;      will be transcoded.
1167 ;;   - category :: option
1168 ;;   - type :: symbol (nil, t) or list of strings
1169 ;;
1170 ;; + `:with-email' :: Non-nil means output should contain author's
1171 ;;                   email.
1172 ;;   - category :: option
1173 ;;   - type :: symbol (nil, t)
1174 ;;
1175 ;; + `:with-emphasize' :: Non-nil means emphasized text should be
1176 ;;      interpreted.
1177 ;;   - category :: option
1178 ;;   - type :: symbol (nil, t)
1179 ;;
1180 ;; + `:with-fixed-width' :: Non-nil if transcoder should interpret
1181 ;;      strings starting with a colon as a fixed-with (verbatim) area.
1182 ;;   - category :: option
1183 ;;   - type :: symbol (nil, t)
1184 ;;
1185 ;; + `:with-footnotes' :: Non-nil if transcoder should interpret
1186 ;;      footnotes.
1187 ;;   - category :: option
1188 ;;   - type :: symbol (nil, t)
1189 ;;
1190 ;; + `:with-plannings' :: Non-nil means transcoding should include
1191 ;;      planning info.
1192 ;;   - category :: option
1193 ;;   - type :: symbol (nil, t)
1194 ;;
1195 ;; + `:with-priority' :: Non-nil means transcoding should include
1196 ;;      priority cookies.
1197 ;;   - category :: option
1198 ;;   - type :: symbol (nil, t)
1199 ;;
1200 ;; + `:with-smart-quotes' :: Non-nil means activate smart quotes in
1201 ;;      plain text.
1202 ;;   - category :: option
1203 ;;   - type :: symbol (nil, t)
1204 ;;
1205 ;; + `:with-special-strings' :: Non-nil means transcoding should
1206 ;;      interpret special strings in plain text.
1207 ;;   - category :: option
1208 ;;   - type :: symbol (nil, t)
1209 ;;
1210 ;; + `:with-sub-superscript' :: Non-nil means transcoding should
1211 ;;      interpret subscript and superscript.  With a value of "{}",
1212 ;;      only interpret those using curly brackets.
1213 ;;   - category :: option
1214 ;;   - type :: symbol (nil, {}, t)
1215 ;;
1216 ;; + `:with-tables' :: Non-nil means transcoding should interpret
1217 ;;      tables.
1218 ;;   - category :: option
1219 ;;   - type :: symbol (nil, t)
1220 ;;
1221 ;; + `:with-tags' :: Non-nil means transcoding should keep tags in
1222 ;;      headlines.  A `not-in-toc' value will remove them from the
1223 ;;      table of contents, if any, nonetheless.
1224 ;;   - category :: option
1225 ;;   - type :: symbol (nil, t, `not-in-toc')
1226 ;;
1227 ;; + `:with-tasks' :: Non-nil means transcoding should include
1228 ;;      headlines with a TODO keyword.  A `todo' value will only
1229 ;;      include headlines with a todo type keyword while a `done'
1230 ;;      value will do the contrary.  If a list of strings is provided,
1231 ;;      only tasks with keywords belonging to that list will be kept.
1232 ;;   - category :: option
1233 ;;   - type :: symbol (t, todo, done, nil) or list of strings
1234 ;;
1235 ;; + `:with-timestamps' :: Non-nil means transcoding should include
1236 ;;      time stamps.  Special value `active' (resp. `inactive') ask to
1237 ;;      export only active (resp. inactive) timestamps.  Otherwise,
1238 ;;      completely remove them.
1239 ;;   - category :: option
1240 ;;   - type :: symbol: (`active', `inactive', t, nil)
1241 ;;
1242 ;; + `:with-toc' :: Non-nil means that a table of contents has to be
1243 ;;      added to the output.  An integer value limits its depth.
1244 ;;   - category :: option
1245 ;;   - type :: symbol (nil, t or integer)
1246 ;;
1247 ;; + `:with-todo-keywords' :: Non-nil means transcoding should
1248 ;;      include TODO keywords.
1249 ;;   - category :: option
1250 ;;   - type :: symbol (nil, t)
1251
1252
1253 ;;;; Environment Options
1254 ;;
1255 ;; Environment options encompass all parameters defined outside the
1256 ;; scope of the parsed data.  They come from five sources, in
1257 ;; increasing precedence order:
1258 ;;
1259 ;; - Global variables,
1260 ;; - Buffer's attributes,
1261 ;; - Options keyword symbols,
1262 ;; - Buffer keywords,
1263 ;; - Subtree properties.
1264 ;;
1265 ;; The central internal function with regards to environment options
1266 ;; is `org-export-get-environment'.  It updates global variables with
1267 ;; "#+BIND:" keywords, then retrieve and prioritize properties from
1268 ;; the different sources.
1269 ;;
1270 ;;  The internal functions doing the retrieval are:
1271 ;;  `org-export--get-global-options',
1272 ;;  `org-export--get-buffer-attributes',
1273 ;;  `org-export--parse-option-keyword',
1274 ;;  `org-export--get-subtree-options' and
1275 ;;  `org-export--get-inbuffer-options'
1276 ;;
1277 ;; Also, `org-export--confirm-letbind' and `org-export--install-letbind'
1278 ;; take care of the part relative to "#+BIND:" keywords.
1279
1280 (defun org-export-get-environment (&optional backend subtreep ext-plist)
1281   "Collect export options from the current buffer.
1282
1283 Optional argument BACKEND is a symbol specifying which back-end
1284 specific options to read, if any.
1285
1286 When optional argument SUBTREEP is non-nil, assume the export is
1287 done against the current sub-tree.
1288
1289 Third optional argument EXT-PLIST is a property list with
1290 external parameters overriding Org default settings, but still
1291 inferior to file-local settings."
1292   ;; First install #+BIND variables.
1293   (org-export--install-letbind-maybe)
1294   ;; Get and prioritize export options...
1295   (org-combine-plists
1296    ;; ... from global variables...
1297    (org-export--get-global-options backend)
1298    ;; ... from buffer's attributes...
1299    (org-export--get-buffer-attributes)
1300    ;; ... from an external property list...
1301    ext-plist
1302    ;; ... from in-buffer settings...
1303    (org-export--get-inbuffer-options
1304     backend
1305     (and buffer-file-name (org-remove-double-quotes buffer-file-name)))
1306    ;; ... and from subtree, when appropriate.
1307    (and subtreep (org-export--get-subtree-options backend))
1308    ;; Eventually install back-end symbol and its translation table.
1309    `(:back-end
1310      ,backend
1311      :translate-alist
1312      ,(let ((trans-alist (intern (format "org-%s-translate-alist" backend))))
1313         (when (boundp trans-alist) (symbol-value trans-alist))))))
1314
1315 (defun org-export--parse-option-keyword (options &optional backend)
1316   "Parse an OPTIONS line and return values as a plist.
1317 Optional argument BACKEND is a symbol specifying which back-end
1318 specific items to read, if any."
1319   (let* ((all
1320           (append org-export-options-alist
1321                   (and backend
1322                        (let ((var (intern
1323                                    (format "org-%s-options-alist" backend))))
1324                          (and (boundp var) (eval var))))))
1325          ;; Build an alist between #+OPTION: item and property-name.
1326          (alist (delq nil
1327                       (mapcar (lambda (e)
1328                                 (when (nth 2 e) (cons (regexp-quote (nth 2 e))
1329                                                       (car e))))
1330                               all)))
1331          plist)
1332     (mapc (lambda (e)
1333             (when (string-match (concat "\\(\\`\\|[ \t]\\)"
1334                                         (car e)
1335                                         ":\\(([^)\n]+)\\|[^ \t\n\r;,.]*\\)")
1336                                 options)
1337               (setq plist (plist-put plist
1338                                      (cdr e)
1339                                      (car (read-from-string
1340                                            (match-string 2 options)))))))
1341           alist)
1342     plist))
1343
1344 (defun org-export--get-subtree-options (&optional backend)
1345   "Get export options in subtree at point.
1346 Optional argument BACKEND is a symbol specifying back-end used
1347 for export.  Return options as a plist."
1348   ;; For each buffer keyword, create an headline property setting the
1349   ;; same property in communication channel. The name for the property
1350   ;; is the keyword with "EXPORT_" appended to it.
1351   (org-with-wide-buffer
1352    (let (prop plist)
1353      ;; Make sure point is at an heading.
1354      (unless (org-at-heading-p) (org-back-to-heading t))
1355      ;; Take care of EXPORT_TITLE. If it isn't defined, use headline's
1356      ;; title as its fallback value.
1357      (when (setq prop (progn (looking-at org-todo-line-regexp)
1358                              (or (save-match-data
1359                                    (org-entry-get (point) "EXPORT_TITLE"))
1360                                  (org-match-string-no-properties 3))))
1361        (setq plist
1362              (plist-put
1363               plist :title
1364               (org-element-parse-secondary-string
1365                prop (org-element-restriction 'keyword)))))
1366      ;; EXPORT_OPTIONS are parsed in a non-standard way.
1367      (when (setq prop (org-entry-get (point) "EXPORT_OPTIONS"))
1368        (setq plist
1369              (nconc plist (org-export--parse-option-keyword prop backend))))
1370      ;; Handle other keywords.  TITLE keyword is excluded as it has
1371      ;; already been handled already.
1372      (let ((seen '("TITLE")))
1373        (mapc
1374         (lambda (option)
1375           (let ((property (nth 1 option)))
1376             (when (and property (not (member property seen)))
1377               (let* ((subtree-prop (concat "EXPORT_" property))
1378                      ;; Export properties are not case-sensitive.
1379                      (value (let ((case-fold-search t))
1380                               (org-entry-get (point) subtree-prop))))
1381                 (push property seen)
1382                 (when value
1383                   (setq plist
1384                         (plist-put
1385                          plist
1386                          (car option)
1387                          ;; Parse VALUE if required.
1388                          (if (member property org-element-document-properties)
1389                              (org-element-parse-secondary-string
1390                               value (org-element-restriction 'keyword))
1391                            value))))))))
1392         ;; Also look for both general keywords and back-end specific
1393         ;; options if BACKEND is provided.
1394         (append (and backend
1395                      (let ((var (intern
1396                                  (format "org-%s-options-alist" backend))))
1397                        (and (boundp var) (symbol-value var))))
1398                 org-export-options-alist)))
1399      ;; Return value.
1400      plist)))
1401
1402 (defun org-export--get-inbuffer-options (&optional backend files)
1403   "Return current buffer export options, as a plist.
1404
1405 Optional argument BACKEND, when non-nil, is a symbol specifying
1406 which back-end specific options should also be read in the
1407 process.
1408
1409 Optional argument FILES is a list of setup files names read so
1410 far, used to avoid circular dependencies.
1411
1412 Assume buffer is in Org mode.  Narrowing, if any, is ignored."
1413   (org-with-wide-buffer
1414    (goto-char (point-min))
1415    (let ((case-fold-search t) plist)
1416      ;; 1. Special keywords, as in `org-export-special-keywords'.
1417      (let ((special-re
1418             (format "^[ \t]*#\\+%s:" (regexp-opt org-export-special-keywords))))
1419        (while (re-search-forward special-re nil t)
1420          (let ((element (org-element-at-point)))
1421            (when (eq (org-element-type element) 'keyword)
1422              (let* ((key (org-element-property :key element))
1423                     (val (org-element-property :value element))
1424                     (prop
1425                      (cond
1426                       ((string= key "SETUP_FILE")
1427                        (let ((file
1428                               (expand-file-name
1429                                (org-remove-double-quotes (org-trim val)))))
1430                          ;; Avoid circular dependencies.
1431                          (unless (member file files)
1432                            (with-temp-buffer
1433                              (insert (org-file-contents file 'noerror))
1434                              (org-mode)
1435                              (org-export--get-inbuffer-options
1436                               backend (cons file files))))))
1437                       ((string= key "OPTIONS")
1438                        (org-export--parse-option-keyword val backend)))))
1439                (setq plist (org-combine-plists plist prop)))))))
1440      ;; 2. Standard options, as in `org-export-options-alist'.
1441      (let* ((all (append org-export-options-alist
1442                          ;; Also look for back-end specific options
1443                          ;; if BACKEND is defined.
1444                          (and backend
1445                               (let ((var
1446                                      (intern
1447                                       (format "org-%s-options-alist" backend))))
1448                                 (and (boundp var) (eval var))))))
1449             ;; Build ALIST between keyword name and property name.
1450             (alist
1451              (delq nil (mapcar
1452                         (lambda (e) (when (nth 1 e) (cons (nth 1 e) (car e))))
1453                         all)))
1454             ;; Build regexp matching all keywords associated to export
1455             ;; options.  Note: the search is case insensitive.
1456             (opt-re (format "^[ \t]*#\\+%s:"
1457                             (regexp-opt
1458                              (delq nil (mapcar (lambda (e) (nth 1 e)) all))))))
1459        (goto-char (point-min))
1460        (while (re-search-forward opt-re nil t)
1461          (let ((element (org-element-at-point)))
1462            (when (eq (org-element-type element) 'keyword)
1463              (let* ((key (org-element-property :key element))
1464                     (val (org-element-property :value element))
1465                     (prop (cdr (assoc key alist)))
1466                     (behaviour (nth 4 (assq prop all))))
1467                (setq plist
1468                      (plist-put
1469                       plist prop
1470                       ;; Handle value depending on specified BEHAVIOUR.
1471                       (case behaviour
1472                         (space
1473                          (if (not (plist-get plist prop)) (org-trim val)
1474                            (concat (plist-get plist prop) " " (org-trim val))))
1475                         (newline
1476                          (org-trim
1477                           (concat (plist-get plist prop) "\n" (org-trim val))))
1478                         (split
1479                          `(,@(plist-get plist prop) ,@(org-split-string val)))
1480                         ('t val)
1481                         (otherwise (if (not (plist-member plist prop)) val
1482                                      (plist-get plist prop))))))))))
1483        ;; Parse keywords specified in
1484        ;; `org-element-document-properties'.
1485        (mapc
1486         (lambda (key)
1487           (let* ((prop (cdr (assoc key alist)))
1488                  (value (and prop (plist-get plist prop))))
1489             (when (stringp value)
1490               (setq plist
1491                     (plist-put
1492                      plist prop
1493                      (org-element-parse-secondary-string
1494                       value (org-element-restriction 'keyword)))))))
1495         org-element-document-properties))
1496      ;; 3. Return final value.
1497      plist)))
1498
1499 (defun org-export--get-buffer-attributes ()
1500   "Return properties related to buffer attributes, as a plist."
1501   (let ((visited-file (buffer-file-name (buffer-base-buffer))))
1502     (list
1503      ;; Store full path of input file name, or nil.  For internal use.
1504      :input-file visited-file
1505      :title (or (and visited-file
1506                      (file-name-sans-extension
1507                       (file-name-nondirectory visited-file)))
1508                 (buffer-name (buffer-base-buffer)))
1509      :footnote-definition-alist
1510      ;; Footnotes definitions must be collected in the original
1511      ;; buffer, as there's no insurance that they will still be in the
1512      ;; parse tree, due to possible narrowing.
1513      (let (alist)
1514        (org-with-wide-buffer
1515         (goto-char (point-min))
1516         (while (re-search-forward org-footnote-definition-re nil t)
1517           (let ((def (save-match-data (org-element-at-point))))
1518             (when (eq (org-element-type def) 'footnote-definition)
1519               (push
1520                (cons (org-element-property :label def)
1521                      (let ((cbeg (org-element-property :contents-begin def)))
1522                        (when cbeg
1523                          (org-element--parse-elements
1524                           cbeg (org-element-property :contents-end def)
1525                           nil nil nil nil (list 'org-data nil)))))
1526                alist))))
1527         alist))
1528      :id-alist
1529      ;; Collect id references.
1530      (let (alist)
1531        (org-with-wide-buffer
1532         (goto-char (point-min))
1533         (while (re-search-forward "\\[\\[id:\\S-+?\\]" nil t)
1534           (let ((link (org-element-context)))
1535             (when (eq (org-element-type link) 'link)
1536               (let* ((id (org-element-property :path link))
1537                      (file (org-id-find-id-file id)))
1538                 (when file
1539                   (push (cons id (file-relative-name file)) alist)))))))
1540        alist))))
1541
1542 (defun org-export--get-global-options (&optional backend)
1543   "Return global export options as a plist.
1544
1545 Optional argument BACKEND, if non-nil, is a symbol specifying
1546 which back-end specific export options should also be read in the
1547 process."
1548   (let ((all (append org-export-options-alist
1549                      (and backend
1550                           (let ((var (intern
1551                                       (format "org-%s-options-alist" backend))))
1552                             (and (boundp var) (symbol-value var))))))
1553         ;; Output value.
1554         plist)
1555     (mapc
1556      (lambda (cell)
1557        (setq plist
1558              (plist-put
1559               plist
1560               (car cell)
1561               ;; Eval default value provided.  If keyword is a member
1562               ;; of `org-element-document-properties', parse it as
1563               ;; a secondary string before storing it.
1564               (let ((value (eval (nth 3 cell))))
1565                 (if (not (stringp value)) value
1566                   (let ((keyword (nth 1 cell)))
1567                     (if (not (member keyword org-element-document-properties))
1568                         value
1569                       (org-element-parse-secondary-string
1570                        value (org-element-restriction 'keyword)))))))))
1571      all)
1572     ;; Return value.
1573     plist))
1574
1575 (defvar org-export--allow-BIND-local nil)
1576 (defun org-export--confirm-letbind ()
1577   "Can we use #+BIND values during export?
1578 By default this will ask for confirmation by the user, to divert
1579 possible security risks."
1580   (cond
1581    ((not org-export-allow-BIND) nil)
1582    ((eq org-export-allow-BIND t) t)
1583    ((local-variable-p 'org-export--allow-BIND-local)
1584     org-export--allow-BIND-local)
1585    (t (org-set-local 'org-export--allow-BIND-local
1586                      (yes-or-no-p "Allow BIND values in this buffer? ")))))
1587
1588 (defun org-export--install-letbind-maybe ()
1589   "Install the values from #+BIND lines as local variables.
1590 Variables must be installed before in-buffer options are
1591 retrieved."
1592   (let ((case-fold-search t) letbind pair)
1593     (org-with-wide-buffer
1594      (goto-char (point-min))
1595      (while (re-search-forward "^[ \t]*#\\+BIND:" nil t)
1596        (let* ((element (org-element-at-point))
1597               (value (org-element-property :value element)))
1598          (when (and (eq (org-element-type element) 'keyword)
1599                     (not (equal value  ""))
1600                     (org-export--confirm-letbind))
1601            (push (read (format "(%s)" value)) letbind)))))
1602     (dolist (pair (nreverse letbind))
1603       (org-set-local (car pair) (nth 1 pair)))))
1604
1605
1606 ;;;; Tree Properties
1607 ;;
1608 ;; Tree properties are information extracted from parse tree.  They
1609 ;; are initialized at the beginning of the transcoding process by
1610 ;; `org-export-collect-tree-properties'.
1611 ;;
1612 ;; Dedicated functions focus on computing the value of specific tree
1613 ;; properties during initialization.  Thus,
1614 ;; `org-export--populate-ignore-list' lists elements and objects that
1615 ;; should be skipped during export, `org-export--get-min-level' gets
1616 ;; the minimal exportable level, used as a basis to compute relative
1617 ;; level for headlines.  Eventually
1618 ;; `org-export--collect-headline-numbering' builds an alist between
1619 ;; headlines and their numbering.
1620
1621 (defun org-export-collect-tree-properties (data info)
1622   "Extract tree properties from parse tree.
1623
1624 DATA is the parse tree from which information is retrieved.  INFO
1625 is a list holding export options.
1626
1627 Following tree properties are set or updated:
1628
1629 `:exported-data' Hash table used to memoize results from
1630                  `org-export-data'.
1631
1632 `:footnote-definition-alist' List of footnotes definitions in
1633                    original buffer and current parse tree.
1634
1635 `:headline-offset' Offset between true level of headlines and
1636                    local level.  An offset of -1 means an headline
1637                    of level 2 should be considered as a level
1638                    1 headline in the context.
1639
1640 `:headline-numbering' Alist of all headlines as key an the
1641                       associated numbering as value.
1642
1643 `:ignore-list'     List of elements that should be ignored during
1644                    export.
1645
1646 `:target-list'     List of all targets in the parse tree.
1647
1648 Return updated plist."
1649   ;; Install the parse tree in the communication channel, in order to
1650   ;; use `org-export-get-genealogy' and al.
1651   (setq info (plist-put info :parse-tree data))
1652   ;; Get the list of elements and objects to ignore, and put it into
1653   ;; `:ignore-list'.  Do not overwrite any user ignore that might have
1654   ;; been done during parse tree filtering.
1655   (setq info
1656         (plist-put info
1657                    :ignore-list
1658                    (append (org-export--populate-ignore-list data info)
1659                            (plist-get info :ignore-list))))
1660   ;; Compute `:headline-offset' in order to be able to use
1661   ;; `org-export-get-relative-level'.
1662   (setq info
1663         (plist-put info
1664                    :headline-offset
1665                    (- 1 (org-export--get-min-level data info))))
1666   ;; Update footnotes definitions list with definitions in parse tree.
1667   ;; This is required since buffer expansion might have modified
1668   ;; boundaries of footnote definitions contained in the parse tree.
1669   ;; This way, definitions in `footnote-definition-alist' are bound to
1670   ;; match those in the parse tree.
1671   (let ((defs (plist-get info :footnote-definition-alist)))
1672     (org-element-map
1673      data 'footnote-definition
1674      (lambda (fn)
1675        (push (cons (org-element-property :label fn)
1676                    `(org-data nil ,@(org-element-contents fn)))
1677              defs)))
1678     (setq info (plist-put info :footnote-definition-alist defs)))
1679   ;; Properties order doesn't matter: get the rest of the tree
1680   ;; properties.
1681   (nconc
1682    `(:target-list
1683      ,(org-element-map
1684        data '(keyword target)
1685        (lambda (blob)
1686          (when (or (eq (org-element-type blob) 'target)
1687                    (string= (org-element-property :key blob) "TARGET"))
1688            blob)) info)
1689      :headline-numbering ,(org-export--collect-headline-numbering data info)
1690      :exported-data ,(make-hash-table :test 'eq :size 4001))
1691    info))
1692
1693 (defun org-export--get-min-level (data options)
1694   "Return minimum exportable headline's level in DATA.
1695 DATA is parsed tree as returned by `org-element-parse-buffer'.
1696 OPTIONS is a plist holding export options."
1697   (catch 'exit
1698     (let ((min-level 10000))
1699       (mapc
1700        (lambda (blob)
1701          (when (and (eq (org-element-type blob) 'headline)
1702                     (not (memq blob (plist-get options :ignore-list))))
1703            (setq min-level
1704                  (min (org-element-property :level blob) min-level)))
1705          (when (= min-level 1) (throw 'exit 1)))
1706        (org-element-contents data))
1707       ;; If no headline was found, for the sake of consistency, set
1708       ;; minimum level to 1 nonetheless.
1709       (if (= min-level 10000) 1 min-level))))
1710
1711 (defun org-export--collect-headline-numbering (data options)
1712   "Return numbering of all exportable headlines in a parse tree.
1713
1714 DATA is the parse tree.  OPTIONS is the plist holding export
1715 options.
1716
1717 Return an alist whose key is an headline and value is its
1718 associated numbering \(in the shape of a list of numbers\)."
1719   (let ((numbering (make-vector org-export-max-depth 0)))
1720     (org-element-map
1721      data
1722      'headline
1723      (lambda (headline)
1724        (let ((relative-level
1725               (1- (org-export-get-relative-level headline options))))
1726          (cons
1727           headline
1728           (loop for n across numbering
1729                 for idx from 0 to org-export-max-depth
1730                 when (< idx relative-level) collect n
1731                 when (= idx relative-level) collect (aset numbering idx (1+ n))
1732                 when (> idx relative-level) do (aset numbering idx 0)))))
1733      options)))
1734
1735 (defun org-export--populate-ignore-list (data options)
1736   "Return list of elements and objects to ignore during export.
1737 DATA is the parse tree to traverse.  OPTIONS is the plist holding
1738 export options."
1739   (let* (ignore
1740          walk-data
1741          ;; First find trees containing a select tag, if any.
1742          (selected (org-export--selected-trees data options))
1743          (walk-data
1744           (lambda (data)
1745             ;; Collect ignored elements or objects into IGNORE-LIST.
1746             (let ((type (org-element-type data)))
1747               (if (org-export--skip-p data options selected) (push data ignore)
1748                 (if (and (eq type 'headline)
1749                          (eq (plist-get options :with-archived-trees) 'headline)
1750                          (org-element-property :archivedp data))
1751                     ;; If headline is archived but tree below has
1752                     ;; to be skipped, add it to ignore list.
1753                     (mapc (lambda (e) (push e ignore))
1754                           (org-element-contents data))
1755                   ;; Move into secondary string, if any.
1756                   (let ((sec-prop
1757                          (cdr (assq type org-element-secondary-value-alist))))
1758                     (when sec-prop
1759                       (mapc walk-data (org-element-property sec-prop data))))
1760                   ;; Move into recursive objects/elements.
1761                   (mapc walk-data (org-element-contents data))))))))
1762     ;; Main call.
1763     (funcall walk-data data)
1764     ;; Return value.
1765     ignore))
1766
1767 (defun org-export--selected-trees (data info)
1768   "Return list of headlines containing a select tag in their tree.
1769 DATA is parsed data as returned by `org-element-parse-buffer'.
1770 INFO is a plist holding export options."
1771   (let* (selected-trees
1772          walk-data                      ; for byte-compiler.
1773          (walk-data
1774           (function
1775            (lambda (data genealogy)
1776              (case (org-element-type data)
1777                (org-data (mapc (lambda (el) (funcall walk-data el genealogy))
1778                                (org-element-contents data)))
1779                (headline
1780                 (let ((tags (org-element-property :tags data)))
1781                   (if (loop for tag in (plist-get info :select-tags)
1782                             thereis (member tag tags))
1783                       ;; When a select tag is found, mark full
1784                       ;; genealogy and every headline within the tree
1785                       ;; as acceptable.
1786                       (setq selected-trees
1787                             (append
1788                              genealogy
1789                              (org-element-map data 'headline 'identity)
1790                              selected-trees))
1791                     ;; Else, continue searching in tree, recursively.
1792                     (mapc
1793                      (lambda (el) (funcall walk-data el (cons data genealogy)))
1794                      (org-element-contents data))))))))))
1795     (funcall walk-data data nil) selected-trees))
1796
1797 (defun org-export--skip-p (blob options selected)
1798   "Non-nil when element or object BLOB should be skipped during export.
1799 OPTIONS is the plist holding export options.  SELECTED, when
1800 non-nil, is a list of headlines belonging to a tree with a select
1801 tag."
1802   (case (org-element-type blob)
1803     (clock (not (plist-get options :with-clocks)))
1804     (drawer
1805      (or (not (plist-get options :with-drawers))
1806          (and (consp (plist-get options :with-drawers))
1807               (not (member (org-element-property :drawer-name blob)
1808                            (plist-get options :with-drawers))))))
1809     (headline
1810      (let ((with-tasks (plist-get options :with-tasks))
1811            (todo (org-element-property :todo-keyword blob))
1812            (todo-type (org-element-property :todo-type blob))
1813            (archived (plist-get options :with-archived-trees))
1814            (tags (org-element-property :tags blob)))
1815        (or
1816         ;; Ignore subtrees with an exclude tag.
1817         (loop for k in (plist-get options :exclude-tags)
1818               thereis (member k tags))
1819         ;; When a select tag is present in the buffer, ignore any tree
1820         ;; without it.
1821         (and selected (not (memq blob selected)))
1822         ;; Ignore commented sub-trees.
1823         (org-element-property :commentedp blob)
1824         ;; Ignore archived subtrees if `:with-archived-trees' is nil.
1825         (and (not archived) (org-element-property :archivedp blob))
1826         ;; Ignore tasks, if specified by `:with-tasks' property.
1827         (and todo
1828              (or (not with-tasks)
1829                  (and (memq with-tasks '(todo done))
1830                       (not (eq todo-type with-tasks)))
1831                  (and (consp with-tasks) (not (member todo with-tasks))))))))
1832     (inlinetask (not (plist-get options :with-inlinetasks)))
1833     (planning (not (plist-get options :with-plannings)))
1834     (statistics-cookie (not (plist-get options :with-statistics-cookies)))
1835     (table-cell
1836      (and (org-export-table-has-special-column-p
1837            (org-export-get-parent-table blob))
1838           (not (org-export-get-previous-element blob options))))
1839     (table-row (org-export-table-row-is-special-p blob options))
1840     (timestamp
1841      (case (plist-get options :with-timestamps)
1842        ;; No timestamp allowed.
1843        ('nil t)
1844        ;; Only active timestamps allowed and the current one isn't
1845        ;; active.
1846        (active
1847         (not (memq (org-element-property :type blob)
1848                    '(active active-range))))
1849        ;; Only inactive timestamps allowed and the current one isn't
1850        ;; inactive.
1851        (inactive
1852         (not (memq (org-element-property :type blob)
1853                    '(inactive inactive-range))))))))
1854
1855
1856 \f
1857 ;;; The Transcoder
1858 ;;
1859 ;; `org-export-data' reads a parse tree (obtained with, i.e.
1860 ;; `org-element-parse-buffer') and transcodes it into a specified
1861 ;; back-end output.  It takes care of filtering out elements or
1862 ;; objects according to export options and organizing the output blank
1863 ;; lines and white space are preserved.  The function memoizes its
1864 ;; results, so it is cheap to call it within translators.
1865 ;;
1866 ;; Internally, three functions handle the filtering of objects and
1867 ;; elements during the export.  In particular,
1868 ;; `org-export-ignore-element' marks an element or object so future
1869 ;; parse tree traversals skip it, `org-export--interpret-p' tells which
1870 ;; elements or objects should be seen as real Org syntax and
1871 ;; `org-export-expand' transforms the others back into their original
1872 ;; shape
1873 ;;
1874 ;; `org-export-transcoder' is an accessor returning appropriate
1875 ;; translator function for a given element or object.
1876
1877 (defun org-export-transcoder (blob info)
1878   "Return appropriate transcoder for BLOB.
1879 INFO is a plist containing export directives."
1880   (let ((type (org-element-type blob)))
1881     ;; Return contents only for complete parse trees.
1882     (if (eq type 'org-data) (lambda (blob contents info) contents)
1883       (let ((transcoder (cdr (assq type (plist-get info :translate-alist)))))
1884         (and (functionp transcoder) transcoder)))))
1885
1886 (defun org-export-data (data info)
1887   "Convert DATA into current back-end format.
1888
1889 DATA is a parse tree, an element or an object or a secondary
1890 string.  INFO is a plist holding export options.
1891
1892 Return transcoded string."
1893   (let ((memo (gethash data (plist-get info :exported-data) 'no-memo)))
1894     (if (not (eq memo 'no-memo)) memo
1895       (let* ((type (org-element-type data))
1896              (results
1897               (cond
1898                ;; Ignored element/object.
1899                ((memq data (plist-get info :ignore-list)) nil)
1900                ;; Plain text.  All residual text properties from parse
1901                ;; tree (i.e. `:parent' property) are removed.
1902                ((eq type 'plain-text)
1903                 (org-no-properties
1904                  (org-export-filter-apply-functions
1905                   (plist-get info :filter-plain-text)
1906                   (let ((transcoder (org-export-transcoder data info)))
1907                     (if transcoder (funcall transcoder data info) data))
1908                   info)))
1909                ;; Uninterpreted element/object: change it back to Org
1910                ;; syntax and export again resulting raw string.
1911                ((not (org-export--interpret-p data info))
1912                 (org-export-data
1913                  (org-export-expand
1914                   data
1915                   (mapconcat (lambda (blob) (org-export-data blob info))
1916                              (org-element-contents data)
1917                              ""))
1918                  info))
1919                ;; Secondary string.
1920                ((not type)
1921                 (mapconcat (lambda (obj) (org-export-data obj info)) data ""))
1922                ;; Element/Object without contents or, as a special case,
1923                ;; headline with archive tag and archived trees restricted
1924                ;; to title only.
1925                ((or (not (org-element-contents data))
1926                     (and (eq type 'headline)
1927                          (eq (plist-get info :with-archived-trees) 'headline)
1928                          (org-element-property :archivedp data)))
1929                 (let ((transcoder (org-export-transcoder data info)))
1930                   (and (functionp transcoder)
1931                        (funcall transcoder data nil info))))
1932                ;; Element/Object with contents.
1933                (t
1934                 (let ((transcoder (org-export-transcoder data info)))
1935                   (when transcoder
1936                     (let* ((greaterp (memq type org-element-greater-elements))
1937                            (objectp
1938                             (and (not greaterp)
1939                                  (memq type org-element-recursive-objects)))
1940                            (contents
1941                             (mapconcat
1942                              (lambda (element) (org-export-data element info))
1943                              (org-element-contents
1944                               (if (or greaterp objectp) data
1945                                 ;; Elements directly containing objects
1946                                 ;; must have their indentation normalized
1947                                 ;; first.
1948                                 (org-element-normalize-contents
1949                                  data
1950                                  ;; When normalizing contents of the first
1951                                  ;; paragraph in an item or a footnote
1952                                  ;; definition, ignore first line's
1953                                  ;; indentation: there is none and it
1954                                  ;; might be misleading.
1955                                  (when (eq type 'paragraph)
1956                                    (let ((parent (org-export-get-parent data)))
1957                                      (and
1958                                       (eq (car (org-element-contents parent))
1959                                           data)
1960                                       (memq (org-element-type parent)
1961                                             '(footnote-definition item))))))))
1962                              "")))
1963                       (funcall transcoder data
1964                                (if (not greaterp) contents
1965                                  (org-element-normalize-string contents))
1966                                info))))))))
1967         ;; Final result will be memoized before being returned.
1968         (puthash
1969          data
1970          (cond
1971           ((not results) nil)
1972           ((memq type '(org-data plain-text nil)) results)
1973           ;; Append the same white space between elements or objects as in
1974           ;; the original buffer, and call appropriate filters.
1975           (t
1976            (let ((results
1977                   (org-export-filter-apply-functions
1978                    (plist-get info (intern (format ":filter-%s" type)))
1979                    (let ((post-blank (or (org-element-property :post-blank data)
1980                                          0)))
1981                      (if (memq type org-element-all-elements)
1982                          (concat (org-element-normalize-string results)
1983                                  (make-string post-blank ?\n))
1984                        (concat results (make-string post-blank ? ))))
1985                    info)))
1986              results)))
1987          (plist-get info :exported-data))))))
1988
1989 (defun org-export--interpret-p (blob info)
1990   "Non-nil if element or object BLOB should be interpreted as Org syntax.
1991 Check is done according to export options INFO, stored as
1992 a plist."
1993   (case (org-element-type blob)
1994     ;; ... entities...
1995     (entity (plist-get info :with-entities))
1996     ;; ... emphasis...
1997     (emphasis (plist-get info :with-emphasize))
1998     ;; ... fixed-width areas.
1999     (fixed-width (plist-get info :with-fixed-width))
2000     ;; ... footnotes...
2001     ((footnote-definition footnote-reference)
2002      (plist-get info :with-footnotes))
2003     ;; ... sub/superscripts...
2004     ((subscript superscript)
2005      (let ((sub/super-p (plist-get info :with-sub-superscript)))
2006        (if (eq sub/super-p '{})
2007            (org-element-property :use-brackets-p blob)
2008          sub/super-p)))
2009     ;; ... tables...
2010     (table (plist-get info :with-tables))
2011     (otherwise t)))
2012
2013 (defun org-export-expand (blob contents)
2014   "Expand a parsed element or object to its original state.
2015 BLOB is either an element or an object.  CONTENTS is its
2016 contents, as a string or nil."
2017   (funcall
2018    (intern (format "org-element-%s-interpreter" (org-element-type blob)))
2019    blob contents))
2020
2021 (defun org-export-ignore-element (element info)
2022   "Add ELEMENT to `:ignore-list' in INFO.
2023
2024 Any element in `:ignore-list' will be skipped when using
2025 `org-element-map'.  INFO is modified by side effects."
2026   (plist-put info :ignore-list (cons element (plist-get info :ignore-list))))
2027
2028
2029 \f
2030 ;;; The Filter System
2031 ;;
2032 ;; Filters allow end-users to tweak easily the transcoded output.
2033 ;; They are the functional counterpart of hooks, as every filter in
2034 ;; a set is applied to the return value of the previous one.
2035 ;;
2036 ;; Every set is back-end agnostic.  Although, a filter is always
2037 ;; called, in addition to the string it applies to, with the back-end
2038 ;; used as argument, so it's easy for the end-user to add back-end
2039 ;; specific filters in the set.  The communication channel, as
2040 ;; a plist, is required as the third argument.
2041 ;;
2042 ;; From the developer side, filters sets can be installed in the
2043 ;; process with the help of `org-export-define-backend', which
2044 ;; internally sets `org-BACKEND-filters-alist' variable.  Each
2045 ;; association has a key among the following symbols and a function or
2046 ;; a list of functions as value.
2047 ;;
2048 ;; - `:filter-parse-tree' applies directly on the complete parsed
2049 ;;   tree.  It's the only filters set that doesn't apply to a string.
2050 ;;   Users can set it through `org-export-filter-parse-tree-functions'
2051 ;;   variable.
2052 ;;
2053 ;; - `:filter-final-output' applies to the final transcoded string.
2054 ;;   Users can set it with `org-export-filter-final-output-functions'
2055 ;;   variable
2056 ;;
2057 ;; - `:filter-plain-text' applies to any string not recognized as Org
2058 ;;   syntax.  `org-export-filter-plain-text-functions' allows users to
2059 ;;   configure it.
2060 ;;
2061 ;; - `:filter-TYPE' applies on the string returned after an element or
2062 ;;   object of type TYPE has been transcoded.  An user can modify
2063 ;;   `org-export-filter-TYPE-functions'
2064 ;;
2065 ;; All filters sets are applied with
2066 ;; `org-export-filter-apply-functions' function.  Filters in a set are
2067 ;; applied in a LIFO fashion.  It allows developers to be sure that
2068 ;; their filters will be applied first.
2069 ;;
2070 ;; Filters properties are installed in communication channel with
2071 ;; `org-export-install-filters' function.
2072 ;;
2073 ;; Eventually, a hook (`org-export-before-parsing-hook') is run just
2074 ;; before parsing to allow for heavy structure modifications.
2075
2076
2077 ;;;; Before Parsing Hook
2078
2079 (defvar org-export-before-parsing-hook nil
2080   "Hook run before parsing an export buffer.
2081
2082 This is run after include keywords have been expanded and Babel
2083 code executed, on a copy of original buffer's area being
2084 exported.  Visibility is the same as in the original one.  Point
2085 is left at the beginning of the new one.
2086
2087 Every function in this hook will be called with one argument: the
2088 back-end currently used, as a symbol.")
2089
2090
2091 ;;;; Special Filters
2092
2093 (defvar org-export-filter-parse-tree-functions nil
2094   "List of functions applied to the parsed tree.
2095 Each filter is called with three arguments: the parse tree, as
2096 returned by `org-element-parse-buffer', the back-end, as
2097 a symbol, and the communication channel, as a plist.  It must
2098 return the modified parse tree to transcode.")
2099
2100 (defvar org-export-filter-final-output-functions nil
2101   "List of functions applied to the transcoded string.
2102 Each filter is called with three arguments: the full transcoded
2103 string, the back-end, as a symbol, and the communication channel,
2104 as a plist.  It must return a string that will be used as the
2105 final export output.")
2106
2107 (defvar org-export-filter-plain-text-functions nil
2108   "List of functions applied to plain text.
2109 Each filter is called with three arguments: a string which
2110 contains no Org syntax, the back-end, as a symbol, and the
2111 communication channel, as a plist.  It must return a string or
2112 nil.")
2113
2114
2115 ;;;; Elements Filters
2116
2117 (defvar org-export-filter-babel-call-functions nil
2118   "List of functions applied to a transcoded babel-call.
2119 Each filter is called with three arguments: the transcoded data,
2120 as a string, the back-end, as a symbol, and the communication
2121 channel, as a plist.  It must return a string or nil.")
2122
2123 (defvar org-export-filter-center-block-functions nil
2124   "List of functions applied to a transcoded center block.
2125 Each filter is called with three arguments: the transcoded data,
2126 as a string, the back-end, as a symbol, and the communication
2127 channel, as a plist.  It must return a string or nil.")
2128
2129 (defvar org-export-filter-clock-functions nil
2130   "List of functions applied to a transcoded clock.
2131 Each filter is called with three arguments: the transcoded data,
2132 as a string, the back-end, as a symbol, and the communication
2133 channel, as a plist.  It must return a string or nil.")
2134
2135 (defvar org-export-filter-comment-functions nil
2136   "List of functions applied to a transcoded comment.
2137 Each filter is called with three arguments: the transcoded data,
2138 as a string, the back-end, as a symbol, and the communication
2139 channel, as a plist.  It must return a string or nil.")
2140
2141 (defvar org-export-filter-comment-block-functions nil
2142   "List of functions applied to a transcoded comment-block.
2143 Each filter is called with three arguments: the transcoded data,
2144 as a string, the back-end, as a symbol, and the communication
2145 channel, as a plist.  It must return a string or nil.")
2146
2147 (defvar org-export-filter-diary-sexp-functions nil
2148   "List of functions applied to a transcoded diary-sexp.
2149 Each filter is called with three arguments: the transcoded data,
2150 as a string, the back-end, as a symbol, and the communication
2151 channel, as a plist.  It must return a string or nil.")
2152
2153 (defvar org-export-filter-drawer-functions nil
2154   "List of functions applied to a transcoded drawer.
2155 Each filter is called with three arguments: the transcoded data,
2156 as a string, the back-end, as a symbol, and the communication
2157 channel, as a plist.  It must return a string or nil.")
2158
2159 (defvar org-export-filter-dynamic-block-functions nil
2160   "List of functions applied to a transcoded dynamic-block.
2161 Each filter is called with three arguments: the transcoded data,
2162 as a string, the back-end, as a symbol, and the communication
2163 channel, as a plist.  It must return a string or nil.")
2164
2165 (defvar org-export-filter-example-block-functions nil
2166   "List of functions applied to a transcoded example-block.
2167 Each filter is called with three arguments: the transcoded data,
2168 as a string, the back-end, as a symbol, and the communication
2169 channel, as a plist.  It must return a string or nil.")
2170
2171 (defvar org-export-filter-export-block-functions nil
2172   "List of functions applied to a transcoded export-block.
2173 Each filter is called with three arguments: the transcoded data,
2174 as a string, the back-end, as a symbol, and the communication
2175 channel, as a plist.  It must return a string or nil.")
2176
2177 (defvar org-export-filter-fixed-width-functions nil
2178   "List of functions applied to a transcoded fixed-width.
2179 Each filter is called with three arguments: the transcoded data,
2180 as a string, the back-end, as a symbol, and the communication
2181 channel, as a plist.  It must return a string or nil.")
2182
2183 (defvar org-export-filter-footnote-definition-functions nil
2184   "List of functions applied to a transcoded footnote-definition.
2185 Each filter is called with three arguments: the transcoded data,
2186 as a string, the back-end, as a symbol, and the communication
2187 channel, as a plist.  It must return a string or nil.")
2188
2189 (defvar org-export-filter-headline-functions nil
2190   "List of functions applied to a transcoded headline.
2191 Each filter is called with three arguments: the transcoded data,
2192 as a string, the back-end, as a symbol, and the communication
2193 channel, as a plist.  It must return a string or nil.")
2194
2195 (defvar org-export-filter-horizontal-rule-functions nil
2196   "List of functions applied to a transcoded horizontal-rule.
2197 Each filter is called with three arguments: the transcoded data,
2198 as a string, the back-end, as a symbol, and the communication
2199 channel, as a plist.  It must return a string or nil.")
2200
2201 (defvar org-export-filter-inlinetask-functions nil
2202   "List of functions applied to a transcoded inlinetask.
2203 Each filter is called with three arguments: the transcoded data,
2204 as a string, the back-end, as a symbol, and the communication
2205 channel, as a plist.  It must return a string or nil.")
2206
2207 (defvar org-export-filter-item-functions nil
2208   "List of functions applied to a transcoded item.
2209 Each filter is called with three arguments: the transcoded data,
2210 as a string, the back-end, as a symbol, and the communication
2211 channel, as a plist.  It must return a string or nil.")
2212
2213 (defvar org-export-filter-keyword-functions nil
2214   "List of functions applied to a transcoded keyword.
2215 Each filter is called with three arguments: the transcoded data,
2216 as a string, the back-end, as a symbol, and the communication
2217 channel, as a plist.  It must return a string or nil.")
2218
2219 (defvar org-export-filter-latex-environment-functions nil
2220   "List of functions applied to a transcoded latex-environment.
2221 Each filter is called with three arguments: the transcoded data,
2222 as a string, the back-end, as a symbol, and the communication
2223 channel, as a plist.  It must return a string or nil.")
2224
2225 (defvar org-export-filter-node-property-functions nil
2226   "List of functions applied to a transcoded node-property.
2227 Each filter is called with three arguments: the transcoded data,
2228 as a string, the back-end, as a symbol, and the communication
2229 channel, as a plist.  It must return a string or nil.")
2230
2231 (defvar org-export-filter-paragraph-functions nil
2232   "List of functions applied to a transcoded paragraph.
2233 Each filter is called with three arguments: the transcoded data,
2234 as a string, the back-end, as a symbol, and the communication
2235 channel, as a plist.  It must return a string or nil.")
2236
2237 (defvar org-export-filter-plain-list-functions nil
2238   "List of functions applied to a transcoded plain-list.
2239 Each filter is called with three arguments: the transcoded data,
2240 as a string, the back-end, as a symbol, and the communication
2241 channel, as a plist.  It must return a string or nil.")
2242
2243 (defvar org-export-filter-planning-functions nil
2244   "List of functions applied to a transcoded planning.
2245 Each filter is called with three arguments: the transcoded data,
2246 as a string, the back-end, as a symbol, and the communication
2247 channel, as a plist.  It must return a string or nil.")
2248
2249 (defvar org-export-filter-property-drawer-functions nil
2250   "List of functions applied to a transcoded property-drawer.
2251 Each filter is called with three arguments: the transcoded data,
2252 as a string, the back-end, as a symbol, and the communication
2253 channel, as a plist.  It must return a string or nil.")
2254
2255 (defvar org-export-filter-quote-block-functions nil
2256   "List of functions applied to a transcoded quote block.
2257 Each filter is called with three arguments: the transcoded quote
2258 data, as a string, the back-end, as a symbol, and the
2259 communication channel, as a plist.  It must return a string or
2260 nil.")
2261
2262 (defvar org-export-filter-quote-section-functions nil
2263   "List of functions applied to a transcoded quote-section.
2264 Each filter is called with three arguments: the transcoded data,
2265 as a string, the back-end, as a symbol, and the communication
2266 channel, as a plist.  It must return a string or nil.")
2267
2268 (defvar org-export-filter-section-functions nil
2269   "List of functions applied to a transcoded section.
2270 Each filter is called with three arguments: the transcoded data,
2271 as a string, the back-end, as a symbol, and the communication
2272 channel, as a plist.  It must return a string or nil.")
2273
2274 (defvar org-export-filter-special-block-functions nil
2275   "List of functions applied to a transcoded special block.
2276 Each filter is called with three arguments: the transcoded data,
2277 as a string, the back-end, as a symbol, and the communication
2278 channel, as a plist.  It must return a string or nil.")
2279
2280 (defvar org-export-filter-src-block-functions nil
2281   "List of functions applied to a transcoded src-block.
2282 Each filter is called with three arguments: the transcoded data,
2283 as a string, the back-end, as a symbol, and the communication
2284 channel, as a plist.  It must return a string or nil.")
2285
2286 (defvar org-export-filter-table-functions nil
2287   "List of functions applied to a transcoded table.
2288 Each filter is called with three arguments: the transcoded data,
2289 as a string, the back-end, as a symbol, and the communication
2290 channel, as a plist.  It must return a string or nil.")
2291
2292 (defvar org-export-filter-table-cell-functions nil
2293   "List of functions applied to a transcoded table-cell.
2294 Each filter is called with three arguments: the transcoded data,
2295 as a string, the back-end, as a symbol, and the communication
2296 channel, as a plist.  It must return a string or nil.")
2297
2298 (defvar org-export-filter-table-row-functions nil
2299   "List of functions applied to a transcoded table-row.
2300 Each filter is called with three arguments: the transcoded data,
2301 as a string, the back-end, as a symbol, and the communication
2302 channel, as a plist.  It must return a string or nil.")
2303
2304 (defvar org-export-filter-verse-block-functions nil
2305   "List of functions applied to a transcoded verse block.
2306 Each filter is called with three arguments: the transcoded data,
2307 as a string, the back-end, as a symbol, and the communication
2308 channel, as a plist.  It must return a string or nil.")
2309
2310
2311 ;;;; Objects Filters
2312
2313 (defvar org-export-filter-bold-functions nil
2314   "List of functions applied to transcoded bold text.
2315 Each filter is called with three arguments: the transcoded data,
2316 as a string, the back-end, as a symbol, and the communication
2317 channel, as a plist.  It must return a string or nil.")
2318
2319 (defvar org-export-filter-code-functions nil
2320   "List of functions applied to transcoded code text.
2321 Each filter is called with three arguments: the transcoded data,
2322 as a string, the back-end, as a symbol, and the communication
2323 channel, as a plist.  It must return a string or nil.")
2324
2325 (defvar org-export-filter-entity-functions nil
2326   "List of functions applied to a transcoded entity.
2327 Each filter is called with three arguments: the transcoded data,
2328 as a string, the back-end, as a symbol, and the communication
2329 channel, as a plist.  It must return a string or nil.")
2330
2331 (defvar org-export-filter-export-snippet-functions nil
2332   "List of functions applied to a transcoded export-snippet.
2333 Each filter is called with three arguments: the transcoded data,
2334 as a string, the back-end, as a symbol, and the communication
2335 channel, as a plist.  It must return a string or nil.")
2336
2337 (defvar org-export-filter-footnote-reference-functions nil
2338   "List of functions applied to a transcoded footnote-reference.
2339 Each filter is called with three arguments: the transcoded data,
2340 as a string, the back-end, as a symbol, and the communication
2341 channel, as a plist.  It must return a string or nil.")
2342
2343 (defvar org-export-filter-inline-babel-call-functions nil
2344   "List of functions applied to a transcoded inline-babel-call.
2345 Each filter is called with three arguments: the transcoded data,
2346 as a string, the back-end, as a symbol, and the communication
2347 channel, as a plist.  It must return a string or nil.")
2348
2349 (defvar org-export-filter-inline-src-block-functions nil
2350   "List of functions applied to a transcoded inline-src-block.
2351 Each filter is called with three arguments: the transcoded data,
2352 as a string, the back-end, as a symbol, and the communication
2353 channel, as a plist.  It must return a string or nil.")
2354
2355 (defvar org-export-filter-italic-functions nil
2356   "List of functions applied to transcoded italic text.
2357 Each filter is called with three arguments: the transcoded data,
2358 as a string, the back-end, as a symbol, and the communication
2359 channel, as a plist.  It must return a string or nil.")
2360
2361 (defvar org-export-filter-latex-fragment-functions nil
2362   "List of functions applied to a transcoded latex-fragment.
2363 Each filter is called with three arguments: the transcoded data,
2364 as a string, the back-end, as a symbol, and the communication
2365 channel, as a plist.  It must return a string or nil.")
2366
2367 (defvar org-export-filter-line-break-functions nil
2368   "List of functions applied to a transcoded line-break.
2369 Each filter is called with three arguments: the transcoded data,
2370 as a string, the back-end, as a symbol, and the communication
2371 channel, as a plist.  It must return a string or nil.")
2372
2373 (defvar org-export-filter-link-functions nil
2374   "List of functions applied to a transcoded link.
2375 Each filter is called with three arguments: the transcoded data,
2376 as a string, the back-end, as a symbol, and the communication
2377 channel, as a plist.  It must return a string or nil.")
2378
2379 (defvar org-export-filter-macro-functions nil
2380   "List of functions applied to a transcoded macro.
2381 Each filter is called with three arguments: the transcoded data,
2382 as a string, the back-end, as a symbol, and the communication
2383 channel, as a plist.  It must return a string or nil.")
2384
2385 (defvar org-export-filter-radio-target-functions nil
2386   "List of functions applied to a transcoded radio-target.
2387 Each filter is called with three arguments: the transcoded data,
2388 as a string, the back-end, as a symbol, and the communication
2389 channel, as a plist.  It must return a string or nil.")
2390
2391 (defvar org-export-filter-statistics-cookie-functions nil
2392   "List of functions applied to a transcoded statistics-cookie.
2393 Each filter is called with three arguments: the transcoded data,
2394 as a string, the back-end, as a symbol, and the communication
2395 channel, as a plist.  It must return a string or nil.")
2396
2397 (defvar org-export-filter-strike-through-functions nil
2398   "List of functions applied to transcoded strike-through text.
2399 Each filter is called with three arguments: the transcoded data,
2400 as a string, the back-end, as a symbol, and the communication
2401 channel, as a plist.  It must return a string or nil.")
2402
2403 (defvar org-export-filter-subscript-functions nil
2404   "List of functions applied to a transcoded subscript.
2405 Each filter is called with three arguments: the transcoded data,
2406 as a string, the back-end, as a symbol, and the communication
2407 channel, as a plist.  It must return a string or nil.")
2408
2409 (defvar org-export-filter-superscript-functions nil
2410   "List of functions applied to a transcoded superscript.
2411 Each filter is called with three arguments: the transcoded data,
2412 as a string, the back-end, as a symbol, and the communication
2413 channel, as a plist.  It must return a string or nil.")
2414
2415 (defvar org-export-filter-target-functions nil
2416   "List of functions applied to a transcoded target.
2417 Each filter is called with three arguments: the transcoded data,
2418 as a string, the back-end, as a symbol, and the communication
2419 channel, as a plist.  It must return a string or nil.")
2420
2421 (defvar org-export-filter-timestamp-functions nil
2422   "List of functions applied to a transcoded timestamp.
2423 Each filter is called with three arguments: the transcoded data,
2424 as a string, the back-end, as a symbol, and the communication
2425 channel, as a plist.  It must return a string or nil.")
2426
2427 (defvar org-export-filter-underline-functions nil
2428   "List of functions applied to transcoded underline text.
2429 Each filter is called with three arguments: the transcoded data,
2430 as a string, the back-end, as a symbol, and the communication
2431 channel, as a plist.  It must return a string or nil.")
2432
2433 (defvar org-export-filter-verbatim-functions nil
2434   "List of functions applied to transcoded verbatim text.
2435 Each filter is called with three arguments: the transcoded data,
2436 as a string, the back-end, as a symbol, and the communication
2437 channel, as a plist.  It must return a string or nil.")
2438
2439
2440 ;;;; Filters Tools
2441 ;;
2442 ;; Internal function `org-export-install-filters' installs filters
2443 ;; hard-coded in back-ends (developer filters) and filters from global
2444 ;; variables (user filters) in the communication channel.
2445 ;;
2446 ;; Internal function `org-export-filter-apply-functions' takes care
2447 ;; about applying each filter in order to a given data.  It ignores
2448 ;; filters returning a nil value but stops whenever a filter returns
2449 ;; an empty string.
2450
2451 (defun org-export-filter-apply-functions (filters value info)
2452   "Call every function in FILTERS.
2453
2454 Functions are called with arguments VALUE, current export
2455 back-end and INFO.  A function returning a nil value will be
2456 skipped.  If it returns the empty string, the process ends and
2457 VALUE is ignored.
2458
2459 Call is done in a LIFO fashion, to be sure that developer
2460 specified filters, if any, are called first."
2461   (catch 'exit
2462     (dolist (filter filters value)
2463       (let ((result (funcall filter value (plist-get info :back-end) info)))
2464         (cond ((not result) value)
2465               ((equal value "") (throw 'exit nil))
2466               (t (setq value result)))))))
2467
2468 (defun org-export-install-filters (info)
2469   "Install filters properties in communication channel.
2470
2471 INFO is a plist containing the current communication channel.
2472
2473 Return the updated communication channel."
2474   (let (plist)
2475     ;; Install user defined filters with `org-export-filters-alist'.
2476     (mapc (lambda (p)
2477             (setq plist (plist-put plist (car p) (eval (cdr p)))))
2478           org-export-filters-alist)
2479     ;; Prepend back-end specific filters to that list.
2480     (let ((back-end-filters (intern (format "org-%s-filters-alist"
2481                                             (plist-get info :back-end)))))
2482       (when (boundp back-end-filters)
2483         (mapc (lambda (p)
2484                 ;; Single values get consed, lists are prepended.
2485                 (let ((key (car p)) (value (cdr p)))
2486                   (when value
2487                     (setq plist
2488                           (plist-put
2489                            plist key
2490                            (if (atom value) (cons value (plist-get plist key))
2491                              (append value (plist-get plist key))))))))
2492               (eval back-end-filters))))
2493     ;; Return new communication channel.
2494     (org-combine-plists info plist)))
2495
2496
2497 \f
2498 ;;; Core functions
2499 ;;
2500 ;; This is the room for the main function, `org-export-as', along with
2501 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
2502 ;; They differ only by the way they output the resulting code.
2503 ;;
2504 ;; `org-export-output-file-name' is an auxiliary function meant to be
2505 ;; used with `org-export-to-file'.  With a given extension, it tries
2506 ;; to provide a canonical file name to write export output to.
2507 ;;
2508 ;; Note that `org-export-as' doesn't really parse the current buffer,
2509 ;; but a copy of it (with the same buffer-local variables and
2510 ;; visibility), where macros and include keywords are expanded and
2511 ;; Babel blocks are executed, if appropriate.
2512 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
2513 ;;
2514 ;; File inclusion is taken care of by
2515 ;; `org-export-expand-include-keyword' and
2516 ;; `org-export--prepare-file-contents'.  Structure wise, including
2517 ;; a whole Org file in a buffer often makes little sense.  For
2518 ;; example, if the file contains an headline and the include keyword
2519 ;; was within an item, the item should contain the headline.  That's
2520 ;; why file inclusion should be done before any structure can be
2521 ;; associated to the file, that is before parsing.
2522 ;;
2523 ;; Macro are expanded with `org-export-expand-macro'.
2524
2525 (defun org-export-as
2526   (backend &optional subtreep visible-only body-only ext-plist noexpand)
2527   "Transcode current Org buffer into BACKEND code.
2528
2529 If narrowing is active in the current buffer, only transcode its
2530 narrowed part.
2531
2532 If a region is active, transcode that region.
2533
2534 When optional argument SUBTREEP is non-nil, transcode the
2535 sub-tree at point, extracting information from the headline
2536 properties first.
2537
2538 When optional argument VISIBLE-ONLY is non-nil, don't export
2539 contents of hidden elements.
2540
2541 When optional argument BODY-ONLY is non-nil, only return body
2542 code, without preamble nor postamble.
2543
2544 Optional argument EXT-PLIST, when provided, is a property list
2545 with external parameters overriding Org default settings, but
2546 still inferior to file-local settings.
2547
2548 Optional argument NOEXPAND, when non-nil, prevents included files
2549 to be expanded and Babel code to be executed.
2550
2551 Return code as a string."
2552   ;; Barf if BACKEND isn't registered.
2553   (org-export-barf-if-invalid-backend backend)
2554   (save-excursion
2555     (save-restriction
2556       ;; Narrow buffer to an appropriate region or subtree for
2557       ;; parsing.  If parsing subtree, be sure to remove main headline
2558       ;; too.
2559       (cond ((org-region-active-p)
2560              (narrow-to-region (region-beginning) (region-end)))
2561             (subtreep
2562              (org-narrow-to-subtree)
2563              (goto-char (point-min))
2564              (forward-line)
2565              (narrow-to-region (point) (point-max))))
2566       ;; Install user's and developer's filters in communication
2567       ;; channel.
2568       (let (info tree)
2569         (org-export-with-current-buffer-copy
2570          ;; Update communication channel and get parse tree.  Buffer
2571          ;; isn't parsed directly.  Instead, a temporary copy is
2572          ;; created, where include keywords, macros are expanded and
2573          ;; code blocks are evaluated.
2574          (unless noexpand
2575            (org-export-expand-include-keyword)
2576            ;; Update macro templates since #+INCLUDE keywords might
2577            ;; have added some new ones.
2578            (org-macro-initialize-templates)
2579            (org-macro-replace-all org-macro-templates)
2580            ;; TODO: Setting `org-current-export-file' is required by
2581            ;; Org Babel to properly resolve noweb references.  Once
2582            ;; "org-exp.el" is removed, modify
2583            ;; `org-export-blocks-preprocess' so it accepts the value
2584            ;; as an argument instead.
2585            (let ((org-current-export-file (current-buffer)))
2586              (org-export-blocks-preprocess)))
2587          ;; Update radio targets since keyword inclusion might have
2588          ;; added some more.
2589          (org-update-radio-target-regexp)
2590          ;; Run hook `org-export-before-parsing-hook'. with current
2591          ;; back-end as argument.
2592          (goto-char (point-min))
2593          (run-hook-with-args 'org-export-before-parsing-hook backend)
2594          ;; Initialize communication channel.
2595          (setq info
2596                (org-export-install-filters
2597                 (org-export-get-environment backend subtreep ext-plist)))
2598          ;; Expand export-specific set of macros: {{{author}}},
2599          ;; {{{date}}}, {{{email}}} and {{{title}}}.  It must be done
2600          ;; once regular macros have been expanded, since document
2601          ;; keywords may contain one of them.
2602          (unless noexpand
2603            (org-macro-replace-all
2604             (list (cons "author"
2605                         (org-element-interpret-data (plist-get info :author)))
2606                   (cons "date"
2607                         (org-element-interpret-data (plist-get info :date)))
2608                   ;; EMAIL is not a parsed keyword: store it as-is.
2609                   (cons "email" (or (plist-get info :email) ""))
2610                   (cons "title"
2611                         (org-element-interpret-data (plist-get info :title))))))
2612          ;; Eventually parse buffer.  Call parse-tree filters to get
2613          ;; the final tree.
2614          (setq tree
2615                (org-export-filter-apply-functions
2616                 (plist-get info :filter-parse-tree)
2617                 (org-element-parse-buffer nil visible-only) info)))
2618         ;; Now tree is complete, compute its properties and add them
2619         ;; to communication channel.
2620         (setq info
2621               (org-combine-plists
2622                info (org-export-collect-tree-properties tree info)))
2623         ;; Eventually transcode TREE.  Wrap the resulting string into
2624         ;; a template, if required.  Finally call final-output filter.
2625         (let* ((body (org-element-normalize-string (org-export-data tree info)))
2626                (template (cdr (assq 'template
2627                                     (plist-get info :translate-alist))))
2628                (output (org-export-filter-apply-functions
2629                         (plist-get info :filter-final-output)
2630                         (if (or (not (functionp template)) body-only) body
2631                           (funcall template body info))
2632                         info)))
2633           ;; Maybe add final OUTPUT to kill ring, then return it.
2634           (when org-export-copy-to-kill-ring (org-kill-new output))
2635           output)))))
2636
2637 (defun org-export-to-buffer
2638   (backend buffer &optional subtreep visible-only body-only ext-plist noexpand)
2639   "Call `org-export-as' with output to a specified buffer.
2640
2641 BACKEND is the back-end used for transcoding, as a symbol.
2642
2643 BUFFER is the output buffer.  If it already exists, it will be
2644 erased first, otherwise, it will be created.
2645
2646 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2647 and NOEXPAND are similar to those used in `org-export-as', which
2648 see.
2649
2650 Return buffer."
2651   (let ((out (org-export-as
2652               backend subtreep visible-only body-only ext-plist noexpand))
2653         (buffer (get-buffer-create buffer)))
2654     (with-current-buffer buffer
2655       (erase-buffer)
2656       (insert out)
2657       (goto-char (point-min)))
2658     buffer))
2659
2660 (defun org-export-to-file
2661   (backend file &optional subtreep visible-only body-only ext-plist noexpand)
2662   "Call `org-export-as' with output to a specified file.
2663
2664 BACKEND is the back-end used for transcoding, as a symbol.  FILE
2665 is the name of the output file, as a string.
2666
2667 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2668 and NOEXPAND are similar to those used in `org-export-as', which
2669 see.
2670
2671 Return output file's name."
2672   ;; Checks for FILE permissions.  `write-file' would do the same, but
2673   ;; we'd rather avoid needless transcoding of parse tree.
2674   (unless (file-writable-p file) (error "Output file not writable"))
2675   ;; Insert contents to a temporary buffer and write it to FILE.
2676   (let ((out (org-export-as
2677               backend subtreep visible-only body-only ext-plist noexpand)))
2678     (with-temp-buffer
2679       (insert out)
2680       (let ((coding-system-for-write org-export-coding-system))
2681         (write-file file))))
2682   ;; Return full path.
2683   file)
2684
2685 (defun org-export-output-file-name (extension &optional subtreep pub-dir)
2686   "Return output file's name according to buffer specifications.
2687
2688 EXTENSION is a string representing the output file extension,
2689 with the leading dot.
2690
2691 With a non-nil optional argument SUBTREEP, try to determine
2692 output file's name by looking for \"EXPORT_FILE_NAME\" property
2693 of subtree at point.
2694
2695 When optional argument PUB-DIR is set, use it as the publishing
2696 directory.
2697
2698 When optional argument VISIBLE-ONLY is non-nil, don't export
2699 contents of hidden elements.
2700
2701 Return file name as a string, or nil if it couldn't be
2702 determined."
2703   (let ((base-name
2704          ;; File name may come from EXPORT_FILE_NAME subtree property,
2705          ;; assuming point is at beginning of said sub-tree.
2706          (file-name-sans-extension
2707           (or (and subtreep
2708                    (org-entry-get
2709                     (save-excursion
2710                       (ignore-errors (org-back-to-heading) (point)))
2711                     "EXPORT_FILE_NAME" t))
2712               ;; File name may be extracted from buffer's associated
2713               ;; file, if any.
2714               (let ((visited-file (buffer-file-name (buffer-base-buffer))))
2715                 (and visited-file (file-name-nondirectory visited-file)))
2716               ;; Can't determine file name on our own: Ask user.
2717               (let ((read-file-name-function
2718                      (and org-completion-use-ido 'ido-read-file-name)))
2719                 (read-file-name
2720                  "Output file: " pub-dir nil nil nil
2721                  (lambda (name)
2722                    (string= (file-name-extension name t) extension))))))))
2723     ;; Build file name.  Enforce EXTENSION over whatever user may have
2724     ;; come up with.  PUB-DIR, if defined, always has precedence over
2725     ;; any provided path.
2726     (cond
2727      (pub-dir
2728       (concat (file-name-as-directory pub-dir)
2729               (file-name-nondirectory base-name)
2730               extension))
2731      ((file-name-absolute-p base-name) (concat base-name extension))
2732      (t (concat (file-name-as-directory ".") base-name extension)))))
2733
2734 (defmacro org-export-with-current-buffer-copy (&rest body)
2735   "Apply BODY in a copy of the current buffer.
2736
2737 The copy preserves local variables and visibility of the original
2738 buffer.
2739
2740 Point is at buffer's beginning when BODY is applied."
2741   (declare (debug (body)))
2742   (org-with-gensyms (original-buffer offset buffer-string overlays region)
2743     `(let* ((,original-buffer (current-buffer))
2744             (,region (list (point-min) (point-max)))
2745             (,buffer-string (org-with-wide-buffer (buffer-string)))
2746             (,overlays (mapcar 'copy-overlay (apply 'overlays-in ,region))))
2747        (with-temp-buffer
2748          (let ((buffer-invisibility-spec nil))
2749            (org-clone-local-variables
2750             ,original-buffer
2751             "^\\(org-\\|orgtbl-\\|major-mode$\\|outline-\\(regexp\\|level\\)$\\)")
2752            (insert ,buffer-string)
2753            (apply 'narrow-to-region ,region)
2754            (mapc (lambda (ov)
2755                    (move-overlay
2756                     ov (overlay-start ov) (overlay-end ov) (current-buffer)))
2757                  ,overlays)
2758            (goto-char (point-min))
2759            (progn ,@body))))))
2760
2761 (defun org-export-expand-include-keyword (&optional included dir)
2762   "Expand every include keyword in buffer.
2763 Optional argument INCLUDED is a list of included file names along
2764 with their line restriction, when appropriate.  It is used to
2765 avoid infinite recursion.  Optional argument DIR is the current
2766 working directory.  It is used to properly resolve relative
2767 paths."
2768   (let ((case-fold-search t))
2769     (goto-char (point-min))
2770     (while (re-search-forward "^[ \t]*#\\+INCLUDE: +\\(.*\\)[ \t]*$" nil t)
2771       (when (eq (org-element-type (save-match-data (org-element-at-point)))
2772                 'keyword)
2773         (beginning-of-line)
2774         ;; Extract arguments from keyword's value.
2775         (let* ((value (match-string 1))
2776                (ind (org-get-indentation))
2777                (file (and (string-match "^\"\\(\\S-+\\)\"" value)
2778                           (prog1 (expand-file-name (match-string 1 value) dir)
2779                             (setq value (replace-match "" nil nil value)))))
2780                (lines
2781                 (and (string-match
2782                       ":lines +\"\\(\\(?:[0-9]+\\)?-\\(?:[0-9]+\\)?\\)\"" value)
2783                      (prog1 (match-string 1 value)
2784                        (setq value (replace-match "" nil nil value)))))
2785                (env (cond ((string-match "\\<example\\>" value) 'example)
2786                           ((string-match "\\<src\\(?: +\\(.*\\)\\)?" value)
2787                            (match-string 1 value))))
2788                ;; Minimal level of included file defaults to the child
2789                ;; level of the current headline, if any, or one.  It
2790                ;; only applies is the file is meant to be included as
2791                ;; an Org one.
2792                (minlevel
2793                 (and (not env)
2794                      (if (string-match ":minlevel +\\([0-9]+\\)" value)
2795                          (prog1 (string-to-number (match-string 1 value))
2796                            (setq value (replace-match "" nil nil value)))
2797                        (let ((cur (org-current-level)))
2798                          (if cur (1+ (org-reduced-level cur)) 1))))))
2799           ;; Remove keyword.
2800           (delete-region (point) (progn (forward-line) (point)))
2801           (cond
2802            ((not file) (error "Invalid syntax in INCLUDE keyword"))
2803            ((not (file-readable-p file)) (error "Cannot include file %s" file))
2804            ;; Check if files has already been parsed.  Look after
2805            ;; inclusion lines too, as different parts of the same file
2806            ;; can be included too.
2807            ((member (list file lines) included)
2808             (error "Recursive file inclusion: %s" file))
2809            (t
2810             (cond
2811              ((eq env 'example)
2812               (insert
2813                (let ((ind-str (make-string ind ? ))
2814                      (contents
2815                       (org-escape-code-in-string
2816                        (org-export--prepare-file-contents file lines))))
2817                  (format "%s#+BEGIN_EXAMPLE\n%s%s#+END_EXAMPLE\n"
2818                          ind-str contents ind-str))))
2819              ((stringp env)
2820               (insert
2821                (let ((ind-str (make-string ind ? ))
2822                      (contents
2823                       (org-escape-code-in-string
2824                        (org-export--prepare-file-contents file lines))))
2825                  (format "%s#+BEGIN_SRC %s\n%s%s#+END_SRC\n"
2826                          ind-str env contents ind-str))))
2827              (t
2828               (insert
2829                (with-temp-buffer
2830                  (org-mode)
2831                  (insert
2832                   (org-export--prepare-file-contents file lines ind minlevel))
2833                  (org-export-expand-include-keyword
2834                   (cons (list file lines) included)
2835                   (file-name-directory file))
2836                  (buffer-string))))))))))))
2837
2838 (defun org-export--prepare-file-contents (file &optional lines ind minlevel)
2839   "Prepare the contents of FILE for inclusion and return them as a string.
2840
2841 When optional argument LINES is a string specifying a range of
2842 lines, include only those lines.
2843
2844 Optional argument IND, when non-nil, is an integer specifying the
2845 global indentation of returned contents.  Since its purpose is to
2846 allow an included file to stay in the same environment it was
2847 created \(i.e. a list item), it doesn't apply past the first
2848 headline encountered.
2849
2850 Optional argument MINLEVEL, when non-nil, is an integer
2851 specifying the level that any top-level headline in the included
2852 file should have."
2853   (with-temp-buffer
2854     (insert-file-contents file)
2855     (when lines
2856       (let* ((lines (split-string lines "-"))
2857              (lbeg (string-to-number (car lines)))
2858              (lend (string-to-number (cadr lines)))
2859              (beg (if (zerop lbeg) (point-min)
2860                     (goto-char (point-min))
2861                     (forward-line (1- lbeg))
2862                     (point)))
2863              (end (if (zerop lend) (point-max)
2864                     (goto-char (point-min))
2865                     (forward-line (1- lend))
2866                     (point))))
2867         (narrow-to-region beg end)))
2868     ;; Remove blank lines at beginning and end of contents.  The logic
2869     ;; behind that removal is that blank lines around include keyword
2870     ;; override blank lines in included file.
2871     (goto-char (point-min))
2872     (org-skip-whitespace)
2873     (beginning-of-line)
2874     (delete-region (point-min) (point))
2875     (goto-char (point-max))
2876     (skip-chars-backward " \r\t\n")
2877     (forward-line)
2878     (delete-region (point) (point-max))
2879     ;; If IND is set, preserve indentation of include keyword until
2880     ;; the first headline encountered.
2881     (when ind
2882       (unless (eq major-mode 'org-mode) (org-mode))
2883       (goto-char (point-min))
2884       (let ((ind-str (make-string ind ? )))
2885         (while (not (or (eobp) (looking-at org-outline-regexp-bol)))
2886           ;; Do not move footnote definitions out of column 0.
2887           (unless (and (looking-at org-footnote-definition-re)
2888                        (eq (org-element-type (org-element-at-point))
2889                            'footnote-definition))
2890             (insert ind-str))
2891           (forward-line))))
2892     ;; When MINLEVEL is specified, compute minimal level for headlines
2893     ;; in the file (CUR-MIN), and remove stars to each headline so
2894     ;; that headlines with minimal level have a level of MINLEVEL.
2895     (when minlevel
2896       (unless (eq major-mode 'org-mode) (org-mode))
2897       (org-with-limited-levels
2898        (let ((levels (org-map-entries
2899                       (lambda () (org-reduced-level (org-current-level))))))
2900          (when levels
2901            (let ((offset (- minlevel (apply 'min levels))))
2902              (unless (zerop offset)
2903                (when org-odd-levels-only (setq offset (* offset 2)))
2904                ;; Only change stars, don't bother moving whole
2905                ;; sections.
2906                (org-map-entries
2907                 (lambda () (if (< offset 0) (delete-char (abs offset))
2908                         (insert (make-string offset ?*)))))))))))
2909     (buffer-string)))
2910
2911 \f
2912 ;;; Tools For Back-Ends
2913 ;;
2914 ;; A whole set of tools is available to help build new exporters.  Any
2915 ;; function general enough to have its use across many back-ends
2916 ;; should be added here.
2917
2918 ;;;; For Affiliated Keywords
2919 ;;
2920 ;; `org-export-read-attribute' reads a property from a given element
2921 ;;  as a plist.  It can be used to normalize affiliated keywords'
2922 ;;  syntax.
2923 ;;
2924 ;; Since captions can span over multiple lines and accept dual values,
2925 ;; their internal representation is a bit tricky.  Therefore,
2926 ;; `org-export-get-caption' transparently returns a given element's
2927 ;; caption as a secondary string.
2928
2929 (defun org-export-read-attribute (attribute element &optional property)
2930   "Turn ATTRIBUTE property from ELEMENT into a plist.
2931
2932 When optional argument PROPERTY is non-nil, return the value of
2933 that property within attributes.
2934
2935 This function assumes attributes are defined as \":keyword
2936 value\" pairs.  It is appropriate for `:attr_html' like
2937 properties."
2938   (let ((attributes
2939          (let ((value (org-element-property attribute element)))
2940            (and value
2941                 (read (format "(%s)" (mapconcat 'identity value " ")))))))
2942     (if property (plist-get attributes property) attributes)))
2943
2944 (defun org-export-get-caption (element &optional shortp)
2945   "Return caption from ELEMENT as a secondary string.
2946
2947 When optional argument SHORTP is non-nil, return short caption,
2948 as a secondary string, instead.
2949
2950 Caption lines are separated by a white space."
2951   (let ((full-caption (org-element-property :caption element)) caption)
2952     (dolist (line full-caption (cdr caption))
2953       (let ((cap (funcall (if shortp 'cdr 'car) line)))
2954         (when cap
2955           (setq caption (nconc (list " ") (copy-sequence cap) caption)))))))
2956
2957
2958 ;;;; For Export Snippets
2959 ;;
2960 ;; Every export snippet is transmitted to the back-end.  Though, the
2961 ;; latter will only retain one type of export-snippet, ignoring
2962 ;; others, based on the former's target back-end.  The function
2963 ;; `org-export-snippet-backend' returns that back-end for a given
2964 ;; export-snippet.
2965
2966 (defun org-export-snippet-backend (export-snippet)
2967   "Return EXPORT-SNIPPET targeted back-end as a symbol.
2968 Translation, with `org-export-snippet-translation-alist', is
2969 applied."
2970   (let ((back-end (org-element-property :back-end export-snippet)))
2971     (intern
2972      (or (cdr (assoc back-end org-export-snippet-translation-alist))
2973          back-end))))
2974
2975
2976 ;;;; For Footnotes
2977 ;;
2978 ;; `org-export-collect-footnote-definitions' is a tool to list
2979 ;; actually used footnotes definitions in the whole parse tree, or in
2980 ;; an headline, in order to add footnote listings throughout the
2981 ;; transcoded data.
2982 ;;
2983 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2984 ;; back-ends, when they need to attach the footnote definition only to
2985 ;; the first occurrence of the corresponding label.
2986 ;;
2987 ;; `org-export-get-footnote-definition' and
2988 ;; `org-export-get-footnote-number' provide easier access to
2989 ;; additional information relative to a footnote reference.
2990
2991 (defun org-export-collect-footnote-definitions (data info)
2992   "Return an alist between footnote numbers, labels and definitions.
2993
2994 DATA is the parse tree from which definitions are collected.
2995 INFO is the plist used as a communication channel.
2996
2997 Definitions are sorted by order of references.  They either
2998 appear as Org data or as a secondary string for inlined
2999 footnotes.  Unreferenced definitions are ignored."
3000   (let* (num-alist
3001          collect-fn                     ; for byte-compiler.
3002          (collect-fn
3003           (function
3004            (lambda (data)
3005              ;; Collect footnote number, label and definition in DATA.
3006              (org-element-map
3007               data 'footnote-reference
3008               (lambda (fn)
3009                 (when (org-export-footnote-first-reference-p fn info)
3010                   (let ((def (org-export-get-footnote-definition fn info)))
3011                     (push
3012                      (list (org-export-get-footnote-number fn info)
3013                            (org-element-property :label fn)
3014                            def)
3015                      num-alist)
3016                     ;; Also search in definition for nested footnotes.
3017                     (when (eq (org-element-property :type fn) 'standard)
3018                       (funcall collect-fn def)))))
3019               ;; Don't enter footnote definitions since it will happen
3020               ;; when their first reference is found.
3021               info nil 'footnote-definition)))))
3022     (funcall collect-fn (plist-get info :parse-tree))
3023     (reverse num-alist)))
3024
3025 (defun org-export-footnote-first-reference-p (footnote-reference info)
3026   "Non-nil when a footnote reference is the first one for its label.
3027
3028 FOOTNOTE-REFERENCE is the footnote reference being considered.
3029 INFO is the plist used as a communication channel."
3030   (let ((label (org-element-property :label footnote-reference)))
3031     ;; Anonymous footnotes are always a first reference.
3032     (if (not label) t
3033       ;; Otherwise, return the first footnote with the same LABEL and
3034       ;; test if it is equal to FOOTNOTE-REFERENCE.
3035       (let* (search-refs                ; for byte-compiler.
3036              (search-refs
3037               (function
3038                (lambda (data)
3039                  (org-element-map
3040                   data 'footnote-reference
3041                   (lambda (fn)
3042                     (cond
3043                      ((string= (org-element-property :label fn) label)
3044                       (throw 'exit fn))
3045                      ;; If FN isn't inlined, be sure to traverse its
3046                      ;; definition before resuming search.  See
3047                      ;; comments in `org-export-get-footnote-number'
3048                      ;; for more information.
3049                      ((eq (org-element-property :type fn) 'standard)
3050                       (funcall search-refs
3051                                (org-export-get-footnote-definition fn info)))))
3052                   ;; Don't enter footnote definitions since it will
3053                   ;; happen when their first reference is found.
3054                   info 'first-match 'footnote-definition)))))
3055         (eq (catch 'exit (funcall search-refs (plist-get info :parse-tree)))
3056                footnote-reference)))))
3057
3058 (defun org-export-get-footnote-definition (footnote-reference info)
3059   "Return definition of FOOTNOTE-REFERENCE as parsed data.
3060 INFO is the plist used as a communication channel."
3061   (let ((label (org-element-property :label footnote-reference)))
3062     (or (org-element-property :inline-definition footnote-reference)
3063         (cdr (assoc label (plist-get info :footnote-definition-alist))))))
3064
3065 (defun org-export-get-footnote-number (footnote info)
3066   "Return number associated to a footnote.
3067
3068 FOOTNOTE is either a footnote reference or a footnote definition.
3069 INFO is the plist used as a communication channel."
3070   (let* ((label (org-element-property :label footnote))
3071          seen-refs
3072          search-ref                     ; For byte-compiler.
3073          (search-ref
3074           (function
3075            (lambda (data)
3076              ;; Search footnote references through DATA, filling
3077              ;; SEEN-REFS along the way.
3078              (org-element-map
3079               data 'footnote-reference
3080               (lambda (fn)
3081                 (let ((fn-lbl (org-element-property :label fn)))
3082                   (cond
3083                    ;; Anonymous footnote match: return number.
3084                    ((and (not fn-lbl) (eq fn footnote))
3085                     (throw 'exit (1+ (length seen-refs))))
3086                    ;; Labels match: return number.
3087                    ((and label (string= label fn-lbl))
3088                     (throw 'exit (1+ (length seen-refs))))
3089                    ;; Anonymous footnote: it's always a new one.  Also,
3090                    ;; be sure to return nil from the `cond' so
3091                    ;; `first-match' doesn't get us out of the loop.
3092                    ((not fn-lbl) (push 'inline seen-refs) nil)
3093                    ;; Label not seen so far: add it so SEEN-REFS.
3094                    ;;
3095                    ;; Also search for subsequent references in
3096                    ;; footnote definition so numbering follows reading
3097                    ;; logic.  Note that we don't have to care about
3098                    ;; inline definitions, since `org-element-map'
3099                    ;; already traverses them at the right time.
3100                    ;;
3101                    ;; Once again, return nil to stay in the loop.
3102                    ((not (member fn-lbl seen-refs))
3103                     (push fn-lbl seen-refs)
3104                     (funcall search-ref
3105                              (org-export-get-footnote-definition fn info))
3106                     nil))))
3107               ;; Don't enter footnote definitions since it will happen
3108               ;; when their first reference is found.
3109               info 'first-match 'footnote-definition)))))
3110     (catch 'exit (funcall search-ref (plist-get info :parse-tree)))))
3111
3112
3113 ;;;; For Headlines
3114 ;;
3115 ;; `org-export-get-relative-level' is a shortcut to get headline
3116 ;; level, relatively to the lower headline level in the parsed tree.
3117 ;;
3118 ;; `org-export-get-headline-number' returns the section number of an
3119 ;; headline, while `org-export-number-to-roman' allows to convert it
3120 ;; to roman numbers.
3121 ;;
3122 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
3123 ;; `org-export-last-sibling-p' are three useful predicates when it
3124 ;; comes to fulfill the `:headline-levels' property.
3125
3126 (defun org-export-get-relative-level (headline info)
3127   "Return HEADLINE relative level within current parsed tree.
3128 INFO is a plist holding contextual information."
3129   (+ (org-element-property :level headline)
3130      (or (plist-get info :headline-offset) 0)))
3131
3132 (defun org-export-low-level-p (headline info)
3133   "Non-nil when HEADLINE is considered as low level.
3134
3135 INFO is a plist used as a communication channel.
3136
3137 A low level headlines has a relative level greater than
3138 `:headline-levels' property value.
3139
3140 Return value is the difference between HEADLINE relative level
3141 and the last level being considered as high enough, or nil."
3142   (let ((limit (plist-get info :headline-levels)))
3143     (when (wholenump limit)
3144       (let ((level (org-export-get-relative-level headline info)))
3145         (and (> level limit) (- level limit))))))
3146
3147 (defun org-export-get-headline-number (headline info)
3148   "Return HEADLINE numbering as a list of numbers.
3149 INFO is a plist holding contextual information."
3150   (cdr (assoc headline (plist-get info :headline-numbering))))
3151
3152 (defun org-export-numbered-headline-p (headline info)
3153   "Return a non-nil value if HEADLINE element should be numbered.
3154 INFO is a plist used as a communication channel."
3155   (let ((sec-num (plist-get info :section-numbers))
3156         (level (org-export-get-relative-level headline info)))
3157     (if (wholenump sec-num) (<= level sec-num) sec-num)))
3158
3159 (defun org-export-number-to-roman (n)
3160   "Convert integer N into a roman numeral."
3161   (let ((roman '((1000 . "M") (900 . "CM") (500 . "D") (400 . "CD")
3162                  ( 100 . "C") ( 90 . "XC") ( 50 . "L") ( 40 . "XL")
3163                  (  10 . "X") (  9 . "IX") (  5 . "V") (  4 . "IV")
3164                  (   1 . "I")))
3165         (res ""))
3166     (if (<= n 0)
3167         (number-to-string n)
3168       (while roman
3169         (if (>= n (caar roman))
3170             (setq n (- n (caar roman))
3171                   res (concat res (cdar roman)))
3172           (pop roman)))
3173       res)))
3174
3175 (defun org-export-get-tags (element info &optional tags inherited)
3176   "Return list of tags associated to ELEMENT.
3177
3178 ELEMENT has either an `headline' or an `inlinetask' type.  INFO
3179 is a plist used as a communication channel.
3180
3181 Select tags (see `org-export-select-tags') and exclude tags (see
3182 `org-export-exclude-tags') are removed from the list.
3183
3184 When non-nil, optional argument TAGS should be a list of strings.
3185 Any tag belonging to this list will also be removed.
3186
3187 When optional argument INHERITED is non-nil, tags can also be
3188 inherited from parent headlines.."
3189   (org-remove-if
3190    (lambda (tag) (or (member tag (plist-get info :select-tags))
3191                 (member tag (plist-get info :exclude-tags))
3192                 (member tag tags)))
3193    (if (not inherited) (org-element-property :tags element)
3194      ;; Build complete list of inherited tags.
3195      (let ((current-tag-list (org-element-property :tags element)))
3196        (mapc
3197         (lambda (parent)
3198           (mapc
3199            (lambda (tag)
3200              (when (and (memq (org-element-type parent) '(headline inlinetask))
3201                         (not (member tag current-tag-list)))
3202                (push tag current-tag-list)))
3203            (org-element-property :tags parent)))
3204         (org-export-get-genealogy element))
3205        current-tag-list))))
3206
3207 (defun org-export-get-node-property (property blob &optional inherited)
3208   "Return node PROPERTY value for BLOB.
3209
3210 PROPERTY is normalized symbol (i.e. `:cookie-data').  BLOB is an
3211 element or object.
3212
3213 If optional argument INHERITED is non-nil, the value can be
3214 inherited from a parent headline.
3215
3216 Return value is a string or nil."
3217   (let ((headline (if (eq (org-element-type blob) 'headline) blob
3218                     (org-export-get-parent-headline blob))))
3219     (if (not inherited) (org-element-property property blob)
3220       (let ((parent headline) value)
3221         (catch 'found
3222           (while parent
3223             (when (plist-member (nth 1 parent) property)
3224               (throw 'found (org-element-property property parent)))
3225             (setq parent (org-element-property :parent parent))))))))
3226
3227 (defun org-export-first-sibling-p (headline info)
3228   "Non-nil when HEADLINE is the first sibling in its sub-tree.
3229 INFO is a plist used as a communication channel."
3230   (not (eq (org-element-type (org-export-get-previous-element headline info))
3231            'headline)))
3232
3233 (defun org-export-last-sibling-p (headline info)
3234   "Non-nil when HEADLINE is the last sibling in its sub-tree.
3235 INFO is a plist used as a communication channel."
3236   (not (org-export-get-next-element headline info)))
3237
3238
3239 ;;;; For Links
3240 ;;
3241 ;; `org-export-solidify-link-text' turns a string into a safer version
3242 ;; for links, replacing most non-standard characters with hyphens.
3243 ;;
3244 ;; `org-export-get-coderef-format' returns an appropriate format
3245 ;; string for coderefs.
3246 ;;
3247 ;; `org-export-inline-image-p' returns a non-nil value when the link
3248 ;; provided should be considered as an inline image.
3249 ;;
3250 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
3251 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
3252 ;; returns an appropriate unique identifier when found, or nil.
3253 ;;
3254 ;; `org-export-resolve-id-link' returns the first headline with
3255 ;; specified id or custom-id in parse tree, the path to the external
3256 ;; file with the id or nil when neither was found.