1 ;;; org-export.el --- Generic Export Engine For Org
3 ;; Copyright (C) 2011 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 export options or
32 ;; contextual data, all in a single place. The exhaustive list of
33 ;; 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 last
92 (eval-when-compile (require 'cl
))
93 (require 'org-element
)
96 ;;; Internal Variables
98 ;; Among internal variables, the most important is
99 ;; `org-export-option-alist'. This variable define the global export
100 ;; options, shared between every exporter, and how they are acquired.
102 (defconst org-export-max-depth
19
103 "Maximum nesting depth for headlines, counting from 0.")
105 (defconst org-export-option-alist
106 '((:author
"AUTHOR" nil user-full-name t
)
107 (:creator
"CREATOR" nil org-export-creator-string
)
108 (:date
"DATE" nil nil t
)
109 (:description
"DESCRIPTION" nil nil newline
)
110 (:email
"EMAIL" nil user-mail-address t
)
111 (:exclude-tags
"EXPORT_EXCLUDE_TAGS" nil org-export-exclude-tags split
)
112 (:headline-levels nil
"H" org-export-headline-levels
)
113 (:keywords
"KEYWORDS" nil nil space
)
114 (:language
"LANGUAGE" nil org-export-default-language t
)
115 (:preserve-breaks nil
"\\n" org-export-preserve-breaks
)
116 (:section-numbers nil
"num" org-export-with-section-numbers
)
117 (:select-tags
"EXPORT_SELECT_TAGS" nil org-export-select-tags split
)
118 (:time-stamp-file nil
"timestamp" org-export-time-stamp-file
)
119 (:title
"TITLE" nil nil space
)
120 (:with-archived-trees nil
"arch" org-export-with-archived-trees
)
121 (:with-author nil
"author" org-export-with-author
)
122 (:with-creator nil
"creator" org-export-with-creator
)
123 (:with-drawers nil
"drawer" org-export-with-drawers
)
124 (:with-email nil
"email" org-export-with-email
)
125 (:with-emphasize nil
"*" org-export-with-emphasize
)
126 (:with-entities nil
"e" org-export-with-entities
)
127 (:with-fixed-width nil
":" org-export-with-fixed-width
)
128 (:with-footnotes nil
"f" org-export-with-footnotes
)
129 (:with-priority nil
"pri" org-export-with-priority
)
130 (:with-special-strings nil
"-" org-export-with-special-strings
)
131 (:with-sub-superscript nil
"^" org-export-with-sub-superscripts
)
132 (:with-toc nil
"toc" org-export-with-toc
)
133 (:with-tables nil
"|" org-export-with-tables
)
134 (:with-tags nil
"tags" org-export-with-tags
)
135 (:with-tasks nil
"tasks" org-export-with-tasks
)
136 (:with-timestamps nil
"<" org-export-with-timestamps
)
137 (:with-todo-keywords nil
"todo" org-export-with-todo-keywords
))
138 "Alist between export properties and ways to set them.
140 The car of the alist is the property name, and the cdr is a list
141 like \(KEYWORD OPTION DEFAULT BEHAVIOUR\) where:
143 KEYWORD is a string representing a buffer keyword, or nil.
144 OPTION is a string that could be found in an #+OPTIONS: line.
145 DEFAULT is the default value for the property.
146 BEHAVIOUR determine how Org should handle multiple keywords for
147 the same property. It is a symbol among:
148 nil Keep old value and discard the new one.
149 t Replace old value with the new one.
150 `space' Concatenate the values, separating them with a space.
151 `newline' Concatenate the values, separating them with
153 `split' Split values at white spaces, and cons them to the
156 KEYWORD and OPTION have precedence over DEFAULT.
158 All these properties should be back-end agnostic. For back-end
159 specific properties, define a similar variable named
160 `org-BACKEND-option-alist', replacing BACKEND with the name of
161 the appropriate back-end. You can also redefine properties
162 there, as they have precedence over these.")
164 (defconst org-export-special-keywords
165 '("SETUP_FILE" "OPTIONS" "MACRO")
166 "List of in-buffer keywords that require special treatment.
167 These keywords are not directly associated to a property. The
168 way they are handled must be hard-coded into
169 `org-export-get-inbuffer-options' function.")
173 ;;; User-configurable Variables
175 ;; Configuration for the masses.
177 ;; They should never be evaled directly, as their value is to be
178 ;; stored in a property list (cf. `org-export-option-alist').
180 (defgroup org-export nil
181 "Options for exporting Org mode files."
185 (defgroup org-export-general nil
186 "General options for export engine."
187 :tag
"Org Export General"
190 (defcustom org-export-with-archived-trees
'headline
191 "Whether sub-trees with the ARCHIVE tag should be exported.
193 This can have three different values:
194 nil Do not export, pretend this tree is not present.
195 t Do export the entire tree.
196 `headline' Only export the headline, but skip the tree below it.
198 This option can also be set with the #+OPTIONS line,
200 :group
'org-export-general
202 (const :tag
"Not at all" nil
)
203 (const :tag
"Headline only" 'headline
)
204 (const :tag
"Entirely" t
)))
206 (defcustom org-export-with-author t
207 "Non-nil means insert author name into the exported file.
208 This option can also be set with the #+OPTIONS line,
209 e.g. \"author:nil\"."
210 :group
'org-export-general
213 (defcustom org-export-with-creator
'comment
214 "Non-nil means the postamble should contain a creator sentence.
216 The sentence can be set in `org-export-creator-string' and
217 defaults to \"Generated by Org mode XX in Emacs XXX.\".
219 If the value is `comment' insert it as a comment."
220 :group
'org-export-general
222 (const :tag
"No creator sentence" nil
)
223 (const :tag
"Sentence as a comment" 'comment
)
224 (const :tag
"Insert the sentence" t
)))
226 (defcustom org-export-creator-string
227 (format "Generated by Org mode %s in Emacs %s." org-version emacs-version
)
228 "String to insert at the end of the generated document."
229 :group
'org-export-general
230 :type
'(string :tag
"Creator string"))
232 (defcustom org-export-with-drawers nil
233 "Non-nil means export with drawers like the property drawer.
234 When t, all drawers are exported. This may also be a list of
235 drawer names to export."
236 :group
'org-export-general
238 (const :tag
"All drawers" t
)
239 (const :tag
"None" nil
)
240 (repeat :tag
"Selected drawers"
241 (string :tag
"Drawer name"))))
243 (defcustom org-export-with-email nil
244 "Non-nil means insert author email into the exported file.
245 This option can also be set with the #+OPTIONS line,
247 :group
'org-export-general
250 (defcustom org-export-with-emphasize t
251 "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
253 If the export target supports emphasizing text, the word will be
254 typeset in bold, italic, or underlined, respectively. Not all
255 export backends support this.
257 This option can also be set with the #+OPTIONS line, e.g. \"*:nil\"."
258 :group
'org-export-general
261 (defcustom org-export-exclude-tags
'("noexport")
262 "Tags that exclude a tree from export.
263 All trees carrying any of these tags will be excluded from
264 export. This is without condition, so even subtrees inside that
265 carry one of the `org-export-select-tags' will be removed."
266 :group
'org-export-general
267 :type
'(repeat (string :tag
"Tag")))
269 (defcustom org-export-with-fixed-width t
270 "Non-nil means lines starting with \":\" will be in fixed width font.
272 This can be used to have pre-formatted text, fragments of code
274 : ;; Some Lisp examples
277 will be looking just like this in also HTML. See also the QUOTE
278 keyword. Not all export backends support this.
280 This option can also be set with the #+OPTIONS line, e.g. \"::nil\"."
281 :group
'org-export-translation
284 (defcustom org-export-with-footnotes t
285 "Non-nil means Org footnotes should be exported.
286 This option can also be set with the #+OPTIONS line,
288 :group
'org-export-general
291 (defcustom org-export-headline-levels
3
292 "The last level which is still exported as a headline.
294 Inferior levels will produce itemize lists when exported. Note
295 that a numeric prefix argument to an exporter function overrides
298 This option can also be set with the #+OPTIONS line, e.g. \"H:2\"."
299 :group
'org-export-general
302 (defcustom org-export-default-language
"en"
303 "The default language for export and clocktable translations, as a string.
304 This may have an association in
305 `org-clock-clocktable-language-setup'."
306 :group
'org-export-general
307 :type
'(string :tag
"Language"))
309 (defcustom org-export-preserve-breaks nil
310 "Non-nil means preserve all line breaks when exporting.
312 Normally, in HTML output paragraphs will be reformatted.
314 This option can also be set with the #+OPTIONS line,
316 :group
'org-export-general
319 (defcustom org-export-with-entities t
320 "Non-nil means interpret entities when exporting.
322 For example, HTML export converts \\alpha to α and \\AA to
325 For a list of supported names, see the constant `org-entities'
326 and the user option `org-entities-user'.
328 This option can also be set with the #+OPTIONS line,
330 :group
'org-export-general
333 (defcustom org-export-with-priority nil
334 "Non-nil means include priority cookies in export.
335 When nil, remove priority cookies for export."
336 :group
'org-export-general
339 (defcustom org-export-with-section-numbers t
340 "Non-nil means add section numbers to headlines when exporting.
342 This option can also be set with the #+OPTIONS line,
344 :group
'org-export-general
347 (defcustom org-export-select-tags
'("export")
348 "Tags that select a tree for export.
349 If any such tag is found in a buffer, all trees that do not carry
350 one of these tags will be deleted before export. Inside trees
351 that are selected like this, you can still deselect a subtree by
352 tagging it with one of the `org-export-exclude-tags'."
353 :group
'org-export-general
354 :type
'(repeat (string :tag
"Tag")))
356 (defcustom org-export-with-special-strings t
357 "Non-nil means interpret \"\-\", \"--\" and \"---\" for export.
359 When this option is turned on, these strings will be exported as:
362 -----+----------+--------
368 This option can also be set with the #+OPTIONS line,
370 :group
'org-export-general
373 (defcustom org-export-with-sub-superscripts t
374 "Non-nil means interpret \"_\" and \"^\" for export.
376 When this option is turned on, you can use TeX-like syntax for
377 sub- and superscripts. Several characters after \"_\" or \"^\"
378 will be considered as a single item - so grouping with {} is
379 normally not needed. For example, the following things will be
380 parsed as single sub- or superscripts.
382 10^24 or 10^tau several digits will be considered 1 item.
383 10^-12 or 10^-tau a leading sign with digits or a word
384 x^2-y^3 will be read as x^2 - y^3, because items are
385 terminated by almost any nonword/nondigit char.
386 x_{i^2} or x^(2-i) braces or parenthesis do grouping.
388 Still, ambiguity is possible - so when in doubt use {} to enclose
389 the sub/superscript. If you set this variable to the symbol
390 `{}', the braces are *required* in order to trigger
391 interpretations as sub/superscript. This can be helpful in
392 documents that need \"_\" frequently in plain text.
394 This option can also be set with the #+OPTIONS line,
396 :group
'org-export-general
398 (const :tag
"Interpret them" t
)
399 (const :tag
"Curly brackets only" {})
400 (const :tag
"Do not interpret them" nil
)))
402 (defcustom org-export-with-toc t
403 "Non-nil means create a table of contents in exported files.
405 The TOC contains headlines with levels up
406 to`org-export-headline-levels'. When an integer, include levels
407 up to N in the toc, this may then be different from
408 `org-export-headline-levels', but it will not be allowed to be
409 larger than the number of headline levels. When nil, no table of
412 This option can also be set with the #+OPTIONS line,
413 e.g. \"toc:nil\" or \"toc:3\"."
414 :group
'org-export-general
416 (const :tag
"No Table of Contents" nil
)
417 (const :tag
"Full Table of Contents" t
)
418 (integer :tag
"TOC to level")))
420 (defcustom org-export-with-tables t
421 "If non-nil, lines starting with \"|\" define a table.
424 | Name | Address | Birthday |
425 |-------------+----------+-----------|
426 | Arthur Dent | England | 29.2.2100 |
428 This option can also be set with the #+OPTIONS line, e.g. \"|:nil\"."
429 :group
'org-export-general
432 (defcustom org-export-with-tags t
433 "If nil, do not export tags, just remove them from headlines.
435 If this is the symbol `not-in-toc', tags will be removed from
436 table of contents entries, but still be shown in the headlines of
439 This option can also be set with the #+OPTIONS line,
441 :group
'org-export-general
443 (const :tag
"Off" nil
)
444 (const :tag
"Not in TOC" not-in-toc
)
445 (const :tag
"On" t
)))
447 (defcustom org-export-with-tasks t
448 "Non-nil means include TODO items for export.
449 This may have the following values:
450 t include tasks independent of state.
451 todo include only tasks that are not yet done.
452 done include only tasks that are already done.
453 nil remove all tasks before export
454 list of keywords keep only tasks with these keywords"
455 :group
'org-export-general
457 (const :tag
"All tasks" t
)
458 (const :tag
"No tasks" nil
)
459 (const :tag
"Not-done tasks" todo
)
460 (const :tag
"Only done tasks" done
)
461 (repeat :tag
"Specific TODO keywords"
462 (string :tag
"Keyword"))))
464 (defcustom org-export-time-stamp-file t
465 "Non-nil means insert a time stamp into the exported file.
466 The time stamp shows when the file was created.
468 This option can also be set with the #+OPTIONS line,
469 e.g. \"timestamp:nil\"."
470 :group
'org-export-general
473 (defcustom org-export-with-timestamps t
474 "If nil, do not export time stamps and associated keywords."
475 :group
'org-export-general
478 (defcustom org-export-with-todo-keywords t
479 "Non-nil means include TODO keywords in export.
480 When nil, remove all these keywords from the export.")
482 (defcustom org-export-allow-BIND
'confirm
483 "Non-nil means allow #+BIND to define local variable values for export.
484 This is a potential security risk, which is why the user must
485 confirm the use of these lines."
486 :group
'org-export-general
488 (const :tag
"Never" nil
)
489 (const :tag
"Always" t
)
490 (const :tag
"Ask a confirmation for each file" confirm
)))
492 (defcustom org-export-snippet-translation-alist nil
493 "Alist between export snippets back-ends and exporter back-ends.
495 This variable allows to provide shortcuts for export snippets.
497 For example, with a value of '\(\(\"h\" . \"html\"\)\), the HTML
498 back-end will recognize the contents of \"@h{<b>}\" as HTML code
499 while every other back-end will ignore it."
500 :group
'org-export-general
503 (string :tag
"Shortcut")
504 (string :tag
"Back-end"))))
508 ;;; The Communication Channel
510 ;; During export process, every function has access to a number of
511 ;; properties. They are of three types:
513 ;; 1. Export options are collected once at the very beginning of the
514 ;; process, out of the original buffer and environment. The task
515 ;; is handled by `org-export-collect-options' function.
517 ;; All export options are defined through the
518 ;; `org-export-option-alist' variable.
520 ;; 2. Persistent properties are stored in
521 ;; `org-export-persistent-properties' and available at every level
522 ;; of recursion. Their value is extracted directly from the parsed
523 ;; tree, and depends on export options (whole trees may be filtered
524 ;; out of the export process).
526 ;; Properties belonging to that type are defined in the
527 ;; `org-export-persistent-properties-list' variable.
529 ;; 3. Every other property is considered local, and available at
530 ;; a precise level of recursion and below.
532 ;; Managing properties during transcode process is mainly done with
533 ;; `org-export-update-info'. Even though they come from different
534 ;; sources, the function transparently concatenates them in a single
535 ;; property list passed as an argument to each transcode function.
536 ;; Thus, during export, all necessary information is available through
537 ;; that single property list, and the element or object itself.
538 ;; Though, modifying a property will still require some special care,
539 ;; and should be done with `org-export-set-property' instead of plain
542 ;; Here is the full list of properties available during transcode
543 ;; process, with their category (option, persistent or local), their
544 ;; value type and the function updating them, when appropriate.
546 ;; + `author' :: Author's name.
547 ;; - category :: option
550 ;; + `back-end' :: Current back-end used for transcoding.
551 ;; - category :: persistent
554 ;; + `code-refs' :: Association list between reference name and real
555 ;; labels in source code. It is used to properly
556 ;; resolve links inside source blocks.
557 ;; - category :: persistent
558 ;; - type :: alist (INT-OR-STRING . STRING)
559 ;; - update :: `org-export-handle-code'
561 ;; + `creator' :: String to write as creation information.
562 ;; - category :: option
565 ;; + `date' :: String to use as date.
566 ;; - category :: option
569 ;; + `description' :: Description text for the current data.
570 ;; - category :: option
573 ;; + `email' :: Author's email.
574 ;; - category :: option
577 ;; + `exclude-tags' :: Tags for exclusion of subtrees from export
579 ;; - category :: option
580 ;; - type :: list of strings
582 ;; + `footnote-definition-alist' :: Alist between footnote labels and
583 ;; their definition, as parsed data. Only non-inlined footnotes
584 ;; are represented in this alist. Also, every definition isn't
585 ;; guaranteed to be referenced in the parse tree. The purpose of
586 ;; this property is to preserve definitions from oblivion
587 ;; (i.e. when the parse tree comes from a part of the original
588 ;; buffer), it isn't meant for direct use in a back-end. To
589 ;; retrieve a definition relative to a reference, use
590 ;; `org-export-get-footnote-definition' instead.
591 ;; - category :: option
592 ;; - type :: alist (STRING . LIST)
594 ;; + `footnote-seen-labels' :: List of already transcoded footnote
595 ;; labels. It is used to know when a reference appears for the
596 ;; first time. (cf. `org-export-footnote-first-reference-p').
597 ;; - category :: persistent
598 ;; - type :: list of strings
599 ;; - update :: `org-export-update-info'
601 ;; + `genealogy' :: List of current element's parents types.
602 ;; - category :: local
603 ;; - type :: list of symbols
604 ;; - update :: `org-export-update-info'
606 ;; + `headline-alist' :: Alist between headlines raw name and their
607 ;; boundaries. It is used to resolve "fuzzy" links
608 ;; (cf. `org-export-resolve-fuzzy-link').
609 ;; - category :: persistent
610 ;; - type :: alist (STRING INTEGER INTEGER)
612 ;; + `headline-levels' :: Maximum level being exported as an
613 ;; headline. Comparison is done with the relative level of
614 ;; headlines in the parse tree, not necessarily with their
616 ;; - category :: option
619 ;; + `headline-offset' :: Difference between relative and real level
620 ;; of headlines in the parse tree. For example, a value of -1
621 ;; means a level 2 headline should be considered as level
622 ;; 1 (cf. `org-export-get-relative-level').
623 ;; - category :: persistent
626 ;; + `headline-numbering' :: Alist between headlines' beginning
627 ;; position and their numbering, as a list of numbers
628 ;; (cf. `org-export-get-headline-number').
629 ;; - category :: persistent
630 ;; - type :: alist (INTEGER . LIST)
632 ;; + `included-files' :: List of files, with full path, included in
633 ;; the current buffer, through the "#+include:" keyword. It is
634 ;; mainly used to verify that no infinite recursive inclusion
636 ;; - category :: local
637 ;; - type :: list of strings
639 ;; + `inherited-properties' :: Properties of the headline ancestors
640 ;; of the current element or object. Those from the closest
641 ;; headline have precedence over the others.
642 ;; - category :: local
645 ;; + `keywords' :: List of keywords attached to data.
646 ;; - category :: option
649 ;; + `language' :: Default language used for translations.
650 ;; - category :: option
653 ;; + `parent-properties' :: Properties of the parent element.
654 ;; - category :: local
656 ;; - update :: `org-export-update-info'
658 ;; + `parse-tree' :: Whole parse tree, available at any time during
660 ;; - category :: global
661 ;; - type :: list (as returned by `org-element-parse-buffer')
663 ;; + `point-max' :: Last ending position in the parse tree.
664 ;; - category :: global
667 ;; + `preserve-breaks' :: Non-nil means transcoding should preserve
669 ;; - category :: option
670 ;; - type :: symbol (nil, t)
672 ;; + `previous-element' :: Previous element's type at the same
674 ;; - category :: local
676 ;; - update :: `org-export-update-info'
678 ;; + `previous-object' :: Previous object type (or `plain-text') at
680 ;; - category :: local
682 ;; - update :: `org-export-update-info'
684 ;; + `section-numbers' :: Non-nil means transcoding should add
685 ;; section numbers to headlines.
686 ;; - category :: option
687 ;; - type :: symbol (nil, t)
689 ;; + `select-tags' :: List of tags enforcing inclusion of sub-trees in
690 ;; transcoding. When such a tag is present,
691 ;; subtrees without it are de facto excluded from
692 ;; the process. See `use-select-tags'.
693 ;; - category :: option
694 ;; - type :: list of strings
696 ;; + `target-list' :: List of targets raw names encoutered in the
697 ;; parse tree. This is used to partly resolve
699 ;; (cf. `org-export-resolve-fuzzy-link').
700 ;; - category :: persistent
701 ;; - type :: list of strings
703 ;; + `time-stamp-file' :: Non-nil means transcoding should insert
704 ;; a time stamp in the output.
705 ;; - category :: option
706 ;; - type :: symbol (nil, t)
708 ;; + `total-loc' :: Contains total lines of code accumulated by source
709 ;; blocks with the "+n" option so far.
710 ;; - category :: persistent
712 ;; - update :: `org-export-handle-code'
714 ;; + `use-select-tags' :: When non-nil, a select tags has been found
715 ;; in the parse tree. Thus, any headline without one will be
716 ;; filtered out. See `select-tags'.
717 ;; - category :: persistent
718 ;; - type :: interger or nil
720 ;; + `with-archived-trees' :: Non-nil when archived subtrees should
721 ;; also be transcoded. If it is set to the `headline' symbol,
722 ;; only the archived headline's name is retained.
723 ;; - category :: option
724 ;; - type :: symbol (nil, t, `headline')
726 ;; + `with-author' :: Non-nil means author's name should be included
728 ;; - category :: option
729 ;; - type :: symbol (nil, t)
731 ;; + `with-creator' :: Non-nild means a creation sentence should be
732 ;; inserted at the end of the transcoded string. If the value
733 ;; is `comment', it should be commented.
734 ;; - category :: option
735 ;; - type :: symbol (`comment', nil, t)
737 ;; + `with-drawers' :: Non-nil means drawers should be exported. If
738 ;; its value is a list of names, only drawers with such names
739 ;; will be transcoded.
740 ;; - category :: option
741 ;; - type :: symbol (nil, t) or list of strings
743 ;; + `with-email' :: Non-nil means output should contain author's
745 ;; - category :: option
746 ;; - type :: symbol (nil, t)
748 ;; + `with-emphasize' :: Non-nil means emphasized text should be
750 ;; - category :: option
751 ;; - type :: symbol (nil, t)
753 ;; + `with-fixed-width' :: Non-nil if transcoder should interpret
754 ;; strings starting with a colon as a fixed-with (verbatim)
756 ;; - category :: option
757 ;; - type :: symbol (nil, t)
759 ;; + `with-footnotes' :: Non-nil if transcoder should interpret
761 ;; - category :: option
762 ;; - type :: symbol (nil, t)
764 ;; + `with-priority' :: Non-nil means transcoding should include
766 ;; - category :: option
767 ;; - type :: symbol (nil, t)
769 ;; + `with-special-strings' :: Non-nil means transcoding should
770 ;; interpret special strings in plain text.
771 ;; - category :: option
772 ;; - type :: symbol (nil, t)
774 ;; + `with-sub-superscript' :: Non-nil means transcoding should
775 ;; interpret subscript and superscript. With a value of "{}",
776 ;; only interpret those using curly brackets.
777 ;; - category :: option
778 ;; - type :: symbol (nil, {}, t)
780 ;; + `with-tables' :: Non-nil means transcoding should interpret
782 ;; - category :: option
783 ;; - type :: symbol (nil, t)
785 ;; + `with-tags' :: Non-nil means transcoding should keep tags in
786 ;; headlines. A `not-in-toc' value will remove them
787 ;; from the table of contents, if any, nonetheless.
788 ;; - category :: option
789 ;; - type :: symbol (nil, t, `not-in-toc')
791 ;; + `with-tasks' :: Non-nil means transcoding should include
792 ;; headlines with a TODO keyword. A `todo' value
793 ;; will only include headlines with a todo type
794 ;; keyword while a `done' value will do the
795 ;; contrary. If a list of strings is provided, only
796 ;; tasks with keywords belonging to that list will
798 ;; - category :: option
799 ;; - type :: symbol (t, todo, done, nil) or list of strings
801 ;; + `with-timestamps' :: Non-nil means transcoding should include
802 ;; time stamps and associated keywords. Otherwise, completely
804 ;; - category :: option
805 ;; - type :: symbol: (t, nil)
807 ;; + `with-toc' :: Non-nil means that a table of contents has to be
808 ;; added to the output. An integer value limits its
810 ;; - category :: option
811 ;; - type :: symbol (nil, t or integer)
813 ;; + `with-todo-keywords' :: Non-nil means transcoding should
814 ;; include TODO keywords.
815 ;; - category :: option
816 ;; - type :: symbol (nil, t)
820 ;; Export options come from five sources, in increasing precedence
823 ;; - Global variables,
824 ;; - External options provided at export time,
825 ;; - Options keyword symbols,
826 ;; - Buffer keywords,
827 ;; - Subtree properties.
829 ;; The central internal function with regards to export options is
830 ;; `org-export-collect-options'. It updates global variables with
831 ;; "#+BIND:" keywords, then retrieve and prioritize properties from
832 ;; the different sources.
834 ;; The internal functions doing the retrieval are:
835 ;; `org-export-parse-option-keyword' ,
836 ;; `org-export-get-subtree-options' ,
837 ;; `org-export-get-inbuffer-options' and
838 ;; `org-export-get-global-options'.
840 ;; Some properties do not rely on the previous sources but still
841 ;; depend on the original buffer are taken care of in
842 ;; `org-export-initial-options'.
844 ;; Also, `org-export-confirm-letbind' and `org-export-install-letbind'
845 ;; take care of the part relative to "#+BIND:" keywords.
847 (defun org-export-collect-options (backend subtreep ext-plist
)
848 "Collect export options from the current buffer.
850 BACKEND is a symbol specifying the back-end to use.
852 When SUBTREEP is non-nil, assume the export is done against the
855 EXT-PLIST is a property list with external parameters overriding
856 org-mode's default settings, but still inferior to file-local
858 ;; First install #+BIND variables.
859 (org-export-install-letbind-maybe)
860 ;; Get and prioritize export options...
861 (let ((options (org-combine-plists
862 ;; ... from global variables...
863 (org-export-get-global-options backend
)
864 ;; ... from an external property list...
866 ;; ... from in-buffer settings...
867 (org-export-get-inbuffer-options
868 (org-with-wide-buffer (buffer-string)) backend
869 (and buffer-file-name
870 (org-remove-double-quotes buffer-file-name
)))
871 ;; ... and from subtree, when appropriate.
873 (org-export-get-subtree-options)))))
874 ;; Add initial options.
875 (setq options
(append (org-export-initial-options options
)
877 ;; Set a default title if none has been specified so far.
878 (unless (plist-get options
:title
)
879 (setq options
(plist-put options
:title
880 (or (and buffer-file-name
881 (file-name-sans-extension
882 (file-name-nondirectory
888 (defun org-export-parse-option-keyword (options backend
)
889 "Parse an OPTIONS line and return values as a plist.
890 BACKEND is a symbol specifying the back-end to use."
891 (let* ((all (append org-export-option-alist
893 (format "org-%s-option-alist" backend
))))
894 (and (boundp var
) (eval var
)))))
895 ;; Build an alist between #+OPTION: item and property-name.
898 (when (nth 2 e
) (cons (regexp-quote (nth 2 e
))
903 (when (string-match (concat "\\(\\`\\|[ \t]\\)"
905 ":\\(([^)\n]+)\\|[^ \t\n\r;,.]*\\)")
907 (setq plist
(plist-put plist
909 (car (read-from-string
910 (match-string 2 options
)))))))
914 (defun org-export-get-subtree-options ()
915 "Get export options in subtree at point.
916 Return the options as a plist."
917 (org-with-wide-buffer
918 (when (ignore-errors (org-back-to-heading t
))
920 (when (setq prop
(progn (looking-at org-todo-line-regexp
)
921 (or (org-entry-get (point) "EXPORT_TITLE")
922 (org-match-string-no-properties 3))))
923 (setq plist
(plist-put plist
:title prop
)))
924 (when (setq prop
(org-entry-get (point) "EXPORT_TEXT"))
925 (setq plist
(plist-put plist
:text prop
)))
926 (when (setq prop
(org-entry-get (point) "EXPORT_AUTHOR"))
927 (setq plist
(plist-put plist
:author prop
)))
928 (when (setq prop
(org-entry-get (point) "EXPORT_DATE"))
929 (setq plist
(plist-put plist
:date prop
)))
930 (when (setq prop
(org-entry-get (point) "EXPORT_OPTIONS"))
931 (setq plist
(org-export-add-options-to-plist plist prop
)))
934 (defun org-export-get-inbuffer-options (buffer-string backend files
)
935 "Return in-buffer options as a plist.
936 BUFFER-STRING is the string of the buffer. BACKEND is a symbol
937 specifying which back-end should be used."
938 (let ((case-fold-search t
) plist
)
939 ;; 1. Special keywords, as in `org-export-special-keywords'.
941 (special-re (org-make-options-regexp org-export-special-keywords
)))
942 (while (string-match special-re buffer-string start
)
943 (setq start
(match-end 0))
944 (let ((key (upcase (org-match-string-no-properties 1 buffer-string
)))
945 ;; Special keywords do not have their value expanded.
946 (val (org-match-string-no-properties 2 buffer-string
)))
950 ((string= key
"SETUP_FILE")
951 (let ((file (expand-file-name
952 (org-remove-double-quotes (org-trim val
)))))
953 ;; Avoid circular dependencies.
954 (unless (member file files
)
955 (org-export-get-inbuffer-options
956 (org-file-contents file
'noerror
)
958 (cons file files
)))))
959 ((string= key
"OPTIONS")
960 (org-export-parse-option-keyword val backend
))
961 ((string= key
"MACRO")
962 (string-match "^\\([-a-zA-Z0-9_]+\\)[ \t]+\\(.*?[ \t]*$\\)"
965 (intern (concat ":macro-"
966 (downcase (match-string 1 val
))))
967 (match-string 2 val
))))
969 ;; 2. Standard options, as in `org-export-option-alist'.
970 (let* ((all (append org-export-option-alist
972 (format "org-%s-option-alist" backend
))))
973 (and (boundp var
) (eval var
)))))
974 ;; Build alist between keyword name and property name.
975 (alist (delq nil
(mapcar (lambda (e)
976 (when (nth 1 e
) (cons (nth 1 e
) (car e
))))
978 ;; Build regexp matching all keywords associated to export
979 ;; options. Note: the search is case insensitive.
980 (opt-re (org-make-options-regexp
981 (delq nil
(mapcar (lambda (e) (nth 1 e
)) all
))))
983 (while (string-match opt-re buffer-string start
)
984 (setq start
(match-end 0))
985 (let* ((key (upcase (org-match-string-no-properties 1 buffer-string
)))
986 ;; Expand value, applying restrictions for keywords.
987 (val (org-match-string-no-properties 2 buffer-string
))
988 (prop (cdr (assoc key alist
)))
989 (behaviour (nth 4 (assq prop all
))))
993 ;; Handle value depending on specified BEHAVIOUR.
995 (space (if (plist-get plist prop
)
996 (concat (plist-get plist prop
) " " (org-trim val
))
1000 (plist-get plist prop
) "\n" (org-trim val
))))
1001 (split `(,@(plist-get plist prop
) ,@(org-split-string val
)))
1003 (otherwise (plist-get plist prop
)))))))
1004 ;; Parse keywords specified in `org-element-parsed-keywords'.
1007 (let* ((prop (cdr (assoc (upcase key
) alist
)))
1008 (value (and prop
(plist-get plist prop
))))
1009 (when (stringp value
)
1013 (org-element-parse-secondary-string
1015 (cdr (assq 'keyword org-element-string-restrictions
))))))))
1016 org-element-parsed-keywords
))
1017 ;; Return final value.
1020 (defun org-export-get-global-options (backend)
1021 "Return global export options as a plist.
1022 BACKEND is a symbol specifying which back-end should be used."
1023 (let ((all (append org-export-option-alist
1025 (format "org-%s-option-alist" backend
))))
1026 (and (boundp var
) (eval var
)))))
1029 (mapc (lambda (cell)
1031 (plist-put plist
(car cell
) (eval (nth 3 cell
)))))
1036 (defun org-export-initial-options (options)
1037 "Return a plist with non-optional properties.
1038 OPTIONS is the export options plist computed so far."
1040 ;; `:macro-date', `:macro-time' and `:macro-property' could as well
1041 ;; be initialized as persistent properties, since they don't depend
1042 ;; on initial environment. Though, it may be more logical to keep
1043 ;; them close to other ":macro-" properties.
1044 :macro-date
"(eval (format-time-string \"$1\"))"
1045 :macro-time
"(eval (format-time-string \"$1\"))"
1046 :macro-property
"(eval (org-entry-get nil \"$1\" 'selective))"
1047 :macro-modification-time
1048 (and (buffer-file-name)
1049 (file-exists-p (buffer-file-name))
1050 (concat "(eval (format-time-string \"$1\" '"
1051 (prin1-to-string (nth 5 (file-attributes (buffer-file-name))))
1053 :macro-input-file
(and (buffer-file-name)
1054 (file-name-nondirectory (buffer-file-name)))
1055 ;; Footnotes definitions must be collected in the original buffer,
1056 ;; as there's no insurance that they will still be in the parse
1057 ;; tree, due to some narrowing.
1058 :footnote-definition-alist
1060 (org-with-wide-buffer
1061 (goto-char (point-min))
1062 (while (re-search-forward org-footnote-definition-re nil t
)
1063 (let ((def (org-footnote-at-definition-p)))
1065 (org-skip-whitespace)
1066 (push (cons (car def
)
1068 (narrow-to-region (point) (nth 2 def
))
1069 (org-element-parse-buffer)))
1073 (defvar org-export-allow-BIND-local nil
)
1074 (defun org-export-confirm-letbind ()
1075 "Can we use #+BIND values during export?
1076 By default this will ask for confirmation by the user, to divert
1077 possible security risks."
1079 ((not org-export-allow-BIND
) nil
)
1080 ((eq org-export-allow-BIND t
) t
)
1081 ((local-variable-p 'org-export-allow-BIND-local
) org-export-allow-BIND-local
)
1082 (t (org-set-local 'org-export-allow-BIND-local
1083 (yes-or-no-p "Allow BIND values in this buffer? ")))))
1085 (defun org-export-install-letbind-maybe ()
1086 "Install the values from #+BIND lines as local variables.
1087 Variables must be installed before in-buffer options are
1090 (org-with-wide-buffer
1091 (goto-char (point-min))
1092 (while (re-search-forward (org-make-options-regexp '("BIND")) nil t
)
1093 (when (org-export-confirm-letbind)
1094 (push (read (concat "(" (org-match-string-no-properties 2) ")"))
1096 (while (setq pair
(pop letbind
))
1097 (org-set-local (car pair
) (nth 1 pair
)))))
1100 ;;;; Persistent Properties
1102 ;; Persistent properties are declared in
1103 ;; `org-export-persistent-properties-list' variable. Most of them are
1104 ;; initialized at the beginning of the transcoding process by
1105 ;; `org-export-initialize-persistent-properties'. The others are
1106 ;; updated during that process.
1108 ;; Dedicated functions focus on computing the value of specific
1109 ;; persistent properties during initialization. Thus,
1110 ;; `org-export-use-select-tag-p' determines if an headline makes use
1111 ;; of an export tag enforcing inclusion. `org-export-get-min-level'
1112 ;; gets the minimal exportable level, used as a basis to compute
1113 ;; relative level for headlines. `org-export-get-point-max' returns
1114 ;; the maximum exportable ending position in the parse tree.
1115 ;; Eventually `org-export-collect-headline-numbering' builds an alist
1116 ;; between headlines' beginning position and their numbering.
1118 (defconst org-export-persistent-properties-list
1119 '(:back-end
:code-refs
:headline-alist
:headline-numbering
:headline-offset
1120 :parse-tree
:point-max
:footnote-seen-labels
:target-list
1121 :total-loc
:use-select-tags
)
1122 "List of persistent properties.")
1124 (defconst org-export-persistent-properties nil
1125 "Used internally to store properties and values during transcoding.
1127 Only properties that should survive recursion are saved here.
1129 This variable is reset before each transcoding.")
1131 (defun org-export-initialize-persistent-properties (data options backend
)
1132 "Initialize `org-export-persistent-properties'.
1134 DATA is the parse tree from which information is retrieved.
1135 OPTIONS is a list holding export options. BACKEND is the
1136 back-end called for transcoding, as a symbol.
1138 Following initial persistent properties are set:
1139 `:back-end' Back-end used for transcoding.
1141 `:headline-alist' Alist of all headlines' name as key and a list
1142 holding beginning and ending positions as
1145 `:headline-offset' Offset between true level of headlines and
1146 local level. An offset of -1 means an headline
1147 of level 2 should be considered as a level
1148 1 headline in the context.
1150 `:headline-numbering' Alist of all headlines' beginning position
1151 as key an the associated numbering as value.
1153 `:parse-tree' Whole parse tree.
1155 `:point-max' Last position in the parse tree
1157 `:target-list' List of all targets' raw name in the parse tree.
1159 `:use-select-tags' Non-nil when parsed tree use a special tag to
1160 enforce transcoding of the headline."
1161 ;; First delete any residual persistent property.
1162 (setq org-export-persistent-properties nil
)
1163 ;; Immediately after, set `:use-select-tags' property, as it will be
1164 ;; required for further computations.
1166 (org-export-set-property
1169 (org-export-use-select-tags-p data options
)))
1170 ;; Get the rest of the initial persistent properties, now
1171 ;; `:use-select-tags' is set...
1172 ;; 1. `:parse-tree' ...
1173 (setq options
(org-export-set-property options
:parse-tree data
))
1174 ;; 2. `:headline-offset' ...
1176 (org-export-set-property
1177 options
:headline-offset
1178 (- 1 (org-export-get-min-level data options
))))
1179 ;; 3. `:point-max' ...
1180 (setq options
(org-export-set-property
1182 (org-export-get-point-max data options
)))
1183 ;; 4. `:target-list'...
1184 (setq options
(org-export-set-property
1185 options
:target-list
1188 (lambda (target info
)
1189 (org-element-get-property :raw-value target
)))))
1190 ;; 5. `:headline-alist'
1191 (setq options
(org-export-set-property
1192 options
:headline-alist
1195 (lambda (headline info
)
1196 (list (org-element-get-property :raw-value headline
)
1197 (org-element-get-property :begin headline
)
1198 (org-element-get-property :end headline
))))))
1199 ;; 6. `:headline-numbering'
1200 (setq options
(org-export-set-property
1201 options
:headline-numbering
1202 (org-export-collect-headline-numbering data options
)))
1204 (setq options
(org-export-set-property options
:back-end backend
)))
1206 (defun org-export-use-select-tags-p (data options
)
1207 "Non-nil when data use a tag enforcing transcoding.
1208 DATA is parsed data as returned by `org-element-parse-buffer'.
1209 OPTIONS is a plist holding export options."
1213 (lambda (headline info
)
1214 (let ((tags (org-element-get-property :with-tags headline
)))
1215 (and tags
(string-match
1216 (format ":%s:" (plist-get info
:select-tags
)) tags
))))
1218 'stop-at-first-match
))
1220 (defun org-export-get-min-level (data options
)
1221 "Return minimum exportable headline's level in DATA.
1222 DATA is parsed tree as returned by `org-element-parse-buffer'.
1223 OPTIONS is a plist holding export options."
1225 (let ((min-level 10000))
1226 (mapc (lambda (blob)
1227 (when (and (eq (car blob
) 'headline
)
1228 (not (org-export-skip-p blob options
)))
1230 (min (org-element-get-property :level blob
) min-level
)))
1231 (when (= min-level
1) (throw 'exit
1)))
1232 (org-element-get-contents data
))
1233 ;; If no headline was found, for the sake of consistency, set
1234 ;; minimum level to 1 nonetheless.
1235 (if (= min-level
10000) 1 min-level
))))
1237 (defun org-export-get-point-max (data options
)
1238 "Return last exportable ending position in DATA.
1239 DATA is parsed tree as returned by `org-element-parse-buffer'.
1240 OPTIONS is a plist holding export options."
1242 (mapc (lambda (blob)
1243 (unless (and (eq (car blob
) 'headline
)
1244 (org-export-skip-p blob options
))
1245 (setq pos-max
(org-element-get-property :end blob
))))
1246 (org-element-get-contents data
))
1249 (defun org-export-collect-headline-numbering (data options
)
1250 "Return numbering of all exportable headlines in a parse tree.
1252 DATA is the parse tree. OPTIONS is the plist holding export
1255 Return an alist whose key is headline's beginning position and
1256 value is its associated numbering (in the shape of a list of
1258 (let ((numbering (make-vector org-export-max-depth
0)))
1262 (lambda (headline info
)
1263 (let ((relative-level
1264 (1- (org-export-get-relative-level headline info
))))
1266 (org-element-get-property :begin headline
)
1267 (loop for n across numbering
1268 for idx from
0 to org-export-max-depth
1269 when
(< idx relative-level
) collect n
1270 when
(= idx relative-level
) collect
(aset numbering idx
(1+ n
))
1271 when
(> idx relative-level
) do
(aset numbering idx
0)))))
1275 ;;;; Properties Management
1277 ;; This is mostly done with the help of two functions. On the one
1278 ;; hand `org-export-update-info' is used to keep up-to-date local
1279 ;; information while walking the nested list representing the parsed
1280 ;; document. On the other end, `org-export-set-property' handles
1281 ;; properties modifications according to their type (persistent or
1284 ;; As exceptions, `:code-refs' and `:total-loc' properties are updated
1285 ;; with `org-export-handle-code' function.
1287 (defun org-export-update-info (blob info recursep
)
1288 "Update export options depending on context.
1290 BLOB is the element or object being parsed. INFO is the plist
1291 holding the export options.
1293 When RECURSEP is non-nil, assume the following element or object
1294 will be inside the current one.
1296 The following properties are updated:
1297 `footnote-seen-labels' List of already parsed footnote
1298 labels (string list)
1299 `genealogy' List of current element's parents
1301 `inherited-properties' List of inherited properties from
1302 parent headlines (plist).
1303 `parent-properties' List of last element's properties
1305 `previous-element' Previous element's type (symbol).
1306 `previous-object' Previous object's type (symbol).
1308 Return the property list."
1309 (let* ((type (and (not (stringp blob
)) (car blob
))))
1311 ;; Case 1: We're moving into a recursive blob.
1315 `(:genealogy
,(cons type
(plist-get info
:genealogy
))
1316 :previous-element nil
1317 :previous-object nil
1319 ,(if (memq type org-element-all-elements
)
1321 (plist-get info
:parent-properties
))
1322 :inherited-properties
1323 ,(if (eq type
'headline
)
1325 (plist-get info
:inherited-properties
) (nth 1 blob
))
1326 (plist-get info
:inherited-properties
)))
1327 ;; Add persistent properties.
1328 org-export-persistent-properties
))
1329 ;; Case 2: No recursion.
1331 ;; At a footnote reference: mark its label as seen, if not
1332 ;; already the case.
1333 (when (eq type
'footnote-reference
)
1334 (let ((label (org-element-get-property :label blob
))
1335 (seen-labels (plist-get org-export-persistent-properties
1336 :footnote-seen-labels
)))
1337 ;; Store anonymous footnotes (nil label) without checking if
1338 ;; another anonymous footnote was seen before.
1339 (unless (and label
(member label seen-labels
))
1340 (setq info
(org-export-set-property
1341 info
:footnote-seen-labels
(push label seen-labels
))))))
1342 ;; Set `:previous-element' or `:previous-object' according to
1344 (setq info
(cond ((not type
)
1345 (org-export-set-property
1346 info
:previous-object
'plain-text
))
1347 ((memq type org-element-all-elements
)
1348 (org-export-set-property info
:previous-element type
))
1349 (t (org-export-set-property info
:previous-object type
))))
1350 ;; Return updated value.
1353 (defun org-export-set-property (info prop value
)
1354 "Set property PROP to VALUE in plist INFO.
1355 Return the new plist."
1356 (when (memq prop org-export-persistent-properties-list
)
1357 (setq org-export-persistent-properties
1358 (plist-put org-export-persistent-properties prop value
)))
1359 (plist-put info prop value
))
1365 ;; This function reads Org data (obtained with, i.e.
1366 ;; `org-element-parse-buffer') and transcodes it into a specified
1367 ;; back-end output. It takes care of updating local properties,
1368 ;; filtering out elements or objects according to export options and
1369 ;; organizing the output blank lines and white space are preserved.
1371 ;; Though, this function is inapropriate for secondary strings, which
1372 ;; require a fresh copy of the plist passed as INFO argument. Thus,
1373 ;; `org-export-secondary-string' is provided for that specific task.
1375 ;; Internally, three functions handle the filtering of objects and
1376 ;; elements during the export. More precisely, `org-export-skip-p'
1377 ;; determines if the considered object or element should be ignored
1378 ;; altogether, `org-export-interpret-p' tells which elements or
1379 ;; objects should be seen as real Org syntax and `org-export-expand'
1380 ;; transforms the others back into their original shape.
1382 (defun org-export-data (data backend info
)
1383 "Convert DATA to a string into BACKEND format.
1385 DATA is a nested list as returned by `org-element-parse-buffer'.
1387 BACKEND is a symbol among supported exporters.
1389 INFO is a plist holding export options and also used as
1390 a communication channel between elements when walking the nested
1391 list. See `org-export-update-info' function for more
1394 Return transcoded string."
1396 ;; BLOB can be an element, an object, a string, or nil.
1399 ((not blob
) nil
) ((equal blob
"") nil
)
1400 ;; BLOB is a string. Check if the optional transcoder for plain
1401 ;; text exists, and call it in that case. Otherwise, simply
1402 ;; return string. Also update INFO and call
1403 ;; `org-export-filter-plain-text-functions'.
1405 (setq info
(org-export-update-info blob info nil
))
1406 (let ((transcoder (intern (format "org-%s-plain-text" backend
))))
1407 (org-export-filter-apply-functions
1408 org-export-filter-plain-text-functions
1409 (if (fboundp transcoder
) (funcall transcoder blob info
) blob
)
1411 ;; BLOB is an element or an object.
1413 (let* ((type (if (stringp blob
) 'plain-text
(car blob
)))
1414 ;; 1. Determine the appropriate TRANSCODER.
1417 ;; 1.0 A full Org document is inserted.
1418 ((eq type
'org-data
) 'identity
)
1419 ;; 1.1. BLOB should be ignored.
1420 ((org-export-skip-p blob info
) nil
)
1421 ;; 1.2. BLOB shouldn't be transcoded. Interpret it
1422 ;; back into Org syntax.
1423 ((not (org-export-interpret-p blob info
))
1425 ;; 1.3. Else apply naming convention.
1426 (t (let ((trans (intern
1427 (format "org-%s-%s" backend type
))))
1428 (and (fboundp trans
) trans
)))))
1429 ;; 2. Compute CONTENTS of BLOB.
1432 ;; Case 0. No transcoder defined: ignore BLOB.
1433 ((not transcoder
) nil
)
1434 ;; Case 1. Transparently export an Org document.
1435 ((eq type
'org-data
)
1436 (org-export-data blob backend info
))
1437 ;; Case 2. For a recursive object.
1438 ((memq type org-element-recursive-objects
)
1440 blob backend
(org-export-update-info blob info t
)))
1441 ;; Case 3. For a recursive element.
1442 ((memq type org-element-greater-elements
)
1443 ;; Ignore contents of an archived tree
1444 ;; when `:with-archived-trees' is `headline'.
1447 (eq (plist-get info
:with-archived-trees
) 'headline
)
1448 (org-element-get-property :archivedp blob
))
1449 (org-element-normalize-string
1451 blob backend
(org-export-update-info blob info t
)))))
1452 ;; Case 4. For a paragraph.
1453 ((eq type
'paragraph
)
1455 (org-element-normalize-contents
1457 ;; When normalizing contents of an item or
1458 ;; a footnote definition, ignore first line's
1459 ;; indentation: there is none and it might be
1461 (and (not (plist-get info
:previous-element
))
1462 (let ((parent (car (plist-get info
:genealogy
))))
1463 (memq parent
'(footnote-definition item
)))))))
1467 (org-export-update-info blob info t
))))))
1468 ;; 3. Transcode BLOB into RESULTS string.
1470 ((not transcoder
) nil
)
1471 ((eq transcoder
'org-export-expand
)
1473 `(org-data nil
,(funcall transcoder blob contents
))
1475 (t (funcall transcoder blob contents info
)))))
1476 ;; 4. Discard nil results. Otherwise, update INFO, append
1477 ;; the same white space between elements or objects as in
1478 ;; the original buffer, and call appropriate filters.
1480 (setq info
(org-export-update-info blob info nil
))
1481 ;; No filter for a full document.
1482 (if (eq type
'org-data
)
1484 (org-export-filter-apply-functions
1485 (eval (intern (format "org-export-filter-%s-functions" type
)))
1486 (if (memq type org-element-all-elements
)
1488 (org-element-normalize-string results
)
1489 (make-string (org-element-get-property :post-blank blob
) 10))
1493 (org-element-get-property :post-blank blob
) 32)))
1495 (org-element-get-contents data
) ""))
1497 (defun org-export-secondary-string (secondary backend info
)
1498 "Convert SECONDARY string into BACKEND format.
1500 SECONDARY is a nested list as returned by
1501 `org-element-parse-secondary-string'.
1503 BACKEND is a symbol among supported exporters.
1505 INFO is a plist holding export options and also used as
1506 a communication channel between elements when walking the nested
1507 list. See `org-export-update-info' function for more
1510 Return transcoded string."
1511 ;; Make SECONDARY acceptable for `org-export-data'.
1512 (let ((s (if (listp secondary
) secondary
(list secondary
))))
1513 (org-export-data `(org-data nil
,@s
) backend
(copy-sequence info
))))
1515 (defun org-export-skip-p (blob info
)
1516 "Non-nil when element or object BLOB should be skipped during export.
1517 INFO is the plist holding export options."
1519 (unless (stringp blob
)
1522 (let ((with-tasks (plist-get info
:with-tasks
))
1523 (todo (org-element-get-property :todo-keyword blob
))
1524 (todo-type (org-element-get-property :todo-type blob
))
1525 (archived (plist-get info
:with-archived-trees
))
1526 (tag-list (let ((tags (org-element-get-property :tags blob
)))
1527 (and tags
(org-split-string tags
":")))))
1529 ;; Ignore subtrees with an exclude tag.
1530 (loop for k in
(plist-get info
:exclude-tags
)
1531 thereis
(member k tag-list
))
1532 ;; Ignore subtrees without a select tag, when such tag is found
1534 (and (plist-get info
:use-select-tags
)
1535 (loop for k in
(plist-get info
:select-tags
)
1536 never
(member k tag-list
)))
1537 ;; Ignore commented sub-trees.
1538 (org-element-get-property :commentedp blob
)
1539 ;; Ignore archived subtrees if `:with-archived-trees' is nil.
1540 (and (not archived
) (org-element-get-property :archivedp blob
))
1541 ;; Ignore tasks, if specified by `:with-tasks' property.
1542 (and todo
(not with-tasks
))
1544 (memq with-tasks
'(todo done
))
1545 (not (eq todo-type with-tasks
)))
1548 (not (member todo with-tasks
))))))
1549 ;; Check time-stamp.
1550 ('time-stamp
(not (plist-get info
:with-timestamps
)))
1553 (or (not (plist-get info
:with-drawers
))
1554 (and (consp (plist-get info
:with-drawers
))
1555 (not (member (org-element-get-property :drawer-name blob
)
1556 (plist-get info
:with-drawers
))))))
1557 ;; Check export snippet.
1559 (let* ((raw-back-end (org-element-get-property :back-end blob
))
1561 (or (cdr (assoc raw-back-end org-export-snippet-translation-alist
))
1563 (not (string= (symbol-name (plist-get info
:back-end
))
1564 true-back-end
)))))))
1566 (defun org-export-interpret-p (blob info
)
1567 "Non-nil if element or object BLOB should be interpreted as Org syntax.
1568 Check is done according to export options INFO, stored as
1572 (entity (plist-get info
:with-entities
))
1574 (emphasis (plist-get info
:with-emphasize
))
1575 ;; ... fixed-width areas.
1576 (fixed-width (plist-get info
:with-fixed-width
))
1578 ((footnote-definition footnote-reference
)
1579 (plist-get info
:with-footnotes
))
1580 ;; ... sub/superscripts...
1581 ((subscript superscript
)
1582 (let ((sub/super-p
(plist-get info
:with-sub-superscript
)))
1583 (if (eq sub
/super-p
'{})
1584 (org-element-get-property :use-brackets-p blob
)
1587 (table (plist-get info
:with-tables
))
1590 (defsubst org-export-expand
(blob contents
)
1591 "Expand a parsed element or object to its original state.
1592 BLOB is either an element or an object. CONTENTS is its
1593 contents, as a string or nil."
1595 (intern (format "org-element-%s-interpreter" (car blob
))) blob contents
))
1599 ;;; The Filter System
1601 ;; Filters allow end-users to tweak easily the transcoded output.
1602 ;; They are the functional counterpart of hooks, as every filter in
1603 ;; a set is applied to the return value of the previous one.
1605 ;; Every set is back-end agnostic. Although, a filter is always
1606 ;; called, in addition to the string it applies to, with the back-end
1607 ;; used as argument, so it's easy enough for the end-user to add
1608 ;; back-end specific filters in the set.
1610 ;; Filters sets are defined below. There are of four types:
1612 ;; - `org-export-filter-parse-tree-functions' applies directly on the
1613 ;; complete parsed tree. It's the only filters set that doesn't
1614 ;; apply to a string.
1615 ;; - `org-export-filter-final-output-functions' applies to the final
1616 ;; transcoded string.
1617 ;; - `org-export-filter-plain-text-functions' applies to any string
1618 ;; not recognized as Org syntax.
1619 ;; - `org-export-filter-TYPE-functions' applies on the string returned
1620 ;; after an element or object of type TYPE has been transcoded.
1622 ;; All filters sets are applied through
1623 ;; `org-export-filter-apply-functions' function. Filters in a set are
1624 ;; applied in reverse order, that is in the order of consing. It
1625 ;; allows developers to be reasonably sure that their filters will be
1628 ;;;; Special Filters
1629 (defvar org-export-filter-parse-tree-functions nil
1630 "Filter, or list of filters, applied to the parsed tree.
1631 Each filter is called with two arguments: the parse tree, as
1632 returned by `org-element-parse-buffer', and the back-end as
1633 a symbol. It must return the modified parse tree to transcode.")
1635 (defvar org-export-filter-final-output-functions nil
1636 "Filter, or list of filters, applied to the transcoded string.
1637 Each filter is called with two arguments: the full transcoded
1638 string, and the back-end as a symbol. It must return a string
1639 that will be used as the final export output.")
1641 (defvar org-export-filter-plain-text-functions nil
1642 "Filter, or list of filters, applied to plain text.
1643 Each filter is called with two arguments: a string which contains
1644 no Org syntax, and the back-end as a symbol. It must return
1648 ;;;; Elements Filters
1650 (defvar org-export-filter-center-block-functions nil
1651 "Filter, or list of filters, applied to a transcoded center block.
1652 Each filter is called with two arguments: the transcoded center
1653 block, as a string, and the back-end, as a symbol. It must
1654 return a string or nil.")
1656 (defvar org-export-filter-drawer-functions nil
1657 "Filter, or list of filters, applied to a transcoded drawer.
1658 Each filter is called with two arguments: the transcoded drawer,
1659 as a string, and the back-end, as a symbol. It must return
1662 (defvar org-export-filter-dynamic-block-functions nil
1663 "Filter, or list of filters, applied to a transcoded dynamic-block.
1664 Each filter is called with two arguments: the transcoded
1665 dynamic-block, as a string, and the back-end, as a symbol. It
1666 must return a string or nil.")
1668 (defvar org-export-filter-headline-functions nil
1669 "Filter, or list of filters, applied to a transcoded headline.
1670 Each filter is called with two arguments: the transcoded
1671 headline, as a string, and the back-end, as a symbol. It must
1672 return a string or nil.")
1674 (defvar org-export-filter-inlinetask-functions nil
1675 "Filter, or list of filters, applied to a transcoded inlinetask.
1676 Each filter is called with two arguments: the transcoded
1677 inlinetask, as a string, and the back-end, as a symbol. It must
1678 return a string or nil.")
1680 (defvar org-export-filter-plain-list-functions nil
1681 "Filter, or list of filters, applied to a transcoded plain-list.
1682 Each filter is called with two arguments: the transcoded
1683 plain-list, as a string, and the back-end, as a symbol. It must
1684 return a string or nil.")
1686 (defvar org-export-filter-item-functions nil
1687 "Filter, or list of filters, applied to a transcoded item.
1688 Each filter is called with two arguments: the transcoded item, as
1689 a string, and the back-end, as a symbol. It must return a string
1692 (defvar org-export-filter-comment-functions nil
1693 "Filter, or list of filters, applied to a transcoded comment.
1694 Each filter is called with two arguments: the transcoded comment,
1695 as a string, and the back-end, as a symbol. It must return
1698 (defvar org-export-filter-comment-block-functions nil
1699 "Filter, or list of filters, applied to a transcoded comment-comment.
1700 Each filter is called with two arguments: the transcoded
1701 comment-block, as a string, and the back-end, as a symbol. It
1702 must return a string or nil.")
1704 (defvar org-export-filter-example-block-functions nil
1705 "Filter, or list of filters, applied to a transcoded example-block.
1706 Each filter is called with two arguments: the transcoded
1707 example-block, as a string, and the back-end, as a symbol. It
1708 must return a string or nil.")
1710 (defvar org-export-filter-export-block-functions nil
1711 "Filter, or list of filters, applied to a transcoded export-block.
1712 Each filter is called with two arguments: the transcoded
1713 export-block, as a string, and the back-end, as a symbol. It
1714 must return a string or nil.")
1716 (defvar org-export-filter-fixed-width-functions nil
1717 "Filter, or list of filters, applied to a transcoded fixed-width.
1718 Each filter is called with two arguments: the transcoded
1719 fixed-width, as a string, and the back-end, as a symbol. It must
1720 return a string or nil.")
1722 (defvar org-export-filter-footnote-definition-functions nil
1723 "Filter, or list of filters, applied to a transcoded footnote-definition.
1724 Each filter is called with two arguments: the transcoded
1725 footnote-definition, as a string, and the back-end, as a symbol.
1726 It must return a string or nil.")
1728 (defvar org-export-filter-horizontal-rule-functions nil
1729 "Filter, or list of filters, applied to a transcoded horizontal-rule.
1730 Each filter is called with two arguments: the transcoded
1731 horizontal-rule, as a string, and the back-end, as a symbol. It
1732 must return a string or nil.")
1734 (defvar org-export-filter-keyword-functions nil
1735 "Filter, or list of filters, applied to a transcoded keyword.
1736 Each filter is called with two arguments: the transcoded keyword,
1737 as a string, and the back-end, as a symbol. It must return
1740 (defvar org-export-filter-latex-environment-functions nil
1741 "Filter, or list of filters, applied to a transcoded latex-environment.
1742 Each filter is called with two arguments: the transcoded
1743 latex-environment, as a string, and the back-end, as a symbol.
1744 It must return a string or nil.")
1746 (defvar org-export-filter-babel-call-functions nil
1747 "Filter, or list of filters, applied to a transcoded babel-call.
1748 Each filter is called with two arguments: the transcoded
1749 babel-call, as a string, and the back-end, as a symbol. It must
1750 return a string or nil.")
1752 (defvar org-export-filter-paragraph-functions nil
1753 "Filter, or list of filters, applied to a transcoded paragraph.
1754 Each filter is called with two arguments: the transcoded
1755 paragraph, as a string, and the back-end, as a symbol. It must
1756 return a string or nil.")
1758 (defvar org-export-filter-property-drawer-functions nil
1759 "Filter, or list of filters, applied to a transcoded property-drawer.
1760 Each filter is called with two arguments: the transcoded
1761 property-drawer, as a string, and the back-end, as a symbol. It
1762 must return a string or nil.")
1764 (defvar org-export-filter-quote-block-functions nil
1765 "Filter, or list of filters, applied to a transcoded quote block.
1766 Each filter is called with two arguments: the transcoded quote
1767 block, as a string, and the back-end, as a symbol. It must
1768 return a string or nil.")
1770 (defvar org-export-filter-quote-section-functions nil
1771 "Filter, or list of filters, applied to a transcoded quote-section.
1772 Each filter is called with two arguments: the transcoded
1773 quote-section, as a string, and the back-end, as a symbol. It
1774 must return a string or nil.")
1776 (defvar org-export-filter-special-block-functions nil
1777 "Filter, or list of filters, applied to a transcoded special block.
1778 Each filter is called with two arguments: the transcoded special
1779 block, as a string, and the back-end, as a symbol. It must
1780 return a string or nil.")
1782 (defvar org-export-filter-src-block-functions nil
1783 "Filter, or list of filters, applied to a transcoded src-block.
1784 Each filter is called with two arguments: the transcoded
1785 src-block, as a string, and the back-end, as a symbol. It must
1786 return a string or nil.")
1788 (defvar org-export-filter-table-functions nil
1789 "Filter, or list of filters, applied to a transcoded table.
1790 Each filter is called with two arguments: the transcoded table,
1791 as a string, and the back-end, as a symbol. It must return
1794 (defvar org-export-filter-verse-block-functions nil
1795 "Filter, or list of filters, applied to a transcoded verse block.
1796 Each filter is called with two arguments: the transcoded verse
1797 block, as a string, and the back-end, as a symbol. It must
1798 return a string or nil.")
1801 ;;;; Objects Filters
1803 (defvar org-export-filter-emphasis-functions nil
1804 "Filter, or list of filters, applied to a transcoded emphasis.
1805 Each filter is called with two arguments: the transcoded
1806 emphasis, as a string, and the back-end, as a symbol. It must
1807 return a string or nil.")
1809 (defvar org-export-filter-entity-functions nil
1810 "Filter, or list of filters, applied to a transcoded entity.
1811 Each filter is called with two arguments: the transcoded entity,
1812 as a string, and the back-end, as a symbol. It must return
1815 (defvar org-export-filter-export-snippet-functions nil
1816 "Filter, or list of filters, applied to a transcoded export-snippet.
1817 Each filter is called with two arguments: the transcoded
1818 export-snippet, as a string, and the back-end, as a symbol. It
1819 must return a string or nil.")
1821 (defvar org-export-filter-footnote-reference-functions nil
1822 "Filter, or list of filters, applied to a transcoded footnote-reference.
1823 Each filter is called with two arguments: the transcoded
1824 footnote-reference, as a string, and the back-end, as a symbol.
1825 It must return a string or nil.")
1827 (defvar org-export-filter-inline-babel-call-functions nil
1828 "Filter, or list of filters, applied to a transcoded inline-babel-call.
1829 Each filter is called with two arguments: the transcoded
1830 inline-babel-call, as a string, and the back-end, as a symbol. It
1831 must return a string or nil.")
1833 (defvar org-export-filter-inline-src-block-functions nil
1834 "Filter, or list of filters, applied to a transcoded inline-src-block.
1835 Each filter is called with two arguments: the transcoded
1836 inline-src-block, as a string, and the back-end, as a symbol. It
1837 must return a string or nil.")
1839 (defvar org-export-filter-latex-fragment-functions nil
1840 "Filter, or list of filters, applied to a transcoded latex-fragment.
1841 Each filter is called with two arguments: the transcoded
1842 latex-fragment, as a string, and the back-end, as a symbol. It
1843 must return a string or nil.")
1845 (defvar org-export-filter-line-break-functions nil
1846 "Filter, or list of filters, applied to a transcoded line-break.
1847 Each filter is called with two arguments: the transcoded
1848 line-break, as a string, and the back-end, as a symbol. It must
1849 return a string or nil.")
1851 (defvar org-export-filter-link-functions nil
1852 "Filter, or list of filters, applied to a transcoded link.
1853 Each filter is called with two arguments: the transcoded link, as
1854 a string, and the back-end, as a symbol. It must return a string
1857 (defvar org-export-filter-macro-functions nil
1858 "Filter, or list of filters, applied to a transcoded macro.
1859 Each filter is called with two arguments: the transcoded macro,
1860 as a string, and the back-end, as a symbol. It must return
1863 (defvar org-export-filter-radio-target-functions nil
1864 "Filter, or list of filters, applied to a transcoded radio-target.
1865 Each filter is called with two arguments: the transcoded
1866 radio-target, as a string, and the back-end, as a symbol. It
1867 must return a string or nil.")
1869 (defvar org-export-filter-statistics-cookie-functions nil
1870 "Filter, or list of filters, applied to a transcoded statistics-cookie.
1871 Each filter is called with two arguments: the transcoded
1872 statistics-cookie, as a string, and the back-end, as a symbol.
1873 It must return a string or nil.")
1875 (defvar org-export-filter-subscript-functions nil
1876 "Filter, or list of filters, applied to a transcoded subscript.
1877 Each filter is called with two arguments: the transcoded
1878 subscript, as a string, and the back-end, as a symbol. It must
1879 return a string or nil.")
1881 (defvar org-export-filter-superscript-functions nil
1882 "Filter, or list of filters, applied to a transcoded superscript.
1883 Each filter is called with two arguments: the transcoded
1884 superscript, as a string, and the back-end, as a symbol. It must
1885 return a string or nil.")
1887 (defvar org-export-filter-target-functions nil
1888 "Filter, or list of filters, applied to a transcoded target.
1889 Each filter is called with two arguments: the transcoded target,
1890 as a string, and the back-end, as a symbol. It must return
1893 (defvar org-export-filter-time-stamp-functions nil
1894 "Filter, or list of filters, applied to a transcoded time-stamp.
1895 Each filter is called with two arguments: the transcoded
1896 time-stamp, as a string, and the back-end, as a symbol. It must
1897 return a string or nil.")
1899 (defvar org-export-filter-verbatim-functions nil
1900 "Filter, or list of filters, applied to a transcoded verbatim.
1901 Each filter is called with two arguments: the transcoded
1902 verbatim, as a string, and the back-end, as a symbol. It must
1903 return a string or nil.")
1905 (defun org-export-filter-apply-functions (filters value backend
)
1906 "Call every function in FILTERS with arguments VALUE and BACKEND.
1907 Functions are called in reverse order, to be reasonably sure that
1908 developer-specified filters, if any, are called first."
1909 ;; Ensure FILTERS is a list.
1910 (let ((filters (if (listp filters
) (reverse filters
) (list filters
))))
1911 (loop for filter in filters
1912 if
(not value
) return nil else
1913 do
(setq value
(funcall filter value backend
))))
1920 ;; This is the room for the main function, `org-export-as', along with
1921 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
1922 ;; They differ only by the way they output the resulting code.
1924 ;; Note that `org-export-as' doesn't really parse the current buffer,
1925 ;; but a copy of it (with the same buffer-local variables and
1926 ;; visibility), where Babel blocks are executed, if appropriate.
1927 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
1929 (defun org-export-as (backend
1930 &optional subtreep visible-only body-only ext-plist
)
1931 "Transcode current Org buffer into BACKEND code.
1933 If narrowing is active in the current buffer, only transcode its
1936 If a region is active, transcode that region.
1938 When optional argument SUBTREEP is non-nil, transcode the
1939 sub-tree at point, extracting information from the headline
1942 When optional argument VISIBLE-ONLY is non-nil, don't export
1943 contents of hidden elements.
1945 When optional argument BODY-ONLY is non-nil, only return body
1946 code, without preamble nor postamble.
1948 EXT-PLIST, when provided, is a property list with external
1949 parameters overriding Org default settings, but still inferior to
1950 file-local settings.
1952 Return code as a string."
1955 ;; Narrow buffer to an appropriate region for parsing.
1956 (when (org-region-active-p)
1957 (narrow-to-region (region-beginning) (region-end)))
1958 (goto-char (point-min))
1960 (unless (org-at-heading-p)
1961 (org-with-limited-levels (outline-next-heading)))
1962 (let ((end (save-excursion (org-end-of-subtree t
)))
1963 (begin (progn (forward-line)
1964 (org-skip-whitespace)
1966 (narrow-to-region begin end
)))
1967 ;; Retrieve export options (INFO) and parsed tree (RAW-DATA).
1968 ;; Buffer isn't parsed directly. Instead, a temporary copy is
1969 ;; created, where all code blocks are evaluated. RAW-DATA is
1970 ;; the parsed tree of the buffer resulting from that process.
1971 ;; Eventually call `org-export-filter-parse-tree-functions'..
1972 (let ((info (org-export-collect-options backend subtreep ext-plist
))
1973 (raw-data (org-export-filter-apply-functions
1974 org-export-filter-parse-tree-functions
1975 (org-export-with-current-buffer-copy
1976 (org-export-blocks-preprocess)
1977 (org-element-parse-buffer nil visible-only
))
1979 ;; Initialize the communication system and combine it to INFO.
1983 (org-export-initialize-persistent-properties
1984 raw-data info backend
)))
1985 ;; Now transcode RAW-DATA. Also call
1986 ;; `org-export-filter-final-output-functions'.
1987 (let ((body (org-element-normalize-string
1988 (org-export-data raw-data backend info
)))
1989 (template (intern (format "org-%s-template" backend
))))
1990 (if (and (not body-only
) (fboundp template
))
1992 (org-export-filter-apply-functions
1993 org-export-filter-final-output-functions
1994 (funcall template body info
)
1996 (org-export-filter-apply-functions
1997 org-export-filter-final-output-functions body backend
)))))))
1999 (defun org-export-to-buffer (backend buffer
&optional subtreep visible-only
2000 body-only ext-plist
)
2001 "Call `org-export-as' with output to a specified buffer.
2003 BACKEND is the back-end used for transcoding, as a symbol.
2005 BUFFER is the output buffer. If it already exists, it will be
2006 erased first, otherwise, it will be created.
2008 Arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and EXT-PLIST are
2009 similar to those used in `org-export-as', which see.
2012 (let ((out (org-export-as backend subtreep visible-only body-only ext-plist
))
2013 (buffer (get-buffer-create buffer
)))
2014 (with-current-buffer buffer
2017 (goto-char (point-min)))
2020 (defun org-export-to-file (backend filename
&optional post-process subtreep
2021 visible-only body-only ext-plist
)
2022 "Call `org-export-as' with output to a specified file.
2024 BACKEND is the back-end used for transcoding, as a symbol.
2026 FILENAME is the output file name. If it already exists, it will
2027 be erased first, unless it isn't writable, in which case an error
2028 will be returned. Otherwise, the file will be created.
2030 Optional argument POST-PROCESS, when non-nil, is a function
2031 applied to the output file. It expects one argument: the file
2032 name, as a string. It can be used to call shell commands on that
2033 file, display a specific buffer, etc.
2035 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and
2036 EXT-PLIST are similar to those used in `org-export-as', which
2040 ;; Checks for file and directory permissions.
2042 ((not (file-exists-p filename
))
2043 (let ((dir (or (file-name-directory filename
) default-directory
)))
2044 (unless (file-writable-p dir
) (error "Output directory not writable"))))
2045 ((not (file-writable-p filename
)) (error "Output file not writable")))
2046 ;; All checks passed: insert contents to a temporary buffer and
2047 ;; write it to the specified file.
2048 (let ((out (org-export-as backend subtreep visible-only body-only ext-plist
)))
2051 (write-file filename
)))
2052 (when post-process
(funcall post-process filename
))
2056 (defmacro org-export-with-current-buffer-copy
(&rest body
)
2057 "Apply BODY in a copy of the current buffer.
2059 The copy preserves local variables and visibility of the original
2062 Point is at buffer's beginning when BODY is applied."
2063 (org-with-gensyms (original-buffer offset buffer-string overlays
)
2064 `(let ((,original-buffer
,(current-buffer))
2065 (,offset
,(1- (point-min)))
2066 (,buffer-string
,(buffer-string))
2068 'copy-overlay
(overlays-in (point-min) (point-max)))))
2070 (let ((buffer-invisibility-spec nil
))
2071 (org-clone-local-variables
2072 ,original-buffer
"^\\(org-\\|orgtbl-\\|major-mode$\\)")
2073 (insert ,buffer-string
)
2077 (- (overlay-start ov
) ,offset
)
2078 (- (overlay-end ov
) ,offset
)
2081 (goto-char (point-min))
2083 (def-edebug-spec org-export-with-current-buffer-copy
(body))
2087 ;;; Tools For Back-Ends
2089 ;; A whole set of tools is available to help build new exporters. Any
2090 ;; function general enough to have its use across many back-ends
2091 ;; should be added here.
2093 ;; As of now, functions operating on footnotes, headlines, include
2094 ;; keywords, links, macros, references, src-blocks, tables and tables
2095 ;; of contents are implemented.
2099 ;; `org-export-collect-footnote-definitions' is a tool to list
2100 ;; actually used footnotes definitions in the whole parse tree, or in
2101 ;; an headline, in order to add footnote listings throughout the
2104 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2105 ;; back-ends, when they need to attach the footnote definition only to
2106 ;; the first occurrence of the corresponding label.
2108 ;; `org-export-get-footnote-definition' and
2109 ;; `org-export-get-footnote-number' provide easier access to
2110 ;; additional information relative to a footnote reference.
2112 (defun org-export-collect-footnote-definitions (data info
)
2113 "Return an alist between footnote label and its definition.
2115 DATA is the parse tree from which definitions are collected.
2116 INFO is the plist used as a communication channel.
2118 As anonymous footnotes have no label, the key used is that case
2119 is their beginning position.
2121 Definitions are sorted by order of references. They either
2122 appear as Org data \(transcoded with `org-export-data'\) or as
2123 a secondary string for inlined footnotes \(transcoded with
2124 `org-export-secondary-string'\). Unreferenced definitions are
2127 data
'footnote-reference
2128 (lambda (footnote local
)
2130 ;; Definition already collected.
2131 ((not (org-export-footnote-first-reference-p footnote local
)) nil
)
2132 ;; Reference has a label: Use it as a key, and get the
2133 ;; corresponding definition.
2134 ((org-element-get-property :label footnote
)
2135 (cons (org-element-get-property :label footnote
)
2136 (org-export-get-footnote-definition footnote local
)))
2137 ;; No label: This is an anonymous footnote. Use beginning
2138 ;; position as the key and inline definition (a secondary
2139 ;; string) as its value.
2140 (t (cons (org-element-get-property :begin footnote
)
2141 (org-element-get-property :inline-definition footnote
)))))
2144 (defun org-export-footnote-first-reference-p (footnote-reference info
)
2145 "Non-nil when a footnote reference is the first one for its label.
2147 FOOTNOTE-REFERENCE is the footnote reference being considered.
2148 INFO is the plist used as a communication channel."
2149 (let ((label (org-element-get-property :label footnote-reference
)))
2150 (not (and label
(member label
(plist-get info
:footnote-seen-labels
))))))
2152 (defun org-export-get-footnote-definition (footnote-reference info
)
2153 "Return definition of FOOTNOTE-REFERENCE as parsed data.
2154 INFO is the plist used as a communication channel."
2155 (let ((label (org-element-get-property :label footnote-reference
)))
2156 (or (org-element-get-property :inline-definition footnote-reference
)
2157 (cdr (assoc label
(plist-get info
:footnote-definition-alist
))))))
2159 (defun org-export-get-footnote-number (footnote info
)
2160 "Return number associated to a footnote.
2162 FOOTNOTE is either a footnote reference or a footnote definition.
2163 INFO is the plist used as a communication channel."
2164 (let ((label (org-element-get-property :label footnote
)))
2165 (if (eq (car footnote
) 'footnote-definition
)
2166 ;; If a footnote definition was provided, first search for
2167 ;; a relative footnote reference, as only footnote references
2168 ;; can determine the associated ordinal.
2170 (plist-get info
:parse-tree
) 'footnote-reference
2171 (lambda (foot-ref local
)
2172 (when (string= (org-element-get-property :label foot-ref
) label
)
2173 (let* ((all-seen (plist-get info
:footnote-seen-labels
))
2174 (seenp (and label
(member label all-seen
))))
2175 (if seenp
(length seenp
) (1+ (length all-seen
))))))
2177 (let* ((all-seen (plist-get info
:footnote-seen-labels
))
2178 ;; Anonymous footnotes are always new footnotes.
2179 (seenp (and label
(member label all-seen
))))
2180 (if seenp
(length seenp
) (1+ (length all-seen
)))))))
2185 ;; `org-export-get-relative-level' is a shortcut to get headline
2186 ;; level, relatively to the lower headline level in the parsed tree.
2188 ;; `org-export-get-headline-number' returns the section number of an
2189 ;; headline, while `org-export-number-to-roman' allows to convert it
2190 ;; to roman numbers.
2192 ;; `org-export-first-sibling-p' and `org-export-last-sibling-p' are
2193 ;; two useful predicates when it comes to fulfill the
2194 ;; `:headline-levels' property.
2196 (defun org-export-get-relative-level (headline info
)
2197 "Return HEADLINE relative level within current parsed tree.
2198 INFO is a plist holding contextual information."
2199 (+ (org-element-get-property :level headline
)
2200 (or (plist-get info
:headline-offset
) 0)))
2202 (defun org-export-get-headline-number (headline info
)
2203 "Return HEADLINE numbering as a list of numbers.
2204 INFO is a plist holding contextual information."
2205 (cdr (assq (org-element-get-property :begin headline
)
2206 (plist-get info
:headline-numbering
))))
2208 (defun org-export-number-to-roman (n)
2209 "Convert integer N into a roman numeral."
2210 (let ((roman '((1000 .
"M") (900 .
"CM") (500 .
"D") (400 .
"CD")
2211 ( 100 .
"C") ( 90 .
"XC") ( 50 .
"L") ( 40 .
"XL")
2212 ( 10 .
"X") ( 9 .
"IX") ( 5 .
"V") ( 4 .
"IV")
2216 (number-to-string n
)
2218 (if (>= n
(caar roman
))
2219 (setq n
(- n
(caar roman
))
2220 res
(concat res
(cdar roman
)))
2224 (defun org-export-first-sibling-p (headline info
)
2225 "Non-nil when HEADLINE is the first sibling in its sub-tree.
2226 INFO is the plist used as a communication channel."
2227 (not (eq (plist-get info
:previous-element
) 'headline
)))
2229 (defun org-export-last-sibling-p (headline info
)
2230 "Non-nil when HEADLINE is the last sibling in its sub-tree.
2231 INFO is the plist used as a communication channel."
2232 (= (org-element-get-property :end headline
)
2233 (or (plist-get (plist-get info
:parent-properties
) :end
)
2234 (plist-get info
:point-max
))))
2237 ;;;; For Include Keywords
2239 ;; This section provides a tool to properly handle insertion of files
2240 ;; during export: `org-export-included-files'. It recursively
2241 ;; transcodes a file specfied by an include keyword.
2243 ;; It uses two helper functions: `org-export-get-file-contents'
2244 ;; returns contents of a file according to parameters specified in the
2245 ;; keyword while `org-export-parse-included-file' parses the file
2248 (defun org-export-included-file (keyword backend info
)
2249 "Transcode file specified with include KEYWORD.
2251 KEYWORD is the include keyword element transcoded. BACKEND is
2252 the language back-end used for transcoding. INFO is the plist
2253 used as a communication channel.
2255 This function updates `:included-files' and `:headline-offset'
2258 Return the transcoded string."
2259 (let ((data (org-export-parse-included-file keyword info
))
2260 (file (let ((value (org-element-get-property :value keyword
)))
2261 (and (string-match "^\"\\(\\S-+\\)\"" value
)
2262 (match-string 1 value
)))))
2263 (org-element-normalize-string
2268 ;; Store full path of already included files to avoid
2269 ;; recursive file inclusion.
2271 ,(cons (expand-file-name file
) (plist-get info
:included-files
))
2272 ;; Ensure that a top-level headline in the included
2273 ;; file becomes a direct child of the current headline
2276 ,(- (+ (plist-get (plist-get info
:inherited-properties
) :level
)
2277 (plist-get info
:headline-offset
))
2278 (1- (org-export-get-min-level data info
)))))))))
2280 (defun org-export-get-file-contents (file &optional lines
)
2281 "Get the contents of FILE and return them as a string.
2282 When optional argument LINES is a string specifying a range of
2283 lines, include only those lines."
2285 (insert-file-contents file
)
2287 (let* ((lines (split-string lines
"-"))
2288 (lbeg (string-to-number (car lines
)))
2289 (lend (string-to-number (cadr lines
)))
2290 (beg (if (zerop lbeg
) (point-min)
2291 (goto-char (point-min))
2292 (forward-line (1- lbeg
))
2294 (end (if (zerop lend
) (point-max)
2295 (goto-char (point-min))
2296 (forward-line (1- lend
))
2298 (narrow-to-region beg end
)))
2301 (defun org-export-parse-included-file (keyword info
)
2302 "Parse file specified by include KEYWORD.
2304 KEYWORD is the include keyword element transcoded. BACKEND is the
2305 language back-end used for transcoding. INFO is the plist used as
2306 a communication channel.
2308 Return the parsed tree."
2309 (let* ((value (org-element-get-property :value keyword
))
2310 (file (and (string-match "^\"\\(\\S-+\\)\"" value
)
2311 (prog1 (match-string 1 value
)
2312 (setq value
(replace-match "" nil nil value
)))))
2313 (lines (and (string-match
2314 ":lines +\"\\(\\(?:[0-9]+\\)?-\\(?:[0-9]+\\)?\\)\"" value
)
2315 (prog1 (match-string 1 value
)
2316 (setq value
(replace-match "" nil nil value
)))))
2317 (env (cond ((string-match "\\<example\\>" value
) "example")
2318 ((string-match "\\<src\\(?: +\\(.*\\)\\)?" value
)
2319 (match-string 1 value
)))))
2322 (not (file-exists-p file
))
2323 (not (file-readable-p file
)))
2324 (format "Cannot include file %s" file
))
2326 (member (expand-file-name file
) (plist-get info
:included-files
)))
2327 (error "Recursive file inclusion: %S" file
))
2328 (t (let ((raw (org-element-normalize-string
2329 (org-export-get-file-contents
2330 (expand-file-name file
) lines
))))
2331 ;; If environment isn't specified, Insert file in
2332 ;; a temporary buffer and parse it as Org syntax.
2333 ;; Otherwise, build the element representing the file.
2337 (insert raw
) (org-mode) (org-element-parse-buffer)))
2338 ((string= "example" env
)
2339 `(org-data nil
(example-block (:value
,raw
:post-blank
0))))
2343 (src-block (:value
,raw
:language
,env
:post-blank
0))))))))))
2348 ;; `org-export-solidify-link-text' turns a string into a safer version
2349 ;; for links, replacing most non-standard characters with hyphens.
2351 ;; `org-export-get-coderef-format' returns an appropriate format
2352 ;; string for coderefs.
2354 ;; `org-export-inline-image-p' returns a non-nil value when the link
2355 ;; provided should be considered as an inline image.
2357 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
2358 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
2359 ;; returns an appropriate unique identifier when found, or nil.
2361 (defun org-export-solidify-link-text (s)
2362 "Take link text and make a safe target out of it."
2364 (mapconcat 'identity
(org-split-string s
"[^a-zA-Z0-9_\\.-]+") "-")))
2366 (defun org-export-get-coderef-format (path desc
)
2367 "Return format string for code reference link.
2368 PATH is the link path. DESC is its description."
2370 (cond ((string-match (regexp-quote (concat "(" path
")")) desc
)
2371 (replace-match "%s" t t desc
))
2372 ((string= desc
"") "%s")
2375 (defun org-export-inline-image-p (link &optional extensions
)
2376 "Non-nil if LINK object points to an inline image.
2378 When non-nil, optional argument EXTENSIONS is a list of valid
2379 extensions for image files, as strings. Otherwise, a default
2380 list is provided \(cf. `org-image-file-name-regexp'\)."
2381 (and (not (org-element-get-contents link
))
2382 (string= (org-element-get-property :type link
) "file")
2384 (expand-file-name (org-element-get-property :path link
))
2387 (defun org-export-resolve-fuzzy-link (link info
)
2388 "Return an unique identifier for LINK destination.
2390 INFO is a plist holding contextual information.
2392 Return value can be a string, an buffer position, or nil:
2394 - If LINK path exactly matches any target, return its name as the
2397 - If LINK path exactly matches any headline name, return
2398 headline's beginning position as the identifier. If more than
2399 one headline share that name, priority will be given to the one
2400 with the closest common ancestor, if any, or the first one in
2401 the parse tree otherwise.
2403 - Otherwise, return nil.
2405 Assume LINK type is \"fuzzy\"."
2406 (let ((path (org-element-get-property :path link
)))
2407 (if (member path
(plist-get info
:target-list
))
2408 ;; Link points to a target: return its name as a string.
2410 ;; Link either points to an headline or nothing. Try to find
2411 ;; the source, with priority given to headlines with the closest
2412 ;; common ancestor. If such candidate is found, return its
2413 ;; beginning position as an unique identifier, otherwise return
2415 (let* ((head-alist (plist-get info
:headline-alist
))
2416 (link-begin (org-element-get-property :begin link
))
2417 (link-end (org-element-get-property :end link
))
2418 ;; Store candidates as a list of cons cells holding their
2419 ;; beginning and ending position.
2420 (cands (loop for head in head-alist
2421 when
(string= (car head
) path
)
2422 collect
(cons (nth 1 head
) (nth 2 head
)))))
2424 ;; No candidate: return nil.
2426 ;; If one or more candidates share common ancestors with
2427 ;; LINK, return beginning position of the first one matching
2428 ;; the closer ancestor shared.
2429 ((let ((ancestors (loop for head in head-alist
2430 when
(and (> link-begin
(nth 1 head
))
2431 (<= link-end
(nth 2 head
)))
2432 collect
(cons (nth 1 head
) (nth 2 head
)))))
2433 (loop named main for ancestor in
(nreverse ancestors
) do
2434 (loop for candidate in cands
2435 when
(and (>= (car candidate
) (car ancestor
))
2436 (<= (cdr candidate
) (cdr ancestor
)))
2437 do
(return-from main
(car candidate
))))))
2438 ;; No candidate have a common ancestor with link: First match
2439 ;; will do. Return its beginning position.
2440 (t (caar cands
)))))))
2445 ;; `org-export-expand-macro' simply takes care of expanding macros.
2447 (defun org-export-expand-macro (macro info
)
2448 "Expand MACRO and return it as a string.
2449 INFO is a plist holding export options."
2450 (let* ((key (org-element-get-property :key macro
))
2451 (args (org-element-get-property :args macro
))
2452 (value (plist-get info
(intern (format ":macro-%s" key
)))))
2453 ;; Replace arguments in VALUE.
2455 (while (string-match "\\$\\([0-9]+\\)" value s
)
2456 (setq s
(1+ (match-beginning 0))
2457 n
(string-to-number (match-string 1 value
)))
2458 (and (>= (length args
) n
)
2459 (setq value
(replace-match (nth (1- n
) args
) t t value
)))))
2460 ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
2461 (when (string-match "\\`(eval\\>" value
)
2462 (setq value
(eval (read value
))))
2463 ;; Return expanded string.
2464 (format "%s" value
)))
2469 ;; `org-export-get-ordinal' associates a sequence number to any object
2472 (defun org-export-get-ordinal (element info
&optional within-section predicate
)
2473 "Return ordinal number of an element or object.
2475 ELEMENT is the element or object considered. INFO is the plist
2476 used as a communication channel.
2478 When optional argument WITHIN-SECTION is non-nil, narrow counting
2479 to the section containing ELEMENT.
2481 Optional argument PREDICATE is a function returning a non-nil
2482 value if the current element or object should be counted in. It
2483 accepts one argument: the element or object being considered.
2484 This argument allows to count only a certain type of objects,
2485 like inline images, which are a subset of links \(in that case,
2486 `org-export-inline-image-p' might be an useful predicate\)."
2488 (type (car element
))
2489 ;; Determine if search should apply to current section, in
2490 ;; which case it should be retrieved first, or to full parse
2491 ;; tree. As a special case, an element or object without
2492 ;; a parent headline will also trigger a full search,
2493 ;; notwithstanding WITHIN-SECTION value.
2495 (let ((parse-tree (plist-get info
:parse-tree
)))
2497 (let ((parent (plist-get (plist-get info
:inherited-properties
)
2499 (if (not parent
) parse-tree
2501 parse-tree
'headline
2503 (when (= (org-element-get-property :begin el
) parent
) el
))
2504 info
'first-match
)))
2506 ;; Increment counter until ELEMENT is found again.
2511 ((and (functionp predicate
) (funcall predicate el
)))
2512 ((equal element el
) (1+ counter
))
2513 (t (incf counter
) nil
)))
2514 info
'first-match
)))
2519 ;; `org-export-handle-code' takes care of line numbering and reference
2520 ;; cleaning in source code, when appropriate. It also updates global
2521 ;; LOC count (`:total-loc' property) and code references alist
2522 ;; (`:code-refs' property).
2524 (defun org-export-handle-code (code switches info
2525 &optional language num-fmt ref-fmt
)
2526 "Handle line numbers and code references in CODE.
2528 CODE is the string to process. SWITCHES is the option string
2529 determining which changes will be applied to CODE. INFO is the
2530 plist used as a communication channel during export.
2532 Optional argument LANGUAGE, when non-nil, is a string specifying
2535 If optional argument NUM-FMT is a string, it will be used as
2536 a format string for numbers at beginning of each line.
2538 If optional argument REF-FMT is a string, it will be used as
2539 a format string for each line of code containing a reference.
2541 Update the following INFO properties by side-effect: `:total-loc'
2544 Return new code as a string."
2545 (let* ((switches (or switches
""))
2546 (numberp (string-match "[-+]n\\>" switches
))
2547 (continuep (string-match "\\+n\\>" switches
))
2548 (total-LOC (if (and numberp
(not continuep
))
2550 (or (plist-get info
:total-loc
) 0)))
2551 (preserve-indent-p (or org-src-preserve-indentation
2552 (string-match "-i\\>" switches
)))
2553 (replace-labels (when (string-match "-r\\>" switches
)
2554 (if (string-match "-k\\>" switches
) 'keep t
)))
2555 ;; Get code and clean it. Remove blank lines at its
2556 ;; beginning and end. Also remove protective commas.
2557 (code (let ((c (replace-regexp-in-string
2558 "\\`\\([ \t]*\n\\)+" ""
2559 (replace-regexp-in-string
2560 "\\(:?[ \t]*\n\\)*[ \t]*\\'" "\n" code
))))
2561 ;; If appropriate, remove global indentation.
2562 (unless preserve-indent-p
(setq c
(org-remove-indentation c
)))
2563 ;; Free up the protected lines. Note: Org blocks
2564 ;; have commas at the beginning or every line.
2565 (if (string= language
"org")
2566 (replace-regexp-in-string "^," "" c
)
2567 (replace-regexp-in-string
2568 "^\\(,\\)\\(:?\\*\\|[ \t]*#\\+\\)" "" c nil nil
1))))
2569 ;; Split code to process it line by line.
2570 (code-lines (org-split-string code
"\n"))
2571 ;; Ensure line numbers will be correctly padded before
2572 ;; applying the format string.
2573 (num-fmt (format (if (stringp num-fmt
) num-fmt
"%s: ")
2575 (length (number-to-string
2576 (+ (length code-lines
)
2578 ;; Get format used for references.
2579 (label-fmt (or (and (string-match "-l +\"\\([^\"\n]+\\)\"" switches
)
2580 (match-string 1 switches
))
2581 org-coderef-label-format
))
2582 ;; Build a regexp matching a loc with a reference.
2583 (with-ref-re (format "^.*?\\S-.*?\\([ \t]*\\(%s\\)\\)[ \t]*$"
2584 (replace-regexp-in-string
2585 "%s" "\\([-a-zA-Z0-9_ ]+\\)" label-fmt nil t
)))
2587 (org-element-normalize-string
2588 (mapconcat (lambda (loc)
2589 ;; Maybe add line number to current line of code
2592 (setq loc
(concat (format num-fmt
(incf total-LOC
)) loc
)))
2593 ;; Take action if at a ref line.
2594 (when (string-match with-ref-re loc
)
2595 (let ((ref (match-string 3 loc
)))
2598 ;; Option "-k": don't remove labels. Use
2599 ;; numbers for references when lines are
2600 ;; numbered, use labels otherwise.
2601 ((eq replace-labels
'keep
)
2602 (let ((full-ref (format "(%s)" ref
)))
2603 (push (cons ref
(if numberp total-LOC full-ref
))
2605 (replace-match full-ref nil nil loc
2))
2606 (replace-match (format "(%s)" ref
) nil nil loc
2))
2607 ;; Option "-r" without "-k": remove labels.
2608 ;; Use numbers for references when lines are
2609 ;; numbered, use labels otherwise.
2611 (push (cons ref
(if numberp total-LOC ref
))
2613 (replace-match "" nil nil loc
1))
2614 ;; Else: don't remove labels and don't use
2615 ;; numbers for references.
2617 (let ((full-ref (format "(%s)" ref
)))
2618 (push (cons ref full-ref
) coderefs
)
2619 (replace-match full-ref nil nil loc
2)))))))
2620 ;; If REF-FMT is defined, apply it to current LOC.
2621 (when (stringp ref-fmt
) (setq loc
(format ref-fmt loc
)))
2622 ;; Update by side-effect communication channel.
2623 ;; Return updated LOC.
2624 (setq info
(org-export-set-property
2625 (org-export-set-property
2626 info
:code-refs coderefs
)
2627 :total-loc total-LOC
))
2634 ;; `org-export-table-format-info' extracts formatting information
2635 ;; (alignment, column groups and presence of a special column) from
2636 ;; a raw table and returns it as a property list.
2638 ;; `org-export-clean-table' cleans the raw table from any Org
2639 ;; table-specific syntax.
2641 (defun org-export-table-format-info (table)
2642 "Extract info from TABLE.
2643 Return a plist whose properties and values are:
2644 `:alignment' vector of strings among \"r\", \"l\" and \"c\",
2645 `:column-groups' vector of symbols among `start', `end', `start-end',
2646 `:row-groups' list of integers representing row groups.
2647 `:special-column-p' non-nil if table has a special column.
2648 `:width' vector of integers representing desired width of
2649 current column, or nil."
2654 (let ((align (vconcat (mapcar (lambda (c) (if c
"r" "l"))
2655 org-table-last-alignment
)))
2656 (width (make-vector (length org-table-last-alignment
) nil
))
2657 (colgroups (make-vector (length org-table-last-alignment
) nil
))
2660 (special-column-p 'empty
))
2662 (if (string-match "^[ \t]*|[-+]+|[ \t]*$" row
)
2664 (push row-group rowgroups
)
2665 ;; Determine if a special column is present by looking
2666 ;; for special markers in the first column. More
2667 ;; accurately, the first column is considered special
2668 ;; if it only contains special markers and, maybe,
2670 (setq special-column-p
2672 ((not special-column-p
) nil
)
2673 ((string-match "^[ \t]*| *\\\\?\\([\#!$*_^]\\) *|"
2675 ((string-match "^[ \t]*| +|" row
) special-column-p
))))
2677 ;; Read forced alignment and width information, if any,
2678 ;; and determine final alignment for the table.
2679 ((org-table-cookie-line-p row
)
2681 (mapc (lambda (field)
2682 (when (string-match "<\\([lrc]\\)\\([0-9]+\\)?>" field
)
2683 (aset align col
(match-string 1 field
))
2684 (aset width col
(let ((w (match-string 2 field
)))
2685 (and w
(string-to-number w
)))))
2687 (org-split-string row
"[ \t]*|[ \t]*"))))
2688 ;; Read column groups information.
2689 ((org-table-colgroup-line-p row
)
2691 (mapc (lambda (field)
2693 (cond ((string= "<" field
) 'start
)
2694 ((string= ">" field
) 'end
)
2695 ((string= "<>" field
) 'start-end
)))
2697 (org-split-string row
"[ \t]*|[ \t]*"))))))
2698 (org-split-string table
"\n"))
2700 (list :alignment align
2701 :column-groups colgroups
2702 :row-groups
(reverse rowgroups
)
2703 :special-column-p
(eq special-column-p
'special
)
2706 (defun org-export-clean-table (table specialp
)
2707 "Clean string TABLE from its formatting elements.
2708 Remove any row containing column groups or formatting cookies and
2709 rows starting with a special marker. If SPECIALP is non-nil,
2710 assume the table contains a special formatting column and remove
2712 (let ((rows (org-split-string table
"\n")))
2713 (mapconcat 'identity
2718 ((org-table-colgroup-line-p row
) nil
)
2719 ((org-table-cookie-line-p row
) nil
)
2720 ;; Ignore rows starting with a special marker.
2721 ((string-match "^[ \t]*| *[!_^/] *|" row
) nil
)
2722 ;; Remove special column.
2724 (or (string-match "^\\([ \t]*\\)|-+\\+" row
)
2725 (string-match "^\\([ \t]*\\)|[^|]*|" row
)))
2726 (replace-match "\\1|" t nil row
))
2732 ;;;; For Tables Of Contents
2734 ;; `org-export-collect-headlines' builds a list of all exportable
2735 ;; headline elements, maybe limited to a certain depth. One can then
2736 ;; easily parse it and transcode it.
2738 ;; Building lists of tables, figures or listings is quite similar.
2739 ;; Once the generic function `org-export-collect-elements' is defined,
2740 ;; `org-export-collect-tables', `org-export-collect-figures' and
2741 ;; `org-export-collect-listings' can be derived from it.
2743 (defun org-export-collect-headlines (info &optional n
)
2744 "Collect headlines in order to build a table of contents.
2746 When non-nil, optional argument N must be an integer. It
2747 specifies the depth of the table of contents.
2749 Return a list of all exportable headlines as parsed elements."
2751 (plist-get info
:parse-tree
)
2753 (lambda (headline local
)
2754 ;; Strip contents from HEADLINE.
2755 (let ((relative-level (org-export-get-relative-level headline local
)))
2756 (unless (and n
(> relative-level n
)) headline
)))
2759 (defun org-export-collect-elements (type backend info
)
2760 "Collect named elements of type TYPE.
2762 Only elements with a caption or a name are collected.
2764 BACKEND is the back-end used to transcode their caption or name.
2765 INFO is a plist holding export options.
2767 Return an alist where key is entry's name and value an unique
2768 identifier that might be used for internal links."
2770 (plist-get info
:parse-tree
)
2772 (lambda (element info
)
2775 ((org-element-get-property :caption element
)
2776 (org-export-secondary-string
2777 (org-element-get-property :caption element
) backend info
))
2778 ((org-element-get-property :name element
)
2779 (org-export-secondary-string
2780 (org-element-get-property :name element
) backend info
)))))
2781 ;; Skip elements with neither a caption nor a name.
2782 (when entry
(cons entry
(org-element-get-property :begin element
)))))
2785 (defun org-export-collect-tables (backend info
)
2786 "Build a list of tables.
2788 BACKEND is the back-end used to transcode table's name. INFO is
2789 a plist holding export options.
2791 Return an alist where key is the caption of the table and value
2792 an unique identifier that might be used for internal links."
2793 (org-export-collect-elements 'table backend info
))
2795 (defun org-export-collect-figures (backend info
)
2796 "Build a list of figures.
2798 A figure is a paragraph type element with a caption or a name.
2800 BACKEND is the back-end used to transcode headline's name. INFO
2801 is a plist holding export options.
2803 Return an alist where key is the caption of the figure and value
2804 an unique indentifier that might be used for internal links."
2805 (org-export-collect-elements 'paragraph backend info
))
2807 (defun org-export-collect-listings (backend info
)
2808 "Build a list of src blocks.
2810 BACKEND is the back-end used to transcode src block's name. INFO
2811 is a plist holding export options.
2813 Return an alist where key is the caption of the src block and
2814 value an unique indentifier that might be used for internal
2816 (org-export-collect-elements 'src-block backend info
))
2819 (provide 'org-export
)
2820 ;;; org-export.el ends here