org-export: Fix export to subtree
[org-mode/org-mode-NeilSmithlineMods.git] / contrib / lisp / org-export.el
blob697a56988072e215b9824427bdc98f12de5c391d
1 ;;; org-export.el --- Generic Export Engine For Org
3 ;; Copyright (C) 2012 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
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.
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.
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/>.
21 ;;; Commentary:
23 ;; This library implements a generic export engine for Org, built on
24 ;; its syntactical parser: Org Elements.
26 ;; Besides that parser, the generic exporter is made of three distinct
27 ;; parts:
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.
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.
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.
46 ;; The core function is `org-export-as'. It returns the transcoded
47 ;; buffer as a string.
49 ;; In order to derive an exporter out of this generic implementation,
50 ;; one can define a transcode function for each element or object.
51 ;; Such function should return a string for the corresponding element,
52 ;; without any trailing space, or nil. It must accept three
53 ;; arguments:
54 ;; 1. the element or object itself,
55 ;; 2. its contents, or nil when it isn't recursive,
56 ;; 3. the property list used as a communication channel.
58 ;; If no such function is found, that element or object type will
59 ;; simply be ignored, along with any separating blank line. The same
60 ;; will happen if the function returns the nil value. If that
61 ;; function returns the empty string, the type will be ignored, but
62 ;; the blank lines will be kept.
64 ;; Contents, when not nil, are stripped from any global indentation
65 ;; (although the relative one is preserved). They also always end
66 ;; with a single newline character.
68 ;; These functions must follow a strict naming convention:
69 ;; `org-BACKEND-TYPE' where, obviously, BACKEND is the name of the
70 ;; export back-end and TYPE the type of the element or object handled.
72 ;; Moreover, two additional functions can be defined. On the one
73 ;; hand, `org-BACKEND-template' returns the final transcoded string,
74 ;; and can be used to add a preamble and a postamble to document's
75 ;; body. It must accept two arguments: the transcoded string and the
76 ;; property list containing export options. On the other hand,
77 ;; `org-BACKEND-plain-text', when defined, is to be called on every
78 ;; text not recognized as an element or an object. It must accept two
79 ;; arguments: the text string and the information channel.
81 ;; Any back-end can define its own variables. Among them, those
82 ;; customizables should belong to the `org-export-BACKEND' group.
83 ;; Also, a special variable, `org-BACKEND-option-alist', allows to
84 ;; define buffer keywords and "#+options:" items specific to that
85 ;; back-end. See `org-export-option-alist' for supported defaults and
86 ;; syntax.
88 ;; Tools for common tasks across back-ends are implemented in the
89 ;; penultimate part of this file. A dispatcher for standard back-ends
90 ;; is provided in the last one.
92 ;;; Code:
93 (eval-when-compile (require 'cl))
94 (require 'org-element)
95 ;; Require major back-ends and publishing tools
96 (require 'org-e-ascii "../../EXPERIMENTAL/org-e-ascii.el")
97 (require 'org-e-html "../../EXPERIMENTAL/org-e-html.el")
98 (require 'org-e-latex "../../EXPERIMENTAL/org-e-latex.el")
99 (require 'org-e-publish "../../EXPERIMENTAL/org-e-publish.el")
102 ;;; Internal Variables
104 ;; Among internal variables, the most important is
105 ;; `org-export-option-alist'. This variable define the global export
106 ;; options, shared between every exporter, and how they are acquired.
108 (defconst org-export-max-depth 19
109 "Maximum nesting depth for headlines, counting from 0.")
111 (defconst org-export-option-alist
112 '((:author "AUTHOR" nil user-full-name t)
113 (:creator "CREATOR" nil org-export-creator-string)
114 (:date "DATE" nil nil t)
115 (:description "DESCRIPTION" nil nil newline)
116 (:email "EMAIL" nil user-mail-address t)
117 (:exclude-tags "EXPORT_EXCLUDE_TAGS" nil org-export-exclude-tags split)
118 (:headline-levels nil "H" org-export-headline-levels)
119 (:keywords "KEYWORDS" nil nil space)
120 (:language "LANGUAGE" nil org-export-default-language t)
121 (:preserve-breaks nil "\\n" org-export-preserve-breaks)
122 (:section-numbers nil "num" org-export-with-section-numbers)
123 (:select-tags "EXPORT_SELECT_TAGS" nil org-export-select-tags split)
124 (:time-stamp-file nil "timestamp" org-export-time-stamp-file)
125 (:title "TITLE" nil nil space)
126 (:with-archived-trees nil "arch" org-export-with-archived-trees)
127 (:with-author nil "author" org-export-with-author)
128 (:with-creator nil "creator" org-export-with-creator)
129 (:with-drawers nil "d" org-export-with-drawers)
130 (:with-email nil "email" org-export-with-email)
131 (:with-emphasize nil "*" org-export-with-emphasize)
132 (:with-entities nil "e" org-export-with-entities)
133 (:with-fixed-width nil ":" org-export-with-fixed-width)
134 (:with-footnotes nil "f" org-export-with-footnotes)
135 (:with-priority nil "pri" org-export-with-priority)
136 (:with-special-strings nil "-" org-export-with-special-strings)
137 (:with-sub-superscript nil "^" org-export-with-sub-superscripts)
138 (:with-toc nil "toc" org-export-with-toc)
139 (:with-tables nil "|" org-export-with-tables)
140 (:with-tags nil "tags" org-export-with-tags)
141 (:with-tasks nil "tasks" org-export-with-tasks)
142 (:with-timestamps nil "<" org-export-with-timestamps)
143 (:with-todo-keywords nil "todo" org-export-with-todo-keywords))
144 "Alist between export properties and ways to set them.
146 The car of the alist is the property name, and the cdr is a list
147 like \(KEYWORD OPTION DEFAULT BEHAVIOUR\) where:
149 KEYWORD is a string representing a buffer keyword, or nil.
150 OPTION is a string that could be found in an #+OPTIONS: line.
151 DEFAULT is the default value for the property.
152 BEHAVIOUR determine how Org should handle multiple keywords for
153 the same property. It is a symbol among:
154 nil Keep old value and discard the new one.
155 t Replace old value with the new one.
156 `space' Concatenate the values, separating them with a space.
157 `newline' Concatenate the values, separating them with
158 a newline.
159 `split' Split values at white spaces, and cons them to the
160 previous list.
162 KEYWORD and OPTION have precedence over DEFAULT.
164 All these properties should be back-end agnostic. For back-end
165 specific properties, define a similar variable named
166 `org-BACKEND-option-alist', replacing BACKEND with the name of
167 the appropriate back-end. You can also redefine properties
168 there, as they have precedence over these.")
170 (defconst org-export-special-keywords
171 '("SETUP_FILE" "OPTIONS" "MACRO")
172 "List of in-buffer keywords that require special treatment.
173 These keywords are not directly associated to a property. The
174 way they are handled must be hard-coded into
175 `org-export-get-inbuffer-options' function.")
177 (defconst org-export-filters-alist
178 '((:filter-babel-call . org-export-filter-babel-call-functions)
179 (:filter-center-block . org-export-filter-center-block-functions)
180 (:filter-comment . org-export-filter-comment-functions)
181 (:filter-comment-block . org-export-filter-comment-block-functions)
182 (:filter-drawer . org-export-filter-drawer-functions)
183 (:filter-dynamic-block . org-export-filter-dynamic-block-functions)
184 (:filter-emphasis . org-export-filter-emphasis-functions)
185 (:filter-entity . org-export-filter-entity-functions)
186 (:filter-example-block . org-export-filter-example-block-functions)
187 (:filter-export-block . org-export-filter-export-block-functions)
188 (:filter-export-snippet . org-export-filter-export-snippet-functions)
189 (:filter-final-output . org-export-filter-final-output-functions)
190 (:filter-fixed-width . org-export-filter-fixed-width-functions)
191 (:filter-footnote-definition . org-export-filter-footnote-definition-functions)
192 (:filter-footnote-reference . org-export-filter-footnote-reference-functions)
193 (:filter-headline . org-export-filter-headline-functions)
194 (:filter-horizontal-rule . org-export-filter-horizontal-rule-functions)
195 (:filter-inline-babel-call . org-export-filter-inline-babel-call-functions)
196 (:filter-inline-src-block . org-export-filter-inline-src-block-functions)
197 (:filter-inlinetask . org-export-filter-inlinetask-functions)
198 (:filter-item . org-export-filter-item-functions)
199 (:filter-keyword . org-export-filter-keyword-functions)
200 (:filter-latex-environment . org-export-filter-latex-environment-functions)
201 (:filter-latex-fragment . org-export-filter-latex-fragment-functions)
202 (:filter-line-break . org-export-filter-line-break-functions)
203 (:filter-link . org-export-filter-link-functions)
204 (:filter-macro . org-export-filter-macro-functions)
205 (:filter-paragraph . org-export-filter-paragraph-functions)
206 (:filter-parse-tree . org-export-filter-parse-tree-functions)
207 (:filter-plain-list . org-export-filter-plain-list-functions)
208 (:filter-plain-text . org-export-filter-plain-text-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-subscript . org-export-filter-subscript-functions)
218 (:filter-superscript . org-export-filter-superscript-functions)
219 (:filter-table . org-export-filter-table-functions)
220 (:filter-target . org-export-filter-target-functions)
221 (:filter-time-stamp . org-export-filter-time-stamp-functions)
222 (:filter-verbatim . org-export-filter-verbatim-functions)
223 (:filter-verse-block . org-export-filter-verse-block-functions))
224 "Alist between filters properties and initial values.
226 The key of each association is a property name accessible through
227 the communication channel its value is a configurable global
228 variable defining initial filters.
230 This list is meant to install user specified filters. Back-end
231 developers may install their own filters using
232 `org-BACKEND-filters-alist', where BACKEND is the name of the
233 considered back-end. Filters defined there will always be
234 prepended to the current list, so they always get applied
235 first.")
237 (defconst org-export-default-inline-image-rule
238 `(("file" .
239 ,(format "\\.%s\\'"
240 (regexp-opt
241 '("png" "jpeg" "jpg" "gif" "tiff" "tif" "xbm"
242 "xpm" "pbm" "pgm" "ppm") t))))
243 "Default rule for link matching an inline image.
244 This rule applies to links with no description. By default, it
245 will be considered as an inline image if it targets a local file
246 whose extension is either \"png\", \"jpeg\", \"jpg\", \"gif\",
247 \"tiff\", \"tif\", \"xbm\", \"xpm\", \"pbm\", \"pgm\" or \"ppm\".
248 See `org-export-inline-image-p' for more information about
249 rules.")
253 ;;; User-configurable Variables
255 ;; Configuration for the masses.
257 ;; They should never be evaled directly, as their value is to be
258 ;; stored in a property list (cf. `org-export-option-alist').
260 (defgroup org-export nil
261 "Options for exporting Org mode files."
262 :tag "Org Export"
263 :group 'org)
265 (defgroup org-export-general nil
266 "General options for export engine."
267 :tag "Org Export General"
268 :group 'org-export)
270 (defcustom org-export-with-archived-trees 'headline
271 "Whether sub-trees with the ARCHIVE tag should be exported.
273 This can have three different values:
274 nil Do not export, pretend this tree is not present.
275 t Do export the entire tree.
276 `headline' Only export the headline, but skip the tree below it.
278 This option can also be set with the #+OPTIONS line,
279 e.g. \"arch:nil\"."
280 :group 'org-export-general
281 :type '(choice
282 (const :tag "Not at all" nil)
283 (const :tag "Headline only" 'headline)
284 (const :tag "Entirely" t)))
286 (defcustom org-export-with-author t
287 "Non-nil means insert author name into the exported file.
288 This option can also be set with the #+OPTIONS line,
289 e.g. \"author:nil\"."
290 :group 'org-export-general
291 :type 'boolean)
293 (defcustom org-export-with-creator 'comment
294 "Non-nil means the postamble should contain a creator sentence.
296 The sentence can be set in `org-export-creator-string' and
297 defaults to \"Generated by Org mode XX in Emacs XXX.\".
299 If the value is `comment' insert it as a comment."
300 :group 'org-export-general
301 :type '(choice
302 (const :tag "No creator sentence" nil)
303 (const :tag "Sentence as a comment" 'comment)
304 (const :tag "Insert the sentence" t)))
306 (defcustom org-export-creator-string
307 (format "Generated by Org mode %s in Emacs %s." org-version emacs-version)
308 "String to insert at the end of the generated document."
309 :group 'org-export-general
310 :type '(string :tag "Creator string"))
312 (defcustom org-export-with-drawers t
313 "Non-nil means export contents of standard drawers.
315 When t, all drawers are exported. This may also be a list of
316 drawer names to export. This variable doesn't apply to
317 properties drawers.
319 This option can also be set with the #+OPTIONS line,
320 e.g. \"d:nil\"."
321 :group 'org-export-general
322 :type '(choice
323 (const :tag "All drawers" t)
324 (const :tag "None" nil)
325 (repeat :tag "Selected drawers"
326 (string :tag "Drawer name"))))
328 (defcustom org-export-with-email nil
329 "Non-nil means insert author email into the exported file.
330 This option can also be set with the #+OPTIONS line,
331 e.g. \"email:t\"."
332 :group 'org-export-general
333 :type 'boolean)
335 (defcustom org-export-with-emphasize t
336 "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
338 If the export target supports emphasizing text, the word will be
339 typeset in bold, italic, or underlined, respectively. Not all
340 export backends support this.
342 This option can also be set with the #+OPTIONS line, e.g. \"*:nil\"."
343 :group 'org-export-general
344 :type 'boolean)
346 (defcustom org-export-exclude-tags '("noexport")
347 "Tags that exclude a tree from export.
348 All trees carrying any of these tags will be excluded from
349 export. This is without condition, so even subtrees inside that
350 carry one of the `org-export-select-tags' will be removed."
351 :group 'org-export-general
352 :type '(repeat (string :tag "Tag")))
354 (defcustom org-export-with-fixed-width t
355 "Non-nil means lines starting with \":\" will be in fixed width font.
357 This can be used to have pre-formatted text, fragments of code
358 etc. For example:
359 : ;; Some Lisp examples
360 : (while (defc cnt)
361 : (ding))
362 will be looking just like this in also HTML. See also the QUOTE
363 keyword. Not all export backends support this.
365 This option can also be set with the #+OPTIONS line, e.g. \"::nil\"."
366 :group 'org-export-translation
367 :type 'boolean)
369 (defcustom org-export-with-footnotes t
370 "Non-nil means Org footnotes should be exported.
371 This option can also be set with the #+OPTIONS line,
372 e.g. \"f:nil\"."
373 :group 'org-export-general
374 :type 'boolean)
376 (defcustom org-export-headline-levels 3
377 "The last level which is still exported as a headline.
379 Inferior levels will produce itemize lists when exported. Note
380 that a numeric prefix argument to an exporter function overrides
381 this setting.
383 This option can also be set with the #+OPTIONS line, e.g. \"H:2\"."
384 :group 'org-export-general
385 :type 'integer)
387 (defcustom org-export-default-language "en"
388 "The default language for export and clocktable translations, as a string.
389 This may have an association in
390 `org-clock-clocktable-language-setup'."
391 :group 'org-export-general
392 :type '(string :tag "Language"))
394 (defcustom org-export-preserve-breaks nil
395 "Non-nil means preserve all line breaks when exporting.
397 Normally, in HTML output paragraphs will be reformatted.
399 This option can also be set with the #+OPTIONS line,
400 e.g. \"\\n:t\"."
401 :group 'org-export-general
402 :type 'boolean)
404 (defcustom org-export-with-entities t
405 "Non-nil means interpret entities when exporting.
407 For example, HTML export converts \\alpha to &alpha; and \\AA to
408 &Aring;.
410 For a list of supported names, see the constant `org-entities'
411 and the user option `org-entities-user'.
413 This option can also be set with the #+OPTIONS line,
414 e.g. \"e:nil\"."
415 :group 'org-export-general
416 :type 'boolean)
418 (defcustom org-export-with-priority nil
419 "Non-nil means include priority cookies in export.
420 When nil, remove priority cookies for export."
421 :group 'org-export-general
422 :type 'boolean)
424 (defcustom org-export-with-section-numbers t
425 "Non-nil means add section numbers to headlines when exporting.
427 When set to an integer n, numbering will only happen for
428 headlines whose relative level is higher or equal to n.
430 This option can also be set with the #+OPTIONS line,
431 e.g. \"num:t\"."
432 :group 'org-export-general
433 :type 'boolean)
435 (defcustom org-export-select-tags '("export")
436 "Tags that select a tree for export.
437 If any such tag is found in a buffer, all trees that do not carry
438 one of these tags will be deleted before export. Inside trees
439 that are selected like this, you can still deselect a subtree by
440 tagging it with one of the `org-export-exclude-tags'."
441 :group 'org-export-general
442 :type '(repeat (string :tag "Tag")))
444 (defcustom org-export-with-special-strings t
445 "Non-nil means interpret \"\-\", \"--\" and \"---\" for export.
447 When this option is turned on, these strings will be exported as:
449 Org HTML LaTeX
450 -----+----------+--------
451 \\- &shy; \\-
452 -- &ndash; --
453 --- &mdash; ---
454 ... &hellip; \ldots
456 This option can also be set with the #+OPTIONS line,
457 e.g. \"-:nil\"."
458 :group 'org-export-general
459 :type 'boolean)
461 (defcustom org-export-with-sub-superscripts t
462 "Non-nil means interpret \"_\" and \"^\" for export.
464 When this option is turned on, you can use TeX-like syntax for
465 sub- and superscripts. Several characters after \"_\" or \"^\"
466 will be considered as a single item - so grouping with {} is
467 normally not needed. For example, the following things will be
468 parsed as single sub- or superscripts.
470 10^24 or 10^tau several digits will be considered 1 item.
471 10^-12 or 10^-tau a leading sign with digits or a word
472 x^2-y^3 will be read as x^2 - y^3, because items are
473 terminated by almost any nonword/nondigit char.
474 x_{i^2} or x^(2-i) braces or parenthesis do grouping.
476 Still, ambiguity is possible - so when in doubt use {} to enclose
477 the sub/superscript. If you set this variable to the symbol
478 `{}', the braces are *required* in order to trigger
479 interpretations as sub/superscript. This can be helpful in
480 documents that need \"_\" frequently in plain text.
482 This option can also be set with the #+OPTIONS line,
483 e.g. \"^:nil\"."
484 :group 'org-export-general
485 :type '(choice
486 (const :tag "Interpret them" t)
487 (const :tag "Curly brackets only" {})
488 (const :tag "Do not interpret them" nil)))
490 (defcustom org-export-with-toc t
491 "Non-nil means create a table of contents in exported files.
493 The TOC contains headlines with levels up
494 to`org-export-headline-levels'. When an integer, include levels
495 up to N in the toc, this may then be different from
496 `org-export-headline-levels', but it will not be allowed to be
497 larger than the number of headline levels. When nil, no table of
498 contents is made.
500 This option can also be set with the #+OPTIONS line,
501 e.g. \"toc:nil\" or \"toc:3\"."
502 :group 'org-export-general
503 :type '(choice
504 (const :tag "No Table of Contents" nil)
505 (const :tag "Full Table of Contents" t)
506 (integer :tag "TOC to level")))
508 (defcustom org-export-with-tables t
509 "If non-nil, lines starting with \"|\" define a table.
510 For example:
512 | Name | Address | Birthday |
513 |-------------+----------+-----------|
514 | Arthur Dent | England | 29.2.2100 |
516 This option can also be set with the #+OPTIONS line, e.g. \"|:nil\"."
517 :group 'org-export-general
518 :type 'boolean)
520 (defcustom org-export-with-tags t
521 "If nil, do not export tags, just remove them from headlines.
523 If this is the symbol `not-in-toc', tags will be removed from
524 table of contents entries, but still be shown in the headlines of
525 the document.
527 This option can also be set with the #+OPTIONS line,
528 e.g. \"tags:nil\"."
529 :group 'org-export-general
530 :type '(choice
531 (const :tag "Off" nil)
532 (const :tag "Not in TOC" not-in-toc)
533 (const :tag "On" t)))
535 (defcustom org-export-with-tasks t
536 "Non-nil means include TODO items for export.
537 This may have the following values:
538 t include tasks independent of state.
539 todo include only tasks that are not yet done.
540 done include only tasks that are already done.
541 nil remove all tasks before export
542 list of keywords keep only tasks with these keywords"
543 :group 'org-export-general
544 :type '(choice
545 (const :tag "All tasks" t)
546 (const :tag "No tasks" nil)
547 (const :tag "Not-done tasks" todo)
548 (const :tag "Only done tasks" done)
549 (repeat :tag "Specific TODO keywords"
550 (string :tag "Keyword"))))
552 (defcustom org-export-time-stamp-file t
553 "Non-nil means insert a time stamp into the exported file.
554 The time stamp shows when the file was created.
556 This option can also be set with the #+OPTIONS line,
557 e.g. \"timestamp:nil\"."
558 :group 'org-export-general
559 :type 'boolean)
561 (defcustom org-export-with-timestamps t
562 "If nil, do not export time stamps and associated keywords."
563 :group 'org-export-general
564 :type 'boolean)
566 (defcustom org-export-with-todo-keywords t
567 "Non-nil means include TODO keywords in export.
568 When nil, remove all these keywords from the export.")
570 (defcustom org-export-allow-BIND 'confirm
571 "Non-nil means allow #+BIND to define local variable values for export.
572 This is a potential security risk, which is why the user must
573 confirm the use of these lines."
574 :group 'org-export-general
575 :type '(choice
576 (const :tag "Never" nil)
577 (const :tag "Always" t)
578 (const :tag "Ask a confirmation for each file" confirm)))
580 (defcustom org-export-snippet-translation-alist nil
581 "Alist between export snippets back-ends and exporter back-ends.
583 This variable allows to provide shortcuts for export snippets.
585 For example, with a value of '\(\(\"h\" . \"html\"\)\), the HTML
586 back-end will recognize the contents of \"@h{<b>}\" as HTML code
587 while every other back-end will ignore it."
588 :group 'org-export-general
589 :type '(repeat
590 (cons
591 (string :tag "Shortcut")
592 (string :tag "Back-end"))))
594 (defcustom org-export-coding-system nil
595 "Coding system for the exported file."
596 :group 'org-export-general
597 :type 'coding-system)
599 (defcustom org-export-copy-to-kill-ring t
600 "Non-nil means exported stuff will also be pushed onto the kill ring."
601 :group 'org-export-general
602 :type 'boolean)
604 (defcustom org-export-initial-scope 'buffer
605 "The initial scope when exporting with `org-export-dispatch'.
606 This variable can be either set to `buffer' or `subtree'."
607 :group 'org-export-general
608 :type '(choice
609 (const :tag "Export current buffer" 'buffer)
610 (const :tag "Export current subtree" 'subtree)))
612 (defcustom org-export-show-temporary-export-buffer t
613 "Non-nil means show buffer after exporting to temp buffer.
614 When Org exports to a file, the buffer visiting that file is ever
615 shown, but remains buried. However, when exporting to a temporary
616 buffer, that buffer is popped up in a second window. When this variable
617 is nil, the buffer remains buried also in these cases."
618 :group 'org-export-general
619 :type 'boolean)
621 (defcustom org-export-dispatch-use-expert-ui nil
622 "Non-nil means using a non-intrusive `org-export-dispatch'.
623 In that case, no help buffer is displayed. Though, an indicator
624 for current export scope is added to the prompt \(i.e. \"b\" when
625 output is restricted to body only, \"s\" when it is restricted to
626 the current subtree and \"v\" when only visible elements are
627 considered for export\). Also, \[?] allows to switch back to
628 standard mode."
629 :group 'org-export-general
630 :type 'boolean)
634 ;;; The Communication Channel
636 ;; During export process, every function has access to a number of
637 ;; properties. They are of three types:
639 ;; 1. Environment options are collected once at the very beginning of
640 ;; the process, out of the original buffer and configuration.
641 ;; Associated to the parse tree, they make an Org closure.
642 ;; Collecting them is handled by `org-export-get-environment'
643 ;; function.
645 ;; Most environment options are defined through the
646 ;; `org-export-option-alist' variable.
648 ;; 2. Tree properties are extracted directly from the parsed tree,
649 ;; just before export, by `org-export-collect-tree-properties'.
651 ;; 3. Local options are updated during parsing, and their value
652 ;; depends on the level of recursion. For now, only `:ignore-list'
653 ;; belongs to that category.
655 ;; Here is the full list of properties available during transcode
656 ;; process, with their category (option, tree or local) and their
657 ;; value type.
659 ;; + `:author' :: Author's name.
660 ;; - category :: option
661 ;; - type :: string
663 ;; + `:back-end' :: Current back-end used for transcoding.
664 ;; - category :: tree
665 ;; - type :: symbol
667 ;; + `:creator' :: String to write as creation information.
668 ;; - category :: option
669 ;; - type :: string
671 ;; + `:date' :: String to use as date.
672 ;; - category :: option
673 ;; - type :: string
675 ;; + `:description' :: Description text for the current data.
676 ;; - category :: option
677 ;; - type :: string
679 ;; + `:email' :: Author's email.
680 ;; - category :: option
681 ;; - type :: string
683 ;; + `:exclude-tags' :: Tags for exclusion of subtrees from export
684 ;; process.
685 ;; - category :: option
686 ;; - type :: list of strings
688 ;; + `:footnote-definition-alist' :: Alist between footnote labels and
689 ;; their definition, as parsed data. Only non-inlined footnotes
690 ;; are represented in this alist. Also, every definition isn't
691 ;; guaranteed to be referenced in the parse tree. The purpose of
692 ;; this property is to preserve definitions from oblivion
693 ;; (i.e. when the parse tree comes from a part of the original
694 ;; buffer), it isn't meant for direct use in a back-end. To
695 ;; retrieve a definition relative to a reference, use
696 ;; `org-export-get-footnote-definition' instead.
697 ;; - category :: option
698 ;; - type :: alist (STRING . LIST)
700 ;; + `:headline-levels' :: Maximum level being exported as an
701 ;; headline. Comparison is done with the relative level of
702 ;; headlines in the parse tree, not necessarily with their
703 ;; actual level.
704 ;; - category :: option
705 ;; - type :: integer
707 ;; + `:headline-offset' :: Difference between relative and real level
708 ;; of headlines in the parse tree. For example, a value of -1
709 ;; means a level 2 headline should be considered as level
710 ;; 1 (cf. `org-export-get-relative-level').
711 ;; - category :: tree
712 ;; - type :: integer
714 ;; + `:headline-numbering' :: Alist between headlines and their
715 ;; numbering, as a list of numbers
716 ;; (cf. `org-export-get-headline-number').
717 ;; - category :: tree
718 ;; - type :: alist (INTEGER . LIST)
720 ;; + `:ignore-list' :: List of elements and objects that should be
721 ;; ignored during export.
722 ;; - category :: local
723 ;; - type :: list of elements and objects
725 ;; + `:input-file' :: Full path to input file, if any.
726 ;; - category :: option
727 ;; - type :: string or nil
729 ;; + `:keywords' :: List of keywords attached to data.
730 ;; - category :: option
731 ;; - type :: string
733 ;; + `:language' :: Default language used for translations.
734 ;; - category :: option
735 ;; - type :: string
737 ;; + `:macro-input-file' :: Macro returning file name of input file,
738 ;; or nil.
739 ;; - category :: option
740 ;; - type :: string or nil
742 ;; + `:parse-tree' :: Whole parse tree, available at any time during
743 ;; transcoding.
744 ;; - category :: global
745 ;; - type :: list (as returned by `org-element-parse-buffer')
747 ;; + `:preserve-breaks' :: Non-nil means transcoding should preserve
748 ;; all line breaks.
749 ;; - category :: option
750 ;; - type :: symbol (nil, t)
752 ;; + `:section-numbers' :: Non-nil means transcoding should add
753 ;; section numbers to headlines.
754 ;; - category :: option
755 ;; - type :: symbol (nil, t)
757 ;; + `:select-tags' :: List of tags enforcing inclusion of sub-trees
758 ;; in transcoding. When such a tag is present,
759 ;; subtrees without it are de facto excluded from
760 ;; the process. See `use-select-tags'.
761 ;; - category :: option
762 ;; - type :: list of strings
764 ;; + `:target-list' :: List of targets encountered in the parse tree.
765 ;; This is used to partly resolve "fuzzy" links
766 ;; (cf. `org-export-resolve-fuzzy-link').
767 ;; - category :: tree
768 ;; - type :: list of strings
770 ;; + `:time-stamp-file' :: Non-nil means transcoding should insert
771 ;; a time stamp in the output.
772 ;; - category :: option
773 ;; - type :: symbol (nil, t)
775 ;; + `:use-select-tags' :: When non-nil, a select tags has been found
776 ;; in the parse tree. Thus, any headline without one will be
777 ;; filtered out. See `select-tags'.
778 ;; - category :: tree
779 ;; - type :: interger or nil
781 ;; + `:with-archived-trees' :: Non-nil when archived subtrees should
782 ;; also be transcoded. If it is set to the `headline' symbol,
783 ;; only the archived headline's name is retained.
784 ;; - category :: option
785 ;; - type :: symbol (nil, t, `headline')
787 ;; + `:with-author' :: Non-nil means author's name should be included
788 ;; in the output.
789 ;; - category :: option
790 ;; - type :: symbol (nil, t)
792 ;; + `:with-creator' :: Non-nild means a creation sentence should be
793 ;; inserted at the end of the transcoded string. If the value
794 ;; is `comment', it should be commented.
795 ;; - category :: option
796 ;; - type :: symbol (`comment', nil, t)
798 ;; + `:with-drawers' :: Non-nil means drawers should be exported. If
799 ;; its value is a list of names, only drawers with such names
800 ;; will be transcoded.
801 ;; - category :: option
802 ;; - type :: symbol (nil, t) or list of strings
804 ;; + `:with-email' :: Non-nil means output should contain author's
805 ;; email.
806 ;; - category :: option
807 ;; - type :: symbol (nil, t)
809 ;; + `:with-emphasize' :: Non-nil means emphasized text should be
810 ;; interpreted.
811 ;; - category :: option
812 ;; - type :: symbol (nil, t)
814 ;; + `:with-fixed-width' :: Non-nil if transcoder should interpret
815 ;; strings starting with a colon as a fixed-with (verbatim) area.
816 ;; - category :: option
817 ;; - type :: symbol (nil, t)
819 ;; + `:with-footnotes' :: Non-nil if transcoder should interpret
820 ;; footnotes.
821 ;; - category :: option
822 ;; - type :: symbol (nil, t)
824 ;; + `:with-priority' :: Non-nil means transcoding should include
825 ;; priority cookies.
826 ;; - category :: option
827 ;; - type :: symbol (nil, t)
829 ;; + `:with-special-strings' :: Non-nil means transcoding should
830 ;; interpret special strings in plain text.
831 ;; - category :: option
832 ;; - type :: symbol (nil, t)
834 ;; + `:with-sub-superscript' :: Non-nil means transcoding should
835 ;; interpret subscript and superscript. With a value of "{}",
836 ;; only interpret those using curly brackets.
837 ;; - category :: option
838 ;; - type :: symbol (nil, {}, t)
840 ;; + `:with-tables' :: Non-nil means transcoding should interpret
841 ;; tables.
842 ;; - category :: option
843 ;; - type :: symbol (nil, t)
845 ;; + `:with-tags' :: Non-nil means transcoding should keep tags in
846 ;; headlines. A `not-in-toc' value will remove them
847 ;; from the table of contents, if any, nonetheless.
848 ;; - category :: option
849 ;; - type :: symbol (nil, t, `not-in-toc')
851 ;; + `:with-tasks' :: Non-nil means transcoding should include
852 ;; headlines with a TODO keyword. A `todo' value
853 ;; will only include headlines with a todo type
854 ;; keyword while a `done' value will do the
855 ;; contrary. If a list of strings is provided, only
856 ;; tasks with keywords belonging to that list will
857 ;; be kept.
858 ;; - category :: option
859 ;; - type :: symbol (t, todo, done, nil) or list of strings
861 ;; + `:with-timestamps' :: Non-nil means transcoding should include
862 ;; time stamps and associated keywords. Otherwise, completely
863 ;; remove them.
864 ;; - category :: option
865 ;; - type :: symbol: (t, nil)
867 ;; + `:with-toc' :: Non-nil means that a table of contents has to be
868 ;; added to the output. An integer value limits its
869 ;; depth.
870 ;; - category :: option
871 ;; - type :: symbol (nil, t or integer)
873 ;; + `:with-todo-keywords' :: Non-nil means transcoding should
874 ;; include TODO keywords.
875 ;; - category :: option
876 ;; - type :: symbol (nil, t)
879 ;;;; Environment Options
881 ;; Environment options encompass all parameters defined outside the
882 ;; scope of the parsed data. They come from five sources, in
883 ;; increasing precedence order:
885 ;; - Global variables,
886 ;; - Options keyword symbols,
887 ;; - Buffer keywords,
888 ;; - Subtree properties.
890 ;; The central internal function with regards to environment options
891 ;; is `org-export-get-environment'. It updates global variables with
892 ;; "#+BIND:" keywords, then retrieve and prioritize properties from
893 ;; the different sources.
895 ;; The internal functions doing the retrieval are:
896 ;; `org-export-parse-option-keyword' ,
897 ;; `org-export-get-subtree-options' ,
898 ;; `org-export-get-inbuffer-options' and
899 ;; `org-export-get-global-options'.
901 ;; Some properties, which do not rely on the previous sources but
902 ;; still depend on the original buffer, are taken care of with
903 ;; `org-export-initial-options'.
905 ;; Also, `org-export-confirm-letbind' and `org-export-install-letbind'
906 ;; take care of the part relative to "#+BIND:" keywords.
908 (defun org-export-get-environment (&optional backend subtreep ext-plist)
909 "Collect export options from the current buffer.
911 Optional argument BACKEND is a symbol specifying which back-end
912 specific options to read, if any.
914 When optional argument SUBTREEP is non-nil, assume the export is
915 done against the current sub-tree.
917 Third optional argument EXT-PLIST is a property list with
918 external parameters overriding Org default settings, but still
919 inferior to file-local settings."
920 ;; First install #+BIND variables.
921 (org-export-install-letbind-maybe)
922 ;; Get and prioritize export options...
923 (let ((options (org-combine-plists
924 ;; ... from global variables...
925 (org-export-get-global-options backend)
926 ;; ... from buffer's name (default title)...
927 `(:title
928 ,(or (let ((file (buffer-file-name (buffer-base-buffer))))
929 (and file
930 (file-name-sans-extension
931 (file-name-nondirectory file))))
932 (buffer-name (buffer-base-buffer))))
933 ;; ... from an external property list...
934 ext-plist
935 ;; ... from in-buffer settings...
936 (org-export-get-inbuffer-options
937 backend
938 (and buffer-file-name
939 (org-remove-double-quotes buffer-file-name)))
940 ;; ... and from subtree, when appropriate.
941 (and subtreep (org-export-get-subtree-options)))))
942 ;; Add initial options.
943 (setq options (append (org-export-initial-options) options))
944 ;; Return plist.
945 options))
947 (defun org-export-parse-option-keyword (options &optional backend)
948 "Parse an OPTIONS line and return values as a plist.
949 Optional argument BACKEND is a symbol specifying which back-end
950 specific items to read, if any."
951 (let* ((all
952 (append org-export-option-alist
953 (and backend
954 (let ((var (intern
955 (format "org-%s-option-alist" backend))))
956 (and (boundp var) (eval var))))))
957 ;; Build an alist between #+OPTION: item and property-name.
958 (alist (delq nil
959 (mapcar (lambda (e)
960 (when (nth 2 e) (cons (regexp-quote (nth 2 e))
961 (car e))))
962 all)))
963 plist)
964 (mapc (lambda (e)
965 (when (string-match (concat "\\(\\`\\|[ \t]\\)"
966 (car e)
967 ":\\(([^)\n]+)\\|[^ \t\n\r;,.]*\\)")
968 options)
969 (setq plist (plist-put plist
970 (cdr e)
971 (car (read-from-string
972 (match-string 2 options)))))))
973 alist)
974 plist))
976 (defun org-export-get-subtree-options ()
977 "Get export options in subtree at point.
979 Assume point is at subtree's beginning.
981 Return options as a plist."
982 (let (prop plist)
983 (when (setq prop (progn (looking-at org-todo-line-regexp)
984 (or (save-match-data
985 (org-entry-get (point) "EXPORT_TITLE"))
986 (org-match-string-no-properties 3))))
987 (setq plist
988 (plist-put
989 plist :title
990 (org-element-parse-secondary-string
991 prop
992 (cdr (assq 'keyword org-element-string-restrictions))))))
993 (when (setq prop (org-entry-get (point) "EXPORT_TEXT"))
994 (setq plist (plist-put plist :text prop)))
995 (when (setq prop (org-entry-get (point) "EXPORT_AUTHOR"))
996 (setq plist (plist-put plist :author prop)))
997 (when (setq prop (org-entry-get (point) "EXPORT_DATE"))
998 (setq plist (plist-put plist :date prop)))
999 (when (setq prop (org-entry-get (point) "EXPORT_OPTIONS"))
1000 (setq plist (org-export-add-options-to-plist plist prop)))
1001 plist))
1003 (defun org-export-get-inbuffer-options (&optional backend files)
1004 "Return current buffer export options, as a plist.
1006 Optional argument BACKEND, when non-nil, is a symbol specifying
1007 which back-end specific options should also be read in the
1008 process.
1010 Optional argument FILES is a list of setup files names read so
1011 far, used to avoid circular dependencies.
1013 Assume buffer is in Org mode. Narrowing, if any, is ignored."
1014 (org-with-wide-buffer
1015 (goto-char (point-min))
1016 (let ((case-fold-search t) plist)
1017 ;; 1. Special keywords, as in `org-export-special-keywords'.
1018 (let ((special-re (org-make-options-regexp org-export-special-keywords)))
1019 (while (re-search-forward special-re nil t)
1020 (let ((element (org-element-at-point)))
1021 (when (eq (org-element-type element) 'keyword)
1022 (let* ((key (upcase (org-element-property :key element)))
1023 (val (org-element-property :value element))
1024 (prop
1025 (cond
1026 ((string= key "SETUP_FILE")
1027 (let ((file
1028 (expand-file-name
1029 (org-remove-double-quotes (org-trim val)))))
1030 ;; Avoid circular dependencies.
1031 (unless (member file files)
1032 (with-temp-buffer
1033 (insert (org-file-contents file 'noerror))
1034 (org-mode)
1035 (org-export-get-inbuffer-options
1036 backend (cons file files))))))
1037 ((string= key "OPTIONS")
1038 (org-export-parse-option-keyword val backend))
1039 ((string= key "MACRO")
1040 (when (string-match
1041 "^\\([-a-zA-Z0-9_]+\\)\\(?:[ \t]+\\(.*?\\)[ \t]*$\\)?"
1042 val)
1043 (let ((key
1044 (intern
1045 (concat ":macro-"
1046 (downcase (match-string 1 val)))))
1047 (value (org-match-string-no-properties 2 val)))
1048 (cond
1049 ((not value) "")
1050 ;; Value will be evaled. Leave it as-is.
1051 ((string-match "\\`(eval\\>" value)
1052 (list key value))
1053 ;; Value has to be parsed for nested
1054 ;; macros.
1056 (list
1058 (let ((restr
1059 (cdr
1060 (assq 'macro
1061 org-element-object-restrictions))))
1062 (org-element-parse-secondary-string
1063 ;; If user explicitly asks for
1064 ;; a newline, be sure to preserve it
1065 ;; from further filling with
1066 ;; `hard-newline'. Also replace
1067 ;; "\\n" with "\n", "\\\n" with "\\n"
1068 ;; and so on...
1069 (replace-regexp-in-string
1070 "\\(\\\\\\\\\\)n" "\\\\"
1071 (replace-regexp-in-string
1072 "\\(?:^\\|[^\\\\]\\)\\(\\\\n\\)"
1073 hard-newline value nil nil 1)
1074 nil nil 1)
1075 restr)))))))))))
1076 (setq plist (org-combine-plists plist prop)))))))
1077 ;; 2. Standard options, as in `org-export-option-alist'.
1078 (let* ((all (append org-export-option-alist
1079 ;; Also look for back-end specific options
1080 ;; if BACKEND is defined.
1081 (and backend
1082 (let ((var
1083 (intern
1084 (format "org-%s-option-alist" backend))))
1085 (and (boundp var) (eval var))))))
1086 ;; Build alist between keyword name and property name.
1087 (alist
1088 (delq nil (mapcar
1089 (lambda (e) (when (nth 1 e) (cons (nth 1 e) (car e))))
1090 all)))
1091 ;; Build regexp matching all keywords associated to export
1092 ;; options. Note: the search is case insensitive.
1093 (opt-re (org-make-options-regexp
1094 (delq nil (mapcar (lambda (e) (nth 1 e)) all)))))
1095 (goto-char (point-min))
1096 (while (re-search-forward opt-re nil t)
1097 (let ((element (org-element-at-point)))
1098 (when (eq (org-element-type element) 'keyword)
1099 (let* ((key (upcase (org-element-property :key element)))
1100 (val (org-element-property :value element))
1101 (prop (cdr (assoc key alist)))
1102 (behaviour (nth 4 (assq prop all))))
1103 (setq plist
1104 (plist-put
1105 plist prop
1106 ;; Handle value depending on specified BEHAVIOUR.
1107 (case behaviour
1108 (space
1109 (if (not (plist-get plist prop)) (org-trim val)
1110 (concat (plist-get plist prop) " " (org-trim val))))
1111 (newline
1112 (org-trim
1113 (concat (plist-get plist prop) "\n" (org-trim val))))
1114 (split
1115 `(,@(plist-get plist prop) ,@(org-split-string val)))
1116 ('t val)
1117 (otherwise (plist-get plist prop)))))))))
1118 ;; Parse keywords specified in `org-element-parsed-keywords'.
1119 (mapc
1120 (lambda (key)
1121 (let* ((prop (cdr (assoc key alist)))
1122 (value (and prop (plist-get plist prop))))
1123 (when (stringp value)
1124 (setq plist
1125 (plist-put
1126 plist prop
1127 (org-element-parse-secondary-string
1128 value
1129 (cdr (assq 'keyword org-element-string-restrictions))))))))
1130 org-element-parsed-keywords))
1131 ;; 3. Return final value.
1132 plist)))
1134 (defun org-export-get-global-options (&optional backend)
1135 "Return global export options as a plist.
1137 Optional argument BACKEND, if non-nil, is a symbol specifying
1138 which back-end specific export options should also be read in the
1139 process."
1140 (let ((all (append org-export-option-alist
1141 (and backend
1142 (let ((var (intern
1143 (format "org-%s-option-alist" backend))))
1144 (and (boundp var) (eval var))))))
1145 ;; Output value.
1146 plist)
1147 (mapc (lambda (cell)
1148 (setq plist (plist-put plist (car cell) (eval (nth 3 cell)))))
1149 all)
1150 ;; Return value.
1151 plist))
1153 (defun org-export-initial-options ()
1154 "Return a plist with properties related to input buffer."
1155 (let ((visited-file (buffer-file-name (buffer-base-buffer))))
1156 (list
1157 ;; Store full path of input file name, or nil. For internal use.
1158 :input-file visited-file
1159 ;; `:macro-date', `:macro-time' and `:macro-property' could as well
1160 ;; be initialized as tree properties, since they don't depend on
1161 ;; initial environment. Though, it may be more logical to keep
1162 ;; them close to other ":macro-" properties.
1163 :macro-date "(eval (format-time-string \"$1\"))"
1164 :macro-time "(eval (format-time-string \"$1\"))"
1165 :macro-property "(eval (org-entry-get nil \"$1\" 'selective))"
1166 :macro-modification-time
1167 (and visited-file
1168 (file-exists-p visited-file)
1169 (concat "(eval (format-time-string \"$1\" '"
1170 (prin1-to-string (nth 5 (file-attributes visited-file)))
1171 "))"))
1172 ;; Store input file name as a macro.
1173 :macro-input-file (and visited-file (file-name-nondirectory visited-file))
1174 ;; Footnotes definitions must be collected in the original buffer,
1175 ;; as there's no insurance that they will still be in the parse
1176 ;; tree, due to some narrowing.
1177 :footnote-definition-alist
1178 (let (alist)
1179 (org-with-wide-buffer
1180 (goto-char (point-min))
1181 (while (re-search-forward org-footnote-definition-re nil t)
1182 (let ((def (org-footnote-at-definition-p)))
1183 (when def
1184 (org-skip-whitespace)
1185 (push (cons (car def)
1186 (save-restriction
1187 (narrow-to-region (point) (nth 2 def))
1188 ;; Like `org-element-parse-buffer', but
1189 ;; makes sure the definition doesn't start
1190 ;; with a section element.
1191 (nconc
1192 (list 'org-data nil)
1193 (org-element-parse-elements
1194 (point-min) (point-max) nil nil nil nil nil))))
1195 alist))))
1196 alist)))))
1198 (defvar org-export-allow-BIND-local nil)
1199 (defun org-export-confirm-letbind ()
1200 "Can we use #+BIND values during export?
1201 By default this will ask for confirmation by the user, to divert
1202 possible security risks."
1203 (cond
1204 ((not org-export-allow-BIND) nil)
1205 ((eq org-export-allow-BIND t) t)
1206 ((local-variable-p 'org-export-allow-BIND-local) org-export-allow-BIND-local)
1207 (t (org-set-local 'org-export-allow-BIND-local
1208 (yes-or-no-p "Allow BIND values in this buffer? ")))))
1210 (defun org-export-install-letbind-maybe ()
1211 "Install the values from #+BIND lines as local variables.
1212 Variables must be installed before in-buffer options are
1213 retrieved."
1214 (let (letbind pair)
1215 (org-with-wide-buffer
1216 (goto-char (point-min))
1217 (while (re-search-forward (org-make-options-regexp '("BIND")) nil t)
1218 (when (org-export-confirm-letbind)
1219 (push (read (concat "(" (org-match-string-no-properties 2) ")"))
1220 letbind))))
1221 (while (setq pair (pop letbind))
1222 (org-set-local (car pair) (nth 1 pair)))))
1225 ;;;; Tree Properties
1227 ;; Tree properties are infromation extracted from parse tree. They
1228 ;; are initialized at the beginning of the transcoding process by
1229 ;; `org-export-collect-tree-properties'.
1231 ;; Dedicated functions focus on computing the value of specific tree
1232 ;; properties during initialization. Thus,
1233 ;; `org-export-use-select-tag-p' determines if an headline makes use
1234 ;; of an export tag enforcing inclusion. `org-export-get-ignore-list'
1235 ;; marks collect elements and objects that should be skipped during
1236 ;; export, `org-export-get-min-level' gets the minimal exportable
1237 ;; level, used as a basis to compute relative level for headlines.
1238 ;; Eventually `org-export-collect-headline-numbering' builds an alist
1239 ;; between headlines and their numbering.
1241 (defun org-export-collect-tree-properties (data info backend)
1242 "Extract tree properties from parse tree.
1244 DATA is the parse tree from which information is retrieved. INFO
1245 is a list holding export options. BACKEND is the back-end called
1246 for transcoding, as a symbol.
1248 Following tree properties are set:
1249 `:back-end' Back-end used for transcoding.
1251 `:headline-offset' Offset between true level of headlines and
1252 local level. An offset of -1 means an headline
1253 of level 2 should be considered as a level
1254 1 headline in the context.
1256 `:headline-numbering' Alist of all headlines' beginning position
1257 as key an the associated numbering as value.
1259 `:ignore-list' List of elements that should be ignored during export.
1261 `:parse-tree' Whole parse tree.
1263 `:target-list' List of all targets in the parse tree.
1265 `:use-select-tags' Non-nil when parsed tree use a special tag to
1266 enforce transcoding of the headline."
1267 ;; First, set `:use-select-tags' property, as it will be required
1268 ;; for further computations.
1269 (setq info
1270 (plist-put info
1271 :use-select-tags (org-export-use-select-tags-p data info)))
1272 ;; Then get the list of elements and objects to ignore, and put it
1273 ;; into `:ignore-list'.
1274 (setq info
1275 (plist-put info :ignore-list (org-export-get-ignore-list data info)))
1276 ;; Finally get `:headline-offset' in order to be able to use
1277 ;; `org-export-get-relative-level'.
1278 (setq info
1279 (plist-put info
1280 :headline-offset (- 1 (org-export-get-min-level data info))))
1281 ;; Now, properties order doesn't matter: get the rest of the tree
1282 ;; properties.
1283 (nconc
1284 `(:parse-tree
1285 ,data
1286 :target-list
1287 ,(org-element-map data 'target (lambda (target local) target) info)
1288 :headline-numbering ,(org-export-collect-headline-numbering data info)
1289 :back-end ,backend)
1290 info))
1292 (defun org-export-use-select-tags-p (data options)
1293 "Non-nil when data use a tag enforcing transcoding.
1294 DATA is parsed data as returned by `org-element-parse-buffer'.
1295 OPTIONS is a plist holding export options."
1296 (org-element-map
1297 data
1298 'headline
1299 (lambda (headline info)
1300 (let ((tags (org-element-property :with-tags headline)))
1301 (and tags (string-match
1302 (format ":%s:" (plist-get info :select-tags)) tags))))
1303 options
1304 'stop-at-first-match))
1306 (defun org-export-get-min-level (data options)
1307 "Return minimum exportable headline's level in DATA.
1308 DATA is parsed tree as returned by `org-element-parse-buffer'.
1309 OPTIONS is a plist holding export options."
1310 (catch 'exit
1311 (let ((min-level 10000))
1312 (mapc
1313 (lambda (blob)
1314 (when (and (eq (org-element-type blob) 'headline)
1315 (not (org-export-ignored-p blob options)))
1316 (setq min-level
1317 (min (org-element-property :level blob) min-level)))
1318 (when (= min-level 1) (throw 'exit 1)))
1319 (org-element-contents data))
1320 ;; If no headline was found, for the sake of consistency, set
1321 ;; minimum level to 1 nonetheless.
1322 (if (= min-level 10000) 1 min-level))))
1324 (defun org-export-collect-headline-numbering (data options)
1325 "Return numbering of all exportable headlines in a parse tree.
1327 DATA is the parse tree. OPTIONS is the plist holding export
1328 options.
1330 Return an alist whose key is an headline and value is its
1331 associated numbering \(in the shape of a list of numbers\)."
1332 (let ((numbering (make-vector org-export-max-depth 0)))
1333 (org-element-map
1334 data
1335 'headline
1336 (lambda (headline info)
1337 (let ((relative-level
1338 (1- (org-export-get-relative-level headline info))))
1339 (cons
1340 headline
1341 (loop for n across numbering
1342 for idx from 0 to org-export-max-depth
1343 when (< idx relative-level) collect n
1344 when (= idx relative-level) collect (aset numbering idx (1+ n))
1345 when (> idx relative-level) do (aset numbering idx 0)))))
1346 options)))
1348 (defun org-export--skip-p (blob options)
1349 "Non-nil when element or object BLOB should be skipped during export.
1350 OPTIONS is the plist holding export options."
1351 (case (org-element-type blob)
1352 ;; Plain text is never skipped.
1353 (plain-text nil)
1354 ;; Check headline.
1355 (headline
1356 (let ((with-tasks (plist-get options :with-tasks))
1357 (todo (org-element-property :todo-keyword blob))
1358 (todo-type (org-element-property :todo-type blob))
1359 (archived (plist-get options :with-archived-trees))
1360 (tag-list (let ((tags (org-element-property :tags blob)))
1361 (and tags (org-split-string tags ":")))))
1363 ;; Ignore subtrees with an exclude tag.
1364 (loop for k in (plist-get options :exclude-tags)
1365 thereis (member k tag-list))
1366 ;; Ignore subtrees without a select tag, when such tag is found
1367 ;; in the buffer.
1368 (and (plist-get options :use-select-tags)
1369 (loop for k in (plist-get options :select-tags)
1370 never (member k tag-list)))
1371 ;; Ignore commented sub-trees.
1372 (org-element-property :commentedp blob)
1373 ;; Ignore archived subtrees if `:with-archived-trees' is nil.
1374 (and (not archived) (org-element-property :archivedp blob))
1375 ;; Ignore tasks, if specified by `:with-tasks' property.
1376 (and todo (not with-tasks))
1377 (and todo
1378 (memq with-tasks '(todo done))
1379 (not (eq todo-type with-tasks)))
1380 (and todo
1381 (consp with-tasks)
1382 (not (member todo with-tasks))))))
1383 ;; Check time-stamp.
1384 (time-stamp (not (plist-get options :with-timestamps)))
1385 ;; Check drawer.
1386 (drawer
1387 (or (not (plist-get options :with-drawers))
1388 (and (consp (plist-get options :with-drawers))
1389 (not (member (org-element-property :drawer-name blob)
1390 (plist-get options :with-drawers))))))
1391 ;; Check export snippet.
1392 (export-snippet
1393 (let* ((raw-back-end (org-element-property :back-end blob))
1394 (true-back-end
1395 (or (cdr (assoc raw-back-end org-export-snippet-translation-alist))
1396 raw-back-end)))
1397 (not (string= (symbol-name (plist-get options :back-end))
1398 true-back-end))))))
1400 (defun org-export-get-ignore-list (data options)
1401 "Return list of elements and objects to ignore during export.
1403 DATA is the parse tree to traverse. OPTIONS is the plist holding
1404 export options.
1406 Return elements or objects to ignore as a list."
1407 (let (ignore-list
1408 (walk-data
1409 (function
1410 (lambda (data options)
1411 ;; Collect ignored elements or objects into IGNORE-LIST.
1412 (mapc
1413 (lambda (el)
1414 (if (org-export--skip-p el options) (push el ignore-list)
1415 (let ((type (org-element-type el)))
1416 (when (or (eq type 'org-data)
1417 (memq type org-element-greater-elements)
1418 (memq type org-element-recursive-objects)
1419 (eq type 'paragraph))
1420 (funcall walk-data el options)))))
1421 (org-element-contents data))))))
1422 (funcall walk-data data options)
1423 ;; Return value.
1424 ignore-list))
1428 ;;; The Transcoder
1430 ;; This function reads Org data (obtained with, i.e.
1431 ;; `org-element-parse-buffer') and transcodes it into a specified
1432 ;; back-end output. It takes care of updating local properties,
1433 ;; filtering out elements or objects according to export options and
1434 ;; organizing the output blank lines and white space are preserved.
1436 ;; Though, this function is inapropriate for secondary strings, which
1437 ;; require a fresh copy of the plist passed as INFO argument. Thus,
1438 ;; `org-export-secondary-string' is provided for that specific task.
1440 ;; Internally, three functions handle the filtering of objects and
1441 ;; elements during the export. In particular,
1442 ;; `org-export-ignore-element' mark an element or object so future
1443 ;; parse tree traversals skip it, `org-export-interpret-p' tells which
1444 ;; elements or objects should be seen as real Org syntax and
1445 ;; `org-export-expand' transforms the others back into their original
1446 ;; shape.
1448 (defun org-export-data (data backend info)
1449 "Convert DATA to a string into BACKEND format.
1451 DATA is a nested list as returned by `org-element-parse-buffer'.
1453 BACKEND is a symbol among supported exporters.
1455 INFO is a plist holding export options and also used as
1456 a communication channel between elements when walking the nested
1457 list. See `org-export-update-info' function for more
1458 details.
1460 Return transcoded string."
1461 (mapconcat
1462 ;; BLOB can be an element, an object, a string, or nil.
1463 (lambda (blob)
1464 (cond
1465 ((not blob) nil)
1466 ;; BLOB is a string. Check if the optional transcoder for plain
1467 ;; text exists, and call it in that case. Otherwise, simply
1468 ;; return string. Also update INFO and call
1469 ;; `org-export-filter-plain-text-functions'.
1470 ((stringp blob)
1471 (let ((transcoder (intern (format "org-%s-plain-text" backend))))
1472 (org-export-filter-apply-functions
1473 (plist-get info :filter-plain-text)
1474 (if (fboundp transcoder) (funcall transcoder blob info) blob)
1475 backend info)))
1476 ;; BLOB is an element or an object.
1478 (let* ((type (org-element-type blob))
1479 ;; 1. Determine the appropriate TRANSCODER.
1480 (transcoder
1481 (cond
1482 ;; 1.0 A full Org document is inserted.
1483 ((eq type 'org-data) 'identity)
1484 ;; 1.1. BLOB should be ignored.
1485 ((member blob (plist-get info :ignore-list)) nil)
1486 ;; 1.2. BLOB shouldn't be transcoded. Interpret it
1487 ;; back into Org syntax.
1488 ((not (org-export-interpret-p blob info)) 'org-export-expand)
1489 ;; 1.3. Else apply naming convention.
1490 (t (let ((trans (intern (format "org-%s-%s" backend type))))
1491 (and (fboundp trans) trans)))))
1492 ;; 2. Compute CONTENTS of BLOB.
1493 (contents
1494 (cond
1495 ;; Case 0. No transcoder defined: ignore BLOB.
1496 ((not transcoder) nil)
1497 ;; Case 1. Transparently export an Org document.
1498 ((eq type 'org-data) (org-export-data blob backend info))
1499 ;; Case 2. For a recursive object.
1500 ((memq type org-element-recursive-objects)
1501 (org-export-data blob backend info))
1502 ;; Case 3. For a recursive element.
1503 ((memq type org-element-greater-elements)
1504 ;; Ignore contents of an archived tree
1505 ;; when `:with-archived-trees' is `headline'.
1506 (unless (and
1507 (eq type 'headline)
1508 (eq (plist-get info :with-archived-trees) 'headline)
1509 (org-element-property :archivedp blob))
1510 (org-element-normalize-string
1511 (org-export-data blob backend info))))
1512 ;; Case 4. For a paragraph.
1513 ((eq type 'paragraph)
1514 (let ((paragraph
1515 (org-element-normalize-contents
1516 blob
1517 ;; When normalizing contents of an item or
1518 ;; a footnote definition, ignore first line's
1519 ;; indentation: there is none and it might be
1520 ;; misleading.
1521 (and (not (org-export-get-previous-element blob info))
1522 (let ((parent (org-export-get-parent blob info)))
1523 (memq (org-element-type parent)
1524 '(footnote-definition item)))))))
1525 (org-export-data paragraph backend info)))))
1526 ;; 3. Transcode BLOB into RESULTS string.
1527 (results (cond
1528 ((not transcoder) nil)
1529 ((eq transcoder 'org-export-expand)
1530 (org-export-data
1531 `(org-data nil ,(funcall transcoder blob contents))
1532 backend info))
1533 (t (funcall transcoder blob contents info)))))
1534 ;; 4. Return results.
1535 (cond
1536 ;; Discard nil results. Also ignore BLOB from further
1537 ;; traversals in parse tree.
1538 ((not results) (org-export-ignore-element blob info) nil)
1539 ;; No filter for a full document.
1540 ((eq type 'org-data) results)
1541 ;; Otherwise, update INFO, append the same white space
1542 ;; between elements or objects as in the original buffer,
1543 ;; and call appropriate filters.
1545 (let ((results
1546 (org-export-filter-apply-functions
1547 (plist-get info (intern (format ":filter-%s" type)))
1548 (let ((post-blank (org-element-property :post-blank blob)))
1549 (if (memq type org-element-all-elements)
1550 (concat (org-element-normalize-string results)
1551 (make-string post-blank ?\n))
1552 (concat results (make-string post-blank ? ))))
1553 backend info)))
1554 ;; If BLOB was transcoded into an empty string, ignore it
1555 ;; from subsequent traversals.
1556 (unless (org-string-nw-p results)
1557 (org-export-ignore-element blob info))
1558 ;; Eventually return string.
1559 results)))))))
1560 (org-element-contents data) ""))
1562 (defun org-export-secondary-string (secondary backend info)
1563 "Convert SECONDARY string into BACKEND format.
1565 SECONDARY is a nested list as returned by
1566 `org-element-parse-secondary-string'.
1568 BACKEND is a symbol among supported exporters. INFO is a plist
1569 used as a communication channel.
1571 Return transcoded string."
1572 ;; Make SECONDARY acceptable for `org-export-data'.
1573 (let ((s (if (listp secondary) secondary (list secondary))))
1574 (org-export-data `(org-data nil ,@s) backend (copy-sequence info))))
1576 (defun org-export-interpret-p (blob info)
1577 "Non-nil if element or object BLOB should be interpreted as Org syntax.
1578 Check is done according to export options INFO, stored as
1579 a plist."
1580 (case (org-element-type blob)
1581 ;; ... entities...
1582 (entity (plist-get info :with-entities))
1583 ;; ... emphasis...
1584 (emphasis (plist-get info :with-emphasize))
1585 ;; ... fixed-width areas.
1586 (fixed-width (plist-get info :with-fixed-width))
1587 ;; ... footnotes...
1588 ((footnote-definition footnote-reference)
1589 (plist-get info :with-footnotes))
1590 ;; ... sub/superscripts...
1591 ((subscript superscript)
1592 (let ((sub/super-p (plist-get info :with-sub-superscript)))
1593 (if (eq sub/super-p '{})
1594 (org-element-property :use-brackets-p blob)
1595 sub/super-p)))
1596 ;; ... tables...
1597 (table (plist-get info :with-tables))
1598 (otherwise t)))
1600 (defsubst org-export-expand (blob contents)
1601 "Expand a parsed element or object to its original state.
1602 BLOB is either an element or an object. CONTENTS is its
1603 contents, as a string or nil."
1604 (funcall (intern (format "org-element-%s-interpreter" (org-element-type blob)))
1605 blob contents))
1607 (defun org-export-ignore-element (element info)
1608 "Add ELEMENT to `:ignore-list' in INFO.
1610 Any element in `:ignore-list' will be skipped when using
1611 `org-element-map'. INFO is modified by side effects."
1612 (plist-put info :ignore-list (cons element (plist-get info :ignore-list))))
1616 ;;; The Filter System
1618 ;; Filters allow end-users to tweak easily the transcoded output.
1619 ;; They are the functional counterpart of hooks, as every filter in
1620 ;; a set is applied to the return value of the previous one.
1622 ;; Every set is back-end agnostic. Although, a filter is always
1623 ;; called, in addition to the string it applies to, with the back-end
1624 ;; used as argument, so it's easy enough for the end-user to add
1625 ;; back-end specific filters in the set. The communication channel,
1626 ;; as a plist, is required as the third argument.
1628 ;; Filters sets are defined below. There are of four types:
1630 ;; - `org-export-filter-parse-tree-functions' applies directly on the
1631 ;; complete parsed tree. It's the only filters set that doesn't
1632 ;; apply to a string.
1633 ;; - `org-export-filter-final-output-functions' applies to the final
1634 ;; transcoded string.
1635 ;; - `org-export-filter-plain-text-functions' applies to any string
1636 ;; not recognized as Org syntax.
1637 ;; - `org-export-filter-TYPE-functions' applies on the string returned
1638 ;; after an element or object of type TYPE has been transcoded.
1640 ;; All filters sets are applied through
1641 ;; `org-export-filter-apply-functions' function. Filters in a set are
1642 ;; applied in a LIFO fashion. It allows developers to be sure that
1643 ;; their filters will be applied first.
1645 ;; Filters properties are installed in communication channel just
1646 ;; before parsing, with `org-export-install-filters' function.
1648 ;;;; Special Filters
1649 (defvar org-export-filter-parse-tree-functions nil
1650 "Filter, or list of filters, applied to the parsed tree.
1651 Each filter is called with three arguments: the parse tree, as
1652 returned by `org-element-parse-buffer', the back-end, as
1653 a symbol, and the communication channel, as a plist. It must
1654 return the modified parse tree to transcode.")
1656 (defvar org-export-filter-final-output-functions nil
1657 "Filter, or list of filters, applied to the transcoded string.
1658 Each filter is called with three arguments: the full transcoded
1659 string, the back-end, as a symbol, and the communication channel,
1660 as a plist. It must return a string that will be used as the
1661 final export output.")
1663 (defvar org-export-filter-plain-text-functions nil
1664 "Filter, or list of filters, applied to plain text.
1665 Each filter is called with three arguments: a string which
1666 contains no Org syntax, the back-end, as a symbol, and the
1667 communication channel, as a plist. It must return a string or
1668 nil.")
1671 ;;;; Elements Filters
1673 (defvar org-export-filter-center-block-functions nil
1674 "List of functions applied to a transcoded center block.
1675 Each filter is called with three arguments: the transcoded center
1676 block, as a string, the back-end, as a symbol, and the
1677 communication channel, as a plist. It must return a string or
1678 nil.")
1680 (defvar org-export-filter-drawer-functions nil
1681 "List of functions applied to a transcoded drawer.
1682 Each filter is called with three arguments: the transcoded
1683 drawer, as a string, the back-end, as a symbol, and the
1684 communication channel, as a plist. It must return a string or
1685 nil.")
1687 (defvar org-export-filter-dynamic-block-functions nil
1688 "List of functions applied to a transcoded dynamic-block.
1689 Each filter is called with three arguments: the transcoded
1690 dynamic-block, as a string, the back-end, as a symbol, and the
1691 communication channel, as a plist. It must return a string or
1692 nil.")
1694 (defvar org-export-filter-headline-functions nil
1695 "List of functions applied to a transcoded headline.
1696 Each filter is called with three arguments: the transcoded
1697 headline, as a string, the back-end, as a symbol, and the
1698 communication channel, as a plist. It must return a string or
1699 nil.")
1701 (defvar org-export-filter-inlinetask-functions nil
1702 "List of functions applied to a transcoded inlinetask.
1703 Each filter is called with three arguments: the transcoded
1704 inlinetask, as a string, the back-end, as a symbol, and the
1705 communication channel, as a plist. It must return a string or
1706 nil.")
1708 (defvar org-export-filter-plain-list-functions nil
1709 "List of functions applied to a transcoded plain-list.
1710 Each filter is called with three arguments: the transcoded
1711 plain-list, as a string, the back-end, as a symbol, and the
1712 communication channel, as a plist. It must return a string or
1713 nil.")
1715 (defvar org-export-filter-item-functions nil
1716 "List of functions applied to a transcoded item.
1717 Each filter is called with three arguments: the transcoded item,
1718 as a string, the back-end, as a symbol, and the communication
1719 channel, as a plist. It must return a string or nil.")
1721 (defvar org-export-filter-comment-functions nil
1722 "List of functions applied to a transcoded comment.
1723 Each filter is called with three arguments: the transcoded
1724 comment, as a string, the back-end, as a symbol, and the
1725 communication channel, as a plist. It must return a string or
1726 nil.")
1728 (defvar org-export-filter-comment-block-functions nil
1729 "List of functions applied to a transcoded comment-comment.
1730 Each filter is called with three arguments: the transcoded
1731 comment-block, as a string, the back-end, as a symbol, and the
1732 communication channel, as a plist. It must return a string or
1733 nil.")
1735 (defvar org-export-filter-example-block-functions nil
1736 "List of functions applied to a transcoded example-block.
1737 Each filter is called with three arguments: the transcoded
1738 example-block, as a string, the back-end, as a symbol, and the
1739 communication channel, as a plist. It must return a string or
1740 nil.")
1742 (defvar org-export-filter-export-block-functions nil
1743 "List of functions applied to a transcoded export-block.
1744 Each filter is called with three arguments: the transcoded
1745 export-block, as a string, the back-end, as a symbol, and the
1746 communication channel, as a plist. It must return a string or
1747 nil.")
1749 (defvar org-export-filter-fixed-width-functions nil
1750 "List of functions applied to a transcoded fixed-width.
1751 Each filter is called with three arguments: the transcoded
1752 fixed-width, as a string, the back-end, as a symbol, and the
1753 communication channel, as a plist. It must return a string or
1754 nil.")
1756 (defvar org-export-filter-footnote-definition-functions nil
1757 "List of functions applied to a transcoded footnote-definition.
1758 Each filter is called with three arguments: the transcoded
1759 footnote-definition, as a string, the back-end, as a symbol, and
1760 the communication channel, as a plist. It must return a string
1761 or nil.")
1763 (defvar org-export-filter-horizontal-rule-functions nil
1764 "List of functions applied to a transcoded horizontal-rule.
1765 Each filter is called with three arguments: the transcoded
1766 horizontal-rule, as a string, the back-end, as a symbol, and the
1767 communication channel, as a plist. It must return a string or
1768 nil.")
1770 (defvar org-export-filter-keyword-functions nil
1771 "List of functions applied to a transcoded keyword.
1772 Each filter is called with three arguments: the transcoded
1773 keyword, as a string, the back-end, as a symbol, and the
1774 communication channel, as a plist. It must return a string or
1775 nil.")
1777 (defvar org-export-filter-latex-environment-functions nil
1778 "List of functions applied to a transcoded latex-environment.
1779 Each filter is called with three arguments: the transcoded
1780 latex-environment, as a string, the back-end, as a symbol, and
1781 the communication channel, as a plist. It must return a string
1782 or nil.")
1784 (defvar org-export-filter-babel-call-functions nil
1785 "List of functions applied to a transcoded babel-call.
1786 Each filter is called with three arguments: the transcoded
1787 babel-call, as a string, the back-end, as a symbol, and the
1788 communication channel, as a plist. It must return a string or
1789 nil.")
1791 (defvar org-export-filter-paragraph-functions nil
1792 "List of functions applied to a transcoded paragraph.
1793 Each filter is called with three arguments: the transcoded
1794 paragraph, as a string, the back-end, as a symbol, and the
1795 communication channel, as a plist. It must return a string or
1796 nil.")
1798 (defvar org-export-filter-property-drawer-functions nil
1799 "List of functions applied to a transcoded property-drawer.
1800 Each filter is called with three arguments: the transcoded
1801 property-drawer, as a string, the back-end, as a symbol, and the
1802 communication channel, as a plist. It must return a string or
1803 nil.")
1805 (defvar org-export-filter-quote-block-functions nil
1806 "List of functions applied to a transcoded quote block.
1807 Each filter is called with three arguments: the transcoded quote
1808 block, as a string, the back-end, as a symbol, and the
1809 communication channel, as a plist. It must return a string or
1810 nil.")
1812 (defvar org-export-filter-quote-section-functions nil
1813 "List of functions applied to a transcoded quote-section.
1814 Each filter is called with three arguments: the transcoded
1815 quote-section, as a string, the back-end, as a symbol, and the
1816 communication channel, as a plist. It must return a string or
1817 nil.")
1819 (defvar org-export-filter-section-functions nil
1820 "List of functions applied to a transcoded section.
1821 Each filter is called with three arguments: the transcoded
1822 section, as a string, the back-end, as a symbol, and the
1823 communication channel, as a plist. It must return a string or
1824 nil.")
1826 (defvar org-export-filter-special-block-functions nil
1827 "List of functions applied to a transcoded special block.
1828 Each filter is called with three arguments: the transcoded
1829 special block, as a string, the back-end, as a symbol, and the
1830 communication channel, as a plist. It must return a string or
1831 nil.")
1833 (defvar org-export-filter-src-block-functions nil
1834 "List of functions applied to a transcoded src-block.
1835 Each filter is called with three arguments: the transcoded
1836 src-block, as a string, the back-end, as a symbol, and the
1837 communication channel, as a plist. It must return a string or
1838 nil.")
1840 (defvar org-export-filter-table-functions nil
1841 "List of functions applied to a transcoded table.
1842 Each filter is called with three arguments: the transcoded table,
1843 as a string, the back-end, as a symbol, and the communication
1844 channel, as a plist. It must return a string or nil.")
1846 (defvar org-export-filter-verse-block-functions nil
1847 "List of functions applied to a transcoded verse block.
1848 Each filter is called with three arguments: the transcoded verse
1849 block, as a string, the back-end, as a symbol, and the
1850 communication channel, as a plist. It must return a string or
1851 nil.")
1854 ;;;; Objects Filters
1856 (defvar org-export-filter-emphasis-functions nil
1857 "List of functions applied to a transcoded emphasis.
1858 Each filter is called with three arguments: the transcoded
1859 emphasis, as a string, the back-end, as a symbol, and the
1860 communication channel, as a plist. It must return a string or
1861 nil.")
1863 (defvar org-export-filter-entity-functions nil
1864 "List of functions applied to a transcoded entity.
1865 Each filter is called with three arguments: the transcoded
1866 entity, as a string, the back-end, as a symbol, and the
1867 communication channel, as a plist. It must return a string or
1868 nil.")
1870 (defvar org-export-filter-export-snippet-functions nil
1871 "List of functions applied to a transcoded export-snippet.
1872 Each filter is called with three arguments: the transcoded
1873 export-snippet, as a string, the back-end, as a symbol, and the
1874 communication channel, as a plist. It must return a string or
1875 nil.")
1877 (defvar org-export-filter-footnote-reference-functions nil
1878 "List of functions applied to a transcoded footnote-reference.
1879 Each filter is called with three arguments: the transcoded
1880 footnote-reference, as a string, the back-end, as a symbol, and
1881 the communication channel, as a plist. It must return a string
1882 or nil.")
1884 (defvar org-export-filter-inline-babel-call-functions nil
1885 "List of functions applied to a transcoded inline-babel-call.
1886 Each filter is called with three arguments: the transcoded
1887 inline-babel-call, as a string, the back-end, as a symbol, and
1888 the communication channel, as a plist. It must return a string
1889 or nil.")
1891 (defvar org-export-filter-inline-src-block-functions nil
1892 "List of functions applied to a transcoded inline-src-block.
1893 Each filter is called with three arguments: the transcoded
1894 inline-src-block, as a string, the back-end, as a symbol, and the
1895 communication channel, as a plist. It must return a string or
1896 nil.")
1898 (defvar org-export-filter-latex-fragment-functions nil
1899 "List of functions applied to a transcoded latex-fragment.
1900 Each filter is called with three arguments: the transcoded
1901 latex-fragment, as a string, the back-end, as a symbol, and the
1902 communication channel, as a plist. It must return a string or
1903 nil.")
1905 (defvar org-export-filter-line-break-functions nil
1906 "List of functions applied to a transcoded line-break.
1907 Each filter is called with three arguments: the transcoded
1908 line-break, as a string, the back-end, as a symbol, and the
1909 communication channel, as a plist. It must return a string or
1910 nil.")
1912 (defvar org-export-filter-link-functions nil
1913 "List of functions applied to a transcoded link.
1914 Each filter is called with three arguments: the transcoded link,
1915 as a string, the back-end, as a symbol, and the communication
1916 channel, as a plist. It must return a string or nil.")
1918 (defvar org-export-filter-macro-functions nil
1919 "List of functions applied to a transcoded macro.
1920 Each filter is called with three arguments: the transcoded macro,
1921 as a string, the back-end, as a symbol, and the communication
1922 channel, as a plist. It must return a string or nil.")
1924 (defvar org-export-filter-radio-target-functions nil
1925 "List of functions applied to a transcoded radio-target.
1926 Each filter is called with three arguments: the transcoded
1927 radio-target, as a string, the back-end, as a symbol, and the
1928 communication channel, as a plist. It must return a string or
1929 nil.")
1931 (defvar org-export-filter-statistics-cookie-functions nil
1932 "List of functions applied to a transcoded statistics-cookie.
1933 Each filter is called with three arguments: the transcoded
1934 statistics-cookie, as a string, the back-end, as a symbol, and
1935 the communication channel, as a plist. It must return a string
1936 or nil.")
1938 (defvar org-export-filter-subscript-functions nil
1939 "List of functions applied to a transcoded subscript.
1940 Each filter is called with three arguments: the transcoded
1941 subscript, as a string, the back-end, as a symbol, and the
1942 communication channel, as a plist. It must return a string or
1943 nil.")
1945 (defvar org-export-filter-superscript-functions nil
1946 "List of functions applied to a transcoded superscript.
1947 Each filter is called with three arguments: the transcoded
1948 superscript, as a string, the back-end, as a symbol, and the
1949 communication channel, as a plist. It must return a string or
1950 nil.")
1952 (defvar org-export-filter-target-functions nil
1953 "List of functions applied to a transcoded target.
1954 Each filter is called with three arguments: the transcoded
1955 target, as a string, the back-end, as a symbol, and the
1956 communication channel, as a plist. It must return a string or
1957 nil.")
1959 (defvar org-export-filter-time-stamp-functions nil
1960 "List of functions applied to a transcoded time-stamp.
1961 Each filter is called with three arguments: the transcoded
1962 time-stamp, as a string, the back-end, as a symbol, and the
1963 communication channel, as a plist. It must return a string or
1964 nil.")
1966 (defvar org-export-filter-verbatim-functions nil
1967 "List of functions applied to a transcoded verbatim.
1968 Each filter is called with three arguments: the transcoded
1969 verbatim, as a string, the back-end, as a symbol, and the
1970 communication channel, as a plist. It must return a string or
1971 nil.")
1973 (defun org-export-filter-apply-functions (filters value backend info)
1974 "Call every function in FILTERS with arguments VALUE, BACKEND and INFO.
1975 Functions are called in a LIFO fashion, to be sure that developer
1976 specified filters, if any, are called first."
1977 (loop for filter in filters
1978 if (not value) return nil else
1979 do (setq value (funcall filter value backend info)))
1980 value)
1982 (defun org-export-install-filters (backend info)
1983 "Install filters properties in communication channel.
1985 BACKEND is a symbol specifying which back-end specific filters to
1986 install, if any. INFO is a plist containing the current
1987 communication channel.
1989 Return the updated communication channel."
1990 (let (plist)
1991 ;; Install user defined filters with `org-export-filters-alist'.
1992 (mapc (lambda (p)
1993 (setq plist (plist-put plist (car p) (eval (cdr p)))))
1994 org-export-filters-alist)
1995 ;; Prepend back-end specific filters to that list.
1996 (let ((back-end-filters (intern (format "org-%s-filters-alist" backend))))
1997 (when (boundp back-end-filters)
1998 (mapc (lambda (p)
1999 ;; Single values get consed, lists are prepended.
2000 (let ((key (car p)) (value (cdr p)))
2001 (when value
2002 (setq plist
2003 (plist-put
2004 plist key
2005 (if (atom value) (cons value (plist-get plist key))
2006 (append value (plist-get plist key))))))))
2007 (eval back-end-filters))))
2008 ;; Return new communication channel.
2009 (org-combine-plists info plist)))
2013 ;;; Core functions
2015 ;; This is the room for the main function, `org-export-as', along with
2016 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
2017 ;; They differ only by the way they output the resulting code.
2019 ;; `org-export-output-file-name' is an auxiliary function meant to be
2020 ;; used with `org-export-to-file'. With a given extension, it tries
2021 ;; to provide a canonical file name to write export output to.
2023 ;; Note that `org-export-as' doesn't really parse the current buffer,
2024 ;; but a copy of it (with the same buffer-local variables and
2025 ;; visibility), where include keywords are expanded and Babel blocks
2026 ;; are executed, if appropriate.
2027 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
2029 ;; File inclusion is taken care of by
2030 ;; `org-export-expand-include-keyword' and
2031 ;; `org-export-prepare-file-contents'. Structure wise, including
2032 ;; a whole Org file in a buffer often makes little sense. For
2033 ;; example, if the file contains an headline and the include keyword
2034 ;; was within an item, the item should contain the headline. That's
2035 ;; why file inclusion should be done before any structure can be
2036 ;; associated to the file, that is before parsing.
2038 (defun org-export-as
2039 (backend &optional subtreep visible-only body-only ext-plist noexpand)
2040 "Transcode current Org buffer into BACKEND code.
2042 If narrowing is active in the current buffer, only transcode its
2043 narrowed part.
2045 If a region is active, transcode that region.
2047 When optional argument SUBTREEP is non-nil, transcode the
2048 sub-tree at point, extracting information from the headline
2049 properties first.
2051 When optional argument VISIBLE-ONLY is non-nil, don't export
2052 contents of hidden elements.
2054 When optional argument BODY-ONLY is non-nil, only return body
2055 code, without preamble nor postamble.
2057 Optional argument EXT-PLIST, when provided, is a property list
2058 with external parameters overriding Org default settings, but
2059 still inferior to file-local settings.
2061 Optional argument NOEXPAND, when non-nil, prevents included files
2062 to be expanded and Babel code to be executed.
2064 Return code as a string."
2065 (save-excursion
2066 (save-restriction
2067 ;; Narrow buffer to an appropriate region for parsing.
2068 (cond ((org-region-active-p)
2069 (narrow-to-region (region-beginning) (region-end)))
2070 (subtreep (org-narrow-to-subtree)))
2071 ;; Retrieve export options (INFO) and parsed tree (RAW-DATA),
2072 ;; Then options can be completed with tree properties. Note:
2073 ;; Buffer isn't parsed directly. Instead, a temporary copy is
2074 ;; created, where include keywords are expanded and code blocks
2075 ;; are evaluated. RAW-DATA is the parsed tree of the buffer
2076 ;; resulting from that process. Eventually call
2077 ;; `org-export-filter-parse-tree-functions'.
2078 (goto-char (point-min))
2079 (let ((info (org-export-get-environment backend subtreep ext-plist)))
2080 ;; Remove subtree's headline from contents if subtree mode is
2081 ;; activated.
2082 (when subtreep (forward-line) (narrow-to-region (point) (point-max)))
2083 ;; Install filters in communication channel.
2084 (setq info (org-export-install-filters backend info))
2085 (let ((raw-data
2086 (org-export-filter-apply-functions
2087 (plist-get info :filter-parse-tree)
2088 ;; If NOEXPAND is non-nil, simply parse current
2089 ;; visible part of buffer.
2090 (if noexpand (org-element-parse-buffer nil visible-only)
2091 (org-export-with-current-buffer-copy
2092 (org-export-expand-include-keyword nil)
2093 (let ((org-current-export-file (current-buffer)))
2094 (org-export-blocks-preprocess))
2095 (org-element-parse-buffer nil visible-only)))
2096 backend info)))
2097 ;; Complete communication channel with tree properties.
2098 (setq info
2099 (org-combine-plists
2100 info
2101 (org-export-collect-tree-properties raw-data info backend)))
2102 ;; Transcode RAW-DATA. Also call
2103 ;; `org-export-filter-final-output-functions'.
2104 (let* ((body (org-element-normalize-string
2105 (org-export-data raw-data backend info)))
2106 (template (intern (format "org-%s-template" backend)))
2107 (output (org-export-filter-apply-functions
2108 (plist-get info :filter-final-output)
2109 (if (or (not (fboundp template)) body-only) body
2110 (funcall template body info))
2111 backend info)))
2112 ;; Maybe add final OUTPUT to kill ring before returning it.
2113 (when org-export-copy-to-kill-ring (org-kill-new output))
2114 output))))))
2116 (defun org-export-to-buffer
2117 (backend buffer &optional subtreep visible-only body-only ext-plist noexpand)
2118 "Call `org-export-as' with output to a specified buffer.
2120 BACKEND is the back-end used for transcoding, as a symbol.
2122 BUFFER is the output buffer. If it already exists, it will be
2123 erased first, otherwise, it will be created.
2125 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2126 and NOEXPAND are similar to those used in `org-export-as', which
2127 see.
2129 Return buffer."
2130 (let ((out (org-export-as
2131 backend subtreep visible-only body-only ext-plist noexpand))
2132 (buffer (get-buffer-create buffer)))
2133 (with-current-buffer buffer
2134 (erase-buffer)
2135 (insert out)
2136 (goto-char (point-min)))
2137 buffer))
2139 (defun org-export-to-file
2140 (backend file &optional subtreep visible-only body-only ext-plist noexpand)
2141 "Call `org-export-as' with output to a specified file.
2143 BACKEND is the back-end used for transcoding, as a symbol. FILE
2144 is the name of the output file, as a string.
2146 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2147 and NOEXPAND are similar to those used in `org-export-as', which
2148 see.
2150 Return output file's name."
2151 ;; Checks for FILE permissions. `write-file' would do the same, but
2152 ;; we'd rather avoid needless transcoding of parse tree.
2153 (unless (file-writable-p file) (error "Output file not writable"))
2154 ;; Insert contents to a temporary buffer and write it to FILE.
2155 (let ((out (org-export-as
2156 backend subtreep visible-only body-only ext-plist noexpand)))
2157 (with-temp-buffer
2158 (insert out)
2159 (let ((coding-system-for-write org-export-coding-system))
2160 (write-file file))))
2161 ;; Return full path.
2162 file)
2164 (defun org-export-output-file-name (extension &optional subtreep pub-dir)
2165 "Return output file's name according to buffer specifications.
2167 EXTENSION is a string representing the output file extension,
2168 with the leading dot.
2170 With a non-nil optional argument SUBTREEP, try to determine
2171 output file's name by looking for \"EXPORT_FILE_NAME\" property
2172 of subtree at point.
2174 When optional argument PUB-DIR is set, use it as the publishing
2175 directory.
2177 Return file name as a string, or nil if it couldn't be
2178 determined."
2179 (let ((base-name
2180 ;; File name may come from EXPORT_FILE_NAME subtree property,
2181 ;; assuming point is at beginning of said sub-tree.
2182 (file-name-sans-extension
2183 (or (and subtreep
2184 (org-entry-get
2185 (save-excursion
2186 (ignore-errors
2187 (org-back-to-heading (not visible-only)) (point)))
2188 "EXPORT_FILE_NAME" t))
2189 ;; File name may be extracted from buffer's associated
2190 ;; file, if any.
2191 (buffer-file-name (buffer-base-buffer))
2192 ;; Can't determine file name on our own: Ask user.
2193 (let ((read-file-name-function
2194 (and org-completion-use-ido 'ido-read-file-name)))
2195 (read-file-name
2196 "Output file: " pub-dir nil nil nil
2197 (lambda (name)
2198 (string= (file-name-extension name t) extension))))))))
2199 ;; Build file name. Enforce EXTENSION over whatever user may have
2200 ;; come up with. PUB-DIR, if defined, always has precedence over
2201 ;; any provided path.
2202 (cond
2203 (pub-dir
2204 (concat (file-name-as-directory pub-dir)
2205 (file-name-nondirectory base-name)
2206 extension))
2207 ((string= (file-name-nondirectory base-name) base-name)
2208 (concat (file-name-as-directory ".") base-name extension))
2209 (t (concat base-name extension)))))
2211 (defmacro org-export-with-current-buffer-copy (&rest body)
2212 "Apply BODY in a copy of the current buffer.
2214 The copy preserves local variables and visibility of the original
2215 buffer.
2217 Point is at buffer's beginning when BODY is applied."
2218 (org-with-gensyms (original-buffer offset buffer-string overlays)
2219 `(let ((,original-buffer ,(current-buffer))
2220 (,offset ,(1- (point-min)))
2221 (,buffer-string ,(buffer-string))
2222 (,overlays (mapcar
2223 'copy-overlay (overlays-in (point-min) (point-max)))))
2224 (with-temp-buffer
2225 (let ((buffer-invisibility-spec nil))
2226 (org-clone-local-variables
2227 ,original-buffer
2228 "^\\(org-\\|orgtbl-\\|major-mode$\\|outline-\\(regexp\\|level\\)$\\)")
2229 (insert ,buffer-string)
2230 (mapc (lambda (ov)
2231 (move-overlay
2233 (- (overlay-start ov) ,offset)
2234 (- (overlay-end ov) ,offset)
2235 (current-buffer)))
2236 ,overlays)
2237 (goto-char (point-min))
2238 (progn ,@body))))))
2239 (def-edebug-spec org-export-with-current-buffer-copy (body))
2241 (defun org-export-expand-include-keyword (included)
2242 "Expand every include keyword in buffer.
2243 INCLUDED is a list of included file names along with their line
2244 restriction, when appropriate. It is used to avoid infinite
2245 recursion."
2246 (let ((case-fold-search nil))
2247 (goto-char (point-min))
2248 (while (re-search-forward "^[ \t]*#\\+include: \\(.*\\)" nil t)
2249 (when (eq (org-element-type (save-match-data (org-element-at-point)))
2250 'keyword)
2251 (beginning-of-line)
2252 ;; Extract arguments from keyword's value.
2253 (let* ((value (match-string 1))
2254 (ind (org-get-indentation))
2255 (file (and (string-match "^\"\\(\\S-+\\)\"" value)
2256 (prog1 (expand-file-name (match-string 1 value))
2257 (setq value (replace-match "" nil nil value)))))
2258 (lines
2259 (and (string-match
2260 ":lines +\"\\(\\(?:[0-9]+\\)?-\\(?:[0-9]+\\)?\\)\"" value)
2261 (prog1 (match-string 1 value)
2262 (setq value (replace-match "" nil nil value)))))
2263 (env (cond ((string-match "\\<example\\>" value) 'example)
2264 ((string-match "\\<src\\(?: +\\(.*\\)\\)?" value)
2265 (match-string 1 value))))
2266 ;; Minimal level of included file defaults to the child
2267 ;; level of the current headline, if any, or one. It
2268 ;; only applies is the file is meant to be included as
2269 ;; an Org one.
2270 (minlevel
2271 (and (not env)
2272 (if (string-match ":minlevel +\\([0-9]+\\)" value)
2273 (prog1 (string-to-number (match-string 1 value))
2274 (setq value (replace-match "" nil nil value)))
2275 (let ((cur (org-current-level)))
2276 (if cur (1+ (org-reduced-level cur)) 1))))))
2277 ;; Remove keyword.
2278 (delete-region (point) (progn (forward-line) (point)))
2279 (cond
2280 ((not (file-readable-p file)) (error "Cannot include file %s" file))
2281 ;; Check if files has already been parsed. Look after
2282 ;; inclusion lines too, as different parts of the same file
2283 ;; can be included too.
2284 ((member (list file lines) included)
2285 (error "Recursive file inclusion: %s" file))
2287 (cond
2288 ((eq env 'example)
2289 (insert
2290 (let ((ind-str (make-string ind ? ))
2291 (contents
2292 ;; Protect sensitive contents with commas.
2293 (replace-regexp-in-string
2294 "\\(^\\)\\([*]\\|[ \t]*#\\+\\)" ","
2295 (org-export-prepare-file-contents file lines)
2296 nil nil 1)))
2297 (format "%s#+begin_example\n%s%s#+end_example\n"
2298 ind-str contents ind-str))))
2299 ((stringp env)
2300 (insert
2301 (let ((ind-str (make-string ind ? ))
2302 (contents
2303 ;; Protect sensitive contents with commas.
2304 (replace-regexp-in-string
2305 (if (string= env "org") "\\(^\\)\\(.\\)"
2306 "\\(^\\)\\([*]\\|[ \t]*#\\+\\)") ","
2307 (org-export-prepare-file-contents file lines)
2308 nil nil 1)))
2309 (format "%s#+begin_src %s\n%s%s#+end_src\n"
2310 ind-str env contents ind-str))))
2312 (insert
2313 (with-temp-buffer
2314 (org-mode)
2315 (insert
2316 (org-export-prepare-file-contents file lines ind minlevel))
2317 (org-export-expand-include-keyword
2318 (cons (list file lines) included))
2319 (buffer-string))))))))))))
2321 (defun org-export-prepare-file-contents (file &optional lines ind minlevel)
2322 "Prepare the contents of FILE for inclusion and return them as a string.
2324 When optional argument LINES is a string specifying a range of
2325 lines, include only those lines.
2327 Optional argument IND, when non-nil, is an integer specifying the
2328 global indentation of returned contents. Since its purpose is to
2329 allow an included file to stay in the same environment it was
2330 created \(i.e. a list item), it doesn't apply past the first
2331 headline encountered.
2333 Optional argument MINLEVEL, when non-nil, is an integer
2334 specifying the level that any top-level headline in the included
2335 file should have."
2336 (with-temp-buffer
2337 (insert-file-contents file)
2338 (when lines
2339 (let* ((lines (split-string lines "-"))
2340 (lbeg (string-to-number (car lines)))
2341 (lend (string-to-number (cadr lines)))
2342 (beg (if (zerop lbeg) (point-min)
2343 (goto-char (point-min))
2344 (forward-line (1- lbeg))
2345 (point)))
2346 (end (if (zerop lend) (point-max)
2347 (goto-char (point-min))
2348 (forward-line (1- lend))
2349 (point))))
2350 (narrow-to-region beg end)))
2351 ;; Remove blank lines at beginning and end of contents. The logic
2352 ;; behind that removal is that blank lines around include keyword
2353 ;; override blank lines in included file.
2354 (goto-char (point-min))
2355 (org-skip-whitespace)
2356 (beginning-of-line)
2357 (delete-region (point-min) (point))
2358 (goto-char (point-max))
2359 (skip-chars-backward " \r\t\n")
2360 (forward-line)
2361 (delete-region (point) (point-max))
2362 ;; If IND is set, preserve indentation of include keyword until
2363 ;; the first headline encountered.
2364 (when ind
2365 (unless (eq major-mode 'org-mode) (org-mode))
2366 (goto-char (point-min))
2367 (let ((ind-str (make-string ind ? )))
2368 (while (not (or (eobp) (looking-at org-outline-regexp-bol)))
2369 ;; Do not move footnote definitions out of column 0.
2370 (unless (and (looking-at org-footnote-definition-re)
2371 (eq (org-element-type (org-element-at-point))
2372 'footnote-definition))
2373 (insert ind-str))
2374 (forward-line))))
2375 ;; When MINLEVEL is specified, compute minimal level for headlines
2376 ;; in the file (CUR-MIN), and remove stars to each headline so
2377 ;; that headlines with minimal level have a level of MINLEVEL.
2378 (when minlevel
2379 (unless (eq major-mode 'org-mode) (org-mode))
2380 (let ((levels (org-map-entries
2381 (lambda () (org-reduced-level (org-current-level))))))
2382 (when levels
2383 (let ((offset (- minlevel (apply 'min levels))))
2384 (unless (zerop offset)
2385 (when org-odd-levels-only (setq offset (* offset 2)))
2386 ;; Only change stars, don't bother moving whole
2387 ;; sections.
2388 (org-map-entries
2389 (lambda () (if (< offset 0) (delete-char (abs offset))
2390 (insert (make-string offset ?*))))))))))
2391 (buffer-string)))
2394 ;;; Tools For Back-Ends
2396 ;; A whole set of tools is available to help build new exporters. Any
2397 ;; function general enough to have its use across many back-ends
2398 ;; should be added here.
2400 ;; As of now, functions operating on footnotes, headlines, links,
2401 ;; macros, references, src-blocks, tables and tables of contents are
2402 ;; implemented.
2404 ;;;; For Footnotes
2406 ;; `org-export-collect-footnote-definitions' is a tool to list
2407 ;; actually used footnotes definitions in the whole parse tree, or in
2408 ;; an headline, in order to add footnote listings throughout the
2409 ;; transcoded data.
2411 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2412 ;; back-ends, when they need to attach the footnote definition only to
2413 ;; the first occurrence of the corresponding label.
2415 ;; `org-export-get-footnote-definition' and
2416 ;; `org-export-get-footnote-number' provide easier access to
2417 ;; additional information relative to a footnote reference.
2419 (defun org-export-collect-footnote-definitions (data info)
2420 "Return an alist between footnote numbers, labels and definitions.
2422 DATA is the parse tree from which definitions are collected.
2423 INFO is the plist used as a communication channel.
2425 Definitions are sorted by order of references. They either
2426 appear as Org data \(transcoded with `org-export-data'\) or as
2427 a secondary string for inlined footnotes \(transcoded with
2428 `org-export-secondary-string'\). Unreferenced definitions are
2429 ignored."
2430 (let (refs)
2431 ;; Collect seen references in REFS.
2432 (org-element-map
2433 data 'footnote-reference
2434 (lambda (footnote local)
2435 (when (org-export-footnote-first-reference-p footnote local)
2436 (list (org-export-get-footnote-number footnote local)
2437 (org-element-property :label footnote)
2438 (org-export-get-footnote-definition footnote local))))
2439 info)))
2441 (defun org-export-footnote-first-reference-p (footnote-reference info)
2442 "Non-nil when a footnote reference is the first one for its label.
2444 FOOTNOTE-REFERENCE is the footnote reference being considered.
2445 INFO is the plist used as a communication channel."
2446 (let ((label (org-element-property :label footnote-reference)))
2447 (or (not label)
2448 (equal
2449 footnote-reference
2450 (org-element-map
2451 (plist-get info :parse-tree) 'footnote-reference
2452 (lambda (footnote local)
2453 (when (string= (org-element-property :label footnote) label)
2454 footnote))
2455 info 'first-match)))))
2457 (defun org-export-get-footnote-definition (footnote-reference info)
2458 "Return definition of FOOTNOTE-REFERENCE as parsed data.
2459 INFO is the plist used as a communication channel."
2460 (let ((label (org-element-property :label footnote-reference)))
2461 (or (org-element-property :inline-definition footnote-reference)
2462 (cdr (assoc label (plist-get info :footnote-definition-alist))))))
2464 (defun org-export-get-footnote-number (footnote info)
2465 "Return number associated to a footnote.
2467 FOOTNOTE is either a footnote reference or a footnote definition.
2468 INFO is the plist used as a communication channel."
2469 (let ((label (org-element-property :label footnote)) seen-refs)
2470 (org-element-map
2471 (plist-get info :parse-tree) 'footnote-reference
2472 (lambda (fn local)
2473 (let ((fn-lbl (org-element-property :label fn)))
2474 (cond
2475 ((and (not fn-lbl) (equal fn footnote)) (1+ (length seen-refs)))
2476 ((and label (string= label fn-lbl)) (1+ (length seen-refs)))
2477 ;; Anonymous footnote: it's always a new one. Also, be sure
2478 ;; to return nil from the `cond' so `first-match' doesn't
2479 ;; get us out of the loop.
2480 ((not fn-lbl) (push 'inline seen-refs) nil)
2481 ;; Label not seen so far: add it so SEEN-REFS. Again,
2482 ;; return nil to stay in the loop.
2483 ((not (member fn-lbl seen-refs)) (push fn-lbl seen-refs) nil))))
2484 info 'first-match)))
2487 ;;;; For Headlines
2489 ;; `org-export-get-relative-level' is a shortcut to get headline
2490 ;; level, relatively to the lower headline level in the parsed tree.
2492 ;; `org-export-get-headline-number' returns the section number of an
2493 ;; headline, while `org-export-number-to-roman' allows to convert it
2494 ;; to roman numbers.
2496 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
2497 ;; `org-export-last-sibling-p' are three useful predicates when it
2498 ;; comes to fulfill the `:headline-levels' property.
2500 (defun org-export-get-relative-level (headline info)
2501 "Return HEADLINE relative level within current parsed tree.
2502 INFO is a plist holding contextual information."
2503 (+ (org-element-property :level headline)
2504 (or (plist-get info :headline-offset) 0)))
2506 (defun org-export-low-level-p (headline info)
2507 "Non-nil when HEADLINE is considered as low level.
2509 INFO is a plist used as a communication channel.
2511 A low level headlines has a relative level greater than
2512 `:headline-levels' property value.
2514 Return value is the difference between HEADLINE relative level
2515 and the last level being considered as high enough, or nil."
2516 (let ((limit (plist-get info :headline-levels)))
2517 (when (wholenump limit)
2518 (let ((level (org-export-get-relative-level headline info)))
2519 (and (> level limit) (- level limit))))))
2521 (defun org-export-get-headline-number (headline info)
2522 "Return HEADLINE numbering as a list of numbers.
2523 INFO is a plist holding contextual information."
2524 (cdr (assoc headline (plist-get info :headline-numbering))))
2526 (defun org-export-number-to-roman (n)
2527 "Convert integer N into a roman numeral."
2528 (let ((roman '((1000 . "M") (900 . "CM") (500 . "D") (400 . "CD")
2529 ( 100 . "C") ( 90 . "XC") ( 50 . "L") ( 40 . "XL")
2530 ( 10 . "X") ( 9 . "IX") ( 5 . "V") ( 4 . "IV")
2531 ( 1 . "I")))
2532 (res ""))
2533 (if (<= n 0)
2534 (number-to-string n)
2535 (while roman
2536 (if (>= n (caar roman))
2537 (setq n (- n (caar roman))
2538 res (concat res (cdar roman)))
2539 (pop roman)))
2540 res)))
2542 (defun org-export-first-sibling-p (headline info)
2543 "Non-nil when HEADLINE is the first sibling in its sub-tree.
2544 INFO is the plist used as a communication channel."
2545 (not (eq (org-element-type (org-export-get-previous-element headline info))
2546 'headline)))
2548 (defun org-export-last-sibling-p (headline info)
2549 "Non-nil when HEADLINE is the last sibling in its sub-tree.
2550 INFO is the plist used as a communication channel."
2551 (not (org-export-get-next-element headline info)))
2554 ;;;; For Links
2556 ;; `org-export-solidify-link-text' turns a string into a safer version
2557 ;; for links, replacing most non-standard characters with hyphens.
2559 ;; `org-export-get-coderef-format' returns an appropriate format
2560 ;; string for coderefs.
2562 ;; `org-export-inline-image-p' returns a non-nil value when the link
2563 ;; provided should be considered as an inline image.
2565 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
2566 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
2567 ;; returns an appropriate unique identifier when found, or nil.
2569 ;; `org-export-resolve-id-link' returns the first headline with
2570 ;; specified id or custom-id in parse tree, or nil when none was
2571 ;; found.
2573 ;; `org-export-resolve-coderef' associates a reference to a line
2574 ;; number in the element it belongs, or returns the reference itself
2575 ;; when the element isn't numbered.
2577 (defun org-export-solidify-link-text (s)
2578 "Take link text S and make a safe target out of it."
2579 (save-match-data
2580 (mapconcat 'identity (org-split-string s "[^a-zA-Z0-9_.-]+") "-")))
2582 (defun org-export-get-coderef-format (path desc)
2583 "Return format string for code reference link.
2584 PATH is the link path. DESC is its description."
2585 (save-match-data
2586 (cond ((string-match (regexp-quote (concat "(" path ")")) desc)
2587 (replace-match "%s" t t desc))
2588 ((string= desc "") "%s")
2589 (t desc))))
2591 (defun org-export-inline-image-p (link &optional rules)
2592 "Non-nil if LINK object points to an inline image.
2594 Optional argument is a set of RULES defining inline images. It
2595 is an alist where associations have the following shape:
2597 \(TYPE . REGEXP)
2599 Applying a rule means apply REGEXP against LINK's path when its
2600 type is TYPE. The function will return a non-nil value if any of
2601 the provided rules is non-nil. The default rule is
2602 `org-export-default-inline-image-rule'.
2604 This only applies to links without a description."
2605 (and (not (org-element-contents link))
2606 (let ((case-fold-search t)
2607 (rules (or rules org-export-default-inline-image-rule)))
2608 (some
2609 (lambda (rule)
2610 (and (string= (org-element-property :type link) (car rule))
2611 (string-match (cdr rule)
2612 (org-element-property :path link))))
2613 rules))))
2615 (defun org-export-resolve-fuzzy-link (link info)
2616 "Return LINK destination.
2618 INFO is a plist holding contextual information.
2620 Return value can be an object, an element, or nil:
2622 - If LINK path exactly matches any target, return the target
2623 object.
2625 - If LINK path exactly matches any headline name, return that
2626 element. If more than one headline share that name, priority
2627 will be given to the one with the closest common ancestor, if
2628 any, or the first one in the parse tree otherwise.
2630 - Otherwise, return nil.
2632 Assume LINK type is \"fuzzy\"."
2633 (let ((path (org-element-property :path link)))
2634 ;; Link points to a target: return it.
2635 (or (loop for target in (plist-get info :target-list)
2636 when (string= (org-element-property :raw-value target) path)
2637 return target)
2638 ;; Link either points to an headline or nothing. Try to find
2639 ;; the source, with priority given to headlines with the closest
2640 ;; common ancestor. If such candidate is found, return its
2641 ;; beginning position as an unique identifier, otherwise return
2642 ;; nil.
2643 (let ((find-headline
2644 (function
2645 ;; Return first headline whose `:raw-value' property
2646 ;; is NAME in parse tree DATA, or nil.
2647 (lambda (name data)
2648 (org-element-map
2649 data 'headline
2650 (lambda (headline local)
2651 (when (string=
2652 (org-element-property :raw-value headline)
2653 name)
2654 headline))
2655 info 'first-match)))))
2656 ;; Search among headlines sharing an ancestor with link,
2657 ;; from closest to farthest.
2658 (or (catch 'exit
2659 (mapc
2660 (lambda (parent)
2661 (when (eq (org-element-type parent) 'headline)
2662 (let ((foundp (funcall find-headline path parent)))
2663 (when foundp (throw 'exit foundp)))))
2664 (org-export-get-genealogy link info)) nil)
2665 ;; No match with a common ancestor: try the full parse-tree.
2666 (funcall find-headline path (plist-get info :parse-tree)))))))
2668 (defun org-export-resolve-id-link (link info)
2669 "Return headline referenced as LINK destination.
2671 INFO is a plist used as a communication channel.
2673 Return value can be an headline element or nil. Assume LINK type
2674 is either \"id\" or \"custom-id\"."
2675 (let ((id (org-element-property :path link)))
2676 (org-element-map
2677 (plist-get info :parse-tree) 'headline
2678 (lambda (headline local)
2679 (when (or (string= (org-element-property :id headline) id)
2680 (string= (org-element-property :custom-id headline) id))
2681 headline))
2682 info 'first-match)))
2684 (defun org-export-resolve-ref-link (link info)
2685 "Return element referenced as LINK destination.
2687 INFO is a plist used as a communication channel.
2689 Assume LINK type is \"ref\" and. Return value is the first
2690 element whose `:name' property matches LINK's `:path', or nil."
2691 (let ((name (org-element-property :path link)))
2692 (org-element-map
2693 (plist-get info :parse-tree) org-element-all-elements
2694 (lambda (el local)
2695 (when (string= (org-element-property :name el) name) el))
2696 info 'first-match)))
2698 (defun org-export-resolve-coderef (ref info)
2699 "Resolve a code reference REF.
2701 INFO is a plist used as a communication channel.
2703 Return associated line number in source code, or REF itself,
2704 depending on src-block or example element's switches."
2705 (org-element-map
2706 (plist-get info :parse-tree) '(src-block example)
2707 (lambda (el local)
2708 (let ((switches (or (org-element-property :switches el) "")))
2709 (with-temp-buffer
2710 (insert (org-trim (org-element-property :value el)))
2711 ;; Build reference regexp.
2712 (let* ((label
2713 (or (and (string-match "-l +\"\\([^\"\n]+\\)\"" switches)
2714 (match-string 1 switches))
2715 org-coderef-label-format))
2716 (ref-re
2717 (format "^.*?\\S-.*?\\([ \t]*\\(%s\\)\\)[ \t]*$"
2718 (replace-regexp-in-string "%s" ref label nil t))))
2719 ;; Element containing REF is found. Only associate REF to
2720 ;; a line number if element has "+n" or "-n" and "-k" or
2721 ;; "-r" as switches. When it has "+n", count accumulated
2722 ;; locs before, too.
2723 (when (re-search-backward ref-re nil t)
2724 (cond
2725 ((not (string-match "-[kr]\\>" switches)) ref)
2726 ((string-match "-n\\>" switches) (line-number-at-pos))
2727 ((string-match "\\+n\\>" switches)
2728 (+ (org-export-get-loc el local) (line-number-at-pos)))
2729 (t ref)))))))
2730 info 'first-match))
2733 ;;;; For Macros
2735 ;; `org-export-expand-macro' simply takes care of expanding macros.
2737 (defun org-export-expand-macro (macro info)
2738 "Expand MACRO and return it as a string.
2739 INFO is a plist holding export options."
2740 (let* ((key (org-element-property :key macro))
2741 (args (org-element-property :args macro))
2742 ;; User's macros are stored in the communication channel with
2743 ;; a ":macro-" prefix. If it's a string leave it as-is.
2744 ;; Otherwise, it's a secondary string that needs to be
2745 ;; expanded recursively.
2746 (value
2747 (let ((val (plist-get info (intern (format ":macro-%s" key)))))
2748 (if (stringp val) val
2749 (org-export-secondary-string
2750 val (plist-get info :back-end) info)))))
2751 ;; Replace arguments in VALUE.
2752 (let ((s 0) n)
2753 (while (string-match "\\$\\([0-9]+\\)" value s)
2754 (setq s (1+ (match-beginning 0))
2755 n (string-to-number (match-string 1 value)))
2756 (and (>= (length args) n)
2757 (setq value (replace-match (nth (1- n) args) t t value)))))
2758 ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
2759 (when (string-match "\\`(eval\\>" value)
2760 (setq value (eval (read value))))
2761 ;; Return string.
2762 (format "%s" (or value ""))))
2765 ;;;; For References
2767 ;; `org-export-get-ordinal' associates a sequence number to any object
2768 ;; or element.
2770 (defun org-export-get-ordinal
2771 (element info &optional types within-section predicate)
2772 "Return ordinal number of an element or object.
2774 ELEMENT is the element or object considered. INFO is the plist
2775 used as a communication channel.
2777 Optional argument TYPES, when non-nil, is a list of element or
2778 object types, as symbols, that should also be counted in.
2779 Otherwise, only provided element's type is considered.
2781 When optional argument WITHIN-SECTION is non-nil, narrow counting
2782 to the section containing ELEMENT.
2784 Optional argument PREDICATE is a function returning a non-nil
2785 value if the current element or object should be counted in. It
2786 accepts one argument: the element or object being considered.
2787 This argument allows to count only a certain type of objects,
2788 like inline images, which are a subset of links \(in that case,
2789 `org-export-inline-image-p' might be an useful predicate\)."
2790 (let ((counter 0)
2791 ;; Determine if search should apply to current section, in
2792 ;; which case it should be retrieved first, or to full parse
2793 ;; tree. As a special case, an element or object without
2794 ;; a parent headline will also trigger a full search,
2795 ;; notwithstanding WITHIN-SECTION value.
2796 (data
2797 (if (not within-section) (plist-get info :parse-tree)
2798 (or (org-export-get-parent-headline element info)
2799 (plist-get info :parse-tree)))))
2800 ;; Increment counter until ELEMENT is found again.
2801 (org-element-map
2802 data (or types (org-element-type element))
2803 (lambda (el local)
2804 (cond
2805 ((equal element el) (1+ counter))
2806 ((not predicate) (incf counter) nil)
2807 ((funcall predicate el) (incf counter) nil)))
2808 info 'first-match)))
2811 ;;;; For Src-Blocks
2813 ;; `org-export-get-loc' counts number of code lines accumulated in
2814 ;; src-block or example-block elements with a "+n" switch until
2815 ;; a given element, excluded. Note: "-n" switches reset that count.
2817 ;; `org-export-handle-code' takes care of line numbering and reference
2818 ;; cleaning in source code, when appropriate.
2820 (defun org-export-get-loc (element info)
2821 "Return accumulated lines of code up to ELEMENT.
2823 INFO is the plist used as a communication channel.
2825 ELEMENT is excluded from count."
2826 (let ((loc 0))
2827 (org-element-map
2828 (plist-get info :parse-tree)
2829 `(src-block example-block ,(org-element-type element))
2830 (lambda (el local)
2831 (cond
2832 ;; ELEMENT is reached: Quit the loop.
2833 ((equal el element) t)
2834 ;; Only count lines from src-block and example-block elements
2835 ;; with a "+n" or "-n" switch. A "-n" switch resets counter.
2836 ((not (memq (org-element-type el) '(src-block example-block))) nil)
2837 ((let ((switches (org-element-property :switches el)))
2838 (when (and switches (string-match "\\([-+]\\)n\\>" switches))
2839 ;; Accumulate locs or reset them.
2840 (let ((accumulatep (string= (match-string 1 switches) "-"))
2841 (lines (org-count-lines
2842 (org-trim (org-element-property :value el)))))
2843 (setq loc (if accumulatep lines (+ loc lines))))))
2844 ;; Return nil to stay in the loop.
2845 nil)))
2846 info 'first-match)
2847 ;; Return value.
2848 loc))
2850 (defun org-export-handle-code (element info &optional num-fmt ref-fmt delayed)
2851 "Handle line numbers and code references in ELEMENT.
2853 ELEMENT has either a `src-block' an `example-block' type. INFO
2854 is a plist used as a communication channel.
2856 If optional argument NUM-FMT is a string, it will be used as
2857 a format string for numbers at beginning of each line.
2859 If optional argument REF-FMT is a string, it will be used as
2860 a format string for each line of code containing a reference.
2862 When optional argument DELAYED is non-nil, `org-loc' and
2863 `org-coderef' properties, set to an adequate value, are applied
2864 to, respectively, numbered lines and lines with a reference. No
2865 line numbering is done and all references are stripped from the
2866 resulting string. Both NUM-FMT and REF-FMT arguments are ignored
2867 in that situation.
2869 Return new code as a string."
2870 (let* ((switches (or (org-element-property :switches element) ""))
2871 (code (org-element-property :value element))
2872 (numberp (string-match "[-+]n\\>" switches))
2873 (accumulatep (string-match "\\+n\\>" switches))
2874 ;; Initialize loc counter when any kind of numbering is
2875 ;; active.
2876 (total-LOC (cond
2877 (accumulatep (org-export-get-loc element info))
2878 (numberp 0)))
2879 ;; Get code and clean it. Remove blank lines at its
2880 ;; beginning and end. Also remove protective commas.
2881 (preserve-indent-p (or org-src-preserve-indentation
2882 (string-match "-i\\>" switches)))
2883 (replace-labels (when (string-match "-r\\>" switches)
2884 (if (string-match "-k\\>" switches) 'keep t)))
2885 (code (let ((c (replace-regexp-in-string
2886 "\\`\\([ \t]*\n\\)+" ""
2887 (replace-regexp-in-string
2888 "\\(:?[ \t]*\n\\)*[ \t]*\\'" "\n" code))))
2889 ;; If appropriate, remove global indentation.
2890 (unless preserve-indent-p (setq c (org-remove-indentation c)))
2891 ;; Free up the protected lines. Note: Org blocks
2892 ;; have commas at the beginning or every line.
2893 (if (string=
2894 (or (org-element-property :language element) "")
2895 "org")
2896 (replace-regexp-in-string "^," "" c)
2897 (replace-regexp-in-string
2898 "^\\(,\\)\\(:?\\*\\|[ \t]*#\\+\\)" "" c nil nil 1))))
2899 ;; Split code to process it line by line.
2900 (code-lines (org-split-string code "\n"))
2901 ;; If numbering is active, ensure line numbers will be
2902 ;; correctly padded before applying the format string.
2903 (num-fmt
2904 (when (and (not delayed) numberp)
2905 (format (if (stringp num-fmt) num-fmt "%s: ")
2906 (format "%%%ds"
2907 (length (number-to-string
2908 (+ (length code-lines) total-LOC)))))))
2909 ;; Get format used for references.
2910 (label-fmt (or (and (string-match "-l +\"\\([^\"\n]+\\)\"" switches)
2911 (match-string 1 switches))
2912 org-coderef-label-format))
2913 ;; Build a regexp matching a loc with a reference.
2914 (with-ref-re (format "^.*?\\S-.*?\\([ \t]*\\(%s\\)\\)[ \t]*$"
2915 (replace-regexp-in-string
2916 "%s" "\\([-a-zA-Z0-9_ ]+\\)" label-fmt nil t))))
2917 (org-element-normalize-string
2918 (mapconcat
2919 (lambda (loc)
2920 ;; Maybe add line number to current line of code (LOC).
2921 (when numberp
2922 (incf total-LOC)
2923 (setq loc (if delayed (org-add-props loc nil 'org-loc total-LOC)
2924 (concat (format num-fmt total-LOC) loc))))
2925 ;; Take action if at a ref line.
2926 (when (string-match with-ref-re loc)
2927 (let ((ref (match-string 3 loc)))
2928 (setq loc
2929 ;; Option "-r" without "-k" removes labels.
2930 ;; A non-nil DELAYED removes labels unconditionally.
2931 (if (or delayed
2932 (and replace-labels (not (eq replace-labels 'keep))))
2933 (replace-match "" nil nil loc 1)
2934 (replace-match (format "(%s)" ref) nil nil loc 2)))
2935 ;; Store REF in `org-coderef' property if DELAYED asks to.
2936 (cond (delayed (setq loc (org-add-props loc nil 'org-coderef ref)))
2937 ;; If REF-FMT is defined, apply it to current LOC.
2938 ((stringp ref-fmt) (setq loc (format ref-fmt loc))))))
2939 ;; Return updated LOC for concatenation.
2940 loc)
2941 code-lines "\n"))))
2944 ;;;; For Tables
2946 ;; `org-export-table-format-info' extracts formatting information
2947 ;; (alignment, column groups and presence of a special column) from
2948 ;; a raw table and returns it as a property list.
2950 ;; `org-export-clean-table' cleans the raw table from any Org
2951 ;; table-specific syntax.
2953 (defun org-export-table-format-info (table)
2954 "Extract info from TABLE.
2955 Return a plist whose properties and values are:
2956 `:alignment' vector of strings among \"r\", \"l\" and \"c\",
2957 `:column-groups' vector of symbols among `start', `end', `start-end',
2958 `:row-groups' list of integers representing row groups.
2959 `:special-column-p' non-nil if table has a special column.
2960 `:width' vector of integers representing desired width of
2961 current column, or nil."
2962 (with-temp-buffer
2963 (insert table)
2964 (goto-char 1)
2965 (org-table-align)
2966 (let ((align (vconcat (mapcar (lambda (c) (if c "r" "l"))
2967 org-table-last-alignment)))
2968 (width (make-vector (length org-table-last-alignment) nil))
2969 (colgroups (make-vector (length org-table-last-alignment) nil))
2970 (row-group 0)
2971 (rowgroups)
2972 (special-column-p 'empty))
2973 (mapc (lambda (row)
2974 (if (string-match "^[ \t]*|[-+]+|[ \t]*$" row)
2975 (incf row-group)
2976 ;; Determine if a special column is present by looking
2977 ;; for special markers in the first column. More
2978 ;; accurately, the first column is considered special
2979 ;; if it only contains special markers and, maybe,
2980 ;; empty cells.
2981 (setq special-column-p
2982 (cond
2983 ((not special-column-p) nil)
2984 ((string-match "^[ \t]*| *\\\\?\\([/#!$*_^]\\) *|" row)
2985 'special)
2986 ((string-match "^[ \t]*| +|" row) special-column-p))))
2987 (cond
2988 ;; Read forced alignment and width information, if any,
2989 ;; and determine final alignment for the table.
2990 ((org-table-cookie-line-p row)
2991 (let ((col 0))
2992 (mapc (lambda (field)
2993 (when (string-match
2994 "<\\([lrc]\\)?\\([0-9]+\\)?>" field)
2995 (let ((align-data (match-string 1 field)))
2996 (when align-data (aset align col align-data)))
2997 (let ((w-data (match-string 2 field)))
2998 (when w-data
2999 (aset width col (string-to-number w-data)))))
3000 (incf col))
3001 (org-split-string row "[ \t]*|[ \t]*"))))
3002 ;; Read column groups information.
3003 ((org-table-colgroup-line-p row)
3004 (let ((col 0))
3005 (mapc (lambda (field)
3006 (aset colgroups col
3007 (cond ((string= "<" field) 'start)
3008 ((string= ">" field) 'end)
3009 ((string= "<>" field) 'start-end)))
3010 (incf col))
3011 (org-split-string row "[ \t]*|[ \t]*"))))
3012 ;; Contents line.
3013 (t (push row-group rowgroups))))
3014 (org-split-string table "\n"))
3015 ;; Return plist.
3016 (list :alignment align
3017 :column-groups colgroups
3018 :row-groups (reverse rowgroups)
3019 :special-column-p (eq special-column-p 'special)
3020 :width width))))
3022 (defun org-export-clean-table (table specialp)
3023 "Clean string TABLE from its formatting elements.
3024 Remove any row containing column groups or formatting cookies and
3025 rows starting with a special marker. If SPECIALP is non-nil,
3026 assume the table contains a special formatting column and remove
3027 it also."
3028 (let ((rows (org-split-string table "\n")))
3029 (mapconcat 'identity
3030 (delq nil
3031 (mapcar
3032 (lambda (row)
3033 (cond
3034 ((org-table-colgroup-line-p row) nil)
3035 ((org-table-cookie-line-p row) nil)
3036 ;; Ignore rows starting with a special marker.
3037 ((string-match "^[ \t]*| *[!_^/$] *|" row) nil)
3038 ;; Remove special column.
3039 ((and specialp
3040 (or (string-match "^\\([ \t]*\\)|-+\\+" row)
3041 (string-match "^\\([ \t]*\\)|[^|]*|" row)))
3042 (replace-match "\\1|" t nil row))
3043 (t row)))
3044 rows))
3045 "\n")))
3048 ;;;; For Tables Of Contents
3050 ;; `org-export-collect-headlines' builds a list of all exportable
3051 ;; headline elements, maybe limited to a certain depth. One can then
3052 ;; easily parse it and transcode it.
3054 ;; Building lists of tables, figures or listings is quite similar.
3055 ;; Once the generic function `org-export-collect-elements' is defined,
3056 ;; `org-export-collect-tables', `org-export-collect-figures' and
3057 ;; `org-export-collect-listings' can be derived from it.
3059 (defun org-export-collect-headlines (info &optional n)
3060 "Collect headlines in order to build a table of contents.
3062 INFO is a plist used as a communication channel.
3064 When non-nil, optional argument N must be an integer. It
3065 specifies the depth of the table of contents.
3067 Return a list of all exportable headlines as parsed elements."
3068 (org-element-map
3069 (plist-get info :parse-tree)
3070 'headline
3071 (lambda (headline local)
3072 ;; Strip contents from HEADLINE.
3073 (let ((relative-level (org-export-get-relative-level headline local)))
3074 (unless (and n (> relative-level n)) headline)))
3075 info))
3077 (defun org-export-collect-elements (type info &optional predicate)
3078 "Collect referenceable elements of a determined type.
3080 TYPE can be a symbol or a list of symbols specifying element
3081 types to search. Only elements with a caption or a name are
3082 collected.
3084 INFO is a plist used as a communication channel.
3086 When non-nil, optional argument PREDICATE is a function accepting
3087 one argument, an element of type TYPE. It returns a non-nil
3088 value when that element should be collected.
3090 Return a list of all elements found, in order of appearance."
3091 (org-element-map
3092 (plist-get info :parse-tree) type
3093 (lambda (element local)
3094 (and (or (org-element-property :caption element)
3095 (org-element-property :name element))
3096 (or (not predicate) (funcall predicate element))
3097 element)) info))
3099 (defun org-export-collect-tables (info)
3100 "Build a list of tables.
3102 INFO is a plist used as a communication channel.
3104 Return a list of table elements with a caption or a name
3105 affiliated keyword."
3106 (org-export-collect-elements 'table info))
3108 (defun org-export-collect-figures (info predicate)
3109 "Build a list of figures.
3111 INFO is a plist used as a communication channel. PREDICATE is
3112 a function which accepts one argument: a paragraph element and
3113 whose return value is non-nil when that element should be
3114 collected.
3116 A figure is a paragraph type element, with a caption or a name,
3117 verifying PREDICATE. The latter has to be provided since
3118 a \"figure\" is a vague concept that may depend on back-end.
3120 Return a list of elements recognized as figures."
3121 (org-export-collect-elements 'paragraph info predicate))
3123 (defun org-export-collect-listings (info)
3124 "Build a list of src blocks.
3126 INFO is a plist used as a communication channel.
3128 Return a list of src-block elements with a caption or a name
3129 affiliated keyword."
3130 (org-export-collect-elements 'src-block info))
3133 ;;;; Topology
3135 ;; Here are various functions to retrieve information about the
3136 ;; neighbourhood of a given element or object. Neighbours of interest
3137 ;; are direct parent (`org-export-get-parent'), parent headline
3138 ;; (`org-export-get-parent-headline'), parent paragraph
3139 ;; (`org-export-get-parent-paragraph'), previous element or object
3140 ;; (`org-export-get-previous-element') and next element or object
3141 ;; (`org-export-get-next-element').
3143 ;; All of these functions are just a specific use of the more generic
3144 ;; `org-export-get-genealogy', which returns the genealogy relative to
3145 ;; the element or object.
3147 (defun org-export-get-genealogy (blob info)
3148 "Return genealogy relative to a given element or object.
3149 BLOB is the element or object being considered. INFO is a plist
3150 used as a communication channel."
3151 (let* ((end (org-element-property :end blob))
3152 (walk-data
3153 (lambda (data genealogy)
3154 (mapc
3155 (lambda (el)
3156 (cond
3157 ((stringp el))
3158 ((equal el blob) (throw 'exit genealogy))
3159 ((>= (org-element-property :end el) end)
3160 (funcall walk-data el (cons el genealogy)))))
3161 (org-element-contents data)))))
3162 (catch 'exit (funcall walk-data (plist-get info :parse-tree) nil) nil)))
3164 (defun org-export-get-parent (blob info)
3165 "Return BLOB parent or nil.
3166 BLOB is the element or object considered. INFO is a plist used
3167 as a communication channel."
3168 (car (org-export-get-genealogy blob info)))
3170 (defun org-export-get-parent-headline (blob info)
3171 "Return closest parent headline or nil.
3173 BLOB is the element or object being considered. INFO is a plist
3174 used as a communication channel."
3175 (catch 'exit
3176 (mapc
3177 (lambda (el) (when (eq (org-element-type el) 'headline) (throw 'exit el)))
3178 (org-export-get-genealogy blob info))
3179 nil))
3181 (defun org-export-get-parent-paragraph (object info)
3182 "Return parent paragraph or nil.
3184 INFO is a plist used as a communication channel.
3186 Optional argument OBJECT, when provided, is the object to consider.
3187 Otherwise, return the paragraph containing current object.
3189 This is useful for objects, which share attributes with the
3190 paragraph containing them."
3191 (catch 'exit
3192 (mapc
3193 (lambda (el) (when (eq (org-element-type el) 'paragraph) (throw 'exit el)))
3194 (org-export-get-genealogy object info))
3195 nil))
3197 (defun org-export-get-previous-element (blob info)
3198 "Return previous element or object.
3200 BLOB is an element or object. INFO is a plist used as
3201 a communication channel.
3203 Return previous element or object, a string, or nil."
3204 (let ((parent (org-export-get-parent blob info)))
3205 (cadr (member blob (reverse (org-element-contents parent))))))
3207 (defun org-export-get-next-element (blob info)
3208 "Return next element or object.
3210 BLOB is an element or object. INFO is a plist used as
3211 a communication channel.
3213 Return next element or object, a string, or nil."
3214 (let ((parent (org-export-get-parent blob info)))
3215 (cadr (member blob (org-element-contents parent)))))
3219 ;;; The Dispatcher
3221 ;; `org-export-dispatch' is the standard interactive way to start an
3222 ;; export process. It uses `org-export-dispatch-ui' as a subroutine
3223 ;; for its interface. Most commons back-ends should have an entry in
3224 ;; it.
3226 (defun org-export-dispatch ()
3227 "Export dispatcher for Org mode.
3229 It provides an access to common export related tasks in a buffer.
3230 Its interface comes in two flavours: standard and expert. While
3231 both share the same set of bindings, only the former displays the
3232 valid keys associations. Set `org-export-dispatch-use-expert-ui'
3233 to switch to one or the other.
3235 Return an error if key pressed has no associated command."
3236 (interactive)
3237 (let* ((input (org-export-dispatch-ui
3238 (if (listp org-export-initial-scope) org-export-initial-scope
3239 (list org-export-initial-scope))
3240 org-export-dispatch-use-expert-ui))
3241 (raw-key (car input))
3242 (optns (cdr input)))
3243 ;; Translate "C-a", "C-b"... into "a", "b"... Then take action
3244 ;; depending on user's key pressed.
3245 (case (if (< raw-key 27) (+ raw-key 96) raw-key)
3246 ;; Allow to quit with "q" key.
3247 (?q nil)
3248 ;; Export with `e-ascii' back-end.
3249 ((?A ?N ?U)
3250 (let ((outbuf
3251 (org-export-to-buffer
3252 'e-ascii "*Org E-ASCII Export*"
3253 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns)
3254 `(:ascii-charset
3255 ,(case raw-key (?A 'ascii) (?N 'latin1) (t 'utf-8))))))
3256 (with-current-buffer outbuf (text-mode))
3257 (when org-export-show-temporary-export-buffer
3258 (switch-to-buffer-other-window outbuf))))
3259 ((?a ?n ?u)
3260 (org-e-ascii-export-to-ascii
3261 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns)
3262 `(:ascii-charset ,(case raw-key (?a 'ascii) (?n 'latin1) (t 'utf-8)))))
3263 ;; Export with `e-latex' back-end.
3265 (let ((outbuf
3266 (org-export-to-buffer
3267 'e-latex "*Org E-LaTeX Export*"
3268 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns))))
3269 (with-current-buffer outbuf (latex-mode))
3270 (when org-export-show-temporary-export-buffer
3271 (switch-to-buffer-other-window outbuf))))
3272 (?l (org-e-latex-export-to-latex
3273 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns)))
3274 (?p (org-e-latex-export-to-pdf
3275 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns)))
3276 (?d (org-open-file
3277 (org-e-latex-export-to-pdf
3278 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns))))
3279 ;; Export with `e-html' back-end.
3281 (let ((outbuf
3282 (org-export-to-buffer
3283 'e-html "*Org E-HTML Export*"
3284 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns))))
3285 ;; set major mode
3286 (with-current-buffer outbuf
3287 (if (featurep 'nxhtml-mode) (nxhtml-mode) (nxml-mode)))
3288 (when org-export-show-temporary-export-buffer
3289 (switch-to-buffer-other-window outbuf))))
3290 (?h (org-e-html-export-to-html
3291 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns)))
3292 (?b (org-open-file
3293 (org-e-html-export-to-html
3294 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns))))
3295 ;; Export with `e-odt' back-end.
3296 (?o (org-e-odt-export-to-odt
3297 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns)))
3298 (?O (org-open-file
3299 (org-e-odt-export-to-odt
3300 (memq 'subtree optns) (memq 'visible optns) (memq 'body optns))))
3301 ;; Publishing facilities
3302 (?F (org-e-publish-current-file (memq 'force optns)))
3303 (?P (org-e-publish-current-project (memq 'force optns)))
3304 (?X (let ((project
3305 (assoc (org-icompleting-read
3306 "Publish project: " org-e-publish-project-alist nil t)
3307 org-e-publish-project-alist)))
3308 (org-e-publish project (memq 'force optns))))
3309 (?E (org-e-publish-all (memq 'force optns)))
3310 ;; Undefined command.
3311 (t (error "No command associated with key %s"
3312 (char-to-string raw-key))))))
3314 (defun org-export-dispatch-ui (options expertp)
3315 "Handle interface for `org-export-dispatch'.
3317 OPTIONS is a list containing current interactive options set for
3318 export. It can contain any of the following symbols:
3319 `body' toggles a body-only export
3320 `subtree' restricts export to current subtree
3321 `visible' restricts export to visible part of buffer.
3322 `force' force publishing files.
3324 EXPERTP, when non-nil, triggers expert UI. In that case, no help
3325 buffer is provided, but indications about currently active
3326 options are given in the prompt. Moreover, \[?] allows to switch
3327 back to standard interface.
3329 Return value is a list with key pressed as CAR and a list of
3330 final interactive export options as CDR."
3331 (let ((help
3332 (format "---- (Options) -------------------------------------------
3334 \[1] Body only: %s [2] Export scope: %s
3335 \[3] Visible only: %s [4] Force publishing: %s
3338 ----(ASCII/Latin-1/UTF-8 Export)--------------------------
3340 \[a/n/u] to TXT file [A/N/U] to temporary buffer
3342 ----(HTML Export)-----------------------------------------
3344 \[h] to HTML file [b] ... and open it
3345 \[H] to temporary buffer
3347 ----(LaTeX Export)----------------------------------------
3349 \[l] to TEX file [L] to temporary buffer
3350 \[p] to PDF file [d] ... and open it
3352 ----(ODF Export)------------------------------------------
3354 \[o] to ODT file [O] ... and open it
3356 ----(Publish)---------------------------------------------
3358 \[F] current file [P] current project
3359 \[X] a project [E] every project"
3360 (if (memq 'body options) "On " "Off")
3361 (if (memq 'subtree options) "Subtree" "Buffer ")
3362 (if (memq 'visible options) "On " "Off")
3363 (if (memq 'force options) "On " "Off")))
3364 (standard-prompt "Export command: ")
3365 (expert-prompt (format "Export command (%s%s%s%s): "
3366 (if (memq 'body options) "b" "-")
3367 (if (memq 'subtree options) "s" "-")
3368 (if (memq 'visible options) "v" "-")
3369 (if (memq 'force options) "f" "-")))
3370 (handle-keypress
3371 (function
3372 ;; Read a character from command input, toggling interactive
3373 ;; options when applicable. PROMPT is the displayed prompt,
3374 ;; as a string.
3375 (lambda (prompt)
3376 (let ((key (read-char-exclusive prompt)))
3377 (cond
3378 ;; Ignore non-standard characters (i.e. "M-a").
3379 ((not (characterp key)) (org-export-dispatch-ui options expertp))
3380 ;; Help key: Switch back to standard interface if
3381 ;; expert UI was active.
3382 ((eq key ??) (org-export-dispatch-ui options nil))
3383 ;; Toggle export options.
3384 ((memq key '(?1 ?2 ?3 ?4))
3385 (org-export-dispatch-ui
3386 (let ((option (case key (?1 'body) (?2 'subtree) (?3 'visible)
3387 (?4 'force))))
3388 (if (memq option options) (remq option options)
3389 (cons option options)))
3390 expertp))
3391 ;; Action selected: Send key and options back to
3392 ;; `org-export-dispatch'.
3393 (t (cons key options))))))))
3394 ;; With expert UI, just read key with a fancy prompt. In standard
3395 ;; UI, display an intrusive help buffer.
3396 (if expertp (funcall handle-keypress expert-prompt)
3397 (save-window-excursion
3398 (delete-other-windows)
3399 (with-output-to-temp-buffer "*Org Export/Publishing Help*" (princ help))
3400 (org-fit-window-to-buffer
3401 (get-buffer-window "*Org Export/Publishing Help*"))
3402 (funcall handle-keypress standard-prompt)))))
3405 (provide 'org-export)
3406 ;;; org-export.el ends here