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/>.
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
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
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
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
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.
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
159 `split' Split values at white spaces, and cons them to the
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
237 (defconst org-export-default-inline-image-rule
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
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."
265 (defgroup org-export-general nil
266 "General options for export engine."
267 :tag
"Org Export General"
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,
280 :group
'org-export-general
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
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
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
319 This option can also be set with the #+OPTIONS line,
321 :group
'org-export-general
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,
332 :group
'org-export-general
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
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
359 : ;; Some Lisp examples
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
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,
373 :group
'org-export-general
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
383 This option can also be set with the #+OPTIONS line, e.g. \"H:2\"."
384 :group
'org-export-general
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,
401 :group
'org-export-general
404 (defcustom org-export-with-entities t
405 "Non-nil means interpret entities when exporting.
407 For example, HTML export converts \\alpha to α and \\AA to
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,
415 :group
'org-export-general
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
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,
432 :group
'org-export-general
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:
450 -----+----------+--------
456 This option can also be set with the #+OPTIONS line,
458 :group
'org-export-general
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,
484 :group
'org-export-general
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
500 This option can also be set with the #+OPTIONS line,
501 e.g. \"toc:nil\" or \"toc:3\"."
502 :group
'org-export-general
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.
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
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
527 This option can also be set with the #+OPTIONS line,
529 :group
'org-export-general
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
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
561 (defcustom org-export-with-timestamps t
562 "If nil, do not export time stamps and associated keywords."
563 :group
'org-export-general
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
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
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
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
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
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
629 :group
'org-export-general
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'
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
659 ;; + `:author' :: Author's name.
660 ;; - category :: option
663 ;; + `:back-end' :: Current back-end used for transcoding.
664 ;; - category :: tree
667 ;; + `:creator' :: String to write as creation information.
668 ;; - category :: option
671 ;; + `:date' :: String to use as date.
672 ;; - category :: option
675 ;; + `:description' :: Description text for the current data.
676 ;; - category :: option
679 ;; + `:email' :: Author's email.
680 ;; - category :: option
683 ;; + `:exclude-tags' :: Tags for exclusion of subtrees from export
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
704 ;; - category :: option
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
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
733 ;; + `:language' :: Default language used for translations.
734 ;; - category :: option
737 ;; + `:macro-input-file' :: Macro returning file name of input file,
739 ;; - category :: option
740 ;; - type :: string or nil
742 ;; + `:parse-tree' :: Whole parse tree, available at any time during
744 ;; - category :: global
745 ;; - type :: list (as returned by `org-element-parse-buffer')
747 ;; + `:preserve-breaks' :: Non-nil means transcoding should preserve
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
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
806 ;; - category :: option
807 ;; - type :: symbol (nil, t)
809 ;; + `:with-emphasize' :: Non-nil means emphasized text should be
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
821 ;; - category :: option
822 ;; - type :: symbol (nil, t)
824 ;; + `:with-priority' :: Non-nil means transcoding should include
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
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
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
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
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)...
928 ,(or (let ((file (buffer-file-name (buffer-base-buffer))))
930 (file-name-sans-extension
931 (file-name-nondirectory file
))))
932 (buffer-name (buffer-base-buffer))))
933 ;; ... from an external property list...
935 ;; ... from in-buffer settings...
936 (org-export-get-inbuffer-options
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
))
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."
952 (append org-export-option-alist
955 (format "org-%s-option-alist" backend
))))
956 (and (boundp var
) (eval var
))))))
957 ;; Build an alist between #+OPTION: item and property-name.
960 (when (nth 2 e
) (cons (regexp-quote (nth 2 e
))
965 (when (string-match (concat "\\(\\`\\|[ \t]\\)"
967 ":\\(([^)\n]+)\\|[^ \t\n\r;,.]*\\)")
969 (setq plist
(plist-put plist
971 (car (read-from-string
972 (match-string 2 options
)))))))
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."
983 (when (setq prop
(progn (looking-at org-todo-line-regexp
)
985 (org-entry-get (point) "EXPORT_TITLE"))
986 (org-match-string-no-properties 3))))
990 (org-element-parse-secondary-string
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
)))
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
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
))
1026 ((string= key
"SETUP_FILE")
1029 (org-remove-double-quotes (org-trim val
)))))
1030 ;; Avoid circular dependencies.
1031 (unless (member file files
)
1033 (insert (org-file-contents file
'noerror
))
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")
1041 "^\\([-a-zA-Z0-9_]+\\)\\(?:[ \t]+\\(.*?\\)[ \t]*$\\)?"
1046 (downcase (match-string 1 val
)))))
1047 (value (org-match-string-no-properties 2 val
)))
1050 ;; Value will be evaled. Leave it as-is.
1051 ((string-match "\\`(eval\\>" value
)
1053 ;; Value has to be parsed for nested
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"
1069 (replace-regexp-in-string
1070 "\\(\\\\\\\\\\)n" "\\\\"
1071 (replace-regexp-in-string
1072 "\\(?:^\\|[^\\\\]\\)\\(\\\\n\\)"
1073 hard-newline value nil nil
1)
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.
1084 (format "org-%s-option-alist" backend
))))
1085 (and (boundp var
) (eval var
))))))
1086 ;; Build alist between keyword name and property name.
1089 (lambda (e) (when (nth 1 e
) (cons (nth 1 e
) (car e
))))
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
))))
1106 ;; Handle value depending on specified BEHAVIOUR.
1109 (if (not (plist-get plist prop
)) (org-trim val
)
1110 (concat (plist-get plist prop
) " " (org-trim val
))))
1113 (concat (plist-get plist prop
) "\n" (org-trim val
))))
1115 `(,@(plist-get plist prop
) ,@(org-split-string val
)))
1117 (otherwise (plist-get plist prop
)))))))))
1118 ;; Parse keywords specified in `org-element-parsed-keywords'.
1121 (let* ((prop (cdr (assoc key alist
)))
1122 (value (and prop
(plist-get plist prop
))))
1123 (when (stringp value
)
1127 (org-element-parse-secondary-string
1129 (cdr (assq 'keyword org-element-string-restrictions
))))))))
1130 org-element-parsed-keywords
))
1131 ;; 3. Return final value.
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
1140 (let ((all (append org-export-option-alist
1143 (format "org-%s-option-alist" backend
))))
1144 (and (boundp var
) (eval var
))))))
1147 (mapc (lambda (cell)
1148 (setq plist
(plist-put plist
(car cell
) (eval (nth 3 cell
)))))
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))))
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
1168 (file-exists-p visited-file
)
1169 (concat "(eval (format-time-string \"$1\" '"
1170 (prin1-to-string (nth 5 (file-attributes visited-file
)))
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
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)))
1184 (org-skip-whitespace)
1185 (push (cons (car def
)
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.
1192 (list 'org-data nil
)
1193 (org-element-parse-elements
1194 (point-min) (point-max) nil nil nil nil nil
))))
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."
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
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) ")"))
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.
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'.
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'.
1280 :headline-offset
(- 1 (org-export-get-min-level data info
))))
1281 ;; Now, properties order doesn't matter: get the rest of the tree
1287 ,(org-element-map data
'target
(lambda (target local
) target
) info
)
1288 :headline-numbering
,(org-export-collect-headline-numbering data 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."
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
))))
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."
1311 (let ((min-level 10000))
1314 (when (and (eq (org-element-type blob
) 'headline
)
1315 (not (org-export-ignored-p blob options
)))
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
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)))
1336 (lambda (headline info
)
1337 (let ((relative-level
1338 (1- (org-export-get-relative-level headline info
))))
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)))))
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.
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
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
))
1378 (memq with-tasks
'(todo done
))
1379 (not (eq todo-type with-tasks
)))
1382 (not (member todo with-tasks
))))))
1383 ;; Check time-stamp.
1384 (time-stamp (not (plist-get options
:with-timestamps
)))
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.
1393 (let* ((raw-back-end (org-element-property :back-end blob
))
1395 (or (cdr (assoc raw-back-end org-export-snippet-translation-alist
))
1397 (not (string= (symbol-name (plist-get options
: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
1406 Return elements or objects to ignore as a list."
1410 (lambda (data options
)
1411 ;; Collect ignored elements or objects into IGNORE-LIST.
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
)
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
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
1460 Return transcoded string."
1462 ;; BLOB can be an element, an object, a string, or 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'.
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
)
1476 ;; BLOB is an element or an object.
1478 (let* ((type (org-element-type blob
))
1479 ;; 1. Determine the appropriate TRANSCODER.
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.
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'.
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
)
1515 (org-element-normalize-contents
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
1521 (and (not (org-export-get-previous-element blob info
))
1524 (org-export-get-genealogy blob info
))))
1525 (memq (org-element-type parent
)
1526 '(footnote-definition item
)))))))
1527 (org-export-data paragraph backend info
)))))
1528 ;; 3. Transcode BLOB into RESULTS string.
1530 ((not transcoder
) nil
)
1531 ((eq transcoder
'org-export-expand
)
1533 `(org-data nil
,(funcall transcoder blob contents
))
1535 (t (funcall transcoder blob contents info
)))))
1536 ;; 4. Return results.
1538 ;; Discard nil results. Also ignore BLOB from further
1539 ;; traversals in parse tree.
1540 ((not results
) (org-export-ignore-element blob info
) nil
)
1541 ;; No filter for a full document.
1542 ((eq type
'org-data
) results
)
1543 ;; Otherwise, update INFO, append the same white space
1544 ;; between elements or objects as in the original buffer,
1545 ;; and call appropriate filters.
1548 (org-export-filter-apply-functions
1549 (plist-get info
(intern (format ":filter-%s" type
)))
1550 (let ((post-blank (org-element-property :post-blank blob
)))
1551 (if (memq type org-element-all-elements
)
1552 (concat (org-element-normalize-string results
)
1553 (make-string post-blank ?
\n))
1554 (concat results
(make-string post-blank ?
))))
1556 ;; If BLOB was transcoded into an empty string, ignore it
1557 ;; from subsequent traversals.
1558 (unless (org-string-nw-p results
)
1559 (org-export-ignore-element blob info
))
1560 ;; Eventually return string.
1562 (org-element-contents data
) ""))
1564 (defun org-export-secondary-string (secondary backend info
)
1565 "Convert SECONDARY string into BACKEND format.
1567 SECONDARY is a nested list as returned by
1568 `org-element-parse-secondary-string'.
1570 BACKEND is a symbol among supported exporters. INFO is a plist
1571 used as a communication channel.
1573 Return transcoded string."
1574 ;; Make SECONDARY acceptable for `org-export-data'.
1575 (let ((s (if (listp secondary
) secondary
(list secondary
))))
1576 (org-export-data `(org-data nil
,@s
) backend
(copy-sequence info
))))
1578 (defun org-export-interpret-p (blob info
)
1579 "Non-nil if element or object BLOB should be interpreted as Org syntax.
1580 Check is done according to export options INFO, stored as
1582 (case (org-element-type blob
)
1584 (entity (plist-get info
:with-entities
))
1586 (emphasis (plist-get info
:with-emphasize
))
1587 ;; ... fixed-width areas.
1588 (fixed-width (plist-get info
:with-fixed-width
))
1590 ((footnote-definition footnote-reference
)
1591 (plist-get info
:with-footnotes
))
1592 ;; ... sub/superscripts...
1593 ((subscript superscript
)
1594 (let ((sub/super-p
(plist-get info
:with-sub-superscript
)))
1595 (if (eq sub
/super-p
'{})
1596 (org-element-property :use-brackets-p blob
)
1599 (table (plist-get info
:with-tables
))
1602 (defsubst org-export-expand
(blob contents
)
1603 "Expand a parsed element or object to its original state.
1604 BLOB is either an element or an object. CONTENTS is its
1605 contents, as a string or nil."
1606 (funcall (intern (format "org-element-%s-interpreter" (org-element-type blob
)))
1609 (defun org-export-ignore-element (element info
)
1610 "Add ELEMENT to `:ignore-list' in INFO.
1612 Any element in `:ignore-list' will be skipped when using
1613 `org-element-map'. INFO is modified by side effects."
1614 (plist-put info
:ignore-list
(cons element
(plist-get info
:ignore-list
))))
1618 ;;; The Filter System
1620 ;; Filters allow end-users to tweak easily the transcoded output.
1621 ;; They are the functional counterpart of hooks, as every filter in
1622 ;; a set is applied to the return value of the previous one.
1624 ;; Every set is back-end agnostic. Although, a filter is always
1625 ;; called, in addition to the string it applies to, with the back-end
1626 ;; used as argument, so it's easy enough for the end-user to add
1627 ;; back-end specific filters in the set. The communication channel,
1628 ;; as a plist, is required as the third argument.
1630 ;; Filters sets are defined below. There are of four types:
1632 ;; - `org-export-filter-parse-tree-functions' applies directly on the
1633 ;; complete parsed tree. It's the only filters set that doesn't
1634 ;; apply to a string.
1635 ;; - `org-export-filter-final-output-functions' applies to the final
1636 ;; transcoded string.
1637 ;; - `org-export-filter-plain-text-functions' applies to any string
1638 ;; not recognized as Org syntax.
1639 ;; - `org-export-filter-TYPE-functions' applies on the string returned
1640 ;; after an element or object of type TYPE has been transcoded.
1642 ;; All filters sets are applied through
1643 ;; `org-export-filter-apply-functions' function. Filters in a set are
1644 ;; applied in a LIFO fashion. It allows developers to be sure that
1645 ;; their filters will be applied first.
1647 ;; Filters properties are installed in communication channel just
1648 ;; before parsing, with `org-export-install-filters' function.
1650 ;;;; Special Filters
1651 (defvar org-export-filter-parse-tree-functions nil
1652 "Filter, or list of filters, applied to the parsed tree.
1653 Each filter is called with three arguments: the parse tree, as
1654 returned by `org-element-parse-buffer', the back-end, as
1655 a symbol, and the communication channel, as a plist. It must
1656 return the modified parse tree to transcode.")
1658 (defvar org-export-filter-final-output-functions nil
1659 "Filter, or list of filters, applied to the transcoded string.
1660 Each filter is called with three arguments: the full transcoded
1661 string, the back-end, as a symbol, and the communication channel,
1662 as a plist. It must return a string that will be used as the
1663 final export output.")
1665 (defvar org-export-filter-plain-text-functions nil
1666 "Filter, or list of filters, applied to plain text.
1667 Each filter is called with three arguments: a string which
1668 contains no Org syntax, the back-end, as a symbol, and the
1669 communication channel, as a plist. It must return a string or
1673 ;;;; Elements Filters
1675 (defvar org-export-filter-center-block-functions nil
1676 "List of functions applied to a transcoded center block.
1677 Each filter is called with three arguments: the transcoded center
1678 block, as a string, the back-end, as a symbol, and the
1679 communication channel, as a plist. It must return a string or
1682 (defvar org-export-filter-drawer-functions nil
1683 "List of functions applied to a transcoded drawer.
1684 Each filter is called with three arguments: the transcoded
1685 drawer, as a string, the back-end, as a symbol, and the
1686 communication channel, as a plist. It must return a string or
1689 (defvar org-export-filter-dynamic-block-functions nil
1690 "List of functions applied to a transcoded dynamic-block.
1691 Each filter is called with three arguments: the transcoded
1692 dynamic-block, as a string, the back-end, as a symbol, and the
1693 communication channel, as a plist. It must return a string or
1696 (defvar org-export-filter-headline-functions nil
1697 "List of functions applied to a transcoded headline.
1698 Each filter is called with three arguments: the transcoded
1699 headline, as a string, the back-end, as a symbol, and the
1700 communication channel, as a plist. It must return a string or
1703 (defvar org-export-filter-inlinetask-functions nil
1704 "List of functions applied to a transcoded inlinetask.
1705 Each filter is called with three arguments: the transcoded
1706 inlinetask, as a string, the back-end, as a symbol, and the
1707 communication channel, as a plist. It must return a string or
1710 (defvar org-export-filter-plain-list-functions nil
1711 "List of functions applied to a transcoded plain-list.
1712 Each filter is called with three arguments: the transcoded
1713 plain-list, as a string, the back-end, as a symbol, and the
1714 communication channel, as a plist. It must return a string or
1717 (defvar org-export-filter-item-functions nil
1718 "List of functions applied to a transcoded item.
1719 Each filter is called with three arguments: the transcoded item,
1720 as a string, the back-end, as a symbol, and the communication
1721 channel, as a plist. It must return a string or nil.")
1723 (defvar org-export-filter-comment-functions nil
1724 "List of functions applied to a transcoded comment.
1725 Each filter is called with three arguments: the transcoded
1726 comment, as a string, the back-end, as a symbol, and the
1727 communication channel, as a plist. It must return a string or
1730 (defvar org-export-filter-comment-block-functions nil
1731 "List of functions applied to a transcoded comment-comment.
1732 Each filter is called with three arguments: the transcoded
1733 comment-block, as a string, the back-end, as a symbol, and the
1734 communication channel, as a plist. It must return a string or
1737 (defvar org-export-filter-example-block-functions nil
1738 "List of functions applied to a transcoded example-block.
1739 Each filter is called with three arguments: the transcoded
1740 example-block, as a string, the back-end, as a symbol, and the
1741 communication channel, as a plist. It must return a string or
1744 (defvar org-export-filter-export-block-functions nil
1745 "List of functions applied to a transcoded export-block.
1746 Each filter is called with three arguments: the transcoded
1747 export-block, as a string, the back-end, as a symbol, and the
1748 communication channel, as a plist. It must return a string or
1751 (defvar org-export-filter-fixed-width-functions nil
1752 "List of functions applied to a transcoded fixed-width.
1753 Each filter is called with three arguments: the transcoded
1754 fixed-width, as a string, the back-end, as a symbol, and the
1755 communication channel, as a plist. It must return a string or
1758 (defvar org-export-filter-footnote-definition-functions nil
1759 "List of functions applied to a transcoded footnote-definition.
1760 Each filter is called with three arguments: the transcoded
1761 footnote-definition, as a string, the back-end, as a symbol, and
1762 the communication channel, as a plist. It must return a string
1765 (defvar org-export-filter-horizontal-rule-functions nil
1766 "List of functions applied to a transcoded horizontal-rule.
1767 Each filter is called with three arguments: the transcoded
1768 horizontal-rule, as a string, the back-end, as a symbol, and the
1769 communication channel, as a plist. It must return a string or
1772 (defvar org-export-filter-keyword-functions nil
1773 "List of functions applied to a transcoded keyword.
1774 Each filter is called with three arguments: the transcoded
1775 keyword, as a string, the back-end, as a symbol, and the
1776 communication channel, as a plist. It must return a string or
1779 (defvar org-export-filter-latex-environment-functions nil
1780 "List of functions applied to a transcoded latex-environment.
1781 Each filter is called with three arguments: the transcoded
1782 latex-environment, as a string, the back-end, as a symbol, and
1783 the communication channel, as a plist. It must return a string
1786 (defvar org-export-filter-babel-call-functions nil
1787 "List of functions applied to a transcoded babel-call.
1788 Each filter is called with three arguments: the transcoded
1789 babel-call, as a string, the back-end, as a symbol, and the
1790 communication channel, as a plist. It must return a string or
1793 (defvar org-export-filter-paragraph-functions nil
1794 "List of functions applied to a transcoded paragraph.
1795 Each filter is called with three arguments: the transcoded
1796 paragraph, as a string, the back-end, as a symbol, and the
1797 communication channel, as a plist. It must return a string or
1800 (defvar org-export-filter-property-drawer-functions nil
1801 "List of functions applied to a transcoded property-drawer.
1802 Each filter is called with three arguments: the transcoded
1803 property-drawer, as a string, the back-end, as a symbol, and the
1804 communication channel, as a plist. It must return a string or
1807 (defvar org-export-filter-quote-block-functions nil
1808 "List of functions applied to a transcoded quote block.
1809 Each filter is called with three arguments: the transcoded quote
1810 block, as a string, the back-end, as a symbol, and the
1811 communication channel, as a plist. It must return a string or
1814 (defvar org-export-filter-quote-section-functions nil
1815 "List of functions applied to a transcoded quote-section.
1816 Each filter is called with three arguments: the transcoded
1817 quote-section, as a string, the back-end, as a symbol, and the
1818 communication channel, as a plist. It must return a string or
1821 (defvar org-export-filter-section-functions nil
1822 "List of functions applied to a transcoded section.
1823 Each filter is called with three arguments: the transcoded
1824 section, as a string, the back-end, as a symbol, and the
1825 communication channel, as a plist. It must return a string or
1828 (defvar org-export-filter-special-block-functions nil
1829 "List of functions applied to a transcoded special block.
1830 Each filter is called with three arguments: the transcoded
1831 special block, as a string, the back-end, as a symbol, and the
1832 communication channel, as a plist. It must return a string or
1835 (defvar org-export-filter-src-block-functions nil
1836 "List of functions applied to a transcoded src-block.
1837 Each filter is called with three arguments: the transcoded
1838 src-block, as a string, the back-end, as a symbol, and the
1839 communication channel, as a plist. It must return a string or
1842 (defvar org-export-filter-table-functions nil
1843 "List of functions applied to a transcoded table.
1844 Each filter is called with three arguments: the transcoded table,
1845 as a string, the back-end, as a symbol, and the communication
1846 channel, as a plist. It must return a string or nil.")
1848 (defvar org-export-filter-verse-block-functions nil
1849 "List of functions applied to a transcoded verse block.
1850 Each filter is called with three arguments: the transcoded verse
1851 block, as a string, the back-end, as a symbol, and the
1852 communication channel, as a plist. It must return a string or
1856 ;;;; Objects Filters
1858 (defvar org-export-filter-emphasis-functions nil
1859 "List of functions applied to a transcoded emphasis.
1860 Each filter is called with three arguments: the transcoded
1861 emphasis, as a string, the back-end, as a symbol, and the
1862 communication channel, as a plist. It must return a string or
1865 (defvar org-export-filter-entity-functions nil
1866 "List of functions applied to a transcoded entity.
1867 Each filter is called with three arguments: the transcoded
1868 entity, as a string, the back-end, as a symbol, and the
1869 communication channel, as a plist. It must return a string or
1872 (defvar org-export-filter-export-snippet-functions nil
1873 "List of functions applied to a transcoded export-snippet.
1874 Each filter is called with three arguments: the transcoded
1875 export-snippet, as a string, the back-end, as a symbol, and the
1876 communication channel, as a plist. It must return a string or
1879 (defvar org-export-filter-footnote-reference-functions nil
1880 "List of functions applied to a transcoded footnote-reference.
1881 Each filter is called with three arguments: the transcoded
1882 footnote-reference, as a string, the back-end, as a symbol, and
1883 the communication channel, as a plist. It must return a string
1886 (defvar org-export-filter-inline-babel-call-functions nil
1887 "List of functions applied to a transcoded inline-babel-call.
1888 Each filter is called with three arguments: the transcoded
1889 inline-babel-call, as a string, the back-end, as a symbol, and
1890 the communication channel, as a plist. It must return a string
1893 (defvar org-export-filter-inline-src-block-functions nil
1894 "List of functions applied to a transcoded inline-src-block.
1895 Each filter is called with three arguments: the transcoded
1896 inline-src-block, as a string, the back-end, as a symbol, and the
1897 communication channel, as a plist. It must return a string or
1900 (defvar org-export-filter-latex-fragment-functions nil
1901 "List of functions applied to a transcoded latex-fragment.
1902 Each filter is called with three arguments: the transcoded
1903 latex-fragment, as a string, the back-end, as a symbol, and the
1904 communication channel, as a plist. It must return a string or
1907 (defvar org-export-filter-line-break-functions nil
1908 "List of functions applied to a transcoded line-break.
1909 Each filter is called with three arguments: the transcoded
1910 line-break, as a string, the back-end, as a symbol, and the
1911 communication channel, as a plist. It must return a string or
1914 (defvar org-export-filter-link-functions nil
1915 "List of functions applied to a transcoded link.
1916 Each filter is called with three arguments: the transcoded link,
1917 as a string, the back-end, as a symbol, and the communication
1918 channel, as a plist. It must return a string or nil.")
1920 (defvar org-export-filter-macro-functions nil
1921 "List of functions applied to a transcoded macro.
1922 Each filter is called with three arguments: the transcoded macro,
1923 as a string, the back-end, as a symbol, and the communication
1924 channel, as a plist. It must return a string or nil.")
1926 (defvar org-export-filter-radio-target-functions nil
1927 "List of functions applied to a transcoded radio-target.
1928 Each filter is called with three arguments: the transcoded
1929 radio-target, as a string, the back-end, as a symbol, and the
1930 communication channel, as a plist. It must return a string or
1933 (defvar org-export-filter-statistics-cookie-functions nil
1934 "List of functions applied to a transcoded statistics-cookie.
1935 Each filter is called with three arguments: the transcoded
1936 statistics-cookie, as a string, the back-end, as a symbol, and
1937 the communication channel, as a plist. It must return a string
1940 (defvar org-export-filter-subscript-functions nil
1941 "List of functions applied to a transcoded subscript.
1942 Each filter is called with three arguments: the transcoded
1943 subscript, as a string, the back-end, as a symbol, and the
1944 communication channel, as a plist. It must return a string or
1947 (defvar org-export-filter-superscript-functions nil
1948 "List of functions applied to a transcoded superscript.
1949 Each filter is called with three arguments: the transcoded
1950 superscript, as a string, the back-end, as a symbol, and the
1951 communication channel, as a plist. It must return a string or
1954 (defvar org-export-filter-target-functions nil
1955 "List of functions applied to a transcoded target.
1956 Each filter is called with three arguments: the transcoded
1957 target, as a string, the back-end, as a symbol, and the
1958 communication channel, as a plist. It must return a string or
1961 (defvar org-export-filter-time-stamp-functions nil
1962 "List of functions applied to a transcoded time-stamp.
1963 Each filter is called with three arguments: the transcoded
1964 time-stamp, as a string, the back-end, as a symbol, and the
1965 communication channel, as a plist. It must return a string or
1968 (defvar org-export-filter-verbatim-functions nil
1969 "List of functions applied to a transcoded verbatim.
1970 Each filter is called with three arguments: the transcoded
1971 verbatim, as a string, the back-end, as a symbol, and the
1972 communication channel, as a plist. It must return a string or
1975 (defun org-export-filter-apply-functions (filters value backend info
)
1976 "Call every function in FILTERS with arguments VALUE, BACKEND and INFO.
1977 Functions are called in a LIFO fashion, to be sure that developer
1978 specified filters, if any, are called first."
1979 (loop for filter in filters
1980 if
(not value
) return nil else
1981 do
(setq value
(funcall filter value backend info
)))
1984 (defun org-export-install-filters (backend info
)
1985 "Install filters properties in communication channel.
1987 BACKEND is a symbol specifying which back-end specific filters to
1988 install, if any. INFO is a plist containing the current
1989 communication channel.
1991 Return the updated communication channel."
1993 ;; Install user defined filters with `org-export-filters-alist'.
1995 (setq plist
(plist-put plist
(car p
) (eval (cdr p
)))))
1996 org-export-filters-alist
)
1997 ;; Prepend back-end specific filters to that list.
1998 (let ((back-end-filters (intern (format "org-%s-filters-alist" backend
))))
1999 (when (boundp back-end-filters
)
2001 ;; Single values get consed, lists are prepended.
2002 (let ((key (car p
)) (value (cdr p
)))
2007 (if (atom value
) (cons value
(plist-get plist key
))
2008 (append value
(plist-get plist key
))))))))
2009 (eval back-end-filters
))))
2010 ;; Return new communication channel.
2011 (org-combine-plists info plist
)))
2017 ;; This is the room for the main function, `org-export-as', along with
2018 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
2019 ;; They differ only by the way they output the resulting code.
2021 ;; `org-export-output-file-name' is an auxiliary function meant to be
2022 ;; used with `org-export-to-file'. With a given extension, it tries
2023 ;; to provide a canonical file name to write export output to.
2025 ;; Note that `org-export-as' doesn't really parse the current buffer,
2026 ;; but a copy of it (with the same buffer-local variables and
2027 ;; visibility), where include keywords are expanded and Babel blocks
2028 ;; are executed, if appropriate.
2029 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
2031 ;; File inclusion is taken care of by
2032 ;; `org-export-expand-include-keyword' and
2033 ;; `org-export-prepare-file-contents'. Structure wise, including
2034 ;; a whole Org file in a buffer often makes little sense. For
2035 ;; example, if the file contains an headline and the include keyword
2036 ;; was within an item, the item should contain the headline. That's
2037 ;; why file inclusion should be done before any structure can be
2038 ;; associated to the file, that is before parsing.
2040 (defun org-export-as
2041 (backend &optional subtreep visible-only body-only ext-plist noexpand
)
2042 "Transcode current Org buffer into BACKEND code.
2044 If narrowing is active in the current buffer, only transcode its
2047 If a region is active, transcode that region.
2049 When optional argument SUBTREEP is non-nil, transcode the
2050 sub-tree at point, extracting information from the headline
2053 When optional argument VISIBLE-ONLY is non-nil, don't export
2054 contents of hidden elements.
2056 When optional argument BODY-ONLY is non-nil, only return body
2057 code, without preamble nor postamble.
2059 Optional argument EXT-PLIST, when provided, is a property list
2060 with external parameters overriding Org default settings, but
2061 still inferior to file-local settings.
2063 Optional argument NOEXPAND, when non-nil, prevents included files
2064 to be expanded and Babel code to be executed.
2066 Return code as a string."
2069 ;; Narrow buffer to an appropriate region for parsing.
2070 (when (org-region-active-p)
2071 (narrow-to-region (region-beginning) (region-end)))
2072 (when (and subtreep
(not (org-at-heading-p)))
2073 ;; Ensure point is at sub-tree's beginning.
2074 (org-narrow-to-subtree))
2075 ;; Retrieve export options (INFO) and parsed tree (RAW-DATA),
2076 ;; Then options can be completed with tree properties. Note:
2077 ;; Buffer isn't parsed directly. Instead, a temporary copy is
2078 ;; created, where include keywords are expanded and code blocks
2079 ;; are evaluated. RAW-DATA is the parsed tree of the buffer
2080 ;; resulting from that process. Eventually call
2081 ;; `org-export-filter-parse-tree-functions'.
2082 (goto-char (point-min))
2083 (let ((info (org-export-get-environment backend subtreep ext-plist
)))
2084 ;; Remove subtree's headline from contents if subtree mode is
2086 (when subtreep
(forward-line) (narrow-to-region (point) (point-max)))
2087 ;; Install filters in communication channel.
2088 (setq info
(org-export-install-filters backend info
))
2090 (org-export-filter-apply-functions
2091 (plist-get info
:filter-parse-tree
)
2092 ;; If NOEXPAND is non-nil, simply parse current
2093 ;; visible part of buffer.
2094 (if noexpand
(org-element-parse-buffer nil visible-only
)
2095 (org-export-with-current-buffer-copy
2096 (org-export-expand-include-keyword nil
)
2097 (let ((org-current-export-file (current-buffer)))
2098 (org-export-blocks-preprocess))
2099 (org-element-parse-buffer nil visible-only
)))
2101 ;; Complete communication channel with tree properties.
2105 (org-export-collect-tree-properties raw-data info backend
)))
2106 ;; Transcode RAW-DATA. Also call
2107 ;; `org-export-filter-final-output-functions'.
2108 (let* ((body (org-element-normalize-string
2109 (org-export-data raw-data backend info
)))
2110 (template (intern (format "org-%s-template" backend
)))
2111 (output (org-export-filter-apply-functions
2112 (plist-get info
:filter-final-output
)
2113 (if (or (not (fboundp template
)) body-only
) body
2114 (funcall template body info
))
2116 ;; Maybe add final OUTPUT to kill ring before returning it.
2117 (when org-export-copy-to-kill-ring
(org-kill-new output
))
2120 (defun org-export-to-buffer
2121 (backend buffer
&optional subtreep visible-only body-only ext-plist noexpand
)
2122 "Call `org-export-as' with output to a specified buffer.
2124 BACKEND is the back-end used for transcoding, as a symbol.
2126 BUFFER is the output buffer. If it already exists, it will be
2127 erased first, otherwise, it will be created.
2129 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2130 and NOEXPAND are similar to those used in `org-export-as', which
2134 (let ((out (org-export-as
2135 backend subtreep visible-only body-only ext-plist noexpand
))
2136 (buffer (get-buffer-create buffer
)))
2137 (with-current-buffer buffer
2140 (goto-char (point-min)))
2143 (defun org-export-to-file
2144 (backend file
&optional subtreep visible-only body-only ext-plist noexpand
)
2145 "Call `org-export-as' with output to a specified file.
2147 BACKEND is the back-end used for transcoding, as a symbol. FILE
2148 is the name of the output file, as a string.
2150 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2151 and NOEXPAND are similar to those used in `org-export-as', which
2154 Return output file's name."
2155 ;; Checks for FILE permissions. `write-file' would do the same, but
2156 ;; we'd rather avoid needless transcoding of parse tree.
2157 (unless (file-writable-p file
) (error "Output file not writable"))
2158 ;; Insert contents to a temporary buffer and write it to FILE.
2159 (let ((out (org-export-as
2160 backend subtreep visible-only body-only ext-plist noexpand
)))
2163 (let ((coding-system-for-write org-export-coding-system
))
2164 (write-file file
))))
2165 ;; Return full path.
2168 (defun org-export-output-file-name (extension &optional subtreep pub-dir
)
2169 "Return output file's name according to buffer specifications.
2171 EXTENSION is a string representing the output file extension,
2172 with the leading dot.
2174 With a non-nil optional argument SUBTREEP, try to determine
2175 output file's name by looking for \"EXPORT_FILE_NAME\" property
2176 of subtree at point.
2178 When optional argument PUB-DIR is set, use it as the publishing
2181 Return file name as a string, or nil if it couldn't be
2184 ;; File name may come from EXPORT_FILE_NAME subtree property,
2185 ;; assuming point is at beginning of said sub-tree.
2186 (file-name-sans-extension
2191 (org-back-to-heading (not visible-only
)) (point)))
2192 "EXPORT_FILE_NAME" t
))
2193 ;; File name may be extracted from buffer's associated
2195 (buffer-file-name (buffer-base-buffer))
2196 ;; Can't determine file name on our own: Ask user.
2197 (let ((read-file-name-function
2198 (and org-completion-use-ido
'ido-read-file-name
)))
2200 "Output file: " pub-dir nil nil nil
2202 (string= (file-name-extension name t
) extension
))))))))
2203 ;; Build file name. Enforce EXTENSION over whatever user may have
2204 ;; come up with. PUB-DIR, if defined, always has precedence over
2205 ;; any provided path.
2208 (concat (file-name-as-directory pub-dir
)
2209 (file-name-nondirectory base-name
)
2211 ((string= (file-name-nondirectory base-name
) base-name
)
2212 (concat (file-name-as-directory ".") base-name extension
))
2213 (t (concat base-name extension
)))))
2215 (defmacro org-export-with-current-buffer-copy
(&rest body
)
2216 "Apply BODY in a copy of the current buffer.
2218 The copy preserves local variables and visibility of the original
2221 Point is at buffer's beginning when BODY is applied."
2222 (org-with-gensyms (original-buffer offset buffer-string overlays
)
2223 `(let ((,original-buffer
,(current-buffer))
2224 (,offset
,(1- (point-min)))
2225 (,buffer-string
,(buffer-string))
2227 'copy-overlay
(overlays-in (point-min) (point-max)))))
2229 (let ((buffer-invisibility-spec nil
))
2230 (org-clone-local-variables
2232 "^\\(org-\\|orgtbl-\\|major-mode$\\|outline-\\(regexp\\|level\\)$\\)")
2233 (insert ,buffer-string
)
2237 (- (overlay-start ov
) ,offset
)
2238 (- (overlay-end ov
) ,offset
)
2241 (goto-char (point-min))
2243 (def-edebug-spec org-export-with-current-buffer-copy
(body))
2245 (defun org-export-expand-include-keyword (included)
2246 "Expand every include keyword in buffer.
2247 INCLUDED is a list of included file names along with their line
2248 restriction, when appropriate. It is used to avoid infinite
2250 (let ((case-fold-search nil
))
2251 (goto-char (point-min))
2252 (while (re-search-forward "^[ \t]*#\\+include: \\(.*\\)" nil t
)
2253 (when (eq (org-element-type (save-match-data (org-element-at-point)))
2256 ;; Extract arguments from keyword's value.
2257 (let* ((value (match-string 1))
2258 (ind (org-get-indentation))
2259 (file (and (string-match "^\"\\(\\S-+\\)\"" value
)
2260 (prog1 (expand-file-name (match-string 1 value
))
2261 (setq value
(replace-match "" nil nil value
)))))
2264 ":lines +\"\\(\\(?:[0-9]+\\)?-\\(?:[0-9]+\\)?\\)\"" value
)
2265 (prog1 (match-string 1 value
)
2266 (setq value
(replace-match "" nil nil value
)))))
2267 (env (cond ((string-match "\\<example\\>" value
) 'example
)
2268 ((string-match "\\<src\\(?: +\\(.*\\)\\)?" value
)
2269 (match-string 1 value
))))
2270 ;; Minimal level of included file defaults to the child
2271 ;; level of the current headline, if any, or one. It
2272 ;; only applies is the file is meant to be included as
2276 (if (string-match ":minlevel +\\([0-9]+\\)" value
)
2277 (prog1 (string-to-number (match-string 1 value
))
2278 (setq value
(replace-match "" nil nil value
)))
2279 (let ((cur (org-current-level)))
2280 (if cur
(1+ (org-reduced-level cur
)) 1))))))
2282 (delete-region (point) (progn (forward-line) (point)))
2284 ((not (file-readable-p file
)) (error "Cannot include file %s" file
))
2285 ;; Check if files has already been parsed. Look after
2286 ;; inclusion lines too, as different parts of the same file
2287 ;; can be included too.
2288 ((member (list file lines
) included
)
2289 (error "Recursive file inclusion: %s" file
))
2294 (let ((ind-str (make-string ind ?
))
2296 ;; Protect sensitive contents with commas.
2297 (replace-regexp-in-string
2298 "\\(^\\)\\([*]\\|[ \t]*#\\+\\)" ","
2299 (org-export-prepare-file-contents file lines
)
2301 (format "%s#+begin_example\n%s%s#+end_example\n"
2302 ind-str contents ind-str
))))
2305 (let ((ind-str (make-string ind ?
))
2307 ;; Protect sensitive contents with commas.
2308 (replace-regexp-in-string
2309 (if (string= env
"org") "\\(^\\)\\(.\\)"
2310 "\\(^\\)\\([*]\\|[ \t]*#\\+\\)") ","
2311 (org-export-prepare-file-contents file lines
)
2313 (format "%s#+begin_src %s\n%s%s#+end_src\n"
2314 ind-str env contents ind-str
))))
2320 (org-export-prepare-file-contents file lines ind minlevel
))
2321 (org-export-expand-include-keyword
2322 (cons (list file lines
) included
))
2323 (buffer-string))))))))))))
2325 (defun org-export-prepare-file-contents (file &optional lines ind minlevel
)
2326 "Prepare the contents of FILE for inclusion and return them as a string.
2328 When optional argument LINES is a string specifying a range of
2329 lines, include only those lines.
2331 Optional argument IND, when non-nil, is an integer specifying the
2332 global indentation of returned contents. Since its purpose is to
2333 allow an included file to stay in the same environment it was
2334 created \(i.e. a list item), it doesn't apply past the first
2335 headline encountered.
2337 Optional argument MINLEVEL, when non-nil, is an integer
2338 specifying the level that any top-level headline in the included
2341 (insert-file-contents file
)
2343 (let* ((lines (split-string lines
"-"))
2344 (lbeg (string-to-number (car lines
)))
2345 (lend (string-to-number (cadr lines
)))
2346 (beg (if (zerop lbeg
) (point-min)
2347 (goto-char (point-min))
2348 (forward-line (1- lbeg
))
2350 (end (if (zerop lend
) (point-max)
2351 (goto-char (point-min))
2352 (forward-line (1- lend
))
2354 (narrow-to-region beg end
)))
2355 ;; Remove blank lines at beginning and end of contents. The logic
2356 ;; behind that removal is that blank lines around include keyword
2357 ;; override blank lines in included file.
2358 (goto-char (point-min))
2359 (org-skip-whitespace)
2361 (delete-region (point-min) (point))
2362 (goto-char (point-max))
2363 (skip-chars-backward " \r\t\n")
2365 (delete-region (point) (point-max))
2366 ;; If IND is set, preserve indentation of include keyword until
2367 ;; the first headline encountered.
2369 (unless (eq major-mode
'org-mode
) (org-mode))
2370 (goto-char (point-min))
2371 (let ((ind-str (make-string ind ?
)))
2372 (while (not (or (eobp) (looking-at org-outline-regexp-bol
)))
2373 ;; Do not move footnote definitions out of column 0.
2374 (unless (and (looking-at org-footnote-definition-re
)
2375 (eq (org-element-type (org-element-at-point))
2376 'footnote-definition
))
2379 ;; When MINLEVEL is specified, compute minimal level for headlines
2380 ;; in the file (CUR-MIN), and remove stars to each headline so
2381 ;; that headlines with minimal level have a level of MINLEVEL.
2383 (unless (eq major-mode
'org-mode
) (org-mode))
2384 (let ((levels (org-map-entries
2385 (lambda () (org-reduced-level (org-current-level))))))
2387 (let ((offset (- minlevel
(apply 'min levels
))))
2388 (unless (zerop offset
)
2389 (when org-odd-levels-only
(setq offset
(* offset
2)))
2390 ;; Only change stars, don't bother moving whole
2393 (lambda () (if (< offset
0) (delete-char (abs offset
))
2394 (insert (make-string offset ?
*))))))))))
2398 ;;; Tools For Back-Ends
2400 ;; A whole set of tools is available to help build new exporters. Any
2401 ;; function general enough to have its use across many back-ends
2402 ;; should be added here.
2404 ;; As of now, functions operating on footnotes, headlines, links,
2405 ;; macros, references, src-blocks, tables and tables of contents are
2410 ;; `org-export-collect-footnote-definitions' is a tool to list
2411 ;; actually used footnotes definitions in the whole parse tree, or in
2412 ;; an headline, in order to add footnote listings throughout the
2415 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2416 ;; back-ends, when they need to attach the footnote definition only to
2417 ;; the first occurrence of the corresponding label.
2419 ;; `org-export-get-footnote-definition' and
2420 ;; `org-export-get-footnote-number' provide easier access to
2421 ;; additional information relative to a footnote reference.
2423 (defun org-export-collect-footnote-definitions (data info
)
2424 "Return an alist between footnote numbers, labels and definitions.
2426 DATA is the parse tree from which definitions are collected.
2427 INFO is the plist used as a communication channel.
2429 Definitions are sorted by order of references. They either
2430 appear as Org data \(transcoded with `org-export-data'\) or as
2431 a secondary string for inlined footnotes \(transcoded with
2432 `org-export-secondary-string'\). Unreferenced definitions are
2435 ;; Collect seen references in REFS.
2437 data
'footnote-reference
2438 (lambda (footnote local
)
2439 (when (org-export-footnote-first-reference-p footnote local
)
2440 (list (org-export-get-footnote-number footnote local
)
2441 (org-element-property :label footnote
)
2442 (org-export-get-footnote-definition footnote local
))))
2445 (defun org-export-footnote-first-reference-p (footnote-reference info
)
2446 "Non-nil when a footnote reference is the first one for its label.
2448 FOOTNOTE-REFERENCE is the footnote reference being considered.
2449 INFO is the plist used as a communication channel."
2450 (let ((label (org-element-property :label footnote-reference
)))
2455 (plist-get info
:parse-tree
) 'footnote-reference
2456 (lambda (footnote local
)
2457 (when (string= (org-element-property :label footnote
) label
)
2459 info
'first-match
)))))
2461 (defun org-export-get-footnote-definition (footnote-reference info
)
2462 "Return definition of FOOTNOTE-REFERENCE as parsed data.
2463 INFO is the plist used as a communication channel."
2464 (let ((label (org-element-property :label footnote-reference
)))
2465 (or (org-element-property :inline-definition footnote-reference
)
2466 (cdr (assoc label
(plist-get info
:footnote-definition-alist
))))))
2468 (defun org-export-get-footnote-number (footnote info
)
2469 "Return number associated to a footnote.
2471 FOOTNOTE is either a footnote reference or a footnote definition.
2472 INFO is the plist used as a communication channel."
2473 (let ((label (org-element-property :label footnote
)) seen-refs
)
2475 (plist-get info
:parse-tree
) 'footnote-reference
2477 (let ((fn-lbl (org-element-property :label fn
)))
2479 ((and (not fn-lbl
) (equal fn footnote
)) (1+ (length seen-refs
)))
2480 ((and label
(string= label fn-lbl
)) (1+ (length seen-refs
)))
2481 ;; Anonymous footnote: it's always a new one. Also, be sure
2482 ;; to return nil from the `cond' so `first-match' doesn't
2483 ;; get us out of the loop.
2484 ((not fn-lbl
) (push 'inline seen-refs
) nil
)
2485 ;; Label not seen so far: add it so SEEN-REFS. Again,
2486 ;; return nil to stay in the loop.
2487 ((not (member fn-lbl seen-refs
)) (push fn-lbl seen-refs
) nil
))))
2488 info
'first-match
)))
2493 ;; `org-export-get-relative-level' is a shortcut to get headline
2494 ;; level, relatively to the lower headline level in the parsed tree.
2496 ;; `org-export-get-headline-number' returns the section number of an
2497 ;; headline, while `org-export-number-to-roman' allows to convert it
2498 ;; to roman numbers.
2500 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
2501 ;; `org-export-last-sibling-p' are three useful predicates when it
2502 ;; comes to fulfill the `:headline-levels' property.
2504 (defun org-export-get-relative-level (headline info
)
2505 "Return HEADLINE relative level within current parsed tree.
2506 INFO is a plist holding contextual information."
2507 (+ (org-element-property :level headline
)
2508 (or (plist-get info
:headline-offset
) 0)))
2510 (defun org-export-low-level-p (headline info
)
2511 "Non-nil when HEADLINE is considered as low level.
2513 INFO is a plist used as a communication channel.
2515 A low level headlines has a relative level greater than
2516 `:headline-levels' property value.
2518 Return value is the difference between HEADLINE relative level
2519 and the last level being considered as high enough, or nil."
2520 (let ((limit (plist-get info
:headline-levels
)))
2521 (when (wholenump limit
)
2522 (let ((level (org-export-get-relative-level headline info
)))
2523 (and (> level limit
) (- level limit
))))))
2525 (defun org-export-get-headline-number (headline info
)
2526 "Return HEADLINE numbering as a list of numbers.
2527 INFO is a plist holding contextual information."
2528 (cdr (assoc headline
(plist-get info
:headline-numbering
))))
2530 (defun org-export-number-to-roman (n)
2531 "Convert integer N into a roman numeral."
2532 (let ((roman '((1000 .
"M") (900 .
"CM") (500 .
"D") (400 .
"CD")
2533 ( 100 .
"C") ( 90 .
"XC") ( 50 .
"L") ( 40 .
"XL")
2534 ( 10 .
"X") ( 9 .
"IX") ( 5 .
"V") ( 4 .
"IV")
2538 (number-to-string n
)
2540 (if (>= n
(caar roman
))
2541 (setq n
(- n
(caar roman
))
2542 res
(concat res
(cdar roman
)))
2546 (defun org-export-first-sibling-p (headline info
)
2547 "Non-nil when HEADLINE is the first sibling in its sub-tree.
2548 INFO is the plist used as a communication channel."
2549 (not (eq (org-element-type (org-export-get-previous-element headline info
))
2552 (defun org-export-last-sibling-p (headline info
)
2553 "Non-nil when HEADLINE is the last sibling in its sub-tree.
2554 INFO is the plist used as a communication channel."
2555 (not (org-export-get-next-element headline info
)))
2560 ;; `org-export-solidify-link-text' turns a string into a safer version
2561 ;; for links, replacing most non-standard characters with hyphens.
2563 ;; `org-export-get-coderef-format' returns an appropriate format
2564 ;; string for coderefs.
2566 ;; `org-export-inline-image-p' returns a non-nil value when the link
2567 ;; provided should be considered as an inline image.
2569 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
2570 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
2571 ;; returns an appropriate unique identifier when found, or nil.
2573 ;; `org-export-resolve-id-link' returns the first headline with
2574 ;; specified id or custom-id in parse tree, or nil when none was
2577 ;; `org-export-resolve-coderef' associates a reference to a line
2578 ;; number in the element it belongs, or returns the reference itself
2579 ;; when the element isn't numbered.
2581 (defun org-export-solidify-link-text (s)
2582 "Take link text S and make a safe target out of it."
2584 (mapconcat 'identity
(org-split-string s
"[^a-zA-Z0-9_.-]+") "-")))
2586 (defun org-export-get-coderef-format (path desc
)
2587 "Return format string for code reference link.
2588 PATH is the link path. DESC is its description."
2590 (cond ((string-match (regexp-quote (concat "(" path
")")) desc
)
2591 (replace-match "%s" t t desc
))
2592 ((string= desc
"") "%s")
2595 (defun org-export-inline-image-p (link &optional rules
)
2596 "Non-nil if LINK object points to an inline image.
2598 Optional argument is a set of RULES defining inline images. It
2599 is an alist where associations have the following shape:
2603 Applying a rule means apply REGEXP against LINK's path when its
2604 type is TYPE. The function will return a non-nil value if any of
2605 the provided rules is non-nil. The default rule is
2606 `org-export-default-inline-image-rule'.
2608 This only applies to links without a description."
2609 (and (not (org-element-contents link
))
2610 (let ((case-fold-search t
)
2611 (rules (or rules org-export-default-inline-image-rule
)))
2614 (and (string= (org-element-property :type link
) (car rule
))
2615 (string-match (cdr rule
)
2616 (org-element-property :path link
))))
2619 (defun org-export-resolve-fuzzy-link (link info
)
2620 "Return LINK destination.
2622 INFO is a plist holding contextual information.
2624 Return value can be an object, an element, or nil:
2626 - If LINK path exactly matches any target, return the target
2629 - If LINK path exactly matches any headline name, return that
2630 element. If more than one headline share that name, priority
2631 will be given to the one with the closest common ancestor, if
2632 any, or the first one in the parse tree otherwise.
2634 - Otherwise, return nil.
2636 Assume LINK type is \"fuzzy\"."
2637 (let ((path (org-element-property :path link
)))
2638 ;; Link points to a target: return it.
2639 (or (loop for target in
(plist-get info
:target-list
)
2640 when
(string= (org-element-property :raw-value target
) path
)
2642 ;; Link either points to an headline or nothing. Try to find
2643 ;; the source, with priority given to headlines with the closest
2644 ;; common ancestor. If such candidate is found, return its
2645 ;; beginning position as an unique identifier, otherwise return
2647 (let ((find-headline
2649 ;; Return first headline whose `:raw-value' property
2650 ;; is NAME in parse tree DATA, or nil.
2654 (lambda (headline local
)
2656 (org-element-property :raw-value headline
)
2659 info
'first-match
)))))
2660 ;; Search among headlines sharing an ancestor with link,
2661 ;; from closest to farthest.
2665 (when (eq (org-element-type parent
) 'headline
)
2666 (let ((foundp (funcall find-headline path parent
)))
2667 (when foundp
(throw 'exit foundp
)))))
2668 (org-export-get-genealogy link info
)) nil
)
2669 ;; No match with a common ancestor: try the full parse-tree.
2670 (funcall find-headline path
(plist-get info
:parse-tree
)))))))
2672 (defun org-export-resolve-id-link (link info
)
2673 "Return headline referenced as LINK destination.
2675 INFO is a plist used as a communication channel.
2677 Return value can be an headline element or nil. Assume LINK type
2678 is either \"id\" or \"custom-id\"."
2679 (let ((id (org-element-property :path link
)))
2681 (plist-get info
:parse-tree
) 'headline
2682 (lambda (headline local
)
2683 (when (or (string= (org-element-property :id headline
) id
)
2684 (string= (org-element-property :custom-id headline
) id
))
2686 info
'first-match
)))
2688 (defun org-export-resolve-ref-link (link info
)
2689 "Return element referenced as LINK destination.
2691 INFO is a plist used as a communication channel.
2693 Assume LINK type is \"ref\" and. Return value is the first
2694 element whose `:name' property matches LINK's `:path', or nil."
2695 (let ((name (org-element-property :path link
)))
2697 (plist-get info
:parse-tree
) org-element-all-elements
2699 (when (string= (org-element-property :name el
) name
) el
))
2700 info
'first-match
)))
2702 (defun org-export-resolve-coderef (ref info
)
2703 "Resolve a code reference REF.
2705 INFO is a plist used as a communication channel.
2707 Return associated line number in source code, or REF itself,
2708 depending on src-block or example element's switches."
2710 (plist-get info
:parse-tree
) '(src-block example
)
2712 (let ((switches (or (org-element-property :switches el
) "")))
2714 (insert (org-trim (org-element-property :value el
)))
2715 ;; Build reference regexp.
2717 (or (and (string-match "-l +\"\\([^\"\n]+\\)\"" switches
)
2718 (match-string 1 switches
))
2719 org-coderef-label-format
))
2721 (format "^.*?\\S-.*?\\([ \t]*\\(%s\\)\\)[ \t]*$"
2722 (replace-regexp-in-string "%s" ref label nil t
))))
2723 ;; Element containing REF is found. Only associate REF to
2724 ;; a line number if element has "+n" or "-n" and "-k" or
2725 ;; "-r" as switches. When it has "+n", count accumulated
2726 ;; locs before, too.
2727 (when (re-search-backward ref-re nil t
)
2729 ((not (string-match "-[kr]\\>" switches
)) ref
)
2730 ((string-match "-n\\>" switches
) (line-number-at-pos))
2731 ((string-match "\\+n\\>" switches
)
2732 (+ (org-export-get-loc el local
) (line-number-at-pos)))
2739 ;; `org-export-expand-macro' simply takes care of expanding macros.
2741 (defun org-export-expand-macro (macro info
)
2742 "Expand MACRO and return it as a string.
2743 INFO is a plist holding export options."
2744 (let* ((key (org-element-property :key macro
))
2745 (args (org-element-property :args macro
))
2746 ;; User's macros are stored in the communication channel with
2747 ;; a ":macro-" prefix. If it's a string leave it as-is.
2748 ;; Otherwise, it's a secondary string that needs to be
2749 ;; expanded recursively.
2751 (let ((val (plist-get info
(intern (format ":macro-%s" key
)))))
2752 (if (stringp val
) val
2753 (org-export-secondary-string
2754 val
(plist-get info
:back-end
) info
)))))
2755 ;; Replace arguments in VALUE.
2757 (while (string-match "\\$\\([0-9]+\\)" value s
)
2758 (setq s
(1+ (match-beginning 0))
2759 n
(string-to-number (match-string 1 value
)))
2760 (and (>= (length args
) n
)
2761 (setq value
(replace-match (nth (1- n
) args
) t t value
)))))
2762 ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
2763 (when (string-match "\\`(eval\\>" value
)
2764 (setq value
(eval (read value
))))
2766 (format "%s" (or value
""))))
2771 ;; `org-export-get-ordinal' associates a sequence number to any object
2774 (defun org-export-get-ordinal
2775 (element info
&optional types within-section predicate
)
2776 "Return ordinal number of an element or object.
2778 ELEMENT is the element or object considered. INFO is the plist
2779 used as a communication channel.
2781 Optional argument TYPES, when non-nil, is a list of element or
2782 object types, as symbols, that should also be counted in.
2783 Otherwise, only provided element's type is considered.
2785 When optional argument WITHIN-SECTION is non-nil, narrow counting
2786 to the section containing ELEMENT.
2788 Optional argument PREDICATE is a function returning a non-nil
2789 value if the current element or object should be counted in. It
2790 accepts one argument: the element or object being considered.
2791 This argument allows to count only a certain type of objects,
2792 like inline images, which are a subset of links \(in that case,
2793 `org-export-inline-image-p' might be an useful predicate\)."
2795 ;; Determine if search should apply to current section, in
2796 ;; which case it should be retrieved first, or to full parse
2797 ;; tree. As a special case, an element or object without
2798 ;; a parent headline will also trigger a full search,
2799 ;; notwithstanding WITHIN-SECTION value.
2801 (if (not within-section
) (plist-get info
:parse-tree
)
2802 (or (org-export-get-parent-headline element info
)
2803 (plist-get info
:parse-tree
)))))
2804 ;; Increment counter until ELEMENT is found again.
2806 data
(or types
(org-element-type element
))
2809 ((equal element el
) (1+ counter
))
2810 ((not predicate
) (incf counter
) nil
)
2811 ((funcall predicate el
) (incf counter
) nil
)))
2812 info
'first-match
)))
2817 ;; `org-export-get-loc' counts number of code lines accumulated in
2818 ;; src-block or example-block elements with a "+n" switch until
2819 ;; a given element, excluded. Note: "-n" switches reset that count.
2821 ;; `org-export-handle-code' takes care of line numbering and reference
2822 ;; cleaning in source code, when appropriate.
2824 (defun org-export-get-loc (element info
)
2825 "Return accumulated lines of code up to ELEMENT.
2827 INFO is the plist used as a communication channel.
2829 ELEMENT is excluded from count."
2832 (plist-get info
:parse-tree
)
2833 `(src-block example-block
,(org-element-type element
))
2836 ;; ELEMENT is reached: Quit the loop.
2837 ((equal el element
) t
)
2838 ;; Only count lines from src-block and example-block elements
2839 ;; with a "+n" or "-n" switch. A "-n" switch resets counter.
2840 ((not (memq (org-element-type el
) '(src-block example-block
))) nil
)
2841 ((let ((switches (org-element-property :switches el
)))
2842 (when (and switches
(string-match "\\([-+]\\)n\\>" switches
))
2843 ;; Accumulate locs or reset them.
2844 (let ((accumulatep (string= (match-string 1 switches
) "-"))
2845 (lines (org-count-lines
2846 (org-trim (org-element-property :value el
)))))
2847 (setq loc
(if accumulatep lines
(+ loc lines
))))))
2848 ;; Return nil to stay in the loop.
2854 (defun org-export-handle-code (element info
&optional num-fmt ref-fmt delayed
)
2855 "Handle line numbers and code references in ELEMENT.
2857 ELEMENT has either a `src-block' an `example-block' type. INFO
2858 is a plist used as a communication channel.
2860 If optional argument NUM-FMT is a string, it will be used as
2861 a format string for numbers at beginning of each line.
2863 If optional argument REF-FMT is a string, it will be used as
2864 a format string for each line of code containing a reference.
2866 When optional argument DELAYED is non-nil, `org-loc' and
2867 `org-coderef' properties, set to an adequate value, are applied
2868 to, respectively, numbered lines and lines with a reference. No
2869 line numbering is done and all references are stripped from the
2870 resulting string. Both NUM-FMT and REF-FMT arguments are ignored
2873 Return new code as a string."
2874 (let* ((switches (or (org-element-property :switches element
) ""))
2875 (code (org-element-property :value element
))
2876 (numberp (string-match "[-+]n\\>" switches
))
2877 (accumulatep (string-match "\\+n\\>" switches
))
2878 ;; Initialize loc counter when any kind of numbering is
2881 (accumulatep (org-export-get-loc element info
))
2883 ;; Get code and clean it. Remove blank lines at its
2884 ;; beginning and end. Also remove protective commas.
2885 (preserve-indent-p (or org-src-preserve-indentation
2886 (string-match "-i\\>" switches
)))
2887 (replace-labels (when (string-match "-r\\>" switches
)
2888 (if (string-match "-k\\>" switches
) 'keep t
)))
2889 (code (let ((c (replace-regexp-in-string
2890 "\\`\\([ \t]*\n\\)+" ""
2891 (replace-regexp-in-string
2892 "\\(:?[ \t]*\n\\)*[ \t]*\\'" "\n" code
))))
2893 ;; If appropriate, remove global indentation.
2894 (unless preserve-indent-p
(setq c
(org-remove-indentation c
)))
2895 ;; Free up the protected lines. Note: Org blocks
2896 ;; have commas at the beginning or every line.
2898 (or (org-element-property :language element
) "")
2900 (replace-regexp-in-string "^," "" c
)
2901 (replace-regexp-in-string
2902 "^\\(,\\)\\(:?\\*\\|[ \t]*#\\+\\)" "" c nil nil
1))))
2903 ;; Split code to process it line by line.
2904 (code-lines (org-split-string code
"\n"))
2905 ;; If numbering is active, ensure line numbers will be
2906 ;; correctly padded before applying the format string.
2908 (when (and (not delayed
) numberp
)
2909 (format (if (stringp num-fmt
) num-fmt
"%s: ")
2911 (length (number-to-string
2912 (+ (length code-lines
) total-LOC
)))))))
2913 ;; Get format used for references.
2914 (label-fmt (or (and (string-match "-l +\"\\([^\"\n]+\\)\"" switches
)
2915 (match-string 1 switches
))
2916 org-coderef-label-format
))
2917 ;; Build a regexp matching a loc with a reference.
2918 (with-ref-re (format "^.*?\\S-.*?\\([ \t]*\\(%s\\)\\)[ \t]*$"
2919 (replace-regexp-in-string
2920 "%s" "\\([-a-zA-Z0-9_ ]+\\)" label-fmt nil t
))))
2921 (org-element-normalize-string
2924 ;; Maybe add line number to current line of code (LOC).
2927 (setq loc
(if delayed
(org-add-props loc nil
'org-loc total-LOC
)
2928 (concat (format num-fmt total-LOC
) loc
))))
2929 ;; Take action if at a ref line.
2930 (when (string-match with-ref-re loc
)
2931 (let ((ref (match-string 3 loc
)))
2933 ;; Option "-r" without "-k" removes labels.
2934 ;; A non-nil DELAYED removes labels unconditionally.
2936 (and replace-labels
(not (eq replace-labels
'keep
))))
2937 (replace-match "" nil nil loc
1)
2938 (replace-match (format "(%s)" ref
) nil nil loc
2)))
2939 ;; Store REF in `org-coderef' property if DELAYED asks to.
2940 (cond (delayed (setq loc
(org-add-props loc nil
'org-coderef ref
)))
2941 ;; If REF-FMT is defined, apply it to current LOC.
2942 ((stringp ref-fmt
) (setq loc
(format ref-fmt loc
))))))
2943 ;; Return updated LOC for concatenation.
2950 ;; `org-export-table-format-info' extracts formatting information
2951 ;; (alignment, column groups and presence of a special column) from
2952 ;; a raw table and returns it as a property list.
2954 ;; `org-export-clean-table' cleans the raw table from any Org
2955 ;; table-specific syntax.
2957 (defun org-export-table-format-info (table)
2958 "Extract info from TABLE.
2959 Return a plist whose properties and values are:
2960 `:alignment' vector of strings among \"r\", \"l\" and \"c\",
2961 `:column-groups' vector of symbols among `start', `end', `start-end',
2962 `:row-groups' list of integers representing row groups.
2963 `:special-column-p' non-nil if table has a special column.
2964 `:width' vector of integers representing desired width of
2965 current column, or nil."
2970 (let ((align (vconcat (mapcar (lambda (c) (if c
"r" "l"))
2971 org-table-last-alignment
)))
2972 (width (make-vector (length org-table-last-alignment
) nil
))
2973 (colgroups (make-vector (length org-table-last-alignment
) nil
))
2976 (special-column-p 'empty
))
2978 (if (string-match "^[ \t]*|[-+]+|[ \t]*$" row
)
2980 ;; Determine if a special column is present by looking
2981 ;; for special markers in the first column. More
2982 ;; accurately, the first column is considered special
2983 ;; if it only contains special markers and, maybe,
2985 (setq special-column-p
2987 ((not special-column-p
) nil
)
2988 ((string-match "^[ \t]*| *\\\\?\\([/#!$*_^]\\) *|" row
)
2990 ((string-match "^[ \t]*| +|" row
) special-column-p
))))
2992 ;; Read forced alignment and width information, if any,
2993 ;; and determine final alignment for the table.
2994 ((org-table-cookie-line-p row
)
2996 (mapc (lambda (field)
2998 "<\\([lrc]\\)?\\([0-9]+\\)?>" field
)
2999 (let ((align-data (match-string 1 field
)))
3000 (when align-data
(aset align col align-data
)))
3001 (let ((w-data (match-string 2 field
)))
3003 (aset width col
(string-to-number w-data
)))))
3005 (org-split-string row
"[ \t]*|[ \t]*"))))
3006 ;; Read column groups information.
3007 ((org-table-colgroup-line-p row
)
3009 (mapc (lambda (field)
3011 (cond ((string= "<" field
) 'start
)
3012 ((string= ">" field
) 'end
)
3013 ((string= "<>" field
) 'start-end
)))
3015 (org-split-string row
"[ \t]*|[ \t]*"))))
3017 (t (push row-group rowgroups
))))
3018 (org-split-string table
"\n"))
3020 (list :alignment align
3021 :column-groups colgroups
3022 :row-groups
(reverse rowgroups
)
3023 :special-column-p
(eq special-column-p
'special
)
3026 (defun org-export-clean-table (table specialp
)
3027 "Clean string TABLE from its formatting elements.
3028 Remove any row containing column groups or formatting cookies and
3029 rows starting with a special marker. If SPECIALP is non-nil,
3030 assume the table contains a special formatting column and remove
3032 (let ((rows (org-split-string table
"\n")))
3033 (mapconcat 'identity
3038 ((org-table-colgroup-line-p row
) nil
)
3039 ((org-table-cookie-line-p row
) nil
)
3040 ;; Ignore rows starting with a special marker.
3041 ((string-match "^[ \t]*| *[!_^/$] *|" row
) nil
)
3042 ;; Remove special column.
3044 (or (string-match "^\\([ \t]*\\)|-+\\+" row
)
3045 (string-match "^\\([ \t]*\\)|[^|]*|" row
)))
3046 (replace-match "\\1|" t nil row
))
3052 ;;;; For Tables Of Contents
3054 ;; `org-export-collect-headlines' builds a list of all exportable
3055 ;; headline elements, maybe limited to a certain depth. One can then
3056 ;; easily parse it and transcode it.
3058 ;; Building lists of tables, figures or listings is quite similar.
3059 ;; Once the generic function `org-export-collect-elements' is defined,
3060 ;; `org-export-collect-tables', `org-export-collect-figures' and
3061 ;; `org-export-collect-listings' can be derived from it.
3063 (defun org-export-collect-headlines (info &optional n
)
3064 "Collect headlines in order to build a table of contents.
3066 INFO is a plist used as a communication channel.
3068 When non-nil, optional argument N must be an integer. It
3069 specifies the depth of the table of contents.
3071 Return a list of all exportable headlines as parsed elements."
3073 (plist-get info
:parse-tree
)
3075 (lambda (headline local
)
3076 ;; Strip contents from HEADLINE.
3077 (let ((relative-level (org-export-get-relative-level headline local
)))
3078 (unless (and n
(> relative-level n
)) headline
)))
3081 (defun org-export-collect-elements (type info
&optional predicate
)
3082 "Collect referenceable elements of a determined type.
3084 TYPE can be a symbol or a list of symbols specifying element
3085 types to search. Only elements with a caption or a name are
3088 INFO is a plist used as a communication channel.
3090 When non-nil, optional argument PREDICATE is a function accepting
3091 one argument, an element of type TYPE. It returns a non-nil
3092 value when that element should be collected.
3094 Return a list of all elements found, in order of appearance."
3096 (plist-get info
:parse-tree
) type
3097 (lambda (element local
)
3098 (and (or (org-element-property :caption element
)
3099 (org-element-property :name element
))
3100 (or (not predicate
) (funcall predicate element
))
3103 (defun org-export-collect-tables (info)
3104 "Build a list of tables.
3106 INFO is a plist used as a communication channel.
3108 Return a list of table elements with a caption or a name
3109 affiliated keyword."
3110 (org-export-collect-elements 'table info
))
3112 (defun org-export-collect-figures (info predicate
)
3113 "Build a list of figures.
3115 INFO is a plist used as a communication channel. PREDICATE is
3116 a function which accepts one argument: a paragraph element and
3117 whose return value is non-nil when that element should be
3120 A figure is a paragraph type element, with a caption or a name,
3121 verifying PREDICATE. The latter has to be provided since
3122 a \"figure\" is a vague concept that may depend on back-end.
3124 Return a list of elements recognized as figures."
3125 (org-export-collect-elements 'paragraph info predicate
))
3127 (defun org-export-collect-listings (info)
3128 "Build a list of src blocks.
3130 INFO is a plist used as a communication channel.
3132 Return a list of src-block elements with a caption or a name
3133 affiliated keyword."
3134 (org-export-collect-elements 'src-block info
))
3139 ;; Here are various functions to retrieve information about the
3140 ;; neighbourhood of a given element or object. Neighbours of interest
3141 ;; are parent headline (`org-export-get-parent-headline'), parent
3142 ;; paragraph (`org-export-get-parent-paragraph'), previous element or
3143 ;; object (`org-export-get-previous-element') and next element or
3144 ;; object (`org-export-get-next-element').
3146 ;; All of these functions are just a specific use of the more generic
3147 ;; `org-export-get-genealogy', which returns the genealogy relative to
3148 ;; the element or object.
3150 (defun org-export-get-genealogy (blob info
)
3151 "Return genealogy relative to a given element or object.
3152 BLOB is the element or object being considered. INFO is a plist
3153 used as a communication channel."
3154 (let* ((end (org-element-property :end blob
))
3156 (lambda (data genealogy
)
3161 ((equal el blob
) (throw 'exit genealogy
))
3162 ((>= (org-element-property :end el
) end
)
3163 (funcall walk-data el
(cons el genealogy
)))))
3164 (org-element-contents data
)))))
3165 (catch 'exit
(funcall walk-data
(plist-get info
:parse-tree
) nil
) nil
)))
3167 (defun org-export-get-parent-headline (blob info
)
3168 "Return closest parent headline or nil.
3170 BLOB is the element or object being considered. INFO is a plist
3171 used as a communication channel."
3174 (lambda (el) (when (eq (org-element-type el
) 'headline
) (throw 'exit el
)))
3175 (org-export-get-genealogy blob info
))
3178 (defun org-export-get-parent-paragraph (object info
)
3179 "Return parent paragraph or nil.
3181 INFO is a plist used as a communication channel.
3183 Optional argument OBJECT, when provided, is the object to consider.
3184 Otherwise, return the paragraph containing current object.
3186 This is useful for objects, which share attributes with the
3187 paragraph containing them."
3190 (lambda (el) (when (eq (org-element-type el
) 'paragraph
) (throw 'exit el
)))
3191 (org-export-get-genealogy object info
))
3194 (defun org-export-get-previous-element (blob info
)
3195 "Return previous element or object.
3197 BLOB is an element or object. INFO is a plist used as
3198 a communication channel.
3200 Return previous element or object, a string, or nil."
3201 (let ((parent (car (org-export-get-genealogy blob info
))))
3202 (cadr (member blob
(reverse (org-element-contents parent
))))))
3204 (defun org-export-get-next-element (blob info
)
3205 "Return next element or object.
3207 BLOB is an element or object. INFO is a plist used as
3208 a communication channel.
3210 Return next element or object, a string, or nil."
3211 (let ((parent (car (org-export-get-genealogy blob info
))))
3212 (cadr (member blob
(org-element-contents parent
)))))
3218 ;; `org-export-dispatch' is the standard interactive way to start an
3219 ;; export process. It uses `org-export-dispatch-ui' as a subroutine
3220 ;; for its interface. Most commons back-ends should have an entry in
3223 (defun org-export-dispatch ()
3224 "Export dispatcher for Org mode.
3226 It provides an access to common export related tasks in a buffer.
3227 Its interface comes in two flavours: standard and expert. While
3228 both share the same set of bindings, only the former displays the
3229 valid keys associations. Set `org-export-dispatch-use-expert-ui'
3230 to switch to one or the other.
3232 Return an error if key pressed has no associated command."
3234 (let* ((input (org-export-dispatch-ui
3235 (if (listp org-export-initial-scope
) org-export-initial-scope
3236 (list org-export-initial-scope
))
3237 org-export-dispatch-use-expert-ui
))
3238 (raw-key (car input
))
3239 (optns (cdr input
)))
3240 ;; Translate "C-a", "C-b"... into "a", "b"... Then take action
3241 ;; depending on user's key pressed.
3242 (case (if (< raw-key
27) (+ raw-key
96) raw-key
)
3243 ;; Export with `e-ascii' back-end.
3246 (org-export-to-buffer
3247 'e-ascii
"*Org E-ASCII Export*"
3248 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
)
3250 ,(case raw-key
(?A
'ascii
) (?N
'latin1
) (t 'utf-8
))))))
3251 (with-current-buffer outbuf
(text-mode))
3252 (when org-export-show-temporary-export-buffer
3253 (switch-to-buffer-other-window outbuf
))))
3255 (org-e-ascii-export-to-ascii
3256 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
)
3257 `(:ascii-charset
,(case raw-key
(?a
'ascii
) (?n
'latin1
) (t 'utf-8
)))))
3258 ;; Export with `e-latex' back-end.
3261 (org-export-to-buffer
3262 'e-latex
"*Org E-LaTeX Export*"
3263 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
))))
3264 (with-current-buffer outbuf
(latex-mode))
3265 (when org-export-show-temporary-export-buffer
3266 (switch-to-buffer-other-window outbuf
))))
3267 (?l
(org-e-latex-export-to-latex
3268 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
)))
3269 (?p
(org-e-latex-export-to-pdf
3270 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
)))
3272 (org-e-latex-export-to-pdf
3273 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
))))
3274 ;; Export with `e-html' back-end.
3277 (org-export-to-buffer
3278 'e-html
"*Org E-HTML Export*"
3279 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
))))
3281 (with-current-buffer outbuf
3282 (if (featurep 'nxhtml-mode
) (nxhtml-mode) (nxml-mode)))
3283 (when org-export-show-temporary-export-buffer
3284 (switch-to-buffer-other-window outbuf
))))
3285 (?h
(org-e-html-export-to-html
3286 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
)))
3288 (org-e-html-export-to-html
3289 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
))))
3290 ;; Export with `e-odt' back-end.
3291 (?o
(org-e-odt-export-to-odt
3292 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
)))
3294 (org-e-odt-export-to-odt
3295 (memq 'subtree optns
) (memq 'visible optns
) (memq 'body optns
))))
3296 ;; Publishing facilities
3297 (?F
(org-e-publish-current-file (memq 'force optns
)))
3298 (?P
(org-e-publish-current-project (memq 'force optns
)))
3300 (assoc (org-icompleting-read
3301 "Publish project: " org-e-publish-project-alist nil t
)
3302 org-e-publish-project-alist
)))
3303 (org-e-publish project
(memq 'force optns
))))
3304 (?E
(org-e-publish-all (memq 'force optns
)))
3305 ;; Undefined command.
3306 (t (error "No command associated with key %s"
3307 (char-to-string raw-key
))))))
3309 (defun org-export-dispatch-ui (options expertp
)
3310 "Handle interface for `org-export-dispatch'.
3312 OPTIONS is a list containing current interactive options set for
3313 export. It can contain any of the following symbols:
3314 `body' toggles a body-only export
3315 `subtree' restricts export to current subtree
3316 `visible' restricts export to visible part of buffer.
3317 `force' force publishing files.
3319 EXPERTP, when non-nil, triggers expert UI. In that case, no help
3320 buffer is provided, but indications about currently active
3321 options are given in the prompt. Moreover, \[?] allows to switch
3322 back to standard interface.
3324 Return value is a list with key pressed as CAR and a list of
3325 final interactive export options as CDR."
3327 (format "-------------------- General Options --------------------
3328 \[1] Body only: %s [2] Export scope: %s
3329 \[3] Visible only: %s [4] Force publishing: %s
3332 -------------- ASCII/Latin-1/UTF-8 Export ---------------
3333 \[a/n/u] to TXT file [A/N/U] to temporary buffer
3335 --------------------- LaTeX Export ----------------------
3336 \[l] to TEX file [L] to temporary buffer
3337 \[p] to PDF file [d] ... and open it
3339 --------------------- HTML Export -----------------------
3340 \[h] to HTML file [b] ... and open it
3341 \[H] to temporary buffer
3343 --------------------- ODF Export -----------------------
3344 \[o] to ODT file [O] ... and open it
3346 ------------------------- Publish -------------------------
3347 \[F] current file [P] current project
3348 \[X] a project [E] every project"
3349 (if (memq 'body options
) "On " "Off")
3350 (if (memq 'subtree options
) "Subtree" "Buffer ")
3351 (if (memq 'visible options
) "On " "Off")
3352 (if (memq 'force options
) "On " "Off")))
3353 (standard-prompt "Export command: ")
3354 (expert-prompt (format "Export command (%s%s%s%s): "
3355 (if (memq 'body options
) "b" "-")
3356 (if (memq 'subtree options
) "s" "-")
3357 (if (memq 'visible options
) "v" "-")
3358 (if (memq 'force options
) "f" "-")))
3361 ;; Read a character from command input, toggling interactive
3362 ;; options when applicable. PROMPT is the displayed prompt,
3365 (let ((key (read-char-exclusive prompt
)))
3367 ;; Ignore non-standard characters (i.e. "M-a").
3368 ((not (characterp key
)) (org-export-dispatch-ui options expertp
))
3369 ;; Help key: Switch back to standard interface if
3370 ;; expert UI was active.
3371 ((eq key ??
) (org-export-dispatch-ui options nil
))
3372 ;; Toggle export options.
3373 ((memq key
'(?
1 ?
2 ?
3 ?
4))
3374 (org-export-dispatch-ui
3375 (let ((option (case key
(?
1 'body
) (?
2 'subtree
) (?
3 'visible
)
3377 (if (memq option options
) (remq option options
)
3378 (cons option options
)))
3380 ;; Action selected: Send key and options back to
3381 ;; `org-export-dispatch'.
3382 (t (cons key options
))))))))
3383 ;; With expert UI, just read key with a fancy prompt. In standard
3384 ;; UI, display an intrusive help buffer.
3385 (if expertp
(funcall handle-keypress expert-prompt
)
3386 (save-window-excursion
3387 (delete-other-windows)
3388 (with-output-to-temp-buffer "*Org Export/Publishing Help*" (princ help
))
3389 (org-fit-window-to-buffer
3390 (get-buffer-window "*Org Export/Publishing Help*"))
3391 (funcall handle-keypress standard-prompt
)))))
3394 (provide 'org-export
)
3395 ;;; org-export.el ends here