| blob | b5b1e3f0a5f2bc94cb82c4376373666f90894ccc |
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."
313 emacs-version)
314 "String to insert at the end of the generated document."
319 "Non-nil means export contents of standard drawers.
321 When t, all drawers are exported. This may also be a list of
322 drawer names to export. This variable doesn't apply to
323 properties drawers.
325 This option can also be set with the #+OPTIONS line,
335 "Non-nil means insert author email into the exported file.
336 This option can also be set with the #+OPTIONS line,
342 "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
344 If the export target supports emphasizing text, the word will be
345 typeset in bold, italic, or underlined, respectively. Not all
346 export backends support this.
353 "Tags that exclude a tree from export.
355 All trees carrying any of these tags will be excluded from
356 export. This is without condition, so even subtrees inside that
357 carry one of the `org-export-select-tags' will be removed.
359 This option can also be set with the #+EXPORT_EXCLUDE_TAGS:
360 keyword."
367 This can be used to have pre-formatted text, fragments of code
368 etc. For example:
369 : ;; Some Lisp examples
370 : (while (defc cnt)
371 : (ding))
372 will be looking just like this in also HTML. See also the QUOTE
373 keyword. Not all export backends support this.
380 "Non-nil means Org footnotes should be exported.
381 This option can also be set with the #+OPTIONS line,
387 "The last level which is still exported as a headline.
389 Inferior levels will produce itemize lists when exported. Note
390 that a numeric prefix argument to an exporter function overrides
391 this setting.
398 "The default language for export and clocktable translations, as a string.
399 This may have an association in
400 `org-clock-clocktable-language-setup'."
405 "Non-nil means preserve all line breaks when exporting.
407 Normally, in HTML output paragraphs will be reformatted.
409 This option can also be set with the #+OPTIONS line,
415 "Non-nil means interpret entities when exporting.
418 Å.
420 For a list of supported names, see the constant `org-entities'
421 and the user option `org-entities-user'.
423 This option can also be set with the #+OPTIONS line,
429 "Non-nil means include priority cookies in export.
431 When nil, remove priority cookies for export.
433 This option can also be set with the #+OPTIONS line,
439 "Non-nil means add section numbers to headlines when exporting.
441 When set to an integer n, numbering will only happen for
442 headlines whose relative level is higher or equal to n.
444 This option can also be set with the #+OPTIONS line,
450 "Tags that select a tree for export.
452 If any such tag is found in a buffer, all trees that do not carry
453 one of these tags will be ignored during export. Inside trees
454 that are selected like this, you can still deselect a subtree by
455 tagging it with one of the `org-export-exclude-tags'.
457 This option can also be set with the #+EXPORT_SELECT_TAGS:
458 keyword."
465 When this option is turned on, these strings will be exported as:
467 Org HTML LaTeX
468 -----+----------+--------
470 -- – --
471 --- — ---
472 ... … \ldots
474 This option can also be set with the #+OPTIONS line,
482 When this option is turned on, you can use TeX-like syntax for
484 will be considered as a single item - so grouping with {} is
485 normally not needed. For example, the following things will be
486 parsed as single sub- or superscripts.
488 10^24 or 10^tau several digits will be considered 1 item.
489 10^-12 or 10^-tau a leading sign with digits or a word
490 x^2-y^3 will be read as x^2 - y^3, because items are
491 terminated by almost any nonword/nondigit char.
492 x_{i^2} or x^(2-i) braces or parenthesis do grouping.
494 Still, ambiguity is possible - so when in doubt use {} to enclose
495 the sub/superscript. If you set this variable to the symbol
496 `{}', the braces are *required* in order to trigger
497 interpretations as sub/superscript. This can be helpful in
500 This option can also be set with the #+OPTIONS line,
509 "Non-nil means create a table of contents in exported files.
511 The TOC contains headlines with levels up
512 to`org-export-headline-levels'. When an integer, include levels
513 up to N in the toc, this may then be different from
514 `org-export-headline-levels', but it will not be allowed to be
515 larger than the number of headline levels. When nil, no table of
516 contents is made.
518 This option can also be set with the #+OPTIONS line,
528 For example:
530 | Name | Address | Birthday |
531 |-------------+----------+-----------|
532 | Arthur Dent | England | 29.2.2100 |
539 "If nil, do not export tags, just remove them from headlines.
541 If this is the symbol `not-in-toc', tags will be removed from
542 table of contents entries, but still be shown in the headlines of
543 the document.
545 This option can also be set with the #+OPTIONS line,
554 "Non-nil means include TODO items for export.
555 This may have the following values:
556 t include tasks independent of state.
557 todo include only tasks that are not yet done.
558 done include only tasks that are already done.
559 nil remove all tasks before export
560 list of keywords keep only tasks with these keywords"
571 "Non-nil means insert a time stamp into the exported file.
572 The time stamp shows when the file was created.
574 This option can also be set with the #+OPTIONS line,
580 "If nil, do not export time stamps and associated keywords."
585 "Non-nil means include TODO keywords in export.
589 "Non-nil means allow #+BIND to define local variable values for export.
590 This is a potential security risk, which is why the user must
591 confirm the use of these lines."
599 "Alist between export snippets back-ends and exporter back-ends.
601 This variable allows to provide shortcuts for export snippets.
605 while every other back-end will ignore it."
613 "Coding system for the exported file."
618 "Non-nil means exported stuff will also be pushed onto the kill ring."
623 "The initial scope when exporting with `org-export-dispatch'.
624 This variable can be either set to `buffer' or `subtree'."
631 "Non-nil means show buffer after exporting to temp buffer.
632 When Org exports to a file, the buffer visiting that file is ever
633 shown, but remains buried. However, when exporting to
634 a temporary buffer, that buffer is popped up in a second window.
635 When this variable is nil, the buffer remains buried also in
636 these cases."
641 "Non-nil means using a non-intrusive `org-export-dispatch'.
642 In that case, no help buffer is displayed. Though, an indicator
646 considered for export\). Also, \[?] allows to switch back to
647 standard mode."
652 \f
653 ;;; The Communication Channel
655 ;; During export process, every function has access to a number of
656 ;; properties. They are of three types:
658 ;; 1. Environment options are collected once at the very beginning of
659 ;; the process, out of the original buffer and configuration.
660 ;; Collecting them is handled by `org-export-get-environment'
661 ;; function.
662 ;;
663 ;; Most environment options are defined through the
664 ;; `org-export-option-alist' variable.
665 ;;
666 ;; 2. Tree properties are extracted directly from the parsed tree,
667 ;; just before export, by `org-export-collect-tree-properties'.
668 ;;
669 ;; 3. Local options are updated during parsing, and their value
670 ;; depends on the level of recursion. For now, only `:ignore-list'
671 ;; belongs to that category.
673 ;; Here is the full list of properties available during transcode
674 ;; process, with their category (option, tree or local) and their
675 ;; value type.
677 ;; + `:author' :: Author's name.
678 ;; - category :: option
679 ;; - type :: string
681 ;; + `:back-end' :: Current back-end used for transcoding.
682 ;; - category :: tree
683 ;; - type :: symbol
685 ;; + `:creator' :: String to write as creation information.
686 ;; - category :: option
687 ;; - type :: string
689 ;; + `:date' :: String to use as date.
690 ;; - category :: option
691 ;; - type :: string
693 ;; + `:description' :: Description text for the current data.
694 ;; - category :: option
695 ;; - type :: string
697 ;; + `:email' :: Author's email.
698 ;; - category :: option
699 ;; - type :: string
701 ;; + `:exclude-tags' :: Tags for exclusion of subtrees from export
702 ;; process.
703 ;; - category :: option
704 ;; - type :: list of strings
706 ;; + `:footnote-definition-alist' :: Alist between footnote labels and
707 ;; their definition, as parsed data. Only non-inlined footnotes
708 ;; are represented in this alist. Also, every definition isn't
709 ;; guaranteed to be referenced in the parse tree. The purpose of
710 ;; this property is to preserve definitions from oblivion
711 ;; (i.e. when the parse tree comes from a part of the original
712 ;; buffer), it isn't meant for direct use in a back-end. To
713 ;; retrieve a definition relative to a reference, use
714 ;; `org-export-get-footnote-definition' instead.
715 ;; - category :: option
716 ;; - type :: alist (STRING . LIST)
718 ;; + `:headline-levels' :: Maximum level being exported as an
719 ;; headline. Comparison is done with the relative level of
720 ;; headlines in the parse tree, not necessarily with their
721 ;; actual level.
722 ;; - category :: option
723 ;; - type :: integer
725 ;; + `:headline-offset' :: Difference between relative and real level
726 ;; of headlines in the parse tree. For example, a value of -1
727 ;; means a level 2 headline should be considered as level
728 ;; 1 (cf. `org-export-get-relative-level').
729 ;; - category :: tree
730 ;; - type :: integer
732 ;; + `:headline-numbering' :: Alist between headlines and their
733 ;; numbering, as a list of numbers
734 ;; (cf. `org-export-get-headline-number').
735 ;; - category :: tree
736 ;; - type :: alist (INTEGER . LIST)
738 ;; + `:ignore-list' :: List of elements and objects that should be
739 ;; ignored during export.
740 ;; - category :: local
741 ;; - type :: list of elements and objects
743 ;; + `:input-file' :: Full path to input file, if any.
744 ;; - category :: option
745 ;; - type :: string or nil
747 ;; + `:keywords' :: List of keywords attached to data.
748 ;; - category :: option
749 ;; - type :: string
751 ;; + `:language' :: Default language used for translations.
752 ;; - category :: option
753 ;; - type :: string
755 ;; + `:macro-input-file' :: Macro returning file name of input file,
756 ;; or nil.
757 ;; - category :: option
758 ;; - type :: string or nil
760 ;; + `:parse-tree' :: Whole parse tree, available at any time during
761 ;; transcoding.
762 ;; - category :: global
763 ;; - type :: list (as returned by `org-element-parse-buffer')
765 ;; + `:preserve-breaks' :: Non-nil means transcoding should preserve
766 ;; all line breaks.
767 ;; - category :: option
768 ;; - type :: symbol (nil, t)
770 ;; + `:section-numbers' :: Non-nil means transcoding should add
771 ;; section numbers to headlines.
772 ;; - category :: option
773 ;; - type :: symbol (nil, t)
775 ;; + `:select-tags' :: List of tags enforcing inclusion of sub-trees
776 ;; in transcoding. When such a tag is present,
777 ;; subtrees without it are de facto excluded from
778 ;; the process. See `use-select-tags'.
779 ;; - category :: option
780 ;; - type :: list of strings
782 ;; + `:target-list' :: List of targets encountered in the parse tree.
783 ;; This is used to partly resolve "fuzzy" links
784 ;; (cf. `org-export-resolve-fuzzy-link').
785 ;; - category :: tree
786 ;; - type :: list of strings
788 ;; + `:time-stamp-file' :: Non-nil means transcoding should insert
789 ;; a time stamp in the output.
790 ;; - category :: option
791 ;; - type :: symbol (nil, t)
793 ;; + `:with-archived-trees' :: Non-nil when archived subtrees should
794 ;; also be transcoded. If it is set to the `headline' symbol,
795 ;; only the archived headline's name is retained.
796 ;; - category :: option
797 ;; - type :: symbol (nil, t, `headline')
799 ;; + `:with-author' :: Non-nil means author's name should be included
800 ;; in the output.
801 ;; - category :: option
802 ;; - type :: symbol (nil, t)
804 ;; + `:with-creator' :: Non-nild means a creation sentence should be
805 ;; inserted at the end of the transcoded string. If the value
806 ;; is `comment', it should be commented.
807 ;; - category :: option
808 ;; - type :: symbol (`comment', nil, t)
810 ;; + `:with-drawers' :: Non-nil means drawers should be exported. If
811 ;; its value is a list of names, only drawers with such names
812 ;; will be transcoded.
813 ;; - category :: option
814 ;; - type :: symbol (nil, t) or list of strings
816 ;; + `:with-email' :: Non-nil means output should contain author's
817 ;; email.
818 ;; - category :: option
819 ;; - type :: symbol (nil, t)
821 ;; + `:with-emphasize' :: Non-nil means emphasized text should be
822 ;; interpreted.
823 ;; - category :: option
824 ;; - type :: symbol (nil, t)
826 ;; + `:with-fixed-width' :: Non-nil if transcoder should interpret
827 ;; strings starting with a colon as a fixed-with (verbatim) area.
828 ;; - category :: option
829 ;; - type :: symbol (nil, t)
831 ;; + `:with-footnotes' :: Non-nil if transcoder should interpret
832 ;; footnotes.
833 ;; - category :: option
834 ;; - type :: symbol (nil, t)
836 ;; + `:with-priority' :: Non-nil means transcoding should include
837 ;; priority cookies.
838 ;; - category :: option
839 ;; - type :: symbol (nil, t)
841 ;; + `:with-special-strings' :: Non-nil means transcoding should
842 ;; interpret special strings in plain text.
843 ;; - category :: option
844 ;; - type :: symbol (nil, t)
846 ;; + `:with-sub-superscript' :: Non-nil means transcoding should
847 ;; interpret subscript and superscript. With a value of "{}",
848 ;; only interpret those using curly brackets.
849 ;; - category :: option
850 ;; - type :: symbol (nil, {}, t)
852 ;; + `:with-tables' :: Non-nil means transcoding should interpret
853 ;; tables.
854 ;; - category :: option
855 ;; - type :: symbol (nil, t)
857 ;; + `:with-tags' :: Non-nil means transcoding should keep tags in
858 ;; headlines. A `not-in-toc' value will remove them
859 ;; from the table of contents, if any, nonetheless.
860 ;; - category :: option
861 ;; - type :: symbol (nil, t, `not-in-toc')
863 ;; + `:with-tasks' :: Non-nil means transcoding should include
864 ;; headlines with a TODO keyword. A `todo' value
865 ;; will only include headlines with a todo type
866 ;; keyword while a `done' value will do the
867 ;; contrary. If a list of strings is provided, only
868 ;; tasks with keywords belonging to that list will
869 ;; be kept.
870 ;; - category :: option
871 ;; - type :: symbol (t, todo, done, nil) or list of strings
873 ;; + `:with-timestamps' :: Non-nil means transcoding should include
874 ;; time stamps and associated keywords. Otherwise, completely
875 ;; remove them.
876 ;; - category :: option
877 ;; - type :: symbol: (t, nil)
879 ;; + `:with-toc' :: Non-nil means that a table of contents has to be
880 ;; added to the output. An integer value limits its
881 ;; depth.
882 ;; - category :: option
883 ;; - type :: symbol (nil, t or integer)
885 ;; + `:with-todo-keywords' :: Non-nil means transcoding should
886 ;; include TODO keywords.
887 ;; - category :: option
888 ;; - type :: symbol (nil, t)
891 ;;;; Environment Options
893 ;; Environment options encompass all parameters defined outside the
894 ;; scope of the parsed data. They come from five sources, in
895 ;; increasing precedence order:
896 ;;
897 ;; - Global variables,
898 ;; - Buffer's attributes,
899 ;; - Options keyword symbols,
900 ;; - Buffer keywords,
901 ;; - Subtree properties.
903 ;; The central internal function with regards to environment options
904 ;; is `org-export-get-environment'. It updates global variables with
905 ;; "#+BIND:" keywords, then retrieve and prioritize properties from
906 ;; the different sources.
908 ;; The internal functions doing the retrieval are:
909 ;; `org-export-get-global-options',
910 ;; `org-export-get-buffer-attributes',
911 ;; `org-export-parse-option-keyword',
912 ;; `org-export-get-subtree-options' and
913 ;; `org-export-get-inbuffer-options'
915 ;; Also, `org-export-confirm-letbind' and `org-export-install-letbind'
916 ;; take care of the part relative to "#+BIND:" keywords.
919 "Collect export options from the current buffer.
921 Optional argument BACKEND is a symbol specifying which back-end
922 specific options to read, if any.
924 When optional argument SUBTREEP is non-nil, assume the export is
925 done against the current sub-tree.
927 Third optional argument EXT-PLIST is a property list with
928 external parameters overriding Org default settings, but still
929 inferior to file-local settings."
930 ;; First install #+BIND variables.
932 ;; Get and prioritize export options...
934 ;; ... from global variables...
936 ;; ... from buffer's attributes...
938 ;; ... from an external property list...
939 ext-plist
940 ;; ... from in-buffer settings...
942 backend
945 ;; ... and from subtree, when appropriate.
947 ;; Return plist.
948 options))
951 "Parse an OPTIONS line and return values as a plist.
952 Optional argument BACKEND is a symbol specifying which back-end
953 specific items to read, if any."
960 ;; Build an alist between #+OPTION: item and property-name.
965 all)))
966 plist)
971 options)
976 alist)
977 plist))
980 "Get export options in subtree at point.
982 Assume point is at subtree's beginning.
984 Return options as a plist."
992 plist :title
994 prop
1004 plist))
1007 "Return current buffer export options, as a plist.
1009 Optional argument BACKEND, when non-nil, is a symbol specifying
1010 which back-end specific options should also be read in the
1011 process.
1013 Optional argument FILES is a list of setup files names read so
1014 far, used to avoid circular dependencies.
1016 Assume buffer is in Org mode. Narrowing, if any, is ignored."
1020 ;; 1. Special keywords, as in `org-export-special-keywords'.
1033 ;; Avoid circular dependencies.
1045 val)
1053 ;; Value will be evaled. Leave it as-is.
1056 ;; Value has to be parsed for nested
1057 ;; macros.
1060 key
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
1130 org-element-parsed-keywords))
1131 ;; 3. Return final value.
1132 plist)))
1135 "Return properties related to buffer attributes, as a plist."
1138 ;; Store full path of input file name, or nil. For internal use.
1139 :input-file visited-file
1144 :macro-modification-time
1150 ;; Store input file name as a macro.
1152 ;; `:macro-date', `:macro-time' and `:macro-property' could as
1153 ;; well be initialized as tree properties, since they don't
1154 ;; depend on buffer properties. Though, it may be more logical
1155 ;; to keep them close to other ":macro-" properties.
1161 "Return global export options as a plist.
1163 Optional argument BACKEND, if non-nil, is a symbol specifying
1164 which back-end specific export options should also be read in the
1165 process."
1171 ;; Output value.
1172 plist)
1175 all)
1176 ;; Return value.
1177 plist))
1180 "Collect and store footnote definitions from current buffer in INFO.
1182 INFO is a plist containing export options.
1184 Footnotes definitions are stored as a alist whose CAR is
1185 footnote's label, as a string, and CDR the contents, as a parse
1186 tree. This alist will be consed to the value of
1187 `:footnote-definition-alist' in INFO, if any.
1189 The new plist is returned; use
1191 \(setq info (org-export-store-footnote-definitions info))
1193 to be sure to use the new value. INFO is modified by side
1194 effects."
1195 ;; Footnotes definitions must be collected in the original buffer,
1196 ;; as there's no insurance that they will still be in the parse
1197 ;; tree, due to some narrowing.
1199 info :footnote-definition-alist
1210 ;; Like `org-element-parse-buffer', but
1211 ;; makes sure the definition doesn't start
1212 ;; with a section element.
1217 alist))))
1218 alist))))
1222 "Can we use #+BIND values during export?
1223 By default this will ask for confirmation by the user, to divert
1224 possible security risks."
1233 "Install the values from #+BIND lines as local variables.
1234 Variables must be installed before in-buffer options are
1235 retrieved."
1242 letbind))))
1247 ;;;; Tree Properties
1249 ;; Tree properties are infromation extracted from parse tree. They
1250 ;; are initialized at the beginning of the transcoding process by
1251 ;; `org-export-collect-tree-properties'.
1253 ;; Dedicated functions focus on computing the value of specific tree
1254 ;; properties during initialization. Thus,
1255 ;; `org-export-populate-ignore-list' lists elements and objects that
1256 ;; should be skipped during export, `org-export-get-min-level' gets
1257 ;; the minimal exportable level, used as a basis to compute relative
1258 ;; level for headlines. Eventually
1259 ;; `org-export-collect-headline-numbering' builds an alist between
1260 ;; headlines and their numbering.
1263 "Extract tree properties from parse tree.
1265 DATA is the parse tree from which information is retrieved. INFO
1266 is a list holding export options. BACKEND is the back-end called
1267 for transcoding, as a symbol.
1269 Following tree properties are set or updated:
1270 `:back-end' Back-end used for transcoding.
1272 `:footnote-definition-alist' List of footnotes definitions in
1273 original buffer and current parse tree.
1275 `:headline-offset' Offset between true level of headlines and
1276 local level. An offset of -1 means an headline
1277 of level 2 should be considered as a level
1278 1 headline in the context.
1280 `:headline-numbering' Alist of all headlines as key an the
1281 associated numbering as value.
1283 `:ignore-list' List of elements that should be ignored during
1284 export.
1286 `:parse-tree' Whole parse tree.
1288 `:target-list' List of all targets in the parse tree."
1289 ;; Install the parse tree in the communication channel, in order to
1290 ;; use `org-export-get-genealogy' and al.
1292 ;; Get the list of elements and objects to ignore, and put it into
1293 ;; `:ignore-list'. Do not overwrite any user ignore that might have
1294 ;; been done during parse tree filtering.
1297 :ignore-list
1300 ;; Compute `:headline-offset' in order to be able to use
1301 ;; `org-export-get-relative-level'.
1305 ;; Update footnotes definitions list with definitions in parse tree.
1306 ;; This is required since buffer expansion might have modified
1307 ;; boundaries of footnote definitions contained in the parse tree.
1308 ;; This way, definitions in `footnote-definition-alist' are bound to
1309 ;; match those in the parse tree.
1312 data 'footnote-definition
1316 defs)))
1318 ;; Properties order doesn't matter: get the rest of the tree
1319 ;; properties.
1321 `(:target-list
1330 info))
1333 "Return minimum exportable headline's level in DATA.
1334 DATA is parsed tree as returned by `org-element-parse-buffer'.
1335 OPTIONS is a plist holding export options."
1346 ;; If no headline was found, for the sake of consistency, set
1347 ;; minimum level to 1 nonetheless.
1351 "Return numbering of all exportable headlines in a parse tree.
1353 DATA is the parse tree. OPTIONS is the plist holding export
1354 options.
1356 Return an alist whose key is an headline and value is its
1357 associated numbering \(in the shape of a list of numbers\)."
1360 data
1361 'headline
1366 headline
1368 for idx from 0 to org-export-max-depth
1372 options)))
1375 "Return list of elements and objects to ignore during export.
1377 DATA is the parse tree to traverse. OPTIONS is the plist holding
1378 export options.
1380 Return elements or objects to ignore as a list."
1385 ;; Collect ignored elements or objects into IGNORE-LIST.
1393 ;; If headline is archived but tree below has
1394 ;; to be skipped, add it to ignore list.
1397 ;; Move into recursive objects/elements.
1401 ;; Main call. First find trees containing a select tag, if any.
1403 ;; Return value.
1404 ignore))
1407 "Return list of headlines containing a select tag in their tree.
1408 DATA is parsed data as returned by `org-element-parse-buffer'.
1409 INFO is a plist holding export options."
1423 ;; When a select tag is found, mark as acceptable
1424 ;; full genealogy and every headline within the
1425 ;; tree.
1430 selected-trees))
1431 ;; Else, continue searching in tree, recursively.
1436 "Non-nil when element or object BLOB should be skipped during export.
1437 OPTIONS is the plist holding export options."
1439 ;; Check headline.
1448 ;; Ignore subtrees with an exclude tag.
1451 ;; Ignore subtrees without a select tag, when such tag is
1452 ;; found in the buffer.
1454 ;; Ignore commented sub-trees.
1456 ;; Ignore archived subtrees if `:with-archived-trees' is nil.
1458 ;; Ignore tasks, if specified by `:with-tasks' property.
1464 ;; Check time-stamp.
1466 ;; Check drawer.
1472 ;; Check table-row.
1474 ;; Check table-cell.
1481 \f
1482 ;;; The Transcoder
1484 ;; This function reads Org data (obtained with, i.e.
1485 ;; `org-element-parse-buffer') and transcodes it into a specified
1486 ;; back-end output. It takes care of updating local properties,
1487 ;; filtering out elements or objects according to export options and
1488 ;; organizing the output blank lines and white space are preserved.
1490 ;; Though, this function is inapropriate for secondary strings, which
1491 ;; require a fresh copy of the plist passed as INFO argument. Thus,
1492 ;; `org-export-secondary-string' is provided for that specific task.
1494 ;; Internally, three functions handle the filtering of objects and
1495 ;; elements during the export. In particular,
1496 ;; `org-export-ignore-element' marks an element or object so future
1497 ;; parse tree traversals skip it, `org-export-interpret-p' tells which
1498 ;; elements or objects should be seen as real Org syntax and
1499 ;; `org-export-expand' transforms the others back into their original
1500 ;; shape.
1503 "Convert DATA to a string into BACKEND format.
1505 DATA is a nested list as returned by `org-element-parse-buffer'.
1507 BACKEND is a symbol among supported exporters.
1509 INFO is a plist holding export options and also used as
1510 a communication channel between elements when walking the nested
1511 list. See `org-export-update-info' function for more
1512 details.
1514 Return transcoded string."
1516 ;; BLOB can be an element, an object, a string, or nil.
1520 ;; BLOB is a string. Check if the optional transcoder for plain
1521 ;; text exists, and call it in that case. Otherwise, simply
1522 ;; return string. Also update INFO and call
1523 ;; `org-export-filter-plain-text-functions'.
1529 backend info)))
1530 ;; BLOB is an element or an object.
1533 ;; 1. Determine the appropriate TRANSCODER.
1536 ;; 1.0 A full Org document is inserted.
1538 ;; 1.1. BLOB should be ignored.
1540 ;; 1.2. BLOB shouldn't be transcoded. Interpret it
1541 ;; back into Org syntax.
1543 ;; 1.3. Else apply naming convention.
1546 ;; 2. Compute CONTENTS of BLOB.
1549 ;; Case 0. No transcoder or no contents: ignore BLOB.
1551 ;; Case 1. Transparently export an Org document.
1553 ;; Case 2. For a greater element.
1555 ;; Ignore contents of an archived tree
1556 ;; when `:with-archived-trees' is `headline'.
1563 ;; Case 3. For an element containing objects.
1567 blob
1568 ;; When normalizing contents of the first paragraph
1569 ;; in an item or a footnote definition, ignore
1570 ;; first line's indentation: there is none and it
1571 ;; might be misleading.
1577 backend info))))
1578 ;; 3. Transcode BLOB into RESULTS string.
1584 backend info))
1586 ;; 4. Return results.
1589 ;; No filter for a full document.
1591 ;; Otherwise, update INFO, append the same white space
1592 ;; between elements or objects as in the original buffer,
1593 ;; and call appropriate filters.
1603 backend info)))
1604 ;; Eventually return string.
1605 results)))))))
1609 "Convert SECONDARY string into BACKEND format.
1611 SECONDARY is a nested list as returned by
1612 `org-element-parse-secondary-string'.
1614 BACKEND is a symbol among supported exporters. INFO is a plist
1615 used as a communication channel.
1617 Return transcoded string."
1618 ;; Make SECONDARY acceptable for `org-export-data'.
1623 "Non-nil if element or object BLOB should be interpreted as Org syntax.
1624 Check is done according to export options INFO, stored as
1625 a plist."
1627 ;; ... entities...
1629 ;; ... emphasis...
1631 ;; ... fixed-width areas.
1633 ;; ... footnotes...
1636 ;; ... sub/superscripts...
1642 ;; ... tables...
1647 "Expand a parsed element or object to its original state.
1648 BLOB is either an element or an object. CONTENTS is its
1649 contents, as a string or nil."
1651 blob contents))
1654 "Add ELEMENT to `:ignore-list' in INFO.
1656 Any element in `:ignore-list' will be skipped when using
1657 `org-element-map'. INFO is modified by side effects."
1661 \f
1662 ;;; The Filter System
1664 ;; Filters allow end-users to tweak easily the transcoded output.
1665 ;; They are the functional counterpart of hooks, as every filter in
1666 ;; a set is applied to the return value of the previous one.
1667 ;;
1668 ;; Every set is back-end agnostic. Although, a filter is always
1669 ;; called, in addition to the string it applies to, with the back-end
1670 ;; used as argument, so it's easy enough for the end-user to add
1671 ;; back-end specific filters in the set. The communication channel,
1672 ;; as a plist, is required as the third argument.
1673 ;;
1674 ;; Filters sets are defined below. There are of four types:
1675 ;;
1676 ;; - `org-export-filter-parse-tree-functions' applies directly on the
1677 ;; complete parsed tree. It's the only filters set that doesn't
1678 ;; apply to a string.
1679 ;; - `org-export-filter-final-output-functions' applies to the final
1680 ;; transcoded string.
1681 ;; - `org-export-filter-plain-text-functions' applies to any string
1682 ;; not recognized as Org syntax.
1683 ;; - `org-export-filter-TYPE-functions' applies on the string returned
1684 ;; after an element or object of type TYPE has been transcoded.
1685 ;;
1686 ;; All filters sets are applied through
1687 ;; `org-export-filter-apply-functions' function. Filters in a set are
1688 ;; applied in a LIFO fashion. It allows developers to be sure that
1689 ;; their filters will be applied first.
1690 ;;
1691 ;; Filters properties are installed in communication channel with
1692 ;; `org-export-install-filters' function.
1693 ;;
1694 ;; Eventually, a hook (`org-export-before-parsing-hook') is run just
1695 ;; before parsing to allow for heavy structure modifications.
1698 ;;;; Before Parsing Hook
1701 "Hook run before parsing an export buffer.
1702 This is run after include keywords have been expanded and Babel
1703 code executed, on a copy of original buffer's area being
1704 exported. Visibility is the same as in the original one. Point
1707 ;;;; Special Filters
1710 "List of functions applied to the parsed tree.
1711 Each filter is called with three arguments: the parse tree, as
1712 returned by `org-element-parse-buffer', the back-end, as
1713 a symbol, and the communication channel, as a plist. It must
1717 "List of functions applied to the transcoded string.
1718 Each filter is called with three arguments: the full transcoded
1719 string, the back-end, as a symbol, and the communication channel,
1720 as a plist. It must return a string that will be used as the
1724 "List of functions applied to plain text.
1725 Each filter is called with three arguments: a string which
1726 contains no Org syntax, the back-end, as a symbol, and the
1727 communication channel, as a plist. It must return a string or
1731 ;;;; Elements Filters
1734 "List of functions applied to a transcoded center block.
1735 Each filter is called with three arguments: the transcoded center
1736 block, as a string, the back-end, as a symbol, and the
1737 communication channel, as a plist. It must return a string or
1741 "List of functions applied to a transcoded drawer.
1742 Each filter is called with three arguments: the transcoded
1743 drawer, as a string, the back-end, as a symbol, and the
1744 communication channel, as a plist. It must return a string or
1748 "List of functions applied to a transcoded dynamic-block.
1749 Each filter is called with three arguments: the transcoded
1750 dynamic-block, as a string, the back-end, as a symbol, and the
1751 communication channel, as a plist. It must return a string or
1755 "List of functions applied to a transcoded headline.
1756 Each filter is called with three arguments: the transcoded
1757 headline, as a string, the back-end, as a symbol, and the
1758 communication channel, as a plist. It must return a string or
1762 "List of functions applied to a transcoded inlinetask.
1763 Each filter is called with three arguments: the transcoded
1764 inlinetask, as a string, the back-end, as a symbol, and the
1765 communication channel, as a plist. It must return a string or
1769 "List of functions applied to a transcoded plain-list.
1770 Each filter is called with three arguments: the transcoded
1771 plain-list, 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 item.
1777 Each filter is called with three arguments: the transcoded item,
1778 as a string, the back-end, as a symbol, and the communication
1782 "List of functions applied to a transcoded comment.
1783 Each filter is called with three arguments: the transcoded
1784 comment, as a string, the back-end, as a symbol, and the
1785 communication channel, as a plist. It must return a string or
1789 "List of functions applied to a transcoded comment-comment.
1790 Each filter is called with three arguments: the transcoded
1791 comment-block, as a string, the back-end, as a symbol, and the
1792 communication channel, as a plist. It must return a string or
1796 "List of functions applied to a transcoded example-block.
1797 Each filter is called with three arguments: the transcoded
1798 example-block, as a string, the back-end, as a symbol, and the
1799 communication channel, as a plist. It must return a string or
1803 "List of functions applied to a transcoded export-block.
1804 Each filter is called with three arguments: the transcoded
1805 export-block, as a string, the back-end, as a symbol, and the
1806 communication channel, as a plist. It must return a string or
1810 "List of functions applied to a transcoded fixed-width.
1811 Each filter is called with three arguments: the transcoded
1812 fixed-width, as a string, the back-end, as a symbol, and the
1813 communication channel, as a plist. It must return a string or
1817 "List of functions applied to a transcoded footnote-definition.
1818 Each filter is called with three arguments: the transcoded
1819 footnote-definition, as a string, the back-end, as a symbol, and
1820 the communication channel, as a plist. It must return a string
1824 "List of functions applied to a transcoded horizontal-rule.
1825 Each filter is called with three arguments: the transcoded
1826 horizontal-rule, as a string, the back-end, as a symbol, and the
1827 communication channel, as a plist. It must return a string or
1831 "List of functions applied to a transcoded keyword.
1832 Each filter is called with three arguments: the transcoded
1833 keyword, as a string, the back-end, as a symbol, and the
1834 communication channel, as a plist. It must return a string or
1838 "List of functions applied to a transcoded latex-environment.
1839 Each filter is called with three arguments: the transcoded
1840 latex-environment, as a string, the back-end, as a symbol, and
1841 the communication channel, as a plist. It must return a string
1845 "List of functions applied to a transcoded babel-call.
1846 Each filter is called with three arguments: the transcoded
1847 babel-call, as a string, the back-end, as a symbol, and the
1848 communication channel, as a plist. It must return a string or
1852 "List of functions applied to a transcoded paragraph.
1853 Each filter is called with three arguments: the transcoded
1854 paragraph, as a string, the back-end, as a symbol, and the
1855 communication channel, as a plist. It must return a string or
1859 "List of functions applied to a transcoded property-drawer.
1860 Each filter is called with three arguments: the transcoded
1861 property-drawer, as a string, the back-end, as a symbol, and the
1862 communication channel, as a plist. It must return a string or
1866 "List of functions applied to a transcoded quote block.
1867 Each filter is called with three arguments: the transcoded quote
1868 block, as a string, the back-end, as a symbol, and the
1869 communication channel, as a plist. It must return a string or
1873 "List of functions applied to a transcoded quote-section.
1874 Each filter is called with three arguments: the transcoded
1875 quote-section, as a string, the back-end, as a symbol, and the
1876 communication channel, as a plist. It must return a string or
1880 "List of functions applied to a transcoded section.
1881 Each filter is called with three arguments: the transcoded
1882 section, as a string, the back-end, as a symbol, and the
1883 communication channel, as a plist. It must return a string or
1887 "List of functions applied to a transcoded special block.
1888 Each filter is called with three arguments: the transcoded
1889 special block, as a string, the back-end, as a symbol, and the
1890 communication channel, as a plist. It must return a string or
1894 "List of functions applied to a transcoded src-block.
1895 Each filter is called with three arguments: the transcoded
1896 src-block, as a string, the back-end, as a symbol, and the
1897 communication channel, as a plist. It must return a string or
1901 "List of functions applied to a transcoded table.
1902 Each filter is called with three arguments: the transcoded table,
1903 as a string, the back-end, as a symbol, and the communication
1907 "List of functions applied to a transcoded table-cell.
1908 Each filter is called with three arguments: the transcoded
1909 table-cell, as a string, the back-end, as a symbol, and the
1910 communication channel, as a plist. It must return a string or
1914 "List of functions applied to a transcoded table-row.
1915 Each filter is called with three arguments: the transcoded
1916 table-row, as a string, the back-end, as a symbol, and the
1917 communication channel, as a plist. It must return a string or
1921 "List of functions applied to a transcoded verse block.
1922 Each filter is called with three arguments: the transcoded verse
1923 block, as a string, the back-end, as a symbol, and the
1924 communication channel, as a plist. It must return a string or
1928 ;;;; Objects Filters
1931 "List of functions applied to a transcoded emphasis.
1932 Each filter is called with three arguments: the transcoded
1933 emphasis, as a string, the back-end, as a symbol, and the
1934 communication channel, as a plist. It must return a string or
1938 "List of functions applied to a transcoded entity.
1939 Each filter is called with three arguments: the transcoded
1940 entity, as a string, the back-end, as a symbol, and the
1941 communication channel, as a plist. It must return a string or
1945 "List of functions applied to a transcoded export-snippet.
1946 Each filter is called with three arguments: the transcoded
1947 export-snippet, as a string, the back-end, as a symbol, and the
1948 communication channel, as a plist. It must return a string or
1952 "List of functions applied to a transcoded footnote-reference.
1953 Each filter is called with three arguments: the transcoded
1954 footnote-reference, as a string, the back-end, as a symbol, and
1955 the communication channel, as a plist. It must return a string
1959 "List of functions applied to a transcoded inline-babel-call.
1960 Each filter is called with three arguments: the transcoded
1961 inline-babel-call, as a string, the back-end, as a symbol, and
1962 the communication channel, as a plist. It must return a string
1966 "List of functions applied to a transcoded inline-src-block.
1967 Each filter is called with three arguments: the transcoded
1968 inline-src-block, as a string, the back-end, as a symbol, and the
1969 communication channel, as a plist. It must return a string or
1973 "List of functions applied to a transcoded latex-fragment.
1974 Each filter is called with three arguments: the transcoded
1975 latex-fragment, as a string, the back-end, as a symbol, and the
1976 communication channel, as a plist. It must return a string or
1980 "List of functions applied to a transcoded line-break.
1981 Each filter is called with three arguments: the transcoded
1982 line-break, as a string, the back-end, as a symbol, and the
1983 communication channel, as a plist. It must return a string or
1987 "List of functions applied to a transcoded link.
1988 Each filter is called with three arguments: the transcoded link,
1989 as a string, the back-end, as a symbol, and the communication
1993 "List of functions applied to a transcoded macro.
1994 Each filter is called with three arguments: the transcoded macro,
1995 as a string, the back-end, as a symbol, and the communication
1999 "List of functions applied to a transcoded radio-target.
2000 Each filter is called with three arguments: the transcoded
2001 radio-target, as a string, the back-end, as a symbol, and the
2002 communication channel, as a plist. It must return a string or
2006 "List of functions applied to a transcoded statistics-cookie.
2007 Each filter is called with three arguments: the transcoded
2008 statistics-cookie, as a string, the back-end, as a symbol, and
2009 the communication channel, as a plist. It must return a string
2013 "List of functions applied to a transcoded subscript.
2014 Each filter is called with three arguments: the transcoded
2015 subscript, as a string, the back-end, as a symbol, and the
2016 communication channel, as a plist. It must return a string or
2020 "List of functions applied to a transcoded superscript.
2021 Each filter is called with three arguments: the transcoded
2022 superscript, as a string, the back-end, as a symbol, and the
2023 communication channel, as a plist. It must return a string or
2027 "List of functions applied to a transcoded target.
2028 Each filter is called with three arguments: the transcoded
2029 target, as a string, the back-end, as a symbol, and the
2030 communication channel, as a plist. It must return a string or
2034 "List of functions applied to a transcoded time-stamp.
2035 Each filter is called with three arguments: the transcoded
2036 time-stamp, as a string, the back-end, as a symbol, and the
2037 communication channel, as a plist. It must return a string or
2041 "List of functions applied to a transcoded verbatim.
2042 Each filter is called with three arguments: the transcoded
2043 verbatim, as a string, the back-end, as a symbol, and the
2044 communication channel, as a plist. It must return a string or
2048 "Call every function in FILTERS with arguments VALUE, BACKEND and INFO.
2049 Functions are called in a LIFO fashion, to be sure that developer
2050 specified filters, if any, are called first."
2054 value)
2057 "Install filters properties in communication channel.
2059 BACKEND is a symbol specifying which back-end specific filters to
2060 install, if any. INFO is a plist containing the current
2061 communication channel.
2063 Return the updated communication channel."
2065 ;; Install user defined filters with `org-export-filters-alist'.
2068 org-export-filters-alist)
2069 ;; Prepend back-end specific filters to that list.
2073 ;; Single values get consed, lists are prepended.
2078 plist key
2082 ;; Return new communication channel.
2086 \f
2087 ;;; Core functions
2089 ;; This is the room for the main function, `org-export-as', along with
2090 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
2091 ;; They differ only by the way they output the resulting code.
2093 ;; `org-export-output-file-name' is an auxiliary function meant to be
2094 ;; used with `org-export-to-file'. With a given extension, it tries
2095 ;; to provide a canonical file name to write export output to.
2097 ;; Note that `org-export-as' doesn't really parse the current buffer,
2098 ;; but a copy of it (with the same buffer-local variables and
2099 ;; visibility), where include keywords are expanded and Babel blocks
2100 ;; are executed, if appropriate.
2101 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
2103 ;; File inclusion is taken care of by
2104 ;; `org-export-expand-include-keyword' and
2105 ;; `org-export-prepare-file-contents'. Structure wise, including
2106 ;; a whole Org file in a buffer often makes little sense. For
2107 ;; example, if the file contains an headline and the include keyword
2108 ;; was within an item, the item should contain the headline. That's
2109 ;; why file inclusion should be done before any structure can be
2110 ;; associated to the file, that is before parsing.
2114 "Transcode current Org buffer into BACKEND code.
2116 If narrowing is active in the current buffer, only transcode its
2117 narrowed part.
2119 If a region is active, transcode that region.
2121 When optional argument SUBTREEP is non-nil, transcode the
2122 sub-tree at point, extracting information from the headline
2123 properties first.
2125 When optional argument VISIBLE-ONLY is non-nil, don't export
2126 contents of hidden elements.
2128 When optional argument BODY-ONLY is non-nil, only return body
2129 code, without preamble nor postamble.
2131 Optional argument EXT-PLIST, when provided, is a property list
2132 with external parameters overriding Org default settings, but
2133 still inferior to file-local settings.
2135 Optional argument NOEXPAND, when non-nil, prevents included files
2136 to be expanded and Babel code to be executed.
2138 Return code as a string."
2141 ;; Narrow buffer to an appropriate region or subtree for
2142 ;; parsing. If parsing subtree, be sure to remove main headline
2143 ;; too.
2151 ;; 1. Get export environment from original buffer. Store
2152 ;; original footnotes definitions in communication channel as
2153 ;; they might not be accessible anymore in a narrowed parse
2154 ;; tree. Also install user's and developer's filters.
2156 backend
2159 ;; 2. Get parse tree. Buffer isn't parsed directly.
2160 ;; Instead, a temporary copy is created, where include
2161 ;; keywords are expanded and code blocks are evaluated.
2167 ;; Setting `org-current-export-file' is
2168 ;; required by Org Babel to properly resolve
2169 ;; noweb references.
2175 ;; 3. Call parse-tree filters to get the final tree.
2179 ;; 4. Now tree is complete, compute its properties and add
2180 ;; them to communication channel.
2183 info
2185 ;; 5. Eventually transcode TREE. Wrap the resulting string
2186 ;; into a template, if required. Eventually call
2187 ;; final-output filter.
2195 backend info)))
2196 ;; Maybe add final OUTPUT to kill ring, then return it.
2198 output)))))
2202 "Call `org-export-as' with output to a specified buffer.
2204 BACKEND is the back-end used for transcoding, as a symbol.
2206 BUFFER is the output buffer. If it already exists, it will be
2207 erased first, otherwise, it will be created.
2209 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2210 and NOEXPAND are similar to those used in `org-export-as', which
2211 see.
2213 Return buffer."
2215 backend subtreep visible-only body-only ext-plist noexpand))
2221 buffer))
2225 "Call `org-export-as' with output to a specified file.
2227 BACKEND is the back-end used for transcoding, as a symbol. FILE
2228 is the name of the output file, as a string.
2230 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2231 and NOEXPAND are similar to those used in `org-export-as', which
2232 see.
2234 Return output file's name."
2235 ;; Checks for FILE permissions. `write-file' would do the same, but
2236 ;; we'd rather avoid needless transcoding of parse tree.
2238 ;; Insert contents to a temporary buffer and write it to FILE.
2240 backend subtreep visible-only body-only ext-plist noexpand)))
2245 ;; Return full path.
2246 file)
2249 "Return output file's name according to buffer specifications.
2251 EXTENSION is a string representing the output file extension,
2252 with the leading dot.
2254 With a non-nil optional argument SUBTREEP, try to determine
2256 of subtree at point.
2258 When optional argument PUB-DIR is set, use it as the publishing
2259 directory.
2261 Return file name as a string, or nil if it couldn't be
2262 determined."
2264 ;; File name may come from EXPORT_FILE_NAME subtree property,
2265 ;; assuming point is at beginning of said sub-tree.
2273 ;; File name may be extracted from buffer's associated
2274 ;; file, if any.
2276 ;; Can't determine file name on our own: Ask user.
2280 "Output file: " pub-dir nil nil nil
2283 ;; Build file name. Enforce EXTENSION over whatever user may have
2284 ;; come up with. PUB-DIR, if defined, always has precedence over
2285 ;; any provided path.
2290 extension))
2296 "Apply BODY in a copy of the current buffer.
2298 The copy preserves local variables and visibility of the original
2299 buffer.
2301 Point is at buffer's beginning when BODY is applied."
2311 ,original-buffer
2316 ov
2326 "Expand every include keyword in buffer.
2327 Optional argument INCLUDED is a list of included file names along
2328 with their line restriction, when appropriate. It is used to
2329 avoid infinite recursion. Optional argument DIR is the current
2330 working directory. It is used to properly resolve relative
2331 paths."
2338 ;; Extract arguments from keyword's value.
2352 ;; Minimal level of included file defaults to the child
2353 ;; level of the current headline, if any, or one. It
2354 ;; only applies is the file is meant to be included as
2355 ;; an Org one.
2363 ;; Remove keyword.
2367 ;; Check if files has already been parsed. Look after
2368 ;; inclusion lines too, as different parts of the same file
2369 ;; can be included too.
2378 ;; Protect sensitive contents with commas.
2384 ind-str contents ind-str))))
2389 ;; Protect sensitive contents with commas.
2396 ind-str env contents ind-str))))
2409 "Prepare the contents of FILE for inclusion and return them as a string.
2411 When optional argument LINES is a string specifying a range of
2412 lines, include only those lines.
2414 Optional argument IND, when non-nil, is an integer specifying the
2415 global indentation of returned contents. Since its purpose is to
2416 allow an included file to stay in the same environment it was
2417 created \(i.e. a list item), it doesn't apply past the first
2418 headline encountered.
2420 Optional argument MINLEVEL, when non-nil, is an integer
2421 specifying the level that any top-level headline in the included
2422 file should have."
2438 ;; Remove blank lines at beginning and end of contents. The logic
2439 ;; behind that removal is that blank lines around include keyword
2440 ;; override blank lines in included file.
2449 ;; If IND is set, preserve indentation of include keyword until
2450 ;; the first headline encountered.
2456 ;; Do not move footnote definitions out of column 0.
2462 ;; When MINLEVEL is specified, compute minimal level for headlines
2463 ;; in the file (CUR-MIN), and remove stars to each headline so
2464 ;; that headlines with minimal level have a level of MINLEVEL.
2473 ;; Only change stars, don't bother moving whole
2474 ;; sections.
2480 \f
2481 ;;; Tools For Back-Ends
2483 ;; A whole set of tools is available to help build new exporters. Any
2484 ;; function general enough to have its use across many back-ends
2485 ;; should be added here.
2487 ;; As of now, functions operating on footnotes, headlines, links,
2488 ;; macros, references, src-blocks, tables and tables of contents are
2489 ;; implemented.
2491 ;;;; For Export Snippets
2493 ;; Every export snippet is transmitted to the back-end. Though, the
2494 ;; latter will only retain one type of export-snippet, ignoring
2495 ;; others, based on the former's target back-end. The function
2496 ;; `org-export-snippet-backend' returns that back-end for a given
2497 ;; export-snippet.
2500 "Return EXPORT-SNIPPET targeted back-end as a symbol.
2501 Translation, with `org-export-snippet-translation-alist', is
2502 applied."
2506 back-end))))
2509 ;;;; For Footnotes
2511 ;; `org-export-collect-footnote-definitions' is a tool to list
2512 ;; actually used footnotes definitions in the whole parse tree, or in
2513 ;; an headline, in order to add footnote listings throughout the
2514 ;; transcoded data.
2516 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2517 ;; back-ends, when they need to attach the footnote definition only to
2518 ;; the first occurrence of the corresponding label.
2520 ;; `org-export-get-footnote-definition' and
2521 ;; `org-export-get-footnote-number' provide easier access to
2522 ;; additional information relative to a footnote reference.
2525 "Return an alist between footnote numbers, labels and definitions.
2527 DATA is the parse tree from which definitions are collected.
2528 INFO is the plist used as a communication channel.
2530 Definitions are sorted by order of references. They either
2531 appear as Org data (transcoded with `org-export-data') or as
2532 a secondary string for inlined footnotes (transcoded with
2533 `org-export-secondary-string'). Unreferenced definitions are
2534 ignored."
2539 ;; Collect footnote number, label and definition in DATA.
2541 data 'footnote-reference
2548 def)
2549 num-alist)
2550 ;; Also search in definition for nested footnotes.
2553 ;; Don't enter footnote definitions since it will happen
2554 ;; when their first reference is found.
2560 "Non-nil when a footnote reference is the first one for its label.
2562 FOOTNOTE-REFERENCE is the footnote reference being considered.
2563 INFO is the plist used as a communication channel."
2565 ;; Anonymous footnotes are always a first reference.
2567 ;; Otherwise, return the first footnote with the same LABEL and
2568 ;; test if it is equal to FOOTNOTE-REFERENCE.
2573 data 'footnote-reference
2578 ;; If FN isn't inlined, be sure to traverse its
2579 ;; definition before resuming search. See
2580 ;; comments in `org-export-get-footnote-number'
2581 ;; for more information.
2585 ;; Don't enter footnote definitions since it will
2586 ;; happen when their first reference is found.
2589 footnote-reference)))))
2592 "Return definition of FOOTNOTE-REFERENCE as parsed data.
2593 INFO is the plist used as a communication channel."
2599 "Return number associated to a footnote.
2601 FOOTNOTE is either a footnote reference or a footnote definition.
2602 INFO is the plist used as a communication channel."
2604 seen-refs
2608 ;; Search footnote references through DATA, filling
2609 ;; SEEN-REFS along the way.
2611 data 'footnote-reference
2615 ;; Anonymous footnote match: return number.
2618 ;; Labels match: return number.
2621 ;; Anonymous footnote: it's always a new one. Also,
2622 ;; be sure to return nil from the `cond' so
2623 ;; `first-match' doesn't get us out of the loop.
2625 ;; Label not seen so far: add it so SEEN-REFS.
2626 ;;
2627 ;; Also search for subsequent references in footnote
2628 ;; definition so numbering following reading logic.
2629 ;; Note that we don't have to care about inline
2630 ;; definitions, since `org-element-map' already
2631 ;; traverse them at the right time.
2632 ;;
2633 ;; Once again, return nil to stay in the loop.
2638 nil))))
2639 ;; Don't enter footnote definitions since it will happen
2640 ;; when their first reference is found.
2645 ;;;; For Headlines
2647 ;; `org-export-get-relative-level' is a shortcut to get headline
2648 ;; level, relatively to the lower headline level in the parsed tree.
2650 ;; `org-export-get-headline-number' returns the section number of an
2651 ;; headline, while `org-export-number-to-roman' allows to convert it
2652 ;; to roman numbers.
2654 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
2655 ;; `org-export-last-sibling-p' are three useful predicates when it
2656 ;; comes to fulfill the `:headline-levels' property.
2659 "Return HEADLINE relative level within current parsed tree.
2660 INFO is a plist holding contextual information."
2665 "Non-nil when HEADLINE is considered as low level.
2667 INFO is a plist used as a communication channel.
2669 A low level headlines has a relative level greater than
2670 `:headline-levels' property value.
2672 Return value is the difference between HEADLINE relative level
2673 and the last level being considered as high enough, or nil."
2680 "Return HEADLINE numbering as a list of numbers.
2681 INFO is a plist holding contextual information."
2685 "Return a non-nil value if HEADLINE element should be numbered.
2686 INFO is a plist used as a communication channel."
2692 "Convert integer N into a roman numeral."
2705 res)))
2708 "Non-nil when HEADLINE is the first sibling in its sub-tree.
2709 INFO is the plist used as a communication channel."
2714 "Non-nil when HEADLINE is the last sibling in its sub-tree.
2715 INFO is the plist used as a communication channel."
2719 ;;;; For Links
2721 ;; `org-export-solidify-link-text' turns a string into a safer version
2722 ;; for links, replacing most non-standard characters with hyphens.
2724 ;; `org-export-get-coderef-format' returns an appropriate format
2725 ;; string for coderefs.
2727 ;; `org-export-inline-image-p' returns a non-nil value when the link
2728 ;; provided should be considered as an inline image.
2730 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
2731 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
2732 ;; returns an appropriate unique identifier when found, or nil.
2734 ;; `org-export-resolve-id-link' returns the first headline with
2735 ;; specified id or custom-id in parse tree, or nil when none was
2736 ;; found.
2738 ;; `org-export-resolve-coderef' associates a reference to a line
2739 ;; number in the element it belongs, or returns the reference itself
2740 ;; when the element isn't numbered.
2743 "Take link text S and make a safe target out of it."
2748 "Return format string for code reference link.
2749 PATH is the link path. DESC is its description."
2757 "Non-nil if LINK object points to an inline image.
2759 Optional argument is a set of RULES defining inline images. It
2760 is an alist where associations have the following shape:
2762 \(TYPE . REGEXP)
2764 Applying a rule means apply REGEXP against LINK's path when its
2765 type is TYPE. The function will return a non-nil value if any of
2766 the provided rules is non-nil. The default rule is
2767 `org-export-default-inline-image-rule'.
2769 This only applies to links without a description."
2778 rules))))
2781 "Return LINK destination.
2783 INFO is a plist holding contextual information.
2785 Return value can be an object, an element, or nil:
2787 - If LINK path matches a target object (i.e. <<path>>) or
2790 - If LINK path exactly matches the name affiliated keyword
2791 \(i.e. #+NAME: path) of an element, return that element.
2793 - If LINK path exactly matches any headline name, return that
2794 element. If more than one headline share that name, priority
2795 will be given to the one with the closest common ancestor, if
2796 any, or the first one in the parse tree otherwise.
2798 - Otherwise, return nil.
2803 ;; First try to find a matching "<<path>>" unless user specified
2804 ;; he was looking for an headline (path starts with a *
2805 ;; character).
2809 return target)))
2810 ;; Then try to find an element with a matching "#+NAME: path"
2811 ;; affiliated keyword.
2818 ;; Last case: link either points to an headline or to
2819 ;; nothingness. Try to find the source, with priority given to
2820 ;; headlines with the closest common ancestor. If such candidate
2821 ;; is found, return its beginning position as an unique
2822 ;; identifier, otherwise return nil.
2826 ;; Return first headline whose `:raw-value' property
2827 ;; is NAME in parse tree DATA, or nil.
2830 data 'headline
2834 name)
2835 headline))
2837 ;; Search among headlines sharing an ancestor with link,
2838 ;; from closest to farthest.
2846 ;; No match with a common ancestor: try the full parse-tree.
2850 "Return headline referenced as LINK destination.
2852 INFO is a plist used as a communication channel.
2854 Return value can be an headline element or nil. Assume LINK type
2862 headline))
2866 "Resolve a code reference REF.
2868 INFO is a plist used as a communication channel.
2870 Return associated line number in source code, or REF itself,
2871 depending on src-block or example element's switches."
2879 org-coderef-label-format)))
2883 ;; Element containing REF is found. Resolve it to either
2884 ;; a label or a line number, as needed.
2894 ;;;; For Macros
2896 ;; `org-export-expand-macro' simply takes care of expanding macros.
2899 "Expand MACRO and return it as a string.
2900 INFO is a plist holding export options."
2903 ;; User's macros are stored in the communication channel with
2904 ;; a ":macro-" prefix. If it's a string leave it as-is.
2905 ;; Otherwise, it's a secondary string that needs to be
2906 ;; expanded recursively.
2912 ;; Replace arguments in VALUE.
2919 ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
2922 ;; Return string.
2926 ;;;; For References
2928 ;; `org-export-get-ordinal' associates a sequence number to any object
2929 ;; or element.
2932 "Return ordinal number of an element or object.
2934 ELEMENT is the element or object considered. INFO is the plist
2935 used as a communication channel.
2937 Optional argument TYPES, when non-nil, is a list of element or
2938 object types, as symbols, that should also be counted in.
2939 Otherwise, only provided element's type is considered.
2941 Optional argument PREDICATE is a function returning a non-nil
2942 value if the current element or object should be counted in. It
2943 accepts two arguments: the element or object being considered and
2944 the plist used as a communication channel. This allows to count
2945 only a certain type of objects (i.e. inline images).
2947 Return value is a list of numbers if ELEMENT is an headline or an
2948 item. It is nil for keywords. It represents the footnote number
2949 for footnote definitions and footnote references. If ELEMENT is
2950 a target, return the same value as if ELEMENT was the closest
2951 table, item or headline containing the target. In any other
2952 case, return the sequence number of ELEMENT among elements or
2953 objects of the same type."
2954 ;; A target keyword, representing an invisible target, never has
2955 ;; a sequence number.
2957 ;; Ordinal of a target object refer to the ordinal of the closest
2958 ;; table, item, or headline containing the object.
2962 when
2966 table))
2967 return parent)))
2969 ;; Special case 1: An headline returns its number as a list.
2971 ;; Special case 2: An item returns its number as a list.
2975 struct
2982 ;; Increment counter until ELEMENT is found again.
2993 ;;;; For Src-Blocks
2995 ;; `org-export-get-loc' counts number of code lines accumulated in
2996 ;; src-block or example-block elements with a "+n" switch until
2997 ;; a given element, excluded. Note: "-n" switches reset that count.
2999 ;; `org-export-unravel-code' extracts source code (along with a code
3000 ;; references alist) from an `element-block' or `src-block' type
3001 ;; element.
3003 ;; `org-export-format-code' applies a formatting function to each line
3004 ;; of code, providing relative line number and code reference when
3005 ;; appropriate. Since it doesn't access the original element from
3006 ;; which the source code is coming, it expects from the code calling
3007 ;; it to know if lines should be numbered and if code references
3008 ;; should appear.
3010 ;; Eventually, `org-export-format-code-default' is a higher-level
3011 ;; function (it makes use of the two previous functions) which handles
3012 ;; line numbering and code references inclusion, and returns source
3013 ;; code in a format suitable for plain text or verbatim output.
3016 "Return accumulated lines of code up to ELEMENT.
3018 INFO is the plist used as a communication channel.
3020 ELEMENT is excluded from count."
3027 ;; ELEMENT is reached: Quit the loop.
3029 ;; Only count lines from src-block and example-block elements
3030 ;; with a "+n" or "-n" switch. A "-n" switch resets counter.
3034 ;; Accumulate locs or reset them.
3038 ;; Return nil to stay in the loop.
3039 nil)))
3041 ;; Return value.
3042 loc))
3045 "Clean source code and extract references out of it.
3047 ELEMENT has either a `src-block' an `example-block' type.
3049 Return a cons cell whose CAR is the source code, cleaned from any
3050 reference and protective comma and CDR is an alist between
3051 relative line number (integer) and name of code reference on that
3052 line (string)."
3054 ;; Get code and clean it. Remove blank lines at its
3055 ;; beginning and end. Also remove protective commas.
3061 ;; If appropriate, remove global indentation.
3065 ;; Free up the protected lines. Note: Org blocks
3066 ;; have commas at the beginning or every line.
3071 ;; Get format used for references.
3074 org-coderef-label-format)))
3075 ;; Build a regexp matching a loc with a reference.
3080 ;; Return value.
3082 ;; Code with references removed.
3088 ;; Ref line: remove ref, and signal its position in REFS.
3092 ;; Reference alist.
3093 refs)))
3096 "Format CODE by applying FUN line-wise and return it.
3098 CODE is a string representing the code to format. FUN is
3099 a function. It must accept three arguments: a line of
3100 code (string), the current line number (integer) or nil and the
3101 reference associated to the current line (string) or nil.
3103 Optional argument NUM-LINES can be an integer representing the
3104 number of code lines accumulated until the current code. Line
3105 numbers passed to FUN will take it into account. If it is nil,
3106 FUN's second argument will always be nil. This number can be
3107 obtained with `org-export-get-loc' function.
3109 Optional argument REF-ALIST can be an alist between relative line
3110 number (i.e. ignoring NUM-LINES) and the name of the code
3111 reference on it. If it is nil, FUN's third argument will always
3112 be nil. It can be obtained through the use of
3113 `org-export-unravel-code' function."
3125 "Return source code from ELEMENT, formatted in a standard way.
3127 ELEMENT is either a `src-block' or `example-block' element. INFO
3128 is a plist used as a communication channel.
3130 This function takes care of line numbering and code references
3131 inclusion. Line numbers, when applicable, appear at the
3132 beginning of the line, separated from the code by two white
3133 spaces. Code references, on the other hand, appear flushed to
3134 the right, separated by six white spaces from the widest line of
3135 code."
3136 ;; Extract code and references.
3142 ;; Handle line numbering.
3151 ;; Prepare references display, if required. Any reference
3152 ;; should start six columns after the widest line of code,
3153 ;; wrapped with parenthesis.
3158 code
3162 number-str
3163 loc
3169 num-start refs)))
3172 ;;;; For Tables
3174 ;; `org-export-table-has-special-column-p' and
3175 ;; `org-export-table-row-is-special-p' are predicates used to look for
3176 ;; meta-information about the table structure.
3178 ;; `org-export-table-cell-width', `org-export-table-cell-alignment'
3179 ;; and `org-export-table-cell-borders' extract information from
3180 ;; a table-cell element.
3182 ;; `org-export-table-dimensions' gives the number on rows and columns
3183 ;; in the table, ignoring horizontal rules and special columns.
3184 ;; `org-export-table-cell-address', given a table-cell object, returns
3185 ;; the absolute address of a cell. On the other hand,
3186 ;; `org-export-get-table-cell-at' does the contrary.
3189 "Non-nil when TABLE has a special column.
3190 All special columns will be ignored during export."
3191 ;; The table has a special column when every first cell of every row
3192 ;; has an empty value or contains a symbol among "/", "#", "!", "$",
3193 ;; "*" "_" and "^". Though, do not consider a first row containing
3194 ;; only empty cells as special.
3210 "Non-nil when TABLE has an header.
3212 INFO is a plist used as a communication channel.
3214 A table has an header when it contains at least two row groups."
3217 table 'table-row
3225 info)))
3228 "Non-nil if TABLE-ROW is considered special.
3230 INFO is a plist used as the communication channel.
3232 All special rows will be ignored during export."
3236 ;; A row is special either when...
3238 ;; ... it starts with a field only containing "/",
3240 ;; ... the table contains a special column and the row start
3241 ;; with a marking character among, "^", "_", "$" or "!",
3245 ;; ... it contains only alignment cookies and empty cells.
3261 "Return TABLE-ROW's group.
3263 INFO is a plist used as the communication channel.
3265 Return value is the group number, as an integer, or nil special
3266 rows and table rules. Group 1 is also table's header."
3283 "Return TABLE-CELL contents width.
3285 INFO is a plist used as the communication channel.
3287 Return value is the width given by the last width cookie in the
3288 same column as TABLE-CELL, or nil."
3294 cookie-width)
3298 ;; In a special row, try to find a width cookie at COLUMN.
3309 ;; Ignore table rules.
3312 ;; Return value.
3313 cookie-width))
3316 "Return TABLE-CELL contents alignment.
3318 INFO is a plist used as the communication channel.
3320 Return alignment as specified by the last alignment cookie in the
3321 same column as TABLE-CELL. If no such cookie is found, a default
3322 alignment value will be deduced from fraction of numbers in the
3323 column (see `org-table-number-fraction' for more information).
3324 Possible values are `left', `right' and `center'."
3332 cookie-align)
3336 ;; In a special row, try to find an alignment cookie at
3337 ;; COLUMN.
3348 ;; Ignore table rules.
3350 ;; In a standard row, check if cell's contents are expressing
3351 ;; some kind of number. Increase NUMBER-CELLS accordingly.
3352 ;; Though, don't bother if an alignment cookie has already
3353 ;; defined cell's alignment.
3362 ;; Return value. Alignment specified by cookies has precedence
3363 ;; over alignment deduced from cells contents.
3372 "Return TABLE-CELL borders.
3374 INFO is a plist used as a communication channel.
3376 Return value is a list of symbols, or nil. Possible values are:
3377 `top', `bottom', `above', `below', `left' and `right'. Note:
3378 `top' (resp. `bottom') only happen for a cell in the first
3379 row (resp. last row) of the table, ignoring table rules, if any.
3381 Returned borders ignore special rows."
3385 borders)
3386 ;; Top/above border? TABLE-CELL has a border above when a rule
3387 ;; used to demarcate row groups can be found above. Hence,
3388 ;; finding a rule isn't sufficient to push `above' in BORDERS:
3389 ;; another regular row has to be found above that rule.
3398 ;; Look at every row before the current one.
3400 ;; No rule above, or rule found starts the table (ignoring any
3401 ;; special row): TABLE-CELL is at the top of the table.
3404 ;; Bottom/below border? TABLE-CELL has a border below when next
3405 ;; non-regular row below is a rule.
3414 ;; Look at every row after the current one.
3416 ;; No rule below, or rule found ends the table (modulo some
3417 ;; special row): TABLE-CELL is at the bottom of the table.
3420 ;; Right/left borders? They can only be specified by column
3421 ;; groups. Column groups are defined in a row starting with "/".
3422 ;; Also a column groups row only contains "<", "<>", ">" or blank
3423 ;; cells.
3440 ;; There's a left border when previous cell, if
3441 ;; any, ends a group, or current one starts one.
3447 ;; There's a right border when next cell, if any,
3448 ;; starts a group, or current one ends one.
3455 ;; Table rows are read in reverse order so last column groups
3456 ;; row has precedence over any previous one.
3458 ;; Return value.
3459 borders))
3462 "Non-nil when TABLE-CELL is at the beginning of a row group.
3463 INFO is a plist used as a communication channel."
3464 ;; A cell starts a column group either when it is at the beginning
3465 ;; of a row (or after the special column, if any) or when it has
3466 ;; a left border.
3470 table-cell)
3474 "Non-nil when TABLE-CELL is at the end of a row group.
3475 INFO is a plist used as a communication channel."
3476 ;; A cell ends a column group either when it is at the end of a row
3477 ;; or when it has a right border.
3480 table-cell)
3484 "Non-nil when TABLE-ROW is at the beginning of a column group.
3485 INFO is a plist used as a communication channel."
3493 "Non-nil when TABLE-ROW is at the end of a column group.
3494 INFO is a plist used as a communication channel."
3502 "Non-nil when TABLE-ROW is the first table header's row.
3503 INFO is a plist used as a communication channel."
3510 "Non-nil when TABLE-ROW is the last table header's row.
3511 INFO is a plist used as a communication channel."
3518 "Return TABLE dimensions.
3520 INFO is a plist used as a communication channel.
3522 Return value is a CONS like (ROWS . COLUMNS) where
3523 ROWS (resp. COLUMNS) is the number of exportable
3524 rows (resp. columns)."
3526 ;; Set number of rows, and extract first one.
3528 table 'table-row
3533 ;; Set number of columns.
3535 ;; Return value.
3539 "Return address of a regular TABLE-CELL object.
3541 TABLE-CELL is the cell considered. INFO is a plist used as
3542 a communication channel.
3544 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3545 zero-based index. Only exportable cells are considered. The
3546 function returns nil for other cells."
3549 ;; Ignore cells in special rows or in special column.
3554 ;; Row number.
3557 table 'table-row
3563 ;; Column number.
3566 table-row 'table-cell
3573 "Return regular table-cell object at ADDRESS in TABLE.
3575 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3576 zero-based index. TABLE is a table type element. INFO is
3577 a plist used as a communication channel.
3579 If no table-cell, among exportable cells, is found at ADDRESS,
3580 return nil."
3583 ;; Row at (car address) or nil.
3586 table 'table-row
3592 'table-cell
3599 ;;;; For Tables Of Contents
3601 ;; `org-export-collect-headlines' builds a list of all exportable
3602 ;; headline elements, maybe limited to a certain depth. One can then
3603 ;; easily parse it and transcode it.
3605 ;; Building lists of tables, figures or listings is quite similar.
3606 ;; Once the generic function `org-export-collect-elements' is defined,
3607 ;; `org-export-collect-tables', `org-export-collect-figures' and
3608 ;; `org-export-collect-listings' can be derived from it.
3611 "Collect headlines in order to build a table of contents.
3613 INFO is a plist used as a communication channel.
3615 When non-nil, optional argument N must be an integer. It
3616 specifies the depth of the table of contents.
3618 Return a list of all exportable headlines as parsed elements."
3621 'headline
3623 ;; Strip contents from HEADLINE.
3626 info))
3629 "Collect referenceable elements of a determined type.
3631 TYPE can be a symbol or a list of symbols specifying element
3632 types to search. Only elements with a caption or a name are
3633 collected.
3635 INFO is a plist used as a communication channel.
3637 When non-nil, optional argument PREDICATE is a function accepting
3638 one argument, an element of type TYPE. It returns a non-nil
3639 value when that element should be collected.
3641 Return a list of all elements found, in order of appearance."
3651 "Build a list of tables.
3653 INFO is a plist used as a communication channel.
3655 Return a list of table elements with a caption or a name
3656 affiliated keyword."
3660 "Build a list of figures.
3662 INFO is a plist used as a communication channel. PREDICATE is
3663 a function which accepts one argument: a paragraph element and
3664 whose return value is non-nil when that element should be
3665 collected.
3667 A figure is a paragraph type element, with a caption or a name,
3668 verifying PREDICATE. The latter has to be provided since
3671 Return a list of elements recognized as figures."
3675 "Build a list of src blocks.
3677 INFO is a plist used as a communication channel.
3679 Return a list of src-block elements with a caption or a name
3680 affiliated keyword."
3684 ;;;; Topology
3686 ;; Here are various functions to retrieve information about the
3687 ;; neighbourhood of a given element or object. Neighbours of interest
3688 ;; are direct parent (`org-export-get-parent'), parent headline
3689 ;; (`org-export-get-parent-headline'), parent paragraph
3690 ;; (`org-export-get-parent-paragraph'), previous element or object
3691 ;; (`org-export-get-previous-element') and next element or object
3692 ;; (`org-export-get-next-element').
3694 ;; All of these functions are just a specific use of the more generic
3695 ;; `org-export-get-genealogy', which returns the genealogy relative to
3696 ;; the element or object.
3699 "Return genealogy relative to a given element or object.
3700 BLOB is the element or object being considered. INFO is a plist
3701 used as a communication channel."
3706 ;; Walk DATA, looking for BLOB. GENEALOGY is the list of
3707 ;; parents of all elements in DATA.
3714 ;; If BLOB is an object and EL contains a secondary
3715 ;; string, be sure to check it.
3719 org-element-secondary-value-alist))))
3722 walk-data
3731 "Return BLOB parent or nil.
3732 BLOB is the element or object considered. INFO is a plist used
3733 as a communication channel."
3737 "Return BLOB parent headline or nil.
3738 BLOB is the element or object being considered. INFO is a plist
3739 used as a communication channel."
3744 nil))
3747 "Return OBJECT parent paragraph or nil.
3748 OBJECT is the object to consider. INFO is a plist used as
3749 a communication channel."
3754 nil))
3757 "Return OBJECT parent table or nil.
3758 OBJECT is either a `table-cell' or `table-element' type object.
3759 INFO is a plist used as a communication channel."
3764 nil))
3767 "Return previous element or object.
3769 BLOB is an element or object. INFO is a plist used as
3770 a communication channel.
3772 Return previous element or object, a string, or nil."
3777 "Return next element or object.
3779 BLOB is an element or object. INFO is a plist used as
3780 a communication channel.
3782 Return next element or object, a string, or nil."
3787 \f
3788 ;;; The Dispatcher
3790 ;; `org-export-dispatch' is the standard interactive way to start an
3791 ;; export process. It uses `org-export-dispatch-ui' as a subroutine
3792 ;; for its interface. Most commons back-ends should have an entry in
3793 ;; it.
3796 "Export dispatcher for Org mode.
3798 It provides an access to common export related tasks in a buffer.
3799 Its interface comes in two flavours: standard and expert. While
3800 both share the same set of bindings, only the former displays the
3801 valid keys associations. Set `org-export-dispatch-use-expert-ui'
3802 to switch to one or the other.
3804 Return an error if key pressed has no associated command."
3809 org-export-dispatch-use-expert-ui))
3812 ;; Translate "C-a", "C-b"... into "a", "b"... Then take action
3813 ;; depending on user's key pressed.
3815 ;; Allow to quit with "q" key.
3817 ;; Export with `e-ascii' back-end.
3823 `(:ascii-charset
3832 ;; Export with `e-latex' back-end.
3833 (?L
3848 ;; Export with `e-html' back-end.
3849 (?H
3854 ;; set major mode
3864 ;; Export with `e-odt' back-end.
3870 ;; Publishing facilities
3876 org-e-publish-project-alist)))
3879 ;; Undefined command.
3884 "Handle interface for `org-export-dispatch'.
3886 OPTIONS is a list containing current interactive options set for
3887 export. It can contain any of the following symbols:
3888 `body' toggles a body-only export
3889 `subtree' restricts export to current subtree
3890 `visible' restricts export to visible part of buffer.
3891 `force' force publishing files.
3893 EXPERTP, when non-nil, triggers expert UI. In that case, no help
3894 buffer is provided, but indications about currently active
3895 options are given in the prompt. Moreover, \[?] allows to switch
3896 back to standard interface.
3898 Return value is a list with key pressed as CAR and a list of
3899 final interactive export options as CDR."
3903 \[1] Body only: %s [2] Export scope: %s
3904 \[3] Visible only: %s [4] Force publishing: %s
3907 --- (ASCII/Latin-1/UTF-8 Export) -------------------------
3909 \[a/n/u] to TXT file [A/N/U] to temporary buffer
3911 --- (HTML Export) ----------------------------------------
3913 \[h] to HTML file [b] ... and open it
3914 \[H] to temporary buffer
3916 --- (LaTeX Export) ---------------------------------------
3918 \[l] to TEX file [L] to temporary buffer
3919 \[p] to PDF file [d] ... and open it
3921 --- (ODF Export) -----------------------------------------
3923 \[o] to ODT file [O] ... and open it
3925 --- (Publish) --------------------------------------------
3927 \[F] current file [P] current project
3928 \[X] a project [E] every project"
3941 ;; Read a character from command input, toggling interactive
3942 ;; options when applicable. PROMPT is the displayed prompt,
3943 ;; as a string.
3947 ;; Ignore non-standard characters (i.e. "M-a").
3949 ;; Help key: Switch back to standard interface if
3950 ;; expert UI was active.
3952 ;; Toggle export options.
3959 expertp))
3960 ;; Action selected: Send key and options back to
3961 ;; `org-export-dispatch'.
3963 ;; With expert UI, just read key with a fancy prompt. In standard
3964 ;; UI, display an intrusive help buffer.
3975 ;;; org-export.el ends here