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