| blob | 015934d9b4043e7b18ad98187e42127c7b72e9e1 |
1 ;;; org-export.el --- Generic Export Engine For Org
3 ;; Copyright (C) 2012 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation, either version 3 of the License, or
11 ;; (at your option) any later version.
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;; GNU General Public License for more details.
18 ;; You should have received a copy of the GNU General Public License
19 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
21 ;;; Commentary:
23 ;; This library implements a generic export engine for Org, built on
24 ;; its syntactical parser: Org Elements.
26 ;; Besides that parser, the generic exporter is made of three distinct
27 ;; parts:
29 ;; - The communication channel consists in a property list, which is
30 ;; created and updated during the process. Its use is to offer
31 ;; every piece of information, would it be about initial environment
32 ;; or contextual data, all in a single place. The exhaustive list
33 ;; of properties is given in "The Communication Channel" section of
34 ;; this file.
36 ;; - The transcoder walks the parse tree, ignores or treat as plain
37 ;; text elements and objects according to export options, and
38 ;; eventually calls back-end specific functions to do the real
39 ;; transcoding, concatenating their return value along the way.
41 ;; - The filter system is activated at the very beginning and the very
42 ;; end of the export process, and each time an element or an object
43 ;; has been converted. It is the entry point to fine-tune standard
44 ;; output from back-end transcoders.
46 ;; The core function is `org-export-as'. It returns the transcoded
47 ;; buffer as a string.
49 ;; In order to derive an exporter out of this generic implementation,
50 ;; one can define a transcode function for each element or object.
51 ;; Such function should return a string for the corresponding element,
52 ;; without any trailing space, or nil. It must accept three
53 ;; arguments:
54 ;; 1. the element or object itself,
55 ;; 2. its contents, or nil when it isn't recursive,
56 ;; 3. the property list used as a communication channel.
58 ;; If no such function is found, that element or object type will
59 ;; simply be ignored, along with any separating blank line. The same
60 ;; will happen if the function returns the nil value. If that
61 ;; function returns the empty string, the type will be ignored, but
62 ;; the blank lines will be kept.
64 ;; Contents, when not nil, are stripped from any global indentation
65 ;; (although the relative one is preserved). They also always end
66 ;; with a single newline character.
68 ;; These functions must follow a strict naming convention:
69 ;; `org-BACKEND-TYPE' where, obviously, BACKEND is the name of the
70 ;; export back-end and TYPE the type of the element or object handled.
72 ;; Moreover, two additional functions can be defined. On the one
73 ;; hand, `org-BACKEND-template' returns the final transcoded string,
74 ;; and can be used to add a preamble and a postamble to document's
75 ;; body. It must accept two arguments: the transcoded string and the
76 ;; property list containing export options. On the other hand,
77 ;; `org-BACKEND-plain-text', when defined, is to be called on every
78 ;; text not recognized as an element or an object. It must accept two
79 ;; arguments: the text string and the information channel.
81 ;; Any back-end can define its own variables. Among them, those
82 ;; customizables should belong to the `org-export-BACKEND' group.
83 ;; Also, a special variable, `org-BACKEND-option-alist', allows to
84 ;; define buffer keywords and "#+options:" items specific to that
85 ;; back-end. See `org-export-option-alist' for supported defaults and
86 ;; syntax.
88 ;; Tools for common tasks across back-ends are implemented in the
89 ;; penultimate part of this file. A dispatcher for standard back-ends
90 ;; is provided in the last one.
92 ;;; Code:
95 ;; Require major back-ends and publishing tools
103 \f
104 ;;; Internal Variables
106 ;; Among internal variables, the most important is
107 ;; `org-export-option-alist'. This variable define the global export
108 ;; options, shared between every exporter, and how they are acquired.
146 "Alist between export properties and ways to set them.
148 The car of the alist is the property name, and the cdr is a list
149 like \(KEYWORD OPTION DEFAULT BEHAVIOUR\) where:
151 KEYWORD is a string representing a buffer keyword, or nil.
152 OPTION is a string that could be found in an #+OPTIONS: line.
153 DEFAULT is the default value for the property.
154 BEHAVIOUR determine how Org should handle multiple keywords for
155 the same property. It is a symbol among:
156 nil Keep old value and discard the new one.
157 t Replace old value with the new one.
158 `space' Concatenate the values, separating them with a space.
159 `newline' Concatenate the values, separating them with
160 a newline.
161 `split' Split values at white spaces, and cons them to the
162 previous list.
164 KEYWORD and OPTION have precedence over DEFAULT.
166 All these properties should be back-end agnostic. For back-end
167 specific properties, define a similar variable named
168 `org-BACKEND-option-alist', replacing BACKEND with the name of
169 the appropriate back-end. You can also redefine properties
174 "List of in-buffer keywords that require special treatment.
175 These keywords are not directly associated to a property. The
176 way they are handled must be hard-coded into
228 "Alist between filters properties and initial values.
230 The key of each association is a property name accessible through
231 the communication channel its value is a configurable global
232 variable defining initial filters.
234 This list is meant to install user specified filters. Back-end
235 developers may install their own filters using
236 `org-BACKEND-filters-alist', where BACKEND is the name of the
237 considered back-end. Filters defined there will always be
238 prepended to the current list, so they always get applied
247 "Default rule for link matching an inline image.
248 This rule applies to links with no description. By default, it
249 will be considered as an inline image if it targets a local file
252 See `org-export-inline-image-p' for more information about
256 \f
257 ;;; User-configurable Variables
259 ;; Configuration for the masses.
261 ;; They should never be evaled directly, as their value is to be
262 ;; stored in a property list (cf. `org-export-option-alist').
265 "Options for exporting Org mode files."
270 "General options for export engine."
275 "Whether sub-trees with the ARCHIVE tag should be exported.
277 This can have three different values:
278 nil Do not export, pretend this tree is not present.
279 t Do export the entire tree.
280 `headline' Only export the headline, but skip the tree below it.
282 This option can also be set with the #+OPTIONS line,
291 "Non-nil means insert author name into the exported file.
292 This option can also be set with the #+OPTIONS line,
298 "Non-nil means the postamble should contain a creator sentence.
300 The sentence can be set in `org-export-creator-string' and
303 If the value is `comment' insert it as a comment."
312 "String to insert at the end of the generated document."
317 "Non-nil means export contents of standard drawers.
319 When t, all drawers are exported. This may also be a list of
320 drawer names to export. This variable doesn't apply to
321 properties drawers.
323 This option can also be set with the #+OPTIONS line,
333 "Non-nil means insert author email into the exported file.
334 This option can also be set with the #+OPTIONS line,
340 "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
342 If the export target supports emphasizing text, the word will be
343 typeset in bold, italic, or underlined, respectively. Not all
344 export backends support this.
351 "Tags that exclude a tree from export.
353 All trees carrying any of these tags will be excluded from
354 export. This is without condition, so even subtrees inside that
355 carry one of the `org-export-select-tags' will be removed.
357 This option can also be set with the #+EXPORT_EXCLUDE_TAGS:
358 keyword."
365 This can be used to have pre-formatted text, fragments of code
366 etc. For example:
367 : ;; Some Lisp examples
368 : (while (defc cnt)
369 : (ding))
370 will be looking just like this in also HTML. See also the QUOTE
371 keyword. Not all export backends support this.
378 "Non-nil means Org footnotes should be exported.
379 This option can also be set with the #+OPTIONS line,
385 "The last level which is still exported as a headline.
387 Inferior levels will produce itemize lists when exported. Note
388 that a numeric prefix argument to an exporter function overrides
389 this setting.
396 "The default language for export and clocktable translations, as a string.
397 This may have an association in
398 `org-clock-clocktable-language-setup'."
403 "Non-nil means preserve all line breaks when exporting.
405 Normally, in HTML output paragraphs will be reformatted.
407 This option can also be set with the #+OPTIONS line,
413 "Non-nil means interpret entities when exporting.
416 Å.
418 For a list of supported names, see the constant `org-entities'
419 and the user option `org-entities-user'.
421 This option can also be set with the #+OPTIONS line,
427 "Non-nil means include priority cookies in export.
429 When nil, remove priority cookies for export.
431 This option can also be set with the #+OPTIONS line,
437 "Non-nil means add section numbers to headlines when exporting.
439 When set to an integer n, numbering will only happen for
440 headlines whose relative level is higher or equal to n.
442 This option can also be set with the #+OPTIONS line,
448 "Tags that select a tree for export.
450 If any such tag is found in a buffer, all trees that do not carry
451 one of these tags will be ignored during export. Inside trees
452 that are selected like this, you can still deselect a subtree by
453 tagging it with one of the `org-export-exclude-tags'.
455 This option can also be set with the #+EXPORT_SELECT_TAGS:
456 keyword."
463 When this option is turned on, these strings will be exported as:
465 Org HTML LaTeX
466 -----+----------+--------
468 -- – --
469 --- — ---
470 ... … \ldots
472 This option can also be set with the #+OPTIONS line,
480 When this option is turned on, you can use TeX-like syntax for
482 will be considered as a single item - so grouping with {} is
483 normally not needed. For example, the following things will be
484 parsed as single sub- or superscripts.
486 10^24 or 10^tau several digits will be considered 1 item.
487 10^-12 or 10^-tau a leading sign with digits or a word
488 x^2-y^3 will be read as x^2 - y^3, because items are
489 terminated by almost any nonword/nondigit char.
490 x_{i^2} or x^(2-i) braces or parenthesis do grouping.
492 Still, ambiguity is possible - so when in doubt use {} to enclose
493 the sub/superscript. If you set this variable to the symbol
494 `{}', the braces are *required* in order to trigger
495 interpretations as sub/superscript. This can be helpful in
498 This option can also be set with the #+OPTIONS line,
507 "Non-nil means create a table of contents in exported files.
509 The TOC contains headlines with levels up
510 to`org-export-headline-levels'. When an integer, include levels
511 up to N in the toc, this may then be different from
512 `org-export-headline-levels', but it will not be allowed to be
513 larger than the number of headline levels. When nil, no table of
514 contents is made.
516 This option can also be set with the #+OPTIONS line,
526 For example:
528 | Name | Address | Birthday |
529 |-------------+----------+-----------|
530 | Arthur Dent | England | 29.2.2100 |
537 "If nil, do not export tags, just remove them from headlines.
539 If this is the symbol `not-in-toc', tags will be removed from
540 table of contents entries, but still be shown in the headlines of
541 the document.
543 This option can also be set with the #+OPTIONS line,
552 "Non-nil means include TODO items for export.
553 This may have the following values:
554 t include tasks independent of state.
555 todo include only tasks that are not yet done.
556 done include only tasks that are already done.
557 nil remove all tasks before export
558 list of keywords keep only tasks with these keywords"
569 "Non-nil means insert a time stamp into the exported file.
570 The time stamp shows when the file was created.
572 This option can also be set with the #+OPTIONS line,
578 "If nil, do not export time stamps and associated keywords."
583 "Non-nil means include TODO keywords in export.
587 "Non-nil means allow #+BIND to define local variable values for export.
588 This is a potential security risk, which is why the user must
589 confirm the use of these lines."
597 "Alist between export snippets back-ends and exporter back-ends.
599 This variable allows to provide shortcuts for export snippets.
603 while every other back-end will ignore it."
611 "Coding system for the exported file."
616 "Non-nil means exported stuff will also be pushed onto the kill ring."
621 "The initial scope when exporting with `org-export-dispatch'.
622 This variable can be either set to `buffer' or `subtree'."
629 "Non-nil means show buffer after exporting to temp buffer.
630 When Org exports to a file, the buffer visiting that file is ever
631 shown, but remains buried. However, when exporting to a temporary
632 buffer, that buffer is popped up in a second window. When this variable
633 is nil, the buffer remains buried also in these cases."
638 "Non-nil means using a non-intrusive `org-export-dispatch'.
639 In that case, no help buffer is displayed. Though, an indicator
643 considered for export\). Also, \[?] allows to switch back to
644 standard mode."
649 \f
650 ;;; The Communication Channel
652 ;; During export process, every function has access to a number of
653 ;; properties. They are of three types:
655 ;; 1. Environment options are collected once at the very beginning of
656 ;; the process, out of the original buffer and configuration.
657 ;; Collecting them is handled by `org-export-get-environment'
658 ;; function.
659 ;;
660 ;; Most environment options are defined through the
661 ;; `org-export-option-alist' variable.
662 ;;
663 ;; 2. Tree properties are extracted directly from the parsed tree,
664 ;; just before export, by `org-export-collect-tree-properties'.
665 ;;
666 ;; 3. Local options are updated during parsing, and their value
667 ;; depends on the level of recursion. For now, only `:ignore-list'
668 ;; belongs to that category.
670 ;; Here is the full list of properties available during transcode
671 ;; process, with their category (option, tree or local) and their
672 ;; value type.
674 ;; + `:author' :: Author's name.
675 ;; - category :: option
676 ;; - type :: string
678 ;; + `:back-end' :: Current back-end used for transcoding.
679 ;; - category :: tree
680 ;; - type :: symbol
682 ;; + `:creator' :: String to write as creation information.
683 ;; - category :: option
684 ;; - type :: string
686 ;; + `:date' :: String to use as date.
687 ;; - category :: option
688 ;; - type :: string
690 ;; + `:description' :: Description text for the current data.
691 ;; - category :: option
692 ;; - type :: string
694 ;; + `:email' :: Author's email.
695 ;; - category :: option
696 ;; - type :: string
698 ;; + `:exclude-tags' :: Tags for exclusion of subtrees from export
699 ;; process.
700 ;; - category :: option
701 ;; - type :: list of strings
703 ;; + `:footnote-definition-alist' :: Alist between footnote labels and
704 ;; their definition, as parsed data. Only non-inlined footnotes
705 ;; are represented in this alist. Also, every definition isn't
706 ;; guaranteed to be referenced in the parse tree. The purpose of
707 ;; this property is to preserve definitions from oblivion
708 ;; (i.e. when the parse tree comes from a part of the original
709 ;; buffer), it isn't meant for direct use in a back-end. To
710 ;; retrieve a definition relative to a reference, use
711 ;; `org-export-get-footnote-definition' instead.
712 ;; - category :: option
713 ;; - type :: alist (STRING . LIST)
715 ;; + `:headline-levels' :: Maximum level being exported as an
716 ;; headline. Comparison is done with the relative level of
717 ;; headlines in the parse tree, not necessarily with their
718 ;; actual level.
719 ;; - category :: option
720 ;; - type :: integer
722 ;; + `:headline-offset' :: Difference between relative and real level
723 ;; of headlines in the parse tree. For example, a value of -1
724 ;; means a level 2 headline should be considered as level
725 ;; 1 (cf. `org-export-get-relative-level').
726 ;; - category :: tree
727 ;; - type :: integer
729 ;; + `:headline-numbering' :: Alist between headlines and their
730 ;; numbering, as a list of numbers
731 ;; (cf. `org-export-get-headline-number').
732 ;; - category :: tree
733 ;; - type :: alist (INTEGER . LIST)
735 ;; + `:ignore-list' :: List of elements and objects that should be
736 ;; ignored during export.
737 ;; - category :: local
738 ;; - type :: list of elements and objects
740 ;; + `:input-file' :: Full path to input file, if any.
741 ;; - category :: option
742 ;; - type :: string or nil
744 ;; + `:keywords' :: List of keywords attached to data.
745 ;; - category :: option
746 ;; - type :: string
748 ;; + `:language' :: Default language used for translations.
749 ;; - category :: option
750 ;; - type :: string
752 ;; + `:macro-input-file' :: Macro returning file name of input file,
753 ;; or nil.
754 ;; - category :: option
755 ;; - type :: string or nil
757 ;; + `:parse-tree' :: Whole parse tree, available at any time during
758 ;; transcoding.
759 ;; - category :: global
760 ;; - type :: list (as returned by `org-element-parse-buffer')
762 ;; + `:preserve-breaks' :: Non-nil means transcoding should preserve
763 ;; all line breaks.
764 ;; - category :: option
765 ;; - type :: symbol (nil, t)
767 ;; + `:section-numbers' :: Non-nil means transcoding should add
768 ;; section numbers to headlines.
769 ;; - category :: option
770 ;; - type :: symbol (nil, t)
772 ;; + `:select-tags' :: List of tags enforcing inclusion of sub-trees
773 ;; in transcoding. When such a tag is present,
774 ;; subtrees without it are de facto excluded from
775 ;; the process. See `use-select-tags'.
776 ;; - category :: option
777 ;; - type :: list of strings
779 ;; + `:target-list' :: List of targets encountered in the parse tree.
780 ;; This is used to partly resolve "fuzzy" links
781 ;; (cf. `org-export-resolve-fuzzy-link').
782 ;; - category :: tree
783 ;; - type :: list of strings
785 ;; + `:time-stamp-file' :: Non-nil means transcoding should insert
786 ;; a time stamp in the output.
787 ;; - category :: option
788 ;; - type :: symbol (nil, t)
790 ;; + `:with-archived-trees' :: Non-nil when archived subtrees should
791 ;; also be transcoded. If it is set to the `headline' symbol,
792 ;; only the archived headline's name is retained.
793 ;; - category :: option
794 ;; - type :: symbol (nil, t, `headline')
796 ;; + `:with-author' :: Non-nil means author's name should be included
797 ;; in the output.
798 ;; - category :: option
799 ;; - type :: symbol (nil, t)
801 ;; + `:with-creator' :: Non-nild means a creation sentence should be
802 ;; inserted at the end of the transcoded string. If the value
803 ;; is `comment', it should be commented.
804 ;; - category :: option
805 ;; - type :: symbol (`comment', nil, t)
807 ;; + `:with-drawers' :: Non-nil means drawers should be exported. If
808 ;; its value is a list of names, only drawers with such names
809 ;; will be transcoded.
810 ;; - category :: option
811 ;; - type :: symbol (nil, t) or list of strings
813 ;; + `:with-email' :: Non-nil means output should contain author's
814 ;; email.
815 ;; - category :: option
816 ;; - type :: symbol (nil, t)
818 ;; + `:with-emphasize' :: Non-nil means emphasized text should be
819 ;; interpreted.
820 ;; - category :: option
821 ;; - type :: symbol (nil, t)
823 ;; + `:with-fixed-width' :: Non-nil if transcoder should interpret
824 ;; strings starting with a colon as a fixed-with (verbatim) area.
825 ;; - category :: option
826 ;; - type :: symbol (nil, t)
828 ;; + `:with-footnotes' :: Non-nil if transcoder should interpret
829 ;; footnotes.
830 ;; - category :: option
831 ;; - type :: symbol (nil, t)
833 ;; + `:with-priority' :: Non-nil means transcoding should include
834 ;; priority cookies.
835 ;; - category :: option
836 ;; - type :: symbol (nil, t)
838 ;; + `:with-special-strings' :: Non-nil means transcoding should
839 ;; interpret special strings in plain text.
840 ;; - category :: option
841 ;; - type :: symbol (nil, t)
843 ;; + `:with-sub-superscript' :: Non-nil means transcoding should
844 ;; interpret subscript and superscript. With a value of "{}",
845 ;; only interpret those using curly brackets.
846 ;; - category :: option
847 ;; - type :: symbol (nil, {}, t)
849 ;; + `:with-tables' :: Non-nil means transcoding should interpret
850 ;; tables.
851 ;; - category :: option
852 ;; - type :: symbol (nil, t)
854 ;; + `:with-tags' :: Non-nil means transcoding should keep tags in
855 ;; headlines. A `not-in-toc' value will remove them
856 ;; from the table of contents, if any, nonetheless.
857 ;; - category :: option
858 ;; - type :: symbol (nil, t, `not-in-toc')
860 ;; + `:with-tasks' :: Non-nil means transcoding should include
861 ;; headlines with a TODO keyword. A `todo' value
862 ;; will only include headlines with a todo type
863 ;; keyword while a `done' value will do the
864 ;; contrary. If a list of strings is provided, only
865 ;; tasks with keywords belonging to that list will
866 ;; be kept.
867 ;; - category :: option
868 ;; - type :: symbol (t, todo, done, nil) or list of strings
870 ;; + `:with-timestamps' :: Non-nil means transcoding should include
871 ;; time stamps and associated keywords. Otherwise, completely
872 ;; remove them.
873 ;; - category :: option
874 ;; - type :: symbol: (t, nil)
876 ;; + `:with-toc' :: Non-nil means that a table of contents has to be
877 ;; added to the output. An integer value limits its
878 ;; depth.
879 ;; - category :: option
880 ;; - type :: symbol (nil, t or integer)
882 ;; + `:with-todo-keywords' :: Non-nil means transcoding should
883 ;; include TODO keywords.
884 ;; - category :: option
885 ;; - type :: symbol (nil, t)
888 ;;;; Environment Options
890 ;; Environment options encompass all parameters defined outside the
891 ;; scope of the parsed data. They come from five sources, in
892 ;; increasing precedence order:
893 ;;
894 ;; - Global variables,
895 ;; - Buffer's attributes,
896 ;; - Options keyword symbols,
897 ;; - Buffer keywords,
898 ;; - Subtree properties.
900 ;; The central internal function with regards to environment options
901 ;; is `org-export-get-environment'. It updates global variables with
902 ;; "#+BIND:" keywords, then retrieve and prioritize properties from
903 ;; the different sources.
905 ;; The internal functions doing the retrieval are:
906 ;; `org-export-get-global-options',
907 ;; `org-export-get-buffer-attributes',
908 ;; `org-export-parse-option-keyword',
909 ;; `org-export-get-subtree-options' and
910 ;; `org-export-get-inbuffer-options'
912 ;; Also, `org-export-confirm-letbind' and `org-export-install-letbind'
913 ;; take care of the part relative to "#+BIND:" keywords.
916 "Collect export options from the current buffer.
918 Optional argument BACKEND is a symbol specifying which back-end
919 specific options to read, if any.
921 When optional argument SUBTREEP is non-nil, assume the export is
922 done against the current sub-tree.
924 Third optional argument EXT-PLIST is a property list with
925 external parameters overriding Org default settings, but still
926 inferior to file-local settings."
927 ;; First install #+BIND variables.
929 ;; Get and prioritize export options...
931 ;; ... from global variables...
933 ;; ... from buffer's attributes...
935 ;; ... from an external property list...
936 ext-plist
937 ;; ... from in-buffer settings...
939 backend
942 ;; ... and from subtree, when appropriate.
944 ;; Return plist.
945 options))
948 "Parse an OPTIONS line and return values as a plist.
949 Optional argument BACKEND is a symbol specifying which back-end
950 specific items to read, if any."
957 ;; Build an alist between #+OPTION: item and property-name.
962 all)))
963 plist)
968 options)
973 alist)
974 plist))
977 "Get export options in subtree at point.
979 Assume point is at subtree's beginning.
981 Return options as a plist."
989 plist :title
991 prop
1001 plist))
1004 "Return current buffer export options, as a plist.
1006 Optional argument BACKEND, when non-nil, is a symbol specifying
1007 which back-end specific options should also be read in the
1008 process.
1010 Optional argument FILES is a list of setup files names read so
1011 far, used to avoid circular dependencies.
1013 Assume buffer is in Org mode. Narrowing, if any, is ignored."
1017 ;; 1. Special keywords, as in `org-export-special-keywords'.
1030 ;; Avoid circular dependencies.
1042 val)
1050 ;; Value will be evaled. Leave it as-is.
1053 ;; Value has to be parsed for nested
1054 ;; macros.
1057 key
1061 org-element-object-restrictions))))
1063 ;; If user explicitly asks for
1064 ;; a newline, be sure to preserve it
1065 ;; from further filling with
1066 ;; `hard-newline'. Also replace
1067 ;; "\\n" with "\n", "\\\n" with "\\n"
1068 ;; and so on...
1075 restr)))))))))))
1077 ;; 2. Standard options, as in `org-export-option-alist'.
1079 ;; Also look for back-end specific options
1080 ;; if BACKEND is defined.
1086 ;; Build alist between keyword name and property name.
1090 all)))
1091 ;; Build regexp matching all keywords associated to export
1092 ;; options. Note: the search is case insensitive.
1105 plist prop
1106 ;; Handle value depending on specified BEHAVIOUR.
1119 ;; Parse keywords specified in `org-element-parsed-keywords'.
1127 plist prop
1129 value
1131 org-element-parsed-keywords))
1132 ;; 3. Return final value.
1133 plist)))
1136 "Return properties related to buffer attributes, as a plist."
1139 ;; Store full path of input file name, or nil. For internal use.
1140 :input-file visited-file
1145 :macro-modification-time
1151 ;; Store input file name as a macro.
1153 ;; `:macro-date', `:macro-time' and `:macro-property' could as
1154 ;; well be initialized as tree properties, since they don't
1155 ;; depend on buffer properties. Though, it may be more logical
1156 ;; to keep them close to other ":macro-" properties.
1162 "Return global export options as a plist.
1164 Optional argument BACKEND, if non-nil, is a symbol specifying
1165 which back-end specific export options should also be read in the
1166 process."
1172 ;; Output value.
1173 plist)
1176 all)
1177 ;; Return value.
1178 plist))
1181 "Collect and store footnote definitions from current buffer in INFO.
1183 INFO is a plist containing export options.
1185 Footnotes definitions are stored as a alist whose CAR is
1186 footnote's label, as a string, and CDR the contents, as a parse
1187 tree. This alist will be consed to the value of
1188 `:footnote-definition-alist' in INFO, if any.
1190 The new plist is returned; use
1192 \(setq info (org-export-store-footnote-definitions info))
1194 to be sure to use the new value. INFO is modified by side
1195 effects."
1196 ;; Footnotes definitions must be collected in the original buffer,
1197 ;; as there's no insurance that they will still be in the parse
1198 ;; tree, due to some narrowing.
1200 info :footnote-definition-alist
1211 ;; Like `org-element-parse-buffer', but
1212 ;; makes sure the definition doesn't start
1213 ;; with a section element.
1218 alist))))
1219 alist))))
1223 "Can we use #+BIND values during export?
1224 By default this will ask for confirmation by the user, to divert
1225 possible security risks."
1234 "Install the values from #+BIND lines as local variables.
1235 Variables must be installed before in-buffer options are
1236 retrieved."
1243 letbind))))
1248 ;;;; Tree Properties
1250 ;; Tree properties are infromation extracted from parse tree. They
1251 ;; are initialized at the beginning of the transcoding process by
1252 ;; `org-export-collect-tree-properties'.
1254 ;; Dedicated functions focus on computing the value of specific tree
1255 ;; properties during initialization. Thus,
1256 ;; `org-export-populate-ignore-list' lists elements and objects that
1257 ;; should be skipped during export, `org-export-get-min-level' gets
1258 ;; the minimal exportable level, used as a basis to compute relative
1259 ;; level for headlines. Eventually
1260 ;; `org-export-collect-headline-numbering' builds an alist between
1261 ;; headlines and their numbering.
1264 "Extract tree properties from parse tree.
1266 DATA is the parse tree from which information is retrieved. INFO
1267 is a list holding export options. BACKEND is the back-end called
1268 for transcoding, as a symbol.
1270 Following tree properties are set or updated:
1271 `:back-end' Back-end used for transcoding.
1273 `:footnote-definition-alist' List of footnotes definitions in
1274 original buffer and current parse tree.
1276 `:headline-offset' Offset between true level of headlines and
1277 local level. An offset of -1 means an headline
1278 of level 2 should be considered as a level
1279 1 headline in the context.
1281 `:headline-numbering' Alist of all headlines as key an the
1282 associated numbering as value.
1284 `:ignore-list' List of elements that should be ignored during
1285 export.
1287 `:parse-tree' Whole parse tree.
1289 `:target-list' List of all targets in the parse tree."
1290 ;; Install the parse tree in the communication channel, in order to
1291 ;; use `org-export-get-genealogy' and al.
1293 ;; Get the list of elements and objects to ignore, and put it into
1294 ;; `:ignore-list'. Do not overwrite any user ignore that might have
1295 ;; been done during parse tree filtering.
1298 :ignore-list
1301 ;; Compute `:headline-offset' in order to be able to use
1302 ;; `org-export-get-relative-level'.
1306 ;; Update footnotes definitions list with definitions in parse tree.
1307 ;; This is required since buffer expansion might have modified
1308 ;; boundaries of footnote definitions contained in the parse tree.
1309 ;; This way, definitions in `footnote-definition-alist' are bound to
1310 ;; match those in the parse tree.
1313 data 'footnote-definition
1317 defs)))
1319 ;; Properties order doesn't matter: get the rest of the tree
1320 ;; properties.
1322 `(:target-list
1331 info))
1334 "Return minimum exportable headline's level in DATA.
1335 DATA is parsed tree as returned by `org-element-parse-buffer'.
1336 OPTIONS is a plist holding export options."
1347 ;; If no headline was found, for the sake of consistency, set
1348 ;; minimum level to 1 nonetheless.
1352 "Return numbering of all exportable headlines in a parse tree.
1354 DATA is the parse tree. OPTIONS is the plist holding export
1355 options.
1357 Return an alist whose key is an headline and value is its
1358 associated numbering \(in the shape of a list of numbers\)."
1361 data
1362 'headline
1367 headline
1369 for idx from 0 to org-export-max-depth
1373 options)))
1376 "Return list of elements and objects to ignore during export.
1378 DATA is the parse tree to traverse. OPTIONS is the plist holding
1379 export options.
1381 Return elements or objects to ignore as a list."
1386 ;; Collect ignored elements or objects into IGNORE-LIST.
1394 ;; If headline is archived but tree below has
1395 ;; to be skipped, add it to ignore list.
1398 ;; Move into recursive objects/elements.
1402 ;; Main call. First find trees containing a select tag, if any.
1404 ;; Return value.
1405 ignore))
1408 "Return list of headlines containing a select tag in their tree.
1409 DATA is parsed data as returned by `org-element-parse-buffer'.
1410 INFO is a plist holding export options."
1424 ;; When a select tag is found, mark as acceptable
1425 ;; full genealogy and every headline within the
1426 ;; tree.
1431 selected-trees))
1432 ;; Else, continue searching in tree, recursively.
1437 "Non-nil when element or object BLOB should be skipped during export.
1438 OPTIONS is the plist holding export options."
1440 ;; Check headline.
1449 ;; Ignore subtrees with an exclude tag.
1452 ;; Ignore subtrees without a select tag, when such tag is
1453 ;; found in the buffer.
1455 ;; Ignore commented sub-trees.
1457 ;; Ignore archived subtrees if `:with-archived-trees' is nil.
1459 ;; Ignore tasks, if specified by `:with-tasks' property.
1465 ;; Check time-stamp.
1467 ;; Check drawer.
1473 ;; Check table-row.
1475 ;; Check table-cell.
1482 \f
1483 ;;; The Transcoder
1485 ;; This function reads Org data (obtained with, i.e.
1486 ;; `org-element-parse-buffer') and transcodes it into a specified
1487 ;; back-end output. It takes care of updating local properties,
1488 ;; filtering out elements or objects according to export options and
1489 ;; organizing the output blank lines and white space are preserved.
1491 ;; Though, this function is inapropriate for secondary strings, which
1492 ;; require a fresh copy of the plist passed as INFO argument. Thus,
1493 ;; `org-export-secondary-string' is provided for that specific task.
1495 ;; Internally, three functions handle the filtering of objects and
1496 ;; elements during the export. In particular,
1497 ;; `org-export-ignore-element' marks an element or object so future
1498 ;; parse tree traversals skip it, `org-export-interpret-p' tells which
1499 ;; elements or objects should be seen as real Org syntax and
1500 ;; `org-export-expand' transforms the others back into their original
1501 ;; shape.
1504 "Convert DATA to a string into BACKEND format.
1506 DATA is a nested list as returned by `org-element-parse-buffer'.
1508 BACKEND is a symbol among supported exporters.
1510 INFO is a plist holding export options and also used as
1511 a communication channel between elements when walking the nested
1512 list. See `org-export-update-info' function for more
1513 details.
1515 Return transcoded string."
1517 ;; BLOB can be an element, an object, a string, or nil.
1521 ;; BLOB is a string. Check if the optional transcoder for plain
1522 ;; text exists, and call it in that case. Otherwise, simply
1523 ;; return string. Also update INFO and call
1524 ;; `org-export-filter-plain-text-functions'.
1530 backend info)))
1531 ;; BLOB is an element or an object.
1534 ;; 1. Determine the appropriate TRANSCODER.
1537 ;; 1.0 A full Org document is inserted.
1539 ;; 1.1. BLOB should be ignored.
1541 ;; 1.2. BLOB shouldn't be transcoded. Interpret it
1542 ;; back into Org syntax.
1544 ;; 1.3. Else apply naming convention.
1547 ;; 2. Compute CONTENTS of BLOB.
1550 ;; Case 0. No transcoder or no contents: ignore BLOB.
1552 ;; Case 1. Transparently export an Org document.
1554 ;; Case 2. For a greater element.
1556 ;; Ignore contents of an archived tree
1557 ;; when `:with-archived-trees' is `headline'.
1564 ;; Case 3. For an element containing objects.
1568 blob
1569 ;; When normalizing contents of the first paragraph
1570 ;; in an item or a footnote definition, ignore
1571 ;; first line's indentation: there is none and it
1572 ;; might be misleading.
1578 backend info))))
1579 ;; 3. Transcode BLOB into RESULTS string.
1585 backend info))
1587 ;; 4. Return results.
1590 ;; No filter for a full document.
1592 ;; Otherwise, update INFO, append the same white space
1593 ;; between elements or objects as in the original buffer,
1594 ;; and call appropriate filters.
1604 backend info)))
1605 ;; Eventually return string.
1606 results)))))))
1610 "Convert SECONDARY string into BACKEND format.
1612 SECONDARY is a nested list as returned by
1613 `org-element-parse-secondary-string'.
1615 BACKEND is a symbol among supported exporters. INFO is a plist
1616 used as a communication channel.
1618 Return transcoded string."
1619 ;; Make SECONDARY acceptable for `org-export-data'.
1624 "Non-nil if element or object BLOB should be interpreted as Org syntax.
1625 Check is done according to export options INFO, stored as
1626 a plist."
1628 ;; ... entities...
1630 ;; ... emphasis...
1632 ;; ... fixed-width areas.
1634 ;; ... footnotes...
1637 ;; ... sub/superscripts...
1643 ;; ... tables...
1648 "Expand a parsed element or object to its original state.
1649 BLOB is either an element or an object. CONTENTS is its
1650 contents, as a string or nil."
1652 blob contents))
1655 "Add ELEMENT to `:ignore-list' in INFO.
1657 Any element in `:ignore-list' will be skipped when using
1658 `org-element-map'. INFO is modified by side effects."
1662 \f
1663 ;;; The Filter System
1665 ;; Filters allow end-users to tweak easily the transcoded output.
1666 ;; They are the functional counterpart of hooks, as every filter in
1667 ;; a set is applied to the return value of the previous one.
1669 ;; Every set is back-end agnostic. Although, a filter is always
1670 ;; called, in addition to the string it applies to, with the back-end
1671 ;; used as argument, so it's easy enough for the end-user to add
1672 ;; back-end specific filters in the set. The communication channel,
1673 ;; as a plist, is required as the third argument.
1675 ;; Filters sets are defined below. There are of four types:
1677 ;; - `org-export-filter-parse-tree-functions' applies directly on the
1678 ;; complete parsed tree. It's the only filters set that doesn't
1679 ;; apply to a string.
1680 ;; - `org-export-filter-final-output-functions' applies to the final
1681 ;; transcoded string.
1682 ;; - `org-export-filter-plain-text-functions' applies to any string
1683 ;; not recognized as Org syntax.
1684 ;; - `org-export-filter-TYPE-functions' applies on the string returned
1685 ;; after an element or object of type TYPE has been transcoded.
1687 ;; All filters sets are applied through
1688 ;; `org-export-filter-apply-functions' function. Filters in a set are
1689 ;; applied in a LIFO fashion. It allows developers to be sure that
1690 ;; their filters will be applied first.
1692 ;; Filters properties are installed in communication channel just
1693 ;; before parsing, with `org-export-install-filters' function.
1695 ;;;; Special Filters
1697 "Filter, or list of filters, applied to the parsed tree.
1698 Each filter is called with three arguments: the parse tree, as
1699 returned by `org-element-parse-buffer', the back-end, as
1700 a symbol, and the communication channel, as a plist. It must
1704 "Filter, or list of filters, applied to the transcoded string.
1705 Each filter is called with three arguments: the full transcoded
1706 string, the back-end, as a symbol, and the communication channel,
1707 as a plist. It must return a string that will be used as the
1711 "Filter, or list of filters, applied to plain text.
1712 Each filter is called with three arguments: a string which
1713 contains no Org syntax, the back-end, as a symbol, and the
1714 communication channel, as a plist. It must return a string or
1718 ;;;; Elements Filters
1721 "List of functions applied to a transcoded center block.
1722 Each filter is called with three arguments: the transcoded center
1723 block, as a string, the back-end, as a symbol, and the
1724 communication channel, as a plist. It must return a string or
1728 "List of functions applied to a transcoded drawer.
1729 Each filter is called with three arguments: the transcoded
1730 drawer, as a string, the back-end, as a symbol, and the
1731 communication channel, as a plist. It must return a string or
1735 "List of functions applied to a transcoded dynamic-block.
1736 Each filter is called with three arguments: the transcoded
1737 dynamic-block, as a string, the back-end, as a symbol, and the
1738 communication channel, as a plist. It must return a string or
1742 "List of functions applied to a transcoded headline.
1743 Each filter is called with three arguments: the transcoded
1744 headline, as a string, the back-end, as a symbol, and the
1745 communication channel, as a plist. It must return a string or
1749 "List of functions applied to a transcoded inlinetask.
1750 Each filter is called with three arguments: the transcoded
1751 inlinetask, as a string, the back-end, as a symbol, and the
1752 communication channel, as a plist. It must return a string or
1756 "List of functions applied to a transcoded plain-list.
1757 Each filter is called with three arguments: the transcoded
1758 plain-list, as a string, the back-end, as a symbol, and the
1759 communication channel, as a plist. It must return a string or
1763 "List of functions applied to a transcoded item.
1764 Each filter is called with three arguments: the transcoded item,
1765 as a string, the back-end, as a symbol, and the communication
1769 "List of functions applied to a transcoded comment.
1770 Each filter is called with three arguments: the transcoded
1771 comment, as a string, the back-end, as a symbol, and the
1772 communication channel, as a plist. It must return a string or
1776 "List of functions applied to a transcoded comment-comment.
1777 Each filter is called with three arguments: the transcoded
1778 comment-block, as a string, the back-end, as a symbol, and the
1779 communication channel, as a plist. It must return a string or
1783 "List of functions applied to a transcoded example-block.
1784 Each filter is called with three arguments: the transcoded
1785 example-block, as a string, the back-end, as a symbol, and the
1786 communication channel, as a plist. It must return a string or
1790 "List of functions applied to a transcoded export-block.
1791 Each filter is called with three arguments: the transcoded
1792 export-block, as a string, the back-end, as a symbol, and the
1793 communication channel, as a plist. It must return a string or
1797 "List of functions applied to a transcoded fixed-width.
1798 Each filter is called with three arguments: the transcoded
1799 fixed-width, as a string, the back-end, as a symbol, and the
1800 communication channel, as a plist. It must return a string or
1804 "List of functions applied to a transcoded footnote-definition.
1805 Each filter is called with three arguments: the transcoded
1806 footnote-definition, as a string, the back-end, as a symbol, and
1807 the communication channel, as a plist. It must return a string
1811 "List of functions applied to a transcoded horizontal-rule.
1812 Each filter is called with three arguments: the transcoded
1813 horizontal-rule, as a string, the back-end, as a symbol, and the
1814 communication channel, as a plist. It must return a string or
1818 "List of functions applied to a transcoded keyword.
1819 Each filter is called with three arguments: the transcoded
1820 keyword, as a string, the back-end, as a symbol, and the
1821 communication channel, as a plist. It must return a string or
1825 "List of functions applied to a transcoded latex-environment.
1826 Each filter is called with three arguments: the transcoded
1827 latex-environment, as a string, the back-end, as a symbol, and
1828 the communication channel, as a plist. It must return a string
1832 "List of functions applied to a transcoded babel-call.
1833 Each filter is called with three arguments: the transcoded
1834 babel-call, as a string, the back-end, as a symbol, and the
1835 communication channel, as a plist. It must return a string or
1839 "List of functions applied to a transcoded paragraph.
1840 Each filter is called with three arguments: the transcoded
1841 paragraph, as a string, the back-end, as a symbol, and the
1842 communication channel, as a plist. It must return a string or
1846 "List of functions applied to a transcoded property-drawer.
1847 Each filter is called with three arguments: the transcoded
1848 property-drawer, as a string, the back-end, as a symbol, and the
1849 communication channel, as a plist. It must return a string or
1853 "List of functions applied to a transcoded quote block.
1854 Each filter is called with three arguments: the transcoded quote
1855 block, as a string, the back-end, as a symbol, and the
1856 communication channel, as a plist. It must return a string or
1860 "List of functions applied to a transcoded quote-section.
1861 Each filter is called with three arguments: the transcoded
1862 quote-section, as a string, the back-end, as a symbol, and the
1863 communication channel, as a plist. It must return a string or
1867 "List of functions applied to a transcoded section.
1868 Each filter is called with three arguments: the transcoded
1869 section, as a string, the back-end, as a symbol, and the
1870 communication channel, as a plist. It must return a string or
1874 "List of functions applied to a transcoded special block.
1875 Each filter is called with three arguments: the transcoded
1876 special block, as a string, the back-end, as a symbol, and the
1877 communication channel, as a plist. It must return a string or
1881 "List of functions applied to a transcoded src-block.
1882 Each filter is called with three arguments: the transcoded
1883 src-block, as a string, the back-end, as a symbol, and the
1884 communication channel, as a plist. It must return a string or
1888 "List of functions applied to a transcoded table.
1889 Each filter is called with three arguments: the transcoded table,
1890 as a string, the back-end, as a symbol, and the communication
1894 "List of functions applied to a transcoded table-cell.
1895 Each filter is called with three arguments: the transcoded
1896 table-cell, as a string, the back-end, as a symbol, and the
1897 communication channel, as a plist. It must return a string or
1901 "List of functions applied to a transcoded table-row.
1902 Each filter is called with three arguments: the transcoded
1903 table-row, as a string, the back-end, as a symbol, and the
1904 communication channel, as a plist. It must return a string or
1908 "List of functions applied to a transcoded verse block.
1909 Each filter is called with three arguments: the transcoded verse
1910 block, as a string, the back-end, as a symbol, and the
1911 communication channel, as a plist. It must return a string or
1915 ;;;; Objects Filters
1918 "List of functions applied to a transcoded emphasis.
1919 Each filter is called with three arguments: the transcoded
1920 emphasis, as a string, the back-end, as a symbol, and the
1921 communication channel, as a plist. It must return a string or
1925 "List of functions applied to a transcoded entity.
1926 Each filter is called with three arguments: the transcoded
1927 entity, as a string, the back-end, as a symbol, and the
1928 communication channel, as a plist. It must return a string or
1932 "List of functions applied to a transcoded export-snippet.
1933 Each filter is called with three arguments: the transcoded
1934 export-snippet, as a string, the back-end, as a symbol, and the
1935 communication channel, as a plist. It must return a string or
1939 "List of functions applied to a transcoded footnote-reference.
1940 Each filter is called with three arguments: the transcoded
1941 footnote-reference, as a string, the back-end, as a symbol, and
1942 the communication channel, as a plist. It must return a string
1946 "List of functions applied to a transcoded inline-babel-call.
1947 Each filter is called with three arguments: the transcoded
1948 inline-babel-call, as a string, the back-end, as a symbol, and
1949 the communication channel, as a plist. It must return a string
1953 "List of functions applied to a transcoded inline-src-block.
1954 Each filter is called with three arguments: the transcoded
1955 inline-src-block, as a string, the back-end, as a symbol, and the
1956 communication channel, as a plist. It must return a string or
1960 "List of functions applied to a transcoded latex-fragment.
1961 Each filter is called with three arguments: the transcoded
1962 latex-fragment, as a string, the back-end, as a symbol, and the
1963 communication channel, as a plist. It must return a string or
1967 "List of functions applied to a transcoded line-break.
1968 Each filter is called with three arguments: the transcoded
1969 line-break, as a string, the back-end, as a symbol, and the
1970 communication channel, as a plist. It must return a string or
1974 "List of functions applied to a transcoded link.
1975 Each filter is called with three arguments: the transcoded link,
1976 as a string, the back-end, as a symbol, and the communication
1980 "List of functions applied to a transcoded macro.
1981 Each filter is called with three arguments: the transcoded macro,
1982 as a string, the back-end, as a symbol, and the communication
1986 "List of functions applied to a transcoded radio-target.
1987 Each filter is called with three arguments: the transcoded
1988 radio-target, as a string, the back-end, as a symbol, and the
1989 communication channel, as a plist. It must return a string or
1993 "List of functions applied to a transcoded statistics-cookie.
1994 Each filter is called with three arguments: the transcoded
1995 statistics-cookie, as a string, the back-end, as a symbol, and
1996 the communication channel, as a plist. It must return a string
2000 "List of functions applied to a transcoded subscript.
2001 Each filter is called with three arguments: the transcoded
2002 subscript, as a string, the back-end, as a symbol, and the
2003 communication channel, as a plist. It must return a string or
2007 "List of functions applied to a transcoded superscript.
2008 Each filter is called with three arguments: the transcoded
2009 superscript, as a string, the back-end, as a symbol, and the
2010 communication channel, as a plist. It must return a string or
2014 "List of functions applied to a transcoded target.
2015 Each filter is called with three arguments: the transcoded
2016 target, as a string, the back-end, as a symbol, and the
2017 communication channel, as a plist. It must return a string or
2021 "List of functions applied to a transcoded time-stamp.
2022 Each filter is called with three arguments: the transcoded
2023 time-stamp, as a string, the back-end, as a symbol, and the
2024 communication channel, as a plist. It must return a string or
2028 "List of functions applied to a transcoded verbatim.
2029 Each filter is called with three arguments: the transcoded
2030 verbatim, as a string, the back-end, as a symbol, and the
2031 communication channel, as a plist. It must return a string or
2035 "Call every function in FILTERS with arguments VALUE, BACKEND and INFO.
2036 Functions are called in a LIFO fashion, to be sure that developer
2037 specified filters, if any, are called first."
2041 value)
2044 "Install filters properties in communication channel.
2046 BACKEND is a symbol specifying which back-end specific filters to
2047 install, if any. INFO is a plist containing the current
2048 communication channel.
2050 Return the updated communication channel."
2052 ;; Install user defined filters with `org-export-filters-alist'.
2055 org-export-filters-alist)
2056 ;; Prepend back-end specific filters to that list.
2060 ;; Single values get consed, lists are prepended.
2065 plist key
2069 ;; Return new communication channel.
2073 \f
2074 ;;; Core functions
2076 ;; This is the room for the main function, `org-export-as', along with
2077 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
2078 ;; They differ only by the way they output the resulting code.
2080 ;; `org-export-output-file-name' is an auxiliary function meant to be
2081 ;; used with `org-export-to-file'. With a given extension, it tries
2082 ;; to provide a canonical file name to write export output to.
2084 ;; Note that `org-export-as' doesn't really parse the current buffer,
2085 ;; but a copy of it (with the same buffer-local variables and
2086 ;; visibility), where include keywords are expanded and Babel blocks
2087 ;; are executed, if appropriate.
2088 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
2090 ;; File inclusion is taken care of by
2091 ;; `org-export-expand-include-keyword' and
2092 ;; `org-export-prepare-file-contents'. Structure wise, including
2093 ;; a whole Org file in a buffer often makes little sense. For
2094 ;; example, if the file contains an headline and the include keyword
2095 ;; was within an item, the item should contain the headline. That's
2096 ;; why file inclusion should be done before any structure can be
2097 ;; associated to the file, that is before parsing.
2101 "Transcode current Org buffer into BACKEND code.
2103 If narrowing is active in the current buffer, only transcode its
2104 narrowed part.
2106 If a region is active, transcode that region.
2108 When optional argument SUBTREEP is non-nil, transcode the
2109 sub-tree at point, extracting information from the headline
2110 properties first.
2112 When optional argument VISIBLE-ONLY is non-nil, don't export
2113 contents of hidden elements.
2115 When optional argument BODY-ONLY is non-nil, only return body
2116 code, without preamble nor postamble.
2118 Optional argument EXT-PLIST, when provided, is a property list
2119 with external parameters overriding Org default settings, but
2120 still inferior to file-local settings.
2122 Optional argument NOEXPAND, when non-nil, prevents included files
2123 to be expanded and Babel code to be executed.
2125 Return code as a string."
2128 ;; Narrow buffer to an appropriate region or subtree for
2129 ;; parsing. If parsing subtree, be sure to remove main headline
2130 ;; too.
2138 ;; 1. Get export environment from original buffer. Store
2139 ;; original footnotes definitions in communication channel as
2140 ;; they might not be accessible anymore in a narrowed parse
2141 ;; tree. Also install user's and developer's filters.
2143 backend
2146 ;; 2. Get parse tree. If NOEXPAND is non-nil, simply
2147 ;; parse current visible part of buffer.
2149 ;; Otherwise, buffer isn't parsed directly.
2150 ;; Instead, a temporary copy is created, where
2151 ;; include keywords are expanded and code blocks
2152 ;; are evaluated.
2157 ;; Setting `org-current-export-file' is
2158 ;; required by Org Babel to properly resolve
2159 ;; noweb references.
2163 ;; 3. Call parse-tree filters to get the final tree.
2167 ;; 4. Now tree is complete, compute its properties and add
2168 ;; them to communication channel.
2171 info
2173 ;; 5. Eventually transcode TREE. Wrap the resulting string
2174 ;; into a template, if required. Eventually call
2175 ;; final-output filter.
2183 backend info)))
2184 ;; Maybe add final OUTPUT to kill ring, then return it.
2186 output)))))
2190 "Call `org-export-as' with output to a specified buffer.
2192 BACKEND is the back-end used for transcoding, as a symbol.
2194 BUFFER is the output buffer. If it already exists, it will be
2195 erased first, otherwise, it will be created.
2197 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2198 and NOEXPAND are similar to those used in `org-export-as', which
2199 see.
2201 Return buffer."
2203 backend subtreep visible-only body-only ext-plist noexpand))
2209 buffer))
2213 "Call `org-export-as' with output to a specified file.
2215 BACKEND is the back-end used for transcoding, as a symbol. FILE
2216 is the name of the output file, as a string.
2218 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2219 and NOEXPAND are similar to those used in `org-export-as', which
2220 see.
2222 Return output file's name."
2223 ;; Checks for FILE permissions. `write-file' would do the same, but
2224 ;; we'd rather avoid needless transcoding of parse tree.
2226 ;; Insert contents to a temporary buffer and write it to FILE.
2228 backend subtreep visible-only body-only ext-plist noexpand)))
2233 ;; Return full path.
2234 file)
2237 "Return output file's name according to buffer specifications.
2239 EXTENSION is a string representing the output file extension,
2240 with the leading dot.
2242 With a non-nil optional argument SUBTREEP, try to determine
2244 of subtree at point.
2246 When optional argument PUB-DIR is set, use it as the publishing
2247 directory.
2249 Return file name as a string, or nil if it couldn't be
2250 determined."
2252 ;; File name may come from EXPORT_FILE_NAME subtree property,
2253 ;; assuming point is at beginning of said sub-tree.
2261 ;; File name may be extracted from buffer's associated
2262 ;; file, if any.
2264 ;; Can't determine file name on our own: Ask user.
2268 "Output file: " pub-dir nil nil nil
2271 ;; Build file name. Enforce EXTENSION over whatever user may have
2272 ;; come up with. PUB-DIR, if defined, always has precedence over
2273 ;; any provided path.
2278 extension))
2284 "Apply BODY in a copy of the current buffer.
2286 The copy preserves local variables and visibility of the original
2287 buffer.
2289 Point is at buffer's beginning when BODY is applied."
2299 ,original-buffer
2304 ov
2314 "Expand every include keyword in buffer.
2315 Optional argument INCLUDED is a list of included file names along
2316 with their line restriction, when appropriate. It is used to
2317 avoid infinite recursion. Optional argument DIR is the current
2318 working directory. It is used to properly resolve relative
2319 paths."
2326 ;; Extract arguments from keyword's value.
2340 ;; Minimal level of included file defaults to the child
2341 ;; level of the current headline, if any, or one. It
2342 ;; only applies is the file is meant to be included as
2343 ;; an Org one.
2351 ;; Remove keyword.
2355 ;; Check if files has already been parsed. Look after
2356 ;; inclusion lines too, as different parts of the same file
2357 ;; can be included too.
2366 ;; Protect sensitive contents with commas.
2372 ind-str contents ind-str))))
2377 ;; Protect sensitive contents with commas.
2384 ind-str env contents ind-str))))
2397 "Prepare the contents of FILE for inclusion and return them as a string.
2399 When optional argument LINES is a string specifying a range of
2400 lines, include only those lines.
2402 Optional argument IND, when non-nil, is an integer specifying the
2403 global indentation of returned contents. Since its purpose is to
2404 allow an included file to stay in the same environment it was
2405 created \(i.e. a list item), it doesn't apply past the first
2406 headline encountered.
2408 Optional argument MINLEVEL, when non-nil, is an integer
2409 specifying the level that any top-level headline in the included
2410 file should have."
2426 ;; Remove blank lines at beginning and end of contents. The logic
2427 ;; behind that removal is that blank lines around include keyword
2428 ;; override blank lines in included file.
2437 ;; If IND is set, preserve indentation of include keyword until
2438 ;; the first headline encountered.
2444 ;; Do not move footnote definitions out of column 0.
2450 ;; When MINLEVEL is specified, compute minimal level for headlines
2451 ;; in the file (CUR-MIN), and remove stars to each headline so
2452 ;; that headlines with minimal level have a level of MINLEVEL.
2461 ;; Only change stars, don't bother moving whole
2462 ;; sections.
2468 \f
2469 ;;; Tools For Back-Ends
2471 ;; A whole set of tools is available to help build new exporters. Any
2472 ;; function general enough to have its use across many back-ends
2473 ;; should be added here.
2475 ;; As of now, functions operating on footnotes, headlines, links,
2476 ;; macros, references, src-blocks, tables and tables of contents are
2477 ;; implemented.
2479 ;;;; For Export Snippets
2481 ;; Every export snippet is transmitted to the back-end. Though, the
2482 ;; latter will only retain one type of export-snippet, ignoring
2483 ;; others, based on the former's target back-end. The function
2484 ;; `org-export-snippet-backend' returns that back-end for a given
2485 ;; export-snippet.
2488 "Return EXPORT-SNIPPET targeted back-end as a symbol.
2489 Translation, with `org-export-snippet-translation-alist', is
2490 applied."
2494 back-end))))
2497 ;;;; For Footnotes
2499 ;; `org-export-collect-footnote-definitions' is a tool to list
2500 ;; actually used footnotes definitions in the whole parse tree, or in
2501 ;; an headline, in order to add footnote listings throughout the
2502 ;; transcoded data.
2504 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2505 ;; back-ends, when they need to attach the footnote definition only to
2506 ;; the first occurrence of the corresponding label.
2508 ;; `org-export-get-footnote-definition' and
2509 ;; `org-export-get-footnote-number' provide easier access to
2510 ;; additional information relative to a footnote reference.
2513 "Return an alist between footnote numbers, labels and definitions.
2515 DATA is the parse tree from which definitions are collected.
2516 INFO is the plist used as a communication channel.
2518 Definitions are sorted by order of references. They either
2519 appear as Org data (transcoded with `org-export-data') or as
2520 a secondary string for inlined footnotes (transcoded with
2521 `org-export-secondary-string'). Unreferenced definitions are
2522 ignored."
2527 ;; Collect footnote number, label and definition in DATA.
2529 data 'footnote-reference
2536 def)
2537 num-alist)
2538 ;; Also search in definition for nested footnotes.
2541 ;; Don't enter footnote definitions since it will happen
2542 ;; when their first reference is found.
2548 "Non-nil when a footnote reference is the first one for its label.
2550 FOOTNOTE-REFERENCE is the footnote reference being considered.
2551 INFO is the plist used as a communication channel."
2553 ;; Anonymous footnotes are always a first reference.
2555 ;; Otherwise, return the first footnote with the same LABEL and
2556 ;; test if it is equal to FOOTNOTE-REFERENCE.
2561 data 'footnote-reference
2566 ;; If FN isn't inlined, be sure to traverse its
2567 ;; definition before resuming search. See
2568 ;; comments in `org-export-get-footnote-number'
2569 ;; for more information.
2573 ;; Don't enter footnote definitions since it will
2574 ;; happen when their first reference is found.
2577 footnote-reference)))))
2580 "Return definition of FOOTNOTE-REFERENCE as parsed data.
2581 INFO is the plist used as a communication channel."
2587 "Return number associated to a footnote.
2589 FOOTNOTE is either a footnote reference or a footnote definition.
2590 INFO is the plist used as a communication channel."
2592 seen-refs
2596 ;; Search footnote references through DATA, filling
2597 ;; SEEN-REFS along the way.
2599 data 'footnote-reference
2603 ;; Anonymous footnote match: return number.
2606 ;; Labels match: return number.
2609 ;; Anonymous footnote: it's always a new one. Also,
2610 ;; be sure to return nil from the `cond' so
2611 ;; `first-match' doesn't get us out of the loop.
2613 ;; Label not seen so far: add it so SEEN-REFS.
2614 ;;
2615 ;; Also search for subsequent references in footnote
2616 ;; definition so numbering following reading logic.
2617 ;; Note that we don't have to care about inline
2618 ;; definitions, since `org-element-map' already
2619 ;; traverse them at the right time.
2620 ;;
2621 ;; Once again, return nil to stay in the loop.
2626 nil))))
2627 ;; Don't enter footnote definitions since it will happen
2628 ;; when their first reference is found.
2633 ;;;; For Headlines
2635 ;; `org-export-get-relative-level' is a shortcut to get headline
2636 ;; level, relatively to the lower headline level in the parsed tree.
2638 ;; `org-export-get-headline-number' returns the section number of an
2639 ;; headline, while `org-export-number-to-roman' allows to convert it
2640 ;; to roman numbers.
2642 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
2643 ;; `org-export-last-sibling-p' are three useful predicates when it
2644 ;; comes to fulfill the `:headline-levels' property.
2647 "Return HEADLINE relative level within current parsed tree.
2648 INFO is a plist holding contextual information."
2653 "Non-nil when HEADLINE is considered as low level.
2655 INFO is a plist used as a communication channel.
2657 A low level headlines has a relative level greater than
2658 `:headline-levels' property value.
2660 Return value is the difference between HEADLINE relative level
2661 and the last level being considered as high enough, or nil."
2668 "Return HEADLINE numbering as a list of numbers.
2669 INFO is a plist holding contextual information."
2673 "Return a non-nil value if HEADLINE element should be numbered.
2674 INFO is a plist used as a communication channel."
2680 "Convert integer N into a roman numeral."
2693 res)))
2696 "Non-nil when HEADLINE is the first sibling in its sub-tree.
2697 INFO is the plist used as a communication channel."
2702 "Non-nil when HEADLINE is the last sibling in its sub-tree.
2703 INFO is the plist used as a communication channel."
2707 ;;;; For Links
2709 ;; `org-export-solidify-link-text' turns a string into a safer version
2710 ;; for links, replacing most non-standard characters with hyphens.
2712 ;; `org-export-get-coderef-format' returns an appropriate format
2713 ;; string for coderefs.
2715 ;; `org-export-inline-image-p' returns a non-nil value when the link
2716 ;; provided should be considered as an inline image.
2718 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
2719 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
2720 ;; returns an appropriate unique identifier when found, or nil.
2722 ;; `org-export-resolve-id-link' returns the first headline with
2723 ;; specified id or custom-id in parse tree, or nil when none was
2724 ;; found.
2726 ;; `org-export-resolve-coderef' associates a reference to a line
2727 ;; number in the element it belongs, or returns the reference itself
2728 ;; when the element isn't numbered.
2731 "Take link text S and make a safe target out of it."
2736 "Return format string for code reference link.
2737 PATH is the link path. DESC is its description."
2745 "Non-nil if LINK object points to an inline image.
2747 Optional argument is a set of RULES defining inline images. It
2748 is an alist where associations have the following shape:
2750 \(TYPE . REGEXP)
2752 Applying a rule means apply REGEXP against LINK's path when its
2753 type is TYPE. The function will return a non-nil value if any of
2754 the provided rules is non-nil. The default rule is
2755 `org-export-default-inline-image-rule'.
2757 This only applies to links without a description."
2766 rules))))
2769 "Return LINK destination.
2771 INFO is a plist holding contextual information.
2773 Return value can be an object, an element, or nil:
2775 - If LINK path matches a target object (i.e. <<path>>) or
2778 - If LINK path exactly matches the name affiliated keyword
2779 \(i.e. #+NAME: path) of an element, return that element.
2781 - If LINK path exactly matches any headline name, return that
2782 element. If more than one headline share that name, priority
2783 will be given to the one with the closest common ancestor, if
2784 any, or the first one in the parse tree otherwise.
2786 - Otherwise, return nil.
2791 ;; First try to find a matching "<<path>>" unless user specified
2792 ;; he was looking for an headline (path starts with a *
2793 ;; character).
2797 return target)))
2798 ;; Then try to find an element with a matching "#+NAME: path"
2799 ;; affiliated keyword.
2806 ;; Last case: link either points to an headline or to
2807 ;; nothingness. Try to find the source, with priority given to
2808 ;; headlines with the closest common ancestor. If such candidate
2809 ;; is found, return its beginning position as an unique
2810 ;; identifier, otherwise return nil.
2814 ;; Return first headline whose `:raw-value' property
2815 ;; is NAME in parse tree DATA, or nil.
2818 data 'headline
2822 name)
2823 headline))
2825 ;; Search among headlines sharing an ancestor with link,
2826 ;; from closest to farthest.
2834 ;; No match with a common ancestor: try the full parse-tree.
2838 "Return headline referenced as LINK destination.
2840 INFO is a plist used as a communication channel.
2842 Return value can be an headline element or nil. Assume LINK type
2850 headline))
2854 "Resolve a code reference REF.
2856 INFO is a plist used as a communication channel.
2858 Return associated line number in source code, or REF itself,
2859 depending on src-block or example element's switches."
2867 org-coderef-label-format)))
2871 ;; Element containing REF is found. Resolve it to either
2872 ;; a label or a line number, as needed.
2882 ;;;; For Macros
2884 ;; `org-export-expand-macro' simply takes care of expanding macros.
2887 "Expand MACRO and return it as a string.
2888 INFO is a plist holding export options."
2891 ;; User's macros are stored in the communication channel with
2892 ;; a ":macro-" prefix. If it's a string leave it as-is.
2893 ;; Otherwise, it's a secondary string that needs to be
2894 ;; expanded recursively.
2900 ;; Replace arguments in VALUE.
2907 ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
2910 ;; Return string.
2914 ;;;; For References
2916 ;; `org-export-get-ordinal' associates a sequence number to any object
2917 ;; or element.
2920 "Return ordinal number of an element or object.
2922 ELEMENT is the element or object considered. INFO is the plist
2923 used as a communication channel.
2925 Optional argument TYPES, when non-nil, is a list of element or
2926 object types, as symbols, that should also be counted in.
2927 Otherwise, only provided element's type is considered.
2929 Optional argument PREDICATE is a function returning a non-nil
2930 value if the current element or object should be counted in. It
2931 accepts two arguments: the element or object being considered and
2932 the plist used as a communication channel. This allows to count
2933 only a certain type of objects (i.e. inline images).
2935 Return value is a list of numbers if ELEMENT is an headline or an
2936 item. It is nil for keywords. It represents the footnote number
2937 for footnote definitions and footnote references. If ELEMENT is
2938 a target, return the same value as if ELEMENT was the closest
2939 table, item or headline containing the target. In any other
2940 case, return the sequence number of ELEMENT among elements or
2941 objects of the same type."
2942 ;; A target keyword, representing an invisible target, never has
2943 ;; a sequence number.
2945 ;; Ordinal of a target object refer to the ordinal of the closest
2946 ;; table, item, or headline containing the object.
2950 when
2954 table))
2955 return parent)))
2957 ;; Special case 1: An headline returns its number as a list.
2959 ;; Special case 2: An item returns its number as a list.
2963 struct
2970 ;; Increment counter until ELEMENT is found again.
2981 ;;;; For Src-Blocks
2983 ;; `org-export-get-loc' counts number of code lines accumulated in
2984 ;; src-block or example-block elements with a "+n" switch until
2985 ;; a given element, excluded. Note: "-n" switches reset that count.
2987 ;; `org-export-unravel-code' extracts source code (along with a code
2988 ;; references alist) from an `element-block' or `src-block' type
2989 ;; element.
2991 ;; `org-export-format-code' applies a formatting function to each line
2992 ;; of code, providing relative line number and code reference when
2993 ;; appropriate. Since it doesn't access the original element from
2994 ;; which the source code is coming, it expects from the code calling
2995 ;; it to know if lines should be numbered and if code references
2996 ;; should appear.
2998 ;; Eventually, `org-export-format-code-default' is a higher-level
2999 ;; function (it makes use of the two previous functions) which handles
3000 ;; line numbering and code references inclusion, and returns source
3001 ;; code in a format suitable for plain text or verbatim output.
3004 "Return accumulated lines of code up to ELEMENT.
3006 INFO is the plist used as a communication channel.
3008 ELEMENT is excluded from count."
3015 ;; ELEMENT is reached: Quit the loop.
3017 ;; Only count lines from src-block and example-block elements
3018 ;; with a "+n" or "-n" switch. A "-n" switch resets counter.
3022 ;; Accumulate locs or reset them.
3026 ;; Return nil to stay in the loop.
3027 nil)))
3029 ;; Return value.
3030 loc))
3033 "Clean source code and extract references out of it.
3035 ELEMENT has either a `src-block' an `example-block' type.
3037 Return a cons cell whose CAR is the source code, cleaned from any
3038 reference and protective comma and CDR is an alist between
3039 relative line number (integer) and name of code reference on that
3040 line (string)."
3042 ;; Get code and clean it. Remove blank lines at its
3043 ;; beginning and end. Also remove protective commas.
3049 ;; If appropriate, remove global indentation.
3053 ;; Free up the protected lines. Note: Org blocks
3054 ;; have commas at the beginning or every line.
3059 ;; Get format used for references.
3062 org-coderef-label-format)))
3063 ;; Build a regexp matching a loc with a reference.
3068 ;; Return value.
3070 ;; Code with references removed.
3076 ;; Ref line: remove ref, and signal its position in REFS.
3080 ;; Reference alist.
3081 refs)))
3084 "Format CODE by applying FUN line-wise and return it.
3086 CODE is a string representing the code to format. FUN is
3087 a function. It must accept three arguments: a line of
3088 code (string), the current line number (integer) or nil and the
3089 reference associated to the current line (string) or nil.
3091 Optional argument NUM-LINES can be an integer representing the
3092 number of code lines accumulated until the current code. Line
3093 numbers passed to FUN will take it into account. If it is nil,
3094 FUN's second argument will always be nil. This number can be
3095 obtained with `org-export-get-loc' function.
3097 Optional argument REF-ALIST can be an alist between relative line
3098 number (i.e. ignoring NUM-LINES) and the name of the code
3099 reference on it. If it is nil, FUN's third argument will always
3100 be nil. It can be obtained through the use of
3101 `org-export-unravel-code' function."
3113 "Return source code from ELEMENT, formatted in a standard way.
3115 ELEMENT is either a `src-block' or `example-block' element. INFO
3116 is a plist used as a communication channel.
3118 This function takes care of line numbering and code references
3119 inclusion. Line numbers, when applicable, appear at the
3120 beginning of the line, separated from the code by two white
3121 spaces. Code references, on the other hand, appear flushed to
3122 the right, separated by six white spaces from the widest line of
3123 code."
3124 ;; Extract code and references.
3130 ;; Handle line numbering.
3139 ;; Prepare references display, if required. Any reference
3140 ;; should start six columns after the widest line of code,
3141 ;; wrapped with parenthesis.
3146 code
3150 number-str
3151 loc
3157 num-start refs)))
3160 ;;;; For Tables
3162 ;; `org-export-table-has-special-column-p' and
3163 ;; `org-export-table-row-is-special-p' are predicates used to look for
3164 ;; meta-information about the table structure.
3166 ;; `org-export-table-cell-width', `org-export-table-cell-alignment'
3167 ;; and `org-export-table-cell-borders' extract information from
3168 ;; a table-cell element.
3170 ;; `org-export-table-dimensions' gives the number on rows and columns
3171 ;; in the table, ignoring horizontal rules and special columns.
3172 ;; `org-export-table-cell-address', given a table-cell object, returns
3173 ;; the absolute address of a cell. On the other hand,
3174 ;; `org-export-get-table-cell-at' does the contrary.
3177 "Non-nil when TABLE has a special column.
3178 All special columns will be ignored during export."
3179 ;; The table has a special column when every first cell of every row
3180 ;; has an empty value or contains a symbol among "/", "#", "!", "$",
3181 ;; "*" "_" and "^". Though, do not consider a first row containing
3182 ;; only empty cells as special.
3198 "Non-nil when TABLE has an header.
3200 INFO is a plist used as a communication channel.
3202 A table has an header when it contains at least two row groups."
3205 table 'table-row
3213 info)))
3216 "Non-nil if TABLE-ROW is considered special.
3218 INFO is a plist used as the communication channel.
3220 All special rows will be ignored during export."
3224 ;; A row is special either when...
3226 ;; ... it starts with a field only containing "/",
3228 ;; ... the table contains a special column and the row start
3229 ;; with a marking character among, "^", "_", "$" or "!",
3233 ;; ... it contains only alignment cookies and empty cells.
3249 "Return TABLE-ROW's group.
3251 INFO is a plist used as the communication channel.
3253 Return value is the group number, as an integer, or nil special
3254 rows and table rules. Group 1 is also table's header."
3271 "Return TABLE-CELL contents width.
3273 INFO is a plist used as the communication channel.
3275 Return value is the width given by the last width cookie in the
3276 same column as TABLE-CELL, or nil."
3282 cookie-width)
3286 ;; In a special row, try to find a width cookie at COLUMN.
3297 ;; Ignore table rules.
3300 ;; Return value.
3301 cookie-width))
3304 "Return TABLE-CELL contents alignment.
3306 INFO is a plist used as the communication channel.
3308 Return alignment as specified by the last alignment cookie in the
3309 same column as TABLE-CELL. If no such cookie is found, a default
3310 alignment value will be deduced from fraction of numbers in the
3311 column (see `org-table-number-fraction' for more information).
3312 Possible values are `left', `right' and `center'."
3320 cookie-align)
3324 ;; In a special row, try to find an alignment cookie at
3325 ;; COLUMN.
3336 ;; Ignore table rules.
3338 ;; In a standard row, check if cell's contents are expressing
3339 ;; some kind of number. Increase NUMBER-CELLS accordingly.
3340 ;; Though, don't bother if an alignment cookie has already
3341 ;; defined cell's alignment.
3350 ;; Return value. Alignment specified by cookies has precedence
3351 ;; over alignment deduced from cells contents.
3360 "Return TABLE-CELL borders.
3362 INFO is a plist used as a communication channel.
3364 Return value is a list of symbols, or nil. Possible values are:
3365 `top', `bottom', `above', `below', `left' and `right'. Note:
3366 `top' (resp. `bottom') only happen for a cell in the first
3367 row (resp. last row) of the table, ignoring table rules, if any.
3369 Returned borders ignore special rows."
3373 borders)
3374 ;; Top/above border? TABLE-CELL has a border above when a rule
3375 ;; used to demarcate row groups can be found above. Hence,
3376 ;; finding a rule isn't sufficient to push `above' in BORDERS:
3377 ;; another regular row has to be found above that rule.
3386 ;; Look at every row before the current one.
3388 ;; No rule above, or rule found starts the table (ignoring any
3389 ;; special row): TABLE-CELL is at the top of the table.
3392 ;; Bottom/below border? TABLE-CELL has a border below when next
3393 ;; non-regular row below is a rule.
3402 ;; Look at every row after the current one.
3404 ;; No rule below, or rule found ends the table (modulo some
3405 ;; special row): TABLE-CELL is at the bottom of the table.
3408 ;; Right/left borders? They can only be specified by column
3409 ;; groups. Column groups are defined in a row starting with "/".
3410 ;; Also a column groups row only contains "<", "<>", ">" or blank
3411 ;; cells.
3428 ;; There's a left border when previous cell, if
3429 ;; any, ends a group, or current one starts one.
3435 ;; There's a right border when next cell, if any,
3436 ;; starts a group, or current one ends one.
3443 ;; Table rows are read in reverse order so last column groups
3444 ;; row has precedence over any previous one.
3446 ;; Return value.
3447 borders))
3450 "Non-nil when TABLE-CELL is at the beginning of a row group.
3451 INFO is a plist used as a communication channel."
3452 ;; A cell starts a column group either when it is at the beginning
3453 ;; of a row (or after the special column, if any) or when it has
3454 ;; a left border.
3458 table-cell)
3462 "Non-nil when TABLE-CELL is at the end of a row group.
3463 INFO is a plist used as a communication channel."
3464 ;; A cell ends a column group either when it is at the end of a row
3465 ;; or when it has a right border.
3468 table-cell)
3472 "Non-nil when TABLE-ROW is at the beginning of a column group.
3473 INFO is a plist used as a communication channel."
3481 "Non-nil when TABLE-ROW is at the end of a column group.
3482 INFO is a plist used as a communication channel."
3490 "Non-nil when TABLE-ROW is the first table header's row.
3491 INFO is a plist used as a communication channel."
3498 "Non-nil when TABLE-ROW is the last table header's row.
3499 INFO is a plist used as a communication channel."
3506 "Return TABLE dimensions.
3508 INFO is a plist used as a communication channel.
3510 Return value is a CONS like (ROWS . COLUMNS) where
3511 ROWS (resp. COLUMNS) is the number of exportable
3512 rows (resp. columns)."
3514 ;; Set number of rows, and extract first one.
3516 table 'table-row
3521 ;; Set number of columns.
3523 ;; Return value.
3527 "Return address of a regular TABLE-CELL object.
3529 TABLE-CELL is the cell considered. INFO is a plist used as
3530 a communication channel.
3532 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3533 zero-based index. Only exportable cells are considered. The
3534 function returns nil for other cells."
3537 ;; Ignore cells in special rows or in special column.
3542 ;; Row number.
3545 table 'table-row
3551 ;; Column number.
3554 table-row 'table-cell
3561 "Return regular table-cell object at ADDRESS in TABLE.
3563 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3564 zero-based index. TABLE is a table type element. INFO is
3565 a plist used as a communication channel.
3567 If no table-cell, among exportable cells, is found at ADDRESS,
3568 return nil."
3571 ;; Row at (car address) or nil.
3574 table 'table-row
3580 'table-cell
3587 ;;;; For Tables Of Contents
3589 ;; `org-export-collect-headlines' builds a list of all exportable
3590 ;; headline elements, maybe limited to a certain depth. One can then
3591 ;; easily parse it and transcode it.
3593 ;; Building lists of tables, figures or listings is quite similar.
3594 ;; Once the generic function `org-export-collect-elements' is defined,
3595 ;; `org-export-collect-tables', `org-export-collect-figures' and
3596 ;; `org-export-collect-listings' can be derived from it.
3599 "Collect headlines in order to build a table of contents.
3601 INFO is a plist used as a communication channel.
3603 When non-nil, optional argument N must be an integer. It
3604 specifies the depth of the table of contents.
3606 Return a list of all exportable headlines as parsed elements."
3609 'headline
3611 ;; Strip contents from HEADLINE.
3614 info))
3617 "Collect referenceable elements of a determined type.
3619 TYPE can be a symbol or a list of symbols specifying element
3620 types to search. Only elements with a caption or a name are
3621 collected.
3623 INFO is a plist used as a communication channel.
3625 When non-nil, optional argument PREDICATE is a function accepting
3626 one argument, an element of type TYPE. It returns a non-nil
3627 value when that element should be collected.
3629 Return a list of all elements found, in order of appearance."
3639 "Build a list of tables.
3641 INFO is a plist used as a communication channel.
3643 Return a list of table elements with a caption or a name
3644 affiliated keyword."
3648 "Build a list of figures.
3650 INFO is a plist used as a communication channel. PREDICATE is
3651 a function which accepts one argument: a paragraph element and
3652 whose return value is non-nil when that element should be
3653 collected.
3655 A figure is a paragraph type element, with a caption or a name,
3656 verifying PREDICATE. The latter has to be provided since
3659 Return a list of elements recognized as figures."
3663 "Build a list of src blocks.
3665 INFO is a plist used as a communication channel.
3667 Return a list of src-block elements with a caption or a name
3668 affiliated keyword."
3672 ;;;; Topology
3674 ;; Here are various functions to retrieve information about the
3675 ;; neighbourhood of a given element or object. Neighbours of interest
3676 ;; are direct parent (`org-export-get-parent'), parent headline
3677 ;; (`org-export-get-parent-headline'), parent paragraph
3678 ;; (`org-export-get-parent-paragraph'), previous element or object
3679 ;; (`org-export-get-previous-element') and next element or object
3680 ;; (`org-export-get-next-element').
3682 ;; All of these functions are just a specific use of the more generic
3683 ;; `org-export-get-genealogy', which returns the genealogy relative to
3684 ;; the element or object.
3687 "Return genealogy relative to a given element or object.
3688 BLOB is the element or object being considered. INFO is a plist
3689 used as a communication channel."
3694 ;; Walk DATA, looking for BLOB. GENEALOGY is the list of
3695 ;; parents of all elements in DATA.
3702 ;; If BLOB is an object and EL contains a secondary
3703 ;; string, be sure to check it.
3707 org-element-secondary-value-alist))))
3710 walk-data
3719 "Return BLOB parent or nil.
3720 BLOB is the element or object considered. INFO is a plist used
3721 as a communication channel."
3725 "Return BLOB parent headline or nil.
3726 BLOB is the element or object being considered. INFO is a plist
3727 used as a communication channel."
3732 nil))
3735 "Return OBJECT parent paragraph or nil.
3736 OBJECT is the object to consider. INFO is a plist used as
3737 a communication channel."
3742 nil))
3745 "Return OBJECT parent table or nil.
3746 OBJECT is either a `table-cell' or `table-element' type object.
3747 INFO is a plist used as a communication channel."
3752 nil))
3755 "Return previous element or object.
3757 BLOB is an element or object. INFO is a plist used as
3758 a communication channel.
3760 Return previous element or object, a string, or nil."
3765 "Return next element or object.
3767 BLOB is an element or object. INFO is a plist used as
3768 a communication channel.
3770 Return next element or object, a string, or nil."
3775 \f
3776 ;;; The Dispatcher
3778 ;; `org-export-dispatch' is the standard interactive way to start an
3779 ;; export process. It uses `org-export-dispatch-ui' as a subroutine
3780 ;; for its interface. Most commons back-ends should have an entry in
3781 ;; it.
3784 "Export dispatcher for Org mode.
3786 It provides an access to common export related tasks in a buffer.
3787 Its interface comes in two flavours: standard and expert. While
3788 both share the same set of bindings, only the former displays the
3789 valid keys associations. Set `org-export-dispatch-use-expert-ui'
3790 to switch to one or the other.
3792 Return an error if key pressed has no associated command."
3797 org-export-dispatch-use-expert-ui))
3800 ;; Translate "C-a", "C-b"... into "a", "b"... Then take action
3801 ;; depending on user's key pressed.
3803 ;; Allow to quit with "q" key.
3805 ;; Export with `e-ascii' back-end.
3811 `(:ascii-charset
3820 ;; Export with `e-latex' back-end.
3821 (?L
3836 ;; Export with `e-html' back-end.
3837 (?H
3842 ;; set major mode
3852 ;; Export with `e-odt' back-end.
3858 ;; Publishing facilities
3864 org-e-publish-project-alist)))
3867 ;; Undefined command.
3872 "Handle interface for `org-export-dispatch'.
3874 OPTIONS is a list containing current interactive options set for
3875 export. It can contain any of the following symbols:
3876 `body' toggles a body-only export
3877 `subtree' restricts export to current subtree
3878 `visible' restricts export to visible part of buffer.
3879 `force' force publishing files.
3881 EXPERTP, when non-nil, triggers expert UI. In that case, no help
3882 buffer is provided, but indications about currently active
3883 options are given in the prompt. Moreover, \[?] allows to switch
3884 back to standard interface.
3886 Return value is a list with key pressed as CAR and a list of
3887 final interactive export options as CDR."
3891 \[1] Body only: %s [2] Export scope: %s
3892 \[3] Visible only: %s [4] Force publishing: %s
3895 --- (ASCII/Latin-1/UTF-8 Export) -------------------------
3897 \[a/n/u] to TXT file [A/N/U] to temporary buffer
3899 --- (HTML Export) ----------------------------------------
3901 \[h] to HTML file [b] ... and open it
3902 \[H] to temporary buffer
3904 --- (LaTeX Export) ---------------------------------------
3906 \[l] to TEX file [L] to temporary buffer
3907 \[p] to PDF file [d] ... and open it
3909 --- (ODF Export) -----------------------------------------
3911 \[o] to ODT file [O] ... and open it
3913 --- (Publish) --------------------------------------------
3915 \[F] current file [P] current project
3916 \[X] a project [E] every project"
3929 ;; Read a character from command input, toggling interactive
3930 ;; options when applicable. PROMPT is the displayed prompt,
3931 ;; as a string.
3935 ;; Ignore non-standard characters (i.e. "M-a").
3937 ;; Help key: Switch back to standard interface if
3938 ;; expert UI was active.
3940 ;; Toggle export options.
3947 expertp))
3948 ;; Action selected: Send key and options back to
3949 ;; `org-export-dispatch'.
3951 ;; With expert UI, just read key with a fancy prompt. In standard
3952 ;; UI, display an intrusive help buffer.
3963 ;;; org-export.el ends here