| blob | d85ef2eb6a9c60d6c33f79358369ae8cec48eb73 |
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:
22 ;;
23 ;; This library implements a generic export engine for Org, built on
24 ;; its syntactical parser: Org Elements.
25 ;;
26 ;; Besides that parser, the generic exporter is made of three distinct
27 ;; parts:
28 ;;
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.
35 ;;
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.
40 ;;
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. See "The Filter System"
45 ;; section for more information.
46 ;;
47 ;; The core function is `org-export-as'. It returns the transcoded
48 ;; buffer as a string.
49 ;;
50 ;; A back-end is defined through one mandatory variable: his
51 ;; translation table. Its name is always
52 ;; `org-BACKEND-translate-alist' where BACKEND stands for the name
53 ;; chosen for the back-end. Its value is an alist whose keys are
54 ;; elements and objects types and values translator functions.
55 ;;
56 ;; These functions should return a string without any trailing space,
57 ;; or nil. They must accept three arguments: the object or element
58 ;; itself, its contents or nil when it isn't recursive and the
59 ;; property list used as a communication channel.
60 ;;
61 ;; Contents, when not nil, are stripped from any global indentation
62 ;; (although the relative one is preserved). They also always end
63 ;; with a single newline character.
64 ;;
65 ;; If, for a given type, no function is found, that element or object
66 ;; type will simply be ignored, along with any blank line or white
67 ;; space at its end. The same will happen if the function returns the
68 ;; nil value. If that function returns the empty string, the type
69 ;; will be ignored, but the blank lines or white spaces will be kept.
70 ;;
71 ;; In addition to element and object types, one function can be
72 ;; associated to the `template' symbol and another one to the
73 ;; `plain-text' symbol.
74 ;;
75 ;; The former returns the final transcoded string, and can be used to
76 ;; add a preamble and a postamble to document's body. It must accept
77 ;; two arguments: the transcoded string and the property list
78 ;; containing export options.
79 ;;
80 ;; The latter, when defined, is to be called on every text not
81 ;; recognized as an element or an object. It must accept two
82 ;; arguments: the text string and the information channel. It is an
83 ;; appropriate place to protect special chars relative to the
84 ;; back-end.
85 ;;
86 ;; Optionally, a back-end can support specific buffer keywords and
87 ;; OPTION keyword's items by setting `org-BACKEND-filters-alist'
88 ;; variable. Refer to `org-export-options-alist' documentation for
89 ;; more information about its value.
90 ;;
91 ;; If the new back-end shares most properties with another one,
92 ;; `org-export-define-derived-backend' can be used to simplify the
93 ;; process.
94 ;;
95 ;; Any back-end can define its own variables. Among them, those
96 ;; customizables should belong to the `org-export-BACKEND' group.
97 ;;
98 ;; Tools for common tasks across back-ends are implemented in the
99 ;; penultimate part of this file. A dispatcher for standard back-ends
100 ;; is provided in the last one.
102 ;;; Code:
129 \f
130 ;;; Internal Variables
131 ;;
132 ;; Among internal variables, the most important is
133 ;; `org-export-options-alist'. This variable define the global export
134 ;; options, shared between every exporter, and how they are acquired.
174 "Alist between export properties and ways to set them.
176 The CAR of the alist is the property name, and the CDR is a list
177 like (KEYWORD OPTION DEFAULT BEHAVIOUR) where:
179 KEYWORD is a string representing a buffer keyword, or nil. Each
180 property defined this way can also be set, during subtree
181 export, through an headline property named after the keyword
183 property).
184 OPTION is a string that could be found in an #+OPTIONS: line.
185 DEFAULT is the default value for the property.
186 BEHAVIOUR determine how Org should handle multiple keywords for
187 the same property. It is a symbol among:
188 nil Keep old value and discard the new one.
189 t Replace old value with the new one.
190 `space' Concatenate the values, separating them with a space.
191 `newline' Concatenate the values, separating them with
192 a newline.
193 `split' Split values at white spaces, and cons them to the
194 previous list.
196 KEYWORD and OPTION have precedence over DEFAULT.
198 All these properties should be back-end agnostic. For back-end
199 specific properties, define a similar variable named
200 `org-BACKEND-options-alist', replacing BACKEND with the name of
201 the appropriate back-end. You can also redefine properties
206 "List of in-buffer keywords that require special treatment.
207 These keywords are not directly associated to a property. The
208 way they are handled must be hard-coded into
266 "Alist between filters properties and initial values.
268 The key of each association is a property name accessible through
269 the communication channel. Its value is a configurable global
270 variable defining initial filters.
272 This list is meant to install user specified filters. Back-end
273 developers may install their own filters using
274 `org-BACKEND-filters-alist', where BACKEND is the name of the
275 considered back-end. Filters defined there will always be
276 prepended to the current list, so they always get applied
285 "Default rule for link matching an inline image.
286 This rule applies to links with no description. By default, it
287 will be considered as an inline image if it targets a local file
290 See `org-export-inline-image-p' for more information about
294 \f
295 ;;; User-configurable Variables
296 ;;
297 ;; Configuration for the masses.
298 ;;
299 ;; They should never be accessed directly, as their value is to be
300 ;; stored in a property list (cf. `org-export-options-alist').
301 ;; Back-ends will read their value from there instead.
304 "Options for exporting Org mode files."
309 "General options for export engine."
314 "Whether sub-trees with the ARCHIVE tag should be exported.
316 This can have three different values:
317 nil Do not export, pretend this tree is not present.
318 t Do export the entire tree.
319 `headline' Only export the headline, but skip the tree below it.
321 This option can also be set with the #+OPTIONS line,
330 "Non-nil means insert author name into the exported file.
331 This option can also be set with the #+OPTIONS line,
337 "Non-nil means export CLOCK keywords.
338 This option can also be set with the #+OPTIONS line,
344 "Non-nil means the postamble should contain a creator sentence.
346 The sentence can be set in `org-export-creator-string' and
349 If the value is `comment' insert it as a comment."
359 emacs-version)
360 "String to insert at the end of the generated document."
365 "Non-nil means export contents of standard drawers.
367 When t, all drawers are exported. This may also be a list of
368 drawer names to export. This variable doesn't apply to
369 properties drawers.
371 This option can also be set with the #+OPTIONS line,
381 "Non-nil means insert author email into the exported file.
382 This option can also be set with the #+OPTIONS line,
388 "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
390 If the export target supports emphasizing text, the word will be
391 typeset in bold, italic, or underlined, respectively. Not all
392 export backends support this.
399 "Tags that exclude a tree from export.
401 All trees carrying any of these tags will be excluded from
402 export. This is without condition, so even subtrees inside that
403 carry one of the `org-export-select-tags' will be removed.
405 This option can also be set with the #+EXCLUDE_TAGS: keyword."
412 This can be used to have pre-formatted text, fragments of code
413 etc. For example:
414 : ;; Some Lisp examples
415 : (while (defc cnt)
416 : (ding))
417 will be looking just like this in also HTML. See also the QUOTE
418 keyword. Not all export backends support this.
425 "Non-nil means Org footnotes should be exported.
426 This option can also be set with the #+OPTIONS line,
432 "The last level which is still exported as a headline.
434 Inferior levels will produce itemize lists when exported. Note
435 that a numeric prefix argument to an exporter function overrides
436 this setting.
443 "The default language for export and clocktable translations, as a string.
444 This may have an association in
445 `org-clock-clocktable-language-setup'."
450 "Non-nil means preserve all line breaks when exporting.
452 Normally, in HTML output paragraphs will be reformatted.
454 This option can also be set with the #+OPTIONS line,
460 "Non-nil means interpret entities when exporting.
463 Å.
465 For a list of supported names, see the constant `org-entities'
466 and the user option `org-entities-user'.
468 This option can also be set with the #+OPTIONS line,
474 "Non-nil means include planning info in export.
475 This option can also be set with the #+OPTIONS: line,
481 "Non-nil means include priority cookies in export.
483 When nil, remove priority cookies for export.
485 This option can also be set with the #+OPTIONS line,
491 "Non-nil means add section numbers to headlines when exporting.
493 When set to an integer n, numbering will only happen for
494 headlines whose relative level is higher or equal to n.
496 This option can also be set with the #+OPTIONS line,
502 "Tags that select a tree for export.
504 If any such tag is found in a buffer, all trees that do not carry
505 one of these tags will be ignored during export. Inside trees
506 that are selected like this, you can still deselect a subtree by
507 tagging it with one of the `org-export-exclude-tags'.
509 This option can also be set with the #+SELECT_TAGS: keyword."
516 When this option is turned on, these strings will be exported as:
518 Org HTML LaTeX
519 -----+----------+--------
521 -- – --
522 --- — ---
523 ... … \ldots
525 This option can also be set with the #+OPTIONS line,
533 When this option is turned on, you can use TeX-like syntax for
535 will be considered as a single item - so grouping with {} is
536 normally not needed. For example, the following things will be
537 parsed as single sub- or superscripts.
539 10^24 or 10^tau several digits will be considered 1 item.
540 10^-12 or 10^-tau a leading sign with digits or a word
541 x^2-y^3 will be read as x^2 - y^3, because items are
542 terminated by almost any nonword/nondigit char.
543 x_{i^2} or x^(2-i) braces or parenthesis do grouping.
545 Still, ambiguity is possible - so when in doubt use {} to enclose
546 the sub/superscript. If you set this variable to the symbol
547 `{}', the braces are *required* in order to trigger
548 interpretations as sub/superscript. This can be helpful in
551 This option can also be set with the #+OPTIONS line,
560 "Non-nil means create a table of contents in exported files.
562 The TOC contains headlines with levels up
563 to`org-export-headline-levels'. When an integer, include levels
564 up to N in the toc, this may then be different from
565 `org-export-headline-levels', but it will not be allowed to be
566 larger than the number of headline levels. When nil, no table of
567 contents is made.
569 This option can also be set with the #+OPTIONS line,
579 For example:
581 | Name | Address | Birthday |
582 |-------------+----------+-----------|
583 | Arthur Dent | England | 29.2.2100 |
590 "If nil, do not export tags, just remove them from headlines.
592 If this is the symbol `not-in-toc', tags will be removed from
593 table of contents entries, but still be shown in the headlines of
594 the document.
596 This option can also be set with the #+OPTIONS line,
605 "Non-nil means include TODO items for export.
606 This may have the following values:
607 t include tasks independent of state.
608 todo include only tasks that are not yet done.
609 done include only tasks that are already done.
610 nil remove all tasks before export
611 list of keywords keep only tasks with these keywords"
622 "Non-nil means insert a time stamp into the exported file.
623 The time stamp shows when the file was created.
625 This option can also be set with the #+OPTIONS line,
631 "Non nil means allow timestamps in export.
633 It can be set to `active', `inactive', t or nil, in order to
634 export, respectively, only active timestamps, only inactive ones,
635 all of them or none.
637 This option can also be set with the #+OPTIONS line, e.g.
647 "Non-nil means include TODO keywords in export.
648 When nil, remove all these keywords from the export."
653 "Non-nil means allow #+BIND to define local variable values for export.
654 This is a potential security risk, which is why the user must
655 confirm the use of these lines."
663 "Alist between export snippets back-ends and exporter back-ends.
665 This variable allows to provide shortcuts for export snippets.
669 HTML code while every other back-end will ignore it."
677 "Coding system for the exported file."
682 "Non-nil means exported stuff will also be pushed onto the kill ring."
687 "The initial scope when exporting with `org-export-dispatch'.
688 This variable can be either set to `buffer' or `subtree'."
695 "Non-nil means show buffer after exporting to temp buffer.
696 When Org exports to a file, the buffer visiting that file is ever
697 shown, but remains buried. However, when exporting to
698 a temporary buffer, that buffer is popped up in a second window.
699 When this variable is nil, the buffer remains buried also in
700 these cases."
705 "Non-nil means using a non-intrusive `org-export-dispatch'.
706 In that case, no help buffer is displayed. Though, an indicator
710 considered for export\). Also, \[?] allows to switch back to
711 standard mode."
716 \f
717 ;;; Defining New Back-ends
720 "Create a new back-end as a variant of an existing one.
722 CHILD is the name of the derived back-end. PARENT is the name of
723 the parent back-end.
725 BODY can start with pre-defined keyword arguments. The following
726 keywords are understood:
728 `:filters-alist'
730 Alist of filters that will overwrite or complete filters
731 defined in PARENT back-end, if any.
733 `:options-alist'
735 Alist of buffer keywords or #+OPTIONS items that will
736 overwrite or complete those defined in PARENT back-end, if
737 any.
739 `:translate-alist'
741 Alist of element and object types and transcoders that will
742 overwrite or complete transcode table from PARENT back-end.
745 as a variant of `e-latex' back-end with a custom template
746 function:
748 \(org-export-define-derived-backend my-latex e-latex
749 :translate-alist ((template . my-latex-template-fun)))
751 The back-end could then be called with, for example:
764 ;; Define filters.
771 "Alist between filters keywords and back-end specific filters.
773 ;; Define options.
780 "Alist between LaTeX export properties and ways to set them.
781 See `org-export-options-alist' for more information on the
783 ;; Define translators.
790 ;; Splice in the body, if any.
794 \f
795 ;;; The Communication Channel
796 ;;
797 ;; During export process, every function has access to a number of
798 ;; properties. They are of two types:
799 ;;
800 ;; 1. Environment options are collected once at the very beginning of
801 ;; the process, out of the original buffer and configuration.
802 ;; Collecting them is handled by `org-export-get-environment'
803 ;; function.
804 ;;
805 ;; Most environment options are defined through the
806 ;; `org-export-options-alist' variable.
807 ;;
808 ;; 2. Tree properties are extracted directly from the parsed tree,
809 ;; just before export, by `org-export-collect-tree-properties'.
810 ;;
811 ;; Here is the full list of properties available during transcode
812 ;; process, with their category (option, tree or local) and their
813 ;; value type.
814 ;;
815 ;; + `:author' :: Author's name.
816 ;; - category :: option
817 ;; - type :: string
818 ;;
819 ;; + `:back-end' :: Current back-end used for transcoding.
820 ;; - category :: tree
821 ;; - type :: symbol
822 ;;
823 ;; + `:creator' :: String to write as creation information.
824 ;; - category :: option
825 ;; - type :: string
826 ;;
827 ;; + `:date' :: String to use as date.
828 ;; - category :: option
829 ;; - type :: string
830 ;;
831 ;; + `:description' :: Description text for the current data.
832 ;; - category :: option
833 ;; - type :: string
834 ;;
835 ;; + `:email' :: Author's email.
836 ;; - category :: option
837 ;; - type :: string
838 ;;
839 ;; + `:exclude-tags' :: Tags for exclusion of subtrees from export
840 ;; process.
841 ;; - category :: option
842 ;; - type :: list of strings
843 ;;
844 ;; + `:footnote-definition-alist' :: Alist between footnote labels and
845 ;; their definition, as parsed data. Only non-inlined footnotes
846 ;; are represented in this alist. Also, every definition isn't
847 ;; guaranteed to be referenced in the parse tree. The purpose of
848 ;; this property is to preserve definitions from oblivion
849 ;; (i.e. when the parse tree comes from a part of the original
850 ;; buffer), it isn't meant for direct use in a back-end. To
851 ;; retrieve a definition relative to a reference, use
852 ;; `org-export-get-footnote-definition' instead.
853 ;; - category :: option
854 ;; - type :: alist (STRING . LIST)
855 ;;
856 ;; + `:headline-levels' :: Maximum level being exported as an
857 ;; headline. Comparison is done with the relative level of
858 ;; headlines in the parse tree, not necessarily with their
859 ;; actual level.
860 ;; - category :: option
861 ;; - type :: integer
862 ;;
863 ;; + `:headline-offset' :: Difference between relative and real level
864 ;; of headlines in the parse tree. For example, a value of -1
865 ;; means a level 2 headline should be considered as level
866 ;; 1 (cf. `org-export-get-relative-level').
867 ;; - category :: tree
868 ;; - type :: integer
869 ;;
870 ;; + `:headline-numbering' :: Alist between headlines and their
871 ;; numbering, as a list of numbers
872 ;; (cf. `org-export-get-headline-number').
873 ;; - category :: tree
874 ;; - type :: alist (INTEGER . LIST)
875 ;;
876 ;; + `:id-alist' :: Alist between ID strings and destination file's
877 ;; path, relative to current directory. It is used by
878 ;; `org-export-resolve-id-link' to resolve ID links targeting an
879 ;; external file.
880 ;; - category :: option
881 ;; - type :: alist (STRING . STRING)
882 ;;
883 ;; + `:ignore-list' :: List of elements and objects that should be
884 ;; ignored during export.
885 ;; - category :: tree
886 ;; - type :: list of elements and objects
887 ;;
888 ;; + `:input-file' :: Full path to input file, if any.
889 ;; - category :: option
890 ;; - type :: string or nil
891 ;;
892 ;; + `:keywords' :: List of keywords attached to data.
893 ;; - category :: option
894 ;; - type :: string
895 ;;
896 ;; + `:language' :: Default language used for translations.
897 ;; - category :: option
898 ;; - type :: string
899 ;;
900 ;; + `:parse-tree' :: Whole parse tree, available at any time during
901 ;; transcoding.
902 ;; - category :: option
903 ;; - type :: list (as returned by `org-element-parse-buffer')
904 ;;
905 ;; + `:preserve-breaks' :: Non-nil means transcoding should preserve
906 ;; all line breaks.
907 ;; - category :: option
908 ;; - type :: symbol (nil, t)
909 ;;
910 ;; + `:section-numbers' :: Non-nil means transcoding should add
911 ;; section numbers to headlines.
912 ;; - category :: option
913 ;; - type :: symbol (nil, t)
914 ;;
915 ;; + `:select-tags' :: List of tags enforcing inclusion of sub-trees
916 ;; in transcoding. When such a tag is present, subtrees without
917 ;; it are de facto excluded from the process. See
918 ;; `use-select-tags'.
919 ;; - category :: option
920 ;; - type :: list of strings
921 ;;
922 ;; + `:target-list' :: List of targets encountered in the parse tree.
923 ;; This is used to partly resolve "fuzzy" links
924 ;; (cf. `org-export-resolve-fuzzy-link').
925 ;; - category :: tree
926 ;; - type :: list of strings
927 ;;
928 ;; + `:time-stamp-file' :: Non-nil means transcoding should insert
929 ;; a time stamp in the output.
930 ;; - category :: option
931 ;; - type :: symbol (nil, t)
932 ;;
933 ;; + `:translate-alist' :: Alist between element and object types and
934 ;; transcoding functions relative to the current back-end.
935 ;; Special keys `template' and `plain-text' are also possible.
936 ;; - category :: option
937 ;; - type :: alist (SYMBOL . FUNCTION)
938 ;;
939 ;; + `:with-archived-trees' :: Non-nil when archived subtrees should
940 ;; also be transcoded. If it is set to the `headline' symbol,
941 ;; only the archived headline's name is retained.
942 ;; - category :: option
943 ;; - type :: symbol (nil, t, `headline')
944 ;;
945 ;; + `:with-author' :: Non-nil means author's name should be included
946 ;; in the output.
947 ;; - category :: option
948 ;; - type :: symbol (nil, t)
949 ;;
950 ;; + `:with-clocks' :: Non-nild means clock keywords should be exported.
951 ;; - category :: option
952 ;; - type :: symbol (nil, t)
953 ;;
954 ;; + `:with-creator' :: Non-nild means a creation sentence should be
955 ;; inserted at the end of the transcoded string. If the value
956 ;; is `comment', it should be commented.
957 ;; - category :: option
958 ;; - type :: symbol (`comment', nil, t)
959 ;;
960 ;; + `:with-drawers' :: Non-nil means drawers should be exported. If
961 ;; its value is a list of names, only drawers with such names
962 ;; will be transcoded.
963 ;; - category :: option
964 ;; - type :: symbol (nil, t) or list of strings
965 ;;
966 ;; + `:with-email' :: Non-nil means output should contain author's
967 ;; email.
968 ;; - category :: option
969 ;; - type :: symbol (nil, t)
970 ;;
971 ;; + `:with-emphasize' :: Non-nil means emphasized text should be
972 ;; interpreted.
973 ;; - category :: option
974 ;; - type :: symbol (nil, t)
975 ;;
976 ;; + `:with-fixed-width' :: Non-nil if transcoder should interpret
977 ;; strings starting with a colon as a fixed-with (verbatim) area.
978 ;; - category :: option
979 ;; - type :: symbol (nil, t)
980 ;;
981 ;; + `:with-footnotes' :: Non-nil if transcoder should interpret
982 ;; footnotes.
983 ;; - category :: option
984 ;; - type :: symbol (nil, t)
985 ;;
986 ;; + `:with-plannings' :: Non-nil means transcoding should include
987 ;; planning info.
988 ;; - category :: option
989 ;; - type :: symbol (nil, t)
990 ;;
991 ;; + `:with-priority' :: Non-nil means transcoding should include
992 ;; priority cookies.
993 ;; - category :: option
994 ;; - type :: symbol (nil, t)
995 ;;
996 ;; + `:with-special-strings' :: Non-nil means transcoding should
997 ;; interpret special strings in plain text.
998 ;; - category :: option
999 ;; - type :: symbol (nil, t)
1000 ;;
1001 ;; + `:with-sub-superscript' :: Non-nil means transcoding should
1002 ;; interpret subscript and superscript. With a value of "{}",
1003 ;; only interpret those using curly brackets.
1004 ;; - category :: option
1005 ;; - type :: symbol (nil, {}, t)
1006 ;;
1007 ;; + `:with-tables' :: Non-nil means transcoding should interpret
1008 ;; tables.
1009 ;; - category :: option
1010 ;; - type :: symbol (nil, t)
1011 ;;
1012 ;; + `:with-tags' :: Non-nil means transcoding should keep tags in
1013 ;; headlines. A `not-in-toc' value will remove them from the
1014 ;; table of contents, if any, nonetheless.
1015 ;; - category :: option
1016 ;; - type :: symbol (nil, t, `not-in-toc')
1017 ;;
1018 ;; + `:with-tasks' :: Non-nil means transcoding should include
1019 ;; headlines with a TODO keyword. A `todo' value will only
1020 ;; include headlines with a todo type keyword while a `done'
1021 ;; value will do the contrary. If a list of strings is provided,
1022 ;; only tasks with keywords belonging to that list will be kept.
1023 ;; - category :: option
1024 ;; - type :: symbol (t, todo, done, nil) or list of strings
1025 ;;
1026 ;; + `:with-timestamps' :: Non-nil means transcoding should include
1027 ;; time stamps. Special value `active' (resp. `inactive') ask to
1028 ;; export only active (resp. inactive) timestamps. Otherwise,
1029 ;; completely remove them.
1030 ;; - category :: option
1031 ;; - type :: symbol: (`active', `inactive', t, nil)
1032 ;;
1033 ;; + `:with-toc' :: Non-nil means that a table of contents has to be
1034 ;; added to the output. An integer value limits its depth.
1035 ;; - category :: option
1036 ;; - type :: symbol (nil, t or integer)
1037 ;;
1038 ;; + `:with-todo-keywords' :: Non-nil means transcoding should
1039 ;; include TODO keywords.
1040 ;; - category :: option
1041 ;; - type :: symbol (nil, t)
1044 ;;;; Environment Options
1045 ;;
1046 ;; Environment options encompass all parameters defined outside the
1047 ;; scope of the parsed data. They come from five sources, in
1048 ;; increasing precedence order:
1049 ;;
1050 ;; - Global variables,
1051 ;; - Buffer's attributes,
1052 ;; - Options keyword symbols,
1053 ;; - Buffer keywords,
1054 ;; - Subtree properties.
1055 ;;
1056 ;; The central internal function with regards to environment options
1057 ;; is `org-export-get-environment'. It updates global variables with
1058 ;; "#+BIND:" keywords, then retrieve and prioritize properties from
1059 ;; the different sources.
1060 ;;
1061 ;; The internal functions doing the retrieval are:
1062 ;; `org-export-get-global-options',
1063 ;; `org-export-get-buffer-attributes',
1064 ;; `org-export-parse-option-keyword',
1065 ;; `org-export-get-subtree-options' and
1066 ;; `org-export-get-inbuffer-options'
1067 ;;
1068 ;; Also, `org-export-confirm-letbind' and `org-export-install-letbind'
1069 ;; take care of the part relative to "#+BIND:" keywords.
1072 "Collect export options from the current buffer.
1074 Optional argument BACKEND is a symbol specifying which back-end
1075 specific options to read, if any.
1077 When optional argument SUBTREEP is non-nil, assume the export is
1078 done against the current sub-tree.
1080 Third optional argument EXT-PLIST is a property list with
1081 external parameters overriding Org default settings, but still
1082 inferior to file-local settings."
1083 ;; First install #+BIND variables.
1085 ;; Get and prioritize export options...
1087 ;; ... from global variables...
1089 ;; ... from buffer's attributes...
1091 ;; ... from an external property list...
1092 ext-plist
1093 ;; ... from in-buffer settings...
1095 backend
1097 ;; ... and from subtree, when appropriate.
1099 ;; Eventually install back-end symbol and its translation table.
1100 `(:back-end
1101 ,backend
1102 :translate-alist
1107 "Parse an OPTIONS line and return values as a plist.
1108 Optional argument BACKEND is a symbol specifying which back-end
1109 specific items to read, if any."
1116 ;; Build an alist between #+OPTION: item and property-name.
1121 all)))
1122 plist)
1127 options)
1132 alist)
1133 plist))
1136 "Get export options in subtree at point.
1137 Optional argument BACKEND is a symbol specifying back-end used
1138 for export. Return options as a plist."
1139 ;; For each buffer keyword, create an headline property setting the
1140 ;; same property in communication channel. The name for the property
1141 ;; is the keyword with "EXPORT_" appended to it.
1144 ;; Make sure point is at an heading.
1146 ;; Take care of EXPORT_TITLE. If it isn't defined, use headline's
1147 ;; title as its fallback value.
1154 plist :title
1157 ;; EXPORT_OPTIONS are parsed in a non-standard way.
1161 ;; Handle other keywords.
1173 plist
1175 ;; Parse VALUE if required.
1179 value))))))))
1180 ;; Also look for both general keywords and back-end specific
1181 ;; options if BACKEND is provided.
1186 org-export-options-alist)))
1187 ;; Return value.
1188 plist)))
1191 "Return current buffer export options, as a plist.
1193 Optional argument BACKEND, when non-nil, is a symbol specifying
1194 which back-end specific options should also be read in the
1195 process.
1197 Optional argument FILES is a list of setup files names read so
1198 far, used to avoid circular dependencies.
1200 Assume buffer is in Org mode. Narrowing, if any, is ignored."
1204 ;; 1. Special keywords, as in `org-export-special-keywords'.
1217 ;; Avoid circular dependencies.
1229 val)
1237 ;; Value will be evaled: do not parse it.
1240 ;; Value has to be parsed for nested
1241 ;; macros.
1244 key
1247 ;; If user explicitly asks for
1248 ;; a newline, be sure to preserve it
1249 ;; from further filling with
1250 ;; `hard-newline'. Also replace
1251 ;; "\\n" with "\n", "\\\n" with "\\n"
1252 ;; and so on...
1259 restr)))))))))))
1261 ;; 2. Standard options, as in `org-export-options-alist'.
1263 ;; Also look for back-end specific options
1264 ;; if BACKEND is defined.
1270 ;; Build alist between keyword name and property name.
1274 all)))
1275 ;; Build regexp matching all keywords associated to export
1276 ;; options. Note: the search is case insensitive.
1289 plist prop
1290 ;; Handle value depending on specified BEHAVIOUR.
1303 ;; Parse keywords specified in `org-element-parsed-keywords'.
1311 plist prop
1314 org-element-parsed-keywords))
1315 ;; 3. Return final value.
1316 plist)))
1319 "Return properties related to buffer attributes, as a plist."
1322 ;; Store full path of input file name, or nil. For internal use.
1323 :input-file visited-file
1328 :footnote-definition-alist
1329 ;; Footnotes definitions must be collected in the original
1330 ;; buffer, as there's no insurance that they will still be in the
1331 ;; parse tree, due to possible narrowing.
1342 ;; Like `org-element-parse-buffer', but
1343 ;; makes sure the definition doesn't start
1344 ;; with a section element.
1348 alist))))
1349 alist))
1350 :id-alist
1351 ;; Collect id references.
1360 alist)
1361 :macro-modification-time
1367 ;; Store input file name as a macro.
1369 ;; `:macro-date', `:macro-time' and `:macro-property' could as
1370 ;; well be initialized as tree properties, since they don't
1371 ;; depend on buffer properties. Though, it may be more logical
1372 ;; to keep them close to other ":macro-" properties.
1378 "Return global export options as a plist.
1380 Optional argument BACKEND, if non-nil, is a symbol specifying
1381 which back-end specific export options should also be read in the
1382 process."
1388 ;; Output value.
1389 plist)
1394 plist
1396 ;; Eval default value provided. If keyword is a member
1397 ;; of `org-element-parsed-keywords', parse it as
1398 ;; a secondary string before storing it.
1405 all)
1406 ;; Return value.
1407 plist))
1411 "Can we use #+BIND values during export?
1412 By default this will ask for confirmation by the user, to divert
1413 possible security risks."
1422 "Install the values from #+BIND lines as local variables.
1423 Variables must be installed before in-buffer options are
1424 retrieved."
1431 letbind))))
1436 ;;;; Tree Properties
1437 ;;
1438 ;; Tree properties are infromation extracted from parse tree. They
1439 ;; are initialized at the beginning of the transcoding process by
1440 ;; `org-export-collect-tree-properties'.
1441 ;;
1442 ;; Dedicated functions focus on computing the value of specific tree
1443 ;; properties during initialization. Thus,
1444 ;; `org-export-populate-ignore-list' lists elements and objects that
1445 ;; should be skipped during export, `org-export-get-min-level' gets
1446 ;; the minimal exportable level, used as a basis to compute relative
1447 ;; level for headlines. Eventually
1448 ;; `org-export-collect-headline-numbering' builds an alist between
1449 ;; headlines and their numbering.
1452 "Extract tree properties from parse tree.
1454 DATA is the parse tree from which information is retrieved. INFO
1455 is a list holding export options.
1457 Following tree properties are set or updated:
1458 `:footnote-definition-alist' List of footnotes definitions in
1459 original buffer and current parse tree.
1461 `:headline-offset' Offset between true level of headlines and
1462 local level. An offset of -1 means an headline
1463 of level 2 should be considered as a level
1464 1 headline in the context.
1466 `:headline-numbering' Alist of all headlines as key an the
1467 associated numbering as value.
1469 `:ignore-list' List of elements that should be ignored during
1470 export.
1472 `:target-list' List of all targets in the parse tree.
1474 Return updated plist."
1475 ;; Install the parse tree in the communication channel, in order to
1476 ;; use `org-export-get-genealogy' and al.
1478 ;; Get the list of elements and objects to ignore, and put it into
1479 ;; `:ignore-list'. Do not overwrite any user ignore that might have
1480 ;; been done during parse tree filtering.
1483 :ignore-list
1486 ;; Compute `:headline-offset' in order to be able to use
1487 ;; `org-export-get-relative-level'.
1491 ;; Update footnotes definitions list with definitions in parse tree.
1492 ;; This is required since buffer expansion might have modified
1493 ;; boundaries of footnote definitions contained in the parse tree.
1494 ;; This way, definitions in `footnote-definition-alist' are bound to
1495 ;; match those in the parse tree.
1498 data 'footnote-definition
1502 defs)))
1504 ;; Properties order doesn't matter: get the rest of the tree
1505 ;; properties.
1507 `(:target-list
1515 info))
1518 "Return minimum exportable headline's level in DATA.
1519 DATA is parsed tree as returned by `org-element-parse-buffer'.
1520 OPTIONS is a plist holding export options."
1531 ;; If no headline was found, for the sake of consistency, set
1532 ;; minimum level to 1 nonetheless.
1536 "Return numbering of all exportable headlines in a parse tree.
1538 DATA is the parse tree. OPTIONS is the plist holding export
1539 options.
1541 Return an alist whose key is an headline and value is its
1542 associated numbering \(in the shape of a list of numbers\)."
1545 data
1546 'headline
1551 headline
1553 for idx from 0 to org-export-max-depth
1557 options)))
1560 "Return list of elements and objects to ignore during export.
1561 DATA is the parse tree to traverse. OPTIONS is the plist holding
1562 export options."
1564 walk-data ; for byte-compiler.
1568 ;; Collect ignored elements or objects into IGNORE-LIST.
1577 ;; If headline is archived but tree below has
1578 ;; to be skipped, add it to ignore list.
1581 ;; Move into recursive objects/elements.
1585 ;; Main call. First find trees containing a select tag, if any.
1587 ;; Return value.
1588 ignore))
1591 "Return list of headlines containing a select tag in their tree.
1592 DATA is parsed data as returned by `org-element-parse-buffer'.
1593 INFO is a plist holding export options."
1595 walk-data ; for byte-compiler.
1606 ;; When a select tag is found, mark full
1607 ;; genealogy and every headline within the tree
1608 ;; as acceptable.
1611 genealogy
1613 selected-trees))
1614 ;; Else, continue searching in tree, recursively.
1621 "Non-nil when element or object BLOB should be skipped during export.
1622 OPTIONS is the plist holding export options. SELECTED, when
1623 non-nil, is a list of headlines belonging to a tree with a select
1624 tag."
1626 ;; Check headline.
1634 ;; Ignore subtrees with an exclude tag.
1637 ;; When a select tag is present in the buffer, ignore any tree
1638 ;; without it.
1640 ;; Ignore commented sub-trees.
1642 ;; Ignore archived subtrees if `:with-archived-trees' is nil.
1644 ;; Ignore tasks, if specified by `:with-tasks' property.
1650 ;; Check timestamp.
1653 ;; No timestamp allowed.
1655 ;; Only active timestamps allowed and the current one isn't
1656 ;; active.
1660 ;; Only inactive timestamps allowed and the current one isn't
1661 ;; inactive.
1665 ;; Check drawer.
1671 ;; Check table-row.
1673 ;; Check table-cell.
1678 ;; Check clock.
1680 ;; Check planning.
1684 \f
1685 ;;; The Transcoder
1686 ;;
1687 ;; `org-export-data' reads a parse tree (obtained with, i.e.
1688 ;; `org-element-parse-buffer') and transcodes it into a specified
1689 ;; back-end output. It takes care of filtering out elements or
1690 ;; objects according to export options and organizing the output blank
1691 ;; lines and white space are preserved.
1692 ;;
1693 ;; Internally, three functions handle the filtering of objects and
1694 ;; elements during the export. In particular,
1695 ;; `org-export-ignore-element' marks an element or object so future
1696 ;; parse tree traversals skip it, `org-export-interpret-p' tells which
1697 ;; elements or objects should be seen as real Org syntax and
1698 ;; `org-export-expand' transforms the others back into their original
1699 ;; shape
1700 ;;
1701 ;; `org-export-transcoder' is an accessor returning appropriate
1702 ;; translator function for a given element or object.
1705 "Return appropriate transcoder for BLOB.
1706 INFO is a plist containing export directives."
1708 ;; Return contents only for complete parse trees.
1714 "Convert DATA into current back-end format.
1716 DATA is a parse tree, an element or an object or a secondary
1717 string. INFO is a plist holding export options.
1719 Return transcoded string."
1723 ;; Ignored element/object.
1725 ;; Plain text.
1731 info))
1732 ;; Uninterpreted element/object: change it back to Org
1733 ;; syntax and export again resulting raw string.
1737 data
1741 info))
1742 ;; Secondary string.
1745 ;; Element/Object without contents or, as a special case,
1746 ;; headline with archive tag and archived trees restricted
1747 ;; to title only.
1754 ;; Element/Object with contents.
1766 ;; Elements directly containing objects
1767 ;; must have their indentation normalized
1768 ;; first.
1770 data
1771 ;; When normalizing contents of the first
1772 ;; paragraph in an item or a footnote
1773 ;; definition, ignore first line's
1774 ;; indentation: there is none and it
1775 ;; might be misleading.
1779 data)
1785 contents)
1786 info))))))))
1790 ;; Append the same white space between elements or objects as in
1791 ;; the original buffer, and call appropriate filters.
1801 info)))
1802 ;; Eventually return string.
1803 results)))))
1806 "Non-nil if element or object BLOB should be interpreted as Org syntax.
1807 Check is done according to export options INFO, stored as
1808 a plist."
1810 ;; ... entities...
1812 ;; ... emphasis...
1814 ;; ... fixed-width areas.
1816 ;; ... footnotes...
1819 ;; ... sub/superscripts...
1825 ;; ... tables...
1830 "Expand a parsed element or object to its original state.
1831 BLOB is either an element or an object. CONTENTS is its
1832 contents, as a string or nil."
1835 blob contents))
1838 "Add ELEMENT to `:ignore-list' in INFO.
1840 Any element in `:ignore-list' will be skipped when using
1841 `org-element-map'. INFO is modified by side effects."
1845 \f
1846 ;;; The Filter System
1847 ;;
1848 ;; Filters allow end-users to tweak easily the transcoded output.
1849 ;; They are the functional counterpart of hooks, as every filter in
1850 ;; a set is applied to the return value of the previous one.
1851 ;;
1852 ;; Every set is back-end agnostic. Although, a filter is always
1853 ;; called, in addition to the string it applies to, with the back-end
1854 ;; used as argument, so it's easy for the end-user to add back-end
1855 ;; specific filters in the set. The communication channel, as
1856 ;; a plist, is required as the third argument.
1857 ;;
1858 ;; From the developer side, filters sets can be installed in the
1859 ;; process with the help of `org-BACKEND-filters-alist' variable.
1860 ;; Each association has a key among the following symbols and
1861 ;; a function or a list of functions as value.
1862 ;;
1863 ;; - `:filter-parse-tree' applies directly on the complete parsed
1864 ;; tree. It's the only filters set that doesn't apply to a string.
1865 ;; Users can set it through `org-export-filter-parse-tree-functions'
1866 ;; variable.
1867 ;;
1868 ;; - `:filter-final-output' applies to the final transcoded string.
1869 ;; Users can set it with `org-export-filter-final-output-functions'
1870 ;; variable
1871 ;;
1872 ;; - `:filter-plain-text' applies to any string not recognized as Org
1873 ;; syntax. `org-export-filter-plain-text-functions' allows users to
1874 ;; configure it.
1875 ;;
1876 ;; - `:filter-TYPE' applies on the string returned after an element or
1877 ;; object of type TYPE has been transcoded. An user can modify
1878 ;; `org-export-filter-TYPE-functions'
1879 ;;
1880 ;; All filters sets are applied with
1881 ;; `org-export-filter-apply-functions' function. Filters in a set are
1882 ;; applied in a LIFO fashion. It allows developers to be sure that
1883 ;; their filters will be applied first.
1884 ;;
1885 ;; Filters properties are installed in communication channel with
1886 ;; `org-export-install-filters' function.
1887 ;;
1888 ;; Eventually, a hook (`org-export-before-parsing-hook') is run just
1889 ;; before parsing to allow for heavy structure modifications.
1892 ;;;; Before Parsing Hook
1895 "Hook run before parsing an export buffer.
1896 This is run after include keywords have been expanded and Babel
1897 code executed, on a copy of original buffer's area being
1898 exported. Visibility is the same as in the original one. Point
1902 ;;;; Special Filters
1905 "List of functions applied to the parsed tree.
1906 Each filter is called with three arguments: the parse tree, as
1907 returned by `org-element-parse-buffer', the back-end, as
1908 a symbol, and the communication channel, as a plist. It must
1912 "List of functions applied to the transcoded string.
1913 Each filter is called with three arguments: the full transcoded
1914 string, the back-end, as a symbol, and the communication channel,
1915 as a plist. It must return a string that will be used as the
1919 "List of functions applied to plain text.
1920 Each filter is called with three arguments: a string which
1921 contains no Org syntax, the back-end, as a symbol, and the
1922 communication channel, as a plist. It must return a string or
1926 ;;;; Elements Filters
1929 "List of functions applied to a transcoded center block.
1930 Each filter is called with three arguments: the transcoded data,
1931 as a string, the back-end, as a symbol, and the communication
1935 "List of functions applied to a transcoded clock.
1936 Each filter is called with three arguments: the transcoded data,
1937 as a string, the back-end, as a symbol, and the communication
1941 "List of functions applied to a transcoded drawer.
1942 Each filter is called with three arguments: the transcoded data,
1943 as a string, the back-end, as a symbol, and the communication
1947 "List of functions applied to a transcoded dynamic-block.
1948 Each filter is called with three arguments: the transcoded data,
1949 as a string, the back-end, as a symbol, and the communication
1953 "List of functions applied to a transcoded headline.
1954 Each filter is called with three arguments: the transcoded data,
1955 as a string, the back-end, as a symbol, and the communication
1959 "List of functions applied to a transcoded inlinetask.
1960 Each filter is called with three arguments: the transcoded data,
1961 as a string, the back-end, as a symbol, and the communication
1965 "List of functions applied to a transcoded plain-list.
1966 Each filter is called with three arguments: the transcoded data,
1967 as a string, the back-end, as a symbol, and the communication
1971 "List of functions applied to a transcoded item.
1972 Each filter is called with three arguments: the transcoded data,
1973 as a string, the back-end, as a symbol, and the communication
1977 "List of functions applied to a transcoded comment.
1978 Each filter is called with three arguments: the transcoded data,
1979 as a string, the back-end, as a symbol, and the communication
1983 "List of functions applied to a transcoded comment-comment.
1984 Each filter is called with three arguments: the transcoded data,
1985 as a string, the back-end, as a symbol, and the communication
1989 "List of functions applied to a transcoded example-block.
1990 Each filter is called with three arguments: the transcoded data,
1991 as a string, the back-end, as a symbol, and the communication
1995 "List of functions applied to a transcoded export-block.
1996 Each filter is called with three arguments: the transcoded data,
1997 as a string, the back-end, as a symbol, and the communication
2001 "List of functions applied to a transcoded fixed-width.
2002 Each filter is called with three arguments: the transcoded data,
2003 as a string, the back-end, as a symbol, and the communication
2007 "List of functions applied to a transcoded footnote-definition.
2008 Each filter is called with three arguments: the transcoded data,
2009 as a string, the back-end, as a symbol, and the communication
2013 "List of functions applied to a transcoded horizontal-rule.
2014 Each filter is called with three arguments: the transcoded data,
2015 as a string, the back-end, as a symbol, and the communication
2019 "List of functions applied to a transcoded keyword.
2020 Each filter is called with three arguments: the transcoded data,
2021 as a string, the back-end, as a symbol, and the communication
2025 "List of functions applied to a transcoded latex-environment.
2026 Each filter is called with three arguments: the transcoded data,
2027 as a string, the back-end, as a symbol, and the communication
2031 "List of functions applied to a transcoded babel-call.
2032 Each filter is called with three arguments: the transcoded data,
2033 as a string, the back-end, as a symbol, and the communication
2037 "List of functions applied to a transcoded paragraph.
2038 Each filter is called with three arguments: the transcoded data,
2039 as a string, the back-end, as a symbol, and the communication
2043 "List of functions applied to a transcoded planning.
2044 Each filter is called with three arguments: the transcoded data,
2045 as a string, the back-end, as a symbol, and the communication
2049 "List of functions applied to a transcoded property-drawer.
2050 Each filter is called with three arguments: the transcoded data,
2051 as a string, the back-end, as a symbol, and the communication
2055 "List of functions applied to a transcoded quote block.
2056 Each filter is called with three arguments: the transcoded quote
2057 data, as a string, the back-end, as a symbol, and the
2058 communication channel, as a plist. It must return a string or
2062 "List of functions applied to a transcoded quote-section.
2063 Each filter is called with three arguments: the transcoded data,
2064 as a string, the back-end, as a symbol, and the communication
2068 "List of functions applied to a transcoded section.
2069 Each filter is called with three arguments: the transcoded data,
2070 as a string, the back-end, as a symbol, and the communication
2074 "List of functions applied to a transcoded special block.
2075 Each filter is called with three arguments: the transcoded data,
2076 as a string, the back-end, as a symbol, and the communication
2080 "List of functions applied to a transcoded src-block.
2081 Each filter is called with three arguments: the transcoded data,
2082 as a string, the back-end, as a symbol, and the communication
2086 "List of functions applied to a transcoded table.
2087 Each filter is called with three arguments: the transcoded data,
2088 as a string, the back-end, as a symbol, and the communication
2092 "List of functions applied to a transcoded table-cell.
2093 Each filter is called with three arguments: the transcoded data,
2094 as a string, the back-end, as a symbol, and the communication
2098 "List of functions applied to a transcoded table-row.
2099 Each filter is called with three arguments: the transcoded data,
2100 as a string, the back-end, as a symbol, and the communication
2104 "List of functions applied to a transcoded verse block.
2105 Each filter is called with three arguments: the transcoded data,
2106 as a string, the back-end, as a symbol, and the communication
2110 ;;;; Objects Filters
2113 "List of functions applied to transcoded bold text.
2114 Each filter is called with three arguments: the transcoded data,
2115 as a string, the back-end, as a symbol, and the communication
2119 "List of functions applied to transcoded code text.
2120 Each filter is called with three arguments: the transcoded data,
2121 as a string, the back-end, as a symbol, and the communication
2125 "List of functions applied to a transcoded entity.
2126 Each filter is called with three arguments: the transcoded data,
2127 as a string, the back-end, as a symbol, and the communication
2131 "List of functions applied to a transcoded export-snippet.
2132 Each filter is called with three arguments: the transcoded data,
2133 as a string, the back-end, as a symbol, and the communication
2137 "List of functions applied to a transcoded footnote-reference.
2138 Each filter is called with three arguments: the transcoded data,
2139 as a string, the back-end, as a symbol, and the communication
2143 "List of functions applied to a transcoded inline-babel-call.
2144 Each filter is called with three arguments: the transcoded data,
2145 as a string, the back-end, as a symbol, and the communication
2149 "List of functions applied to a transcoded inline-src-block.
2150 Each filter is called with three arguments: the transcoded data,
2151 as a string, the back-end, as a symbol, and the communication
2155 "List of functions applied to transcoded italic text.
2156 Each filter is called with three arguments: the transcoded data,
2157 as a string, the back-end, as a symbol, and the communication
2161 "List of functions applied to a transcoded latex-fragment.
2162 Each filter is called with three arguments: the transcoded data,
2163 as a string, the back-end, as a symbol, and the communication
2167 "List of functions applied to a transcoded line-break.
2168 Each filter is called with three arguments: the transcoded data,
2169 as a string, the back-end, as a symbol, and the communication
2173 "List of functions applied to a transcoded link.
2174 Each filter is called with three arguments: the transcoded data,
2175 as a string, the back-end, as a symbol, and the communication
2179 "List of functions applied to a transcoded macro.
2180 Each filter is called with three arguments: the transcoded data,
2181 as a string, the back-end, as a symbol, and the communication
2185 "List of functions applied to a transcoded radio-target.
2186 Each filter is called with three arguments: the transcoded data,
2187 as a string, the back-end, as a symbol, and the communication
2191 "List of functions applied to a transcoded statistics-cookie.
2192 Each filter is called with three arguments: the transcoded data,
2193 as a string, the back-end, as a symbol, and the communication
2197 "List of functions applied to transcoded strike-through text.
2198 Each filter is called with three arguments: the transcoded data,
2199 as a string, the back-end, as a symbol, and the communication
2203 "List of functions applied to a transcoded subscript.
2204 Each filter is called with three arguments: the transcoded data,
2205 as a string, the back-end, as a symbol, and the communication
2209 "List of functions applied to a transcoded superscript.
2210 Each filter is called with three arguments: the transcoded data,
2211 as a string, the back-end, as a symbol, and the communication
2215 "List of functions applied to a transcoded target.
2216 Each filter is called with three arguments: the transcoded data,
2217 as a string, the back-end, as a symbol, and the communication
2221 "List of functions applied to a transcoded timestamp.
2222 Each filter is called with three arguments: the transcoded data,
2223 as a string, the back-end, as a symbol, and the communication
2227 "List of functions applied to transcoded underline text.
2228 Each filter is called with three arguments: the transcoded data,
2229 as a string, the back-end, as a symbol, and the communication
2233 "List of functions applied to transcoded verbatim text.
2234 Each filter is called with three arguments: the transcoded data,
2235 as a string, the back-end, as a symbol, and the communication
2239 ;;;; Filters Tools
2240 ;;
2241 ;; Internal function `org-export-install-filters' installs filters
2242 ;; hard-coded in back-ends (developer filters) and filters from global
2243 ;; variables (user filters) in the communication channel.
2244 ;;
2245 ;; Internal function `org-export-filter-apply-functions' takes care
2246 ;; about applying each filter in order to a given data. It stops
2247 ;; whenever a filter returns a nil value.
2248 ;;
2249 ;; User-oriented function `org-export-set-element' replaces one
2250 ;; element or object in the parse tree with another one. It is meant
2251 ;; to be used as a tool for parse tree filters.
2254 "Call every function in FILTERS.
2255 Functions are called with arguments VALUE, current export
2256 back-end and INFO. Call is done in a LIFO fashion, to be sure
2257 that developer specified filters, if any, are called first."
2261 value)
2264 "Install filters properties in communication channel.
2266 INFO is a plist containing the current communication channel.
2268 Return the updated communication channel."
2270 ;; Install user defined filters with `org-export-filters-alist'.
2273 org-export-filters-alist)
2274 ;; Prepend back-end specific filters to that list.
2279 ;; Single values get consed, lists are prepended.
2284 plist key
2288 ;; Return new communication channel.
2292 "Replace element or object OLD with element or object NEW.
2293 The function takes care of setting `:parent' property for NEW."
2294 ;; OLD can belong to the contents of PARENT or to its secondary
2295 ;; string.
2298 org-element-secondary-value-alist)))
2301 ;; Ensure NEW has correct parent. Then replace OLD with NEW.
2308 \f
2309 ;;; Core functions
2310 ;;
2311 ;; This is the room for the main function, `org-export-as', along with
2312 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
2313 ;; They differ only by the way they output the resulting code.
2314 ;;
2315 ;; `org-export-output-file-name' is an auxiliary function meant to be
2316 ;; used with `org-export-to-file'. With a given extension, it tries
2317 ;; to provide a canonical file name to write export output to.
2318 ;;
2319 ;; Note that `org-export-as' doesn't really parse the current buffer,
2320 ;; but a copy of it (with the same buffer-local variables and
2321 ;; visibility), where include keywords are expanded and Babel blocks
2322 ;; are executed, if appropriate.
2323 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
2324 ;;
2325 ;; File inclusion is taken care of by
2326 ;; `org-export-expand-include-keyword' and
2327 ;; `org-export-prepare-file-contents'. Structure wise, including
2328 ;; a whole Org file in a buffer often makes little sense. For
2329 ;; example, if the file contains an headline and the include keyword
2330 ;; was within an item, the item should contain the headline. That's
2331 ;; why file inclusion should be done before any structure can be
2332 ;; associated to the file, that is before parsing.
2338 "Transcode current Org buffer into BACKEND code.
2340 If narrowing is active in the current buffer, only transcode its
2341 narrowed part.
2343 If a region is active, transcode that region.
2345 When optional argument SUBTREEP is non-nil, transcode the
2346 sub-tree at point, extracting information from the headline
2347 properties first.
2349 When optional argument VISIBLE-ONLY is non-nil, don't export
2350 contents of hidden elements.
2352 When optional argument BODY-ONLY is non-nil, only return body
2353 code, without preamble nor postamble.
2355 Optional argument EXT-PLIST, when provided, is a property list
2356 with external parameters overriding Org default settings, but
2357 still inferior to file-local settings.
2359 Optional argument NOEXPAND, when non-nil, prevents included files
2360 to be expanded and Babel code to be executed.
2362 Return code as a string."
2365 ;; Narrow buffer to an appropriate region or subtree for
2366 ;; parsing. If parsing subtree, be sure to remove main headline
2367 ;; too.
2375 ;; 1. Get export environment from original buffer. Also install
2376 ;; user's and developer's filters.
2379 ;; 2. Get parse tree. Buffer isn't parsed directly.
2380 ;; Instead, a temporary copy is created, where include
2381 ;; keywords are expanded and code blocks are evaluated.
2387 ;; Setting `org-current-export-file' is
2388 ;; required by Org Babel to properly resolve
2389 ;; noweb references.
2393 ;; Run hook with `org-export-current-backend' set
2394 ;; to BACKEND.
2397 ;; Eventually parse buffer.
2399 ;; 3. Call parse-tree filters to get the final tree.
2403 ;; 4. Now tree is complete, compute its properties and add
2404 ;; them to communication channel.
2408 ;; 5. Eventually transcode TREE. Wrap the resulting string
2409 ;; into a template, if required. Eventually call
2410 ;; final-output filter.
2418 info)))
2419 ;; Maybe add final OUTPUT to kill ring, then return it.
2421 output)))))
2425 "Call `org-export-as' with output to a specified buffer.
2427 BACKEND is the back-end used for transcoding, as a symbol.
2429 BUFFER is the output buffer. If it already exists, it will be
2430 erased first, otherwise, it will be created.
2432 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2433 and NOEXPAND are similar to those used in `org-export-as', which
2434 see.
2436 Return buffer."
2438 backend subtreep visible-only body-only ext-plist noexpand))
2444 buffer))
2448 "Call `org-export-as' with output to a specified file.
2450 BACKEND is the back-end used for transcoding, as a symbol. FILE
2451 is the name of the output file, as a string.
2453 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2454 and NOEXPAND are similar to those used in `org-export-as', which
2455 see.
2457 Return output file's name."
2458 ;; Checks for FILE permissions. `write-file' would do the same, but
2459 ;; we'd rather avoid needless transcoding of parse tree.
2461 ;; Insert contents to a temporary buffer and write it to FILE.
2463 backend subtreep visible-only body-only ext-plist noexpand)))
2468 ;; Return full path.
2469 file)
2472 "Return output file's name according to buffer specifications.
2474 EXTENSION is a string representing the output file extension,
2475 with the leading dot.
2477 With a non-nil optional argument SUBTREEP, try to determine
2479 of subtree at point.
2481 When optional argument PUB-DIR is set, use it as the publishing
2482 directory.
2484 When optional argument VISIBLE-ONLY is non-nil, don't export
2485 contents of hidden elements.
2487 Return file name as a string, or nil if it couldn't be
2488 determined."
2490 ;; File name may come from EXPORT_FILE_NAME subtree property,
2491 ;; assuming point is at beginning of said sub-tree.
2498 ;; File name may be extracted from buffer's associated
2499 ;; file, if any.
2501 ;; Can't determine file name on our own: Ask user.
2505 "Output file: " pub-dir nil nil nil
2508 ;; Build file name. Enforce EXTENSION over whatever user may have
2509 ;; come up with. PUB-DIR, if defined, always has precedence over
2510 ;; any provided path.
2515 extension))
2521 "Apply BODY in a copy of the current buffer.
2523 The copy preserves local variables and visibility of the original
2524 buffer.
2526 Point is at buffer's beginning when BODY is applied."
2536 ,original-buffer
2541 ov
2551 "Expand every include keyword in buffer.
2552 Optional argument INCLUDED is a list of included file names along
2553 with their line restriction, when appropriate. It is used to
2554 avoid infinite recursion. Optional argument DIR is the current
2555 working directory. It is used to properly resolve relative
2556 paths."
2563 ;; Extract arguments from keyword's value.
2577 ;; Minimal level of included file defaults to the child
2578 ;; level of the current headline, if any, or one. It
2579 ;; only applies is the file is meant to be included as
2580 ;; an Org one.
2588 ;; Remove keyword.
2592 ;; Check if files has already been parsed. Look after
2593 ;; inclusion lines too, as different parts of the same file
2594 ;; can be included too.
2603 ;; Protect sensitive contents with commas.
2609 ind-str contents ind-str))))
2614 ;; Protect sensitive contents with commas.
2621 ind-str env contents ind-str))))
2634 "Prepare the contents of FILE for inclusion and return them as a string.
2636 When optional argument LINES is a string specifying a range of
2637 lines, include only those lines.
2639 Optional argument IND, when non-nil, is an integer specifying the
2640 global indentation of returned contents. Since its purpose is to
2641 allow an included file to stay in the same environment it was
2642 created \(i.e. a list item), it doesn't apply past the first
2643 headline encountered.
2645 Optional argument MINLEVEL, when non-nil, is an integer
2646 specifying the level that any top-level headline in the included
2647 file should have."
2663 ;; Remove blank lines at beginning and end of contents. The logic
2664 ;; behind that removal is that blank lines around include keyword
2665 ;; override blank lines in included file.
2674 ;; If IND is set, preserve indentation of include keyword until
2675 ;; the first headline encountered.
2681 ;; Do not move footnote definitions out of column 0.
2687 ;; When MINLEVEL is specified, compute minimal level for headlines
2688 ;; in the file (CUR-MIN), and remove stars to each headline so
2689 ;; that headlines with minimal level have a level of MINLEVEL.
2698 ;; Only change stars, don't bother moving whole
2699 ;; sections.
2705 \f
2706 ;;; Tools For Back-Ends
2707 ;;
2708 ;; A whole set of tools is available to help build new exporters. Any
2709 ;; function general enough to have its use across many back-ends
2710 ;; should be added here.
2711 ;;
2712 ;; As of now, functions operating on footnotes, headlines, links,
2713 ;; macros, references, src-blocks, tables and tables of contents are
2714 ;; implemented.
2716 ;;;; For Affiliated Keywords
2717 ;;
2718 ;; `org-export-read-attribute' reads a property from a given element
2719 ;; as a plist. It can be used to normalize affiliated keywords'
2720 ;; syntax.
2723 "Turn ATTRIBUTE property from ELEMENT into a plist.
2726 properties."
2732 ;;;; For Export Snippets
2733 ;;
2734 ;; Every export snippet is transmitted to the back-end. Though, the
2735 ;; latter will only retain one type of export-snippet, ignoring
2736 ;; others, based on the former's target back-end. The function
2737 ;; `org-export-snippet-backend' returns that back-end for a given
2738 ;; export-snippet.
2741 "Return EXPORT-SNIPPET targeted back-end as a symbol.
2742 Translation, with `org-export-snippet-translation-alist', is
2743 applied."
2747 back-end))))
2750 ;;;; For Footnotes
2751 ;;
2752 ;; `org-export-collect-footnote-definitions' is a tool to list
2753 ;; actually used footnotes definitions in the whole parse tree, or in
2754 ;; an headline, in order to add footnote listings throughout the
2755 ;; transcoded data.
2756 ;;
2757 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2758 ;; back-ends, when they need to attach the footnote definition only to
2759 ;; the first occurrence of the corresponding label.
2760 ;;
2761 ;; `org-export-get-footnote-definition' and
2762 ;; `org-export-get-footnote-number' provide easier access to
2763 ;; additional information relative to a footnote reference.
2766 "Return an alist between footnote numbers, labels and definitions.
2768 DATA is the parse tree from which definitions are collected.
2769 INFO is the plist used as a communication channel.
2771 Definitions are sorted by order of references. They either
2772 appear as Org data or as a secondary string for inlined
2773 footnotes. Unreferenced definitions are ignored."
2775 collect-fn ; for byte-compiler.
2779 ;; Collect footnote number, label and definition in DATA.
2781 data 'footnote-reference
2788 def)
2789 num-alist)
2790 ;; Also search in definition for nested footnotes.
2793 ;; Don't enter footnote definitions since it will happen
2794 ;; when their first reference is found.
2800 "Non-nil when a footnote reference is the first one for its label.
2802 FOOTNOTE-REFERENCE is the footnote reference being considered.
2803 INFO is the plist used as a communication channel."
2805 ;; Anonymous footnotes are always a first reference.
2807 ;; Otherwise, return the first footnote with the same LABEL and
2808 ;; test if it is equal to FOOTNOTE-REFERENCE.
2814 data 'footnote-reference
2819 ;; If FN isn't inlined, be sure to traverse its
2820 ;; definition before resuming search. See
2821 ;; comments in `org-export-get-footnote-number'
2822 ;; for more information.
2826 ;; Don't enter footnote definitions since it will
2827 ;; happen when their first reference is found.
2830 footnote-reference)))))
2833 "Return definition of FOOTNOTE-REFERENCE as parsed data.
2834 INFO is the plist used as a communication channel."
2840 "Return number associated to a footnote.
2842 FOOTNOTE is either a footnote reference or a footnote definition.
2843 INFO is the plist used as a communication channel."
2845 seen-refs
2846 search-ref ; for byte-compiler.
2850 ;; Search footnote references through DATA, filling
2851 ;; SEEN-REFS along the way.
2853 data 'footnote-reference
2857 ;; Anonymous footnote match: return number.
2860 ;; Labels match: return number.
2863 ;; Anonymous footnote: it's always a new one. Also,
2864 ;; be sure to return nil from the `cond' so
2865 ;; `first-match' doesn't get us out of the loop.
2867 ;; Label not seen so far: add it so SEEN-REFS.
2868 ;;
2869 ;; Also search for subsequent references in footnote
2870 ;; definition so numbering following reading logic.
2871 ;; Note that we don't have to care about inline
2872 ;; definitions, since `org-element-map' already
2873 ;; traverse them at the right time.
2874 ;;
2875 ;; Once again, return nil to stay in the loop.
2880 nil))))
2881 ;; Don't enter footnote definitions since it will happen
2882 ;; when their first reference is found.
2887 ;;;; For Headlines
2888 ;;
2889 ;; `org-export-get-relative-level' is a shortcut to get headline
2890 ;; level, relatively to the lower headline level in the parsed tree.
2891 ;;
2892 ;; `org-export-get-headline-number' returns the section number of an
2893 ;; headline, while `org-export-number-to-roman' allows to convert it
2894 ;; to roman numbers.
2895 ;;
2896 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
2897 ;; `org-export-last-sibling-p' are three useful predicates when it
2898 ;; comes to fulfill the `:headline-levels' property.
2901 "Return HEADLINE relative level within current parsed tree.
2902 INFO is a plist holding contextual information."
2907 "Non-nil when HEADLINE is considered as low level.
2909 INFO is a plist used as a communication channel.
2911 A low level headlines has a relative level greater than
2912 `:headline-levels' property value.
2914 Return value is the difference between HEADLINE relative level
2915 and the last level being considered as high enough, or nil."
2922 "Return HEADLINE numbering as a list of numbers.
2923 INFO is a plist holding contextual information."
2927 "Return a non-nil value if HEADLINE element should be numbered.
2928 INFO is a plist used as a communication channel."
2934 "Convert integer N into a roman numeral."
2947 res)))
2950 "Return list of tags associated to ELEMENT.
2952 ELEMENT has either an `headline' or an `inlinetask' type. INFO
2953 is a plist used as a communication channel.
2955 Select tags (see `org-export-select-tags') and exclude tags (see
2956 `org-export-exclude-tags') are removed from the list.
2958 When non-nil, optional argument TAGS should be a list of strings.
2959 Any tag belonging to this list will also be removed."
2966 "Non-nil when HEADLINE is the first sibling in its sub-tree."
2971 "Non-nil when HEADLINE is the last sibling in its sub-tree."
2975 ;;;; For Links
2976 ;;
2977 ;; `org-export-solidify-link-text' turns a string into a safer version
2978 ;; for links, replacing most non-standard characters with hyphens.
2979 ;;
2980 ;; `org-export-get-coderef-format' returns an appropriate format
2981 ;; string for coderefs.
2982 ;;
2983 ;; `org-export-inline-image-p' returns a non-nil value when the link
2984 ;; provided should be considered as an inline image.
2985 ;;
2986 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
2987 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
2988 ;; returns an appropriate unique identifier when found, or nil.
2989 ;;
2990 ;; `org-export-resolve-id-link' returns the first headline with
2991 ;; specified id or custom-id in parse tree, the path to the external
2992 ;; file with the id or nil when neither was found.
2993 ;;
2994 ;; `org-export-resolve-coderef' associates a reference to a line
2995 ;; number in the element it belongs, or returns the reference itself
2996 ;; when the element isn't numbered.
2999 "Take link text S and make a safe target out of it."
3004 "Return format string for code reference link.
3005 PATH is the link path. DESC is its description."
3013 "Non-nil if LINK object points to an inline image.
3015 Optional argument is a set of RULES defining inline images. It
3016 is an alist where associations have the following shape:
3018 \(TYPE . REGEXP)
3020 Applying a rule means apply REGEXP against LINK's path when its
3021 type is TYPE. The function will return a non-nil value if any of
3022 the provided rules is non-nil. The default rule is
3023 `org-export-default-inline-image-rule'.
3025 This only applies to links without a description."
3036 rules)
3037 ;; Return nil if no rule matched.
3038 nil))))
3041 "Resolve a code reference REF.
3043 INFO is a plist used as a communication channel.
3045 Return associated line number in source code, or REF itself,
3046 depending on src-block or example element's switches."
3054 org-coderef-label-format)))
3058 ;; Element containing REF is found. Resolve it to either
3059 ;; a label or a line number, as needed.
3069 "Return LINK destination.
3071 INFO is a plist holding contextual information.
3073 Return value can be an object, an element, or nil:
3075 - If LINK path matches a target object (i.e. <<path>>) or
3078 - If LINK path exactly matches the name affiliated keyword
3079 \(i.e. #+NAME: path) of an element, return that element.
3081 - If LINK path exactly matches any headline name, return that
3082 element. If more than one headline share that name, priority
3083 will be given to the one with the closest common ancestor, if
3084 any, or the first one in the parse tree otherwise.
3086 - Otherwise, return nil.
3092 ;; First try to find a matching "<<path>>" unless user specified
3093 ;; he was looking for an headline (path starts with a *
3094 ;; character).
3098 return target)))
3099 ;; Then try to find an element with a matching "#+NAME: path"
3100 ;; affiliated keyword.
3107 ;; Last case: link either points to an headline or to
3108 ;; nothingness. Try to find the source, with priority given to
3109 ;; headlines with the closest common ancestor. If such candidate
3110 ;; is found, return it, otherwise return nil.
3114 ;; Return first headline whose `:raw-value' property
3115 ;; is NAME in parse tree DATA, or nil.
3118 data 'headline
3122 name)
3123 headline))
3125 ;; Search among headlines sharing an ancestor with link,
3126 ;; from closest to farthest.
3134 ;; No match with a common ancestor: try the full parse-tree.
3140 "Return headline referenced as LINK destination.
3142 INFO is a plist used as a communication channel.
3144 Return value can be the headline element matched in current parse
3148 ;; First check if id is within the current parse tree.
3154 headline))
3156 ;; Otherwise, look for external files.
3160 "Return radio-target object referenced as LINK destination.
3162 INFO is a plist used as a communication channel.
3164 Return value can be a radio-target object or nil. Assume LINK
3174 ;;;; For Macros
3175 ;;
3176 ;; `org-export-expand-macro' simply takes care of expanding macros.
3179 "Expand MACRO and return it as a string.
3180 INFO is a plist holding export options."
3183 ;; User's macros are stored in the communication channel with
3184 ;; a ":macro-" prefix. Replace arguments in VALUE. Also
3185 ;; expand recursively macros within.
3194 obj)))
3196 info)))
3197 ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
3199 ;; Return string.
3203 ;;;; For References
3204 ;;
3205 ;; `org-export-get-ordinal' associates a sequence number to any object
3206 ;; or element.
3209 "Return ordinal number of an element or object.
3211 ELEMENT is the element or object considered. INFO is the plist
3212 used as a communication channel.
3214 Optional argument TYPES, when non-nil, is a list of element or
3215 object types, as symbols, that should also be counted in.
3216 Otherwise, only provided element's type is considered.
3218 Optional argument PREDICATE is a function returning a non-nil
3219 value if the current element or object should be counted in. It
3220 accepts two arguments: the element or object being considered and
3221 the plist used as a communication channel. This allows to count
3222 only a certain type of objects (i.e. inline images).
3224 Return value is a list of numbers if ELEMENT is an headline or an
3225 item. It is nil for keywords. It represents the footnote number
3226 for footnote definitions and footnote references. If ELEMENT is
3227 a target, return the same value as if ELEMENT was the closest
3228 table, item or headline containing the target. In any other
3229 case, return the sequence number of ELEMENT among elements or
3230 objects of the same type."
3231 ;; A target keyword, representing an invisible target, never has
3232 ;; a sequence number.
3234 ;; Ordinal of a target object refer to the ordinal of the closest
3235 ;; table, item, or headline containing the object.
3239 when
3243 table))
3244 return parent)))
3246 ;; Special case 1: An headline returns its number as a list.
3248 ;; Special case 2: An item returns its number as a list.
3252 struct
3259 ;; Increment counter until ELEMENT is found again.
3270 ;;;; For Src-Blocks
3271 ;;
3272 ;; `org-export-get-loc' counts number of code lines accumulated in
3273 ;; src-block or example-block elements with a "+n" switch until
3274 ;; a given element, excluded. Note: "-n" switches reset that count.
3275 ;;
3276 ;; `org-export-unravel-code' extracts source code (along with a code
3277 ;; references alist) from an `element-block' or `src-block' type
3278 ;; element.
3279 ;;
3280 ;; `org-export-format-code' applies a formatting function to each line
3281 ;; of code, providing relative line number and code reference when
3282 ;; appropriate. Since it doesn't access the original element from
3283 ;; which the source code is coming, it expects from the code calling
3284 ;; it to know if lines should be numbered and if code references
3285 ;; should appear.
3286 ;;
3287 ;; Eventually, `org-export-format-code-default' is a higher-level
3288 ;; function (it makes use of the two previous functions) which handles
3289 ;; line numbering and code references inclusion, and returns source
3290 ;; code in a format suitable for plain text or verbatim output.
3293 "Return accumulated lines of code up to ELEMENT.
3295 INFO is the plist used as a communication channel.
3297 ELEMENT is excluded from count."
3304 ;; ELEMENT is reached: Quit the loop.
3306 ;; Only count lines from src-block and example-block elements
3307 ;; with a "+n" or "-n" switch. A "-n" switch resets counter.
3311 ;; Accumulate locs or reset them.
3315 ;; Return nil to stay in the loop.
3316 nil)))
3318 ;; Return value.
3319 loc))
3322 "Clean source code and extract references out of it.
3324 ELEMENT has either a `src-block' an `example-block' type.
3326 Return a cons cell whose CAR is the source code, cleaned from any
3327 reference and protective comma and CDR is an alist between
3328 relative line number (integer) and name of code reference on that
3329 line (string)."
3331 ;; Get code and clean it. Remove blank lines at its
3332 ;; beginning and end. Also remove protective commas.
3338 ;; If appropriate, remove global indentation.
3342 ;; Free up the protected lines. Note: Org blocks
3343 ;; have commas at the beginning or every line.
3348 ;; Get format used for references.
3351 org-coderef-label-format)))
3352 ;; Build a regexp matching a loc with a reference.
3357 ;; Return value.
3359 ;; Code with references removed.
3365 ;; Ref line: remove ref, and signal its position in REFS.
3369 ;; Reference alist.
3370 refs)))
3373 "Format CODE by applying FUN line-wise and return it.
3375 CODE is a string representing the code to format. FUN is
3376 a function. It must accept three arguments: a line of
3377 code (string), the current line number (integer) or nil and the
3378 reference associated to the current line (string) or nil.
3380 Optional argument NUM-LINES can be an integer representing the
3381 number of code lines accumulated until the current code. Line
3382 numbers passed to FUN will take it into account. If it is nil,
3383 FUN's second argument will always be nil. This number can be
3384 obtained with `org-export-get-loc' function.
3386 Optional argument REF-ALIST can be an alist between relative line
3387 number (i.e. ignoring NUM-LINES) and the name of the code
3388 reference on it. If it is nil, FUN's third argument will always
3389 be nil. It can be obtained through the use of
3390 `org-export-unravel-code' function."
3402 "Return source code from ELEMENT, formatted in a standard way.
3404 ELEMENT is either a `src-block' or `example-block' element. INFO
3405 is a plist used as a communication channel.
3407 This function takes care of line numbering and code references
3408 inclusion. Line numbers, when applicable, appear at the
3409 beginning of the line, separated from the code by two white
3410 spaces. Code references, on the other hand, appear flushed to
3411 the right, separated by six white spaces from the widest line of
3412 code."
3413 ;; Extract code and references.
3419 ;; Handle line numbering.
3428 ;; Prepare references display, if required. Any reference
3429 ;; should start six columns after the widest line of code,
3430 ;; wrapped with parenthesis.
3435 code
3439 number-str
3440 loc
3446 num-start refs)))
3449 ;;;; For Tables
3450 ;;
3451 ;; `org-export-table-has-special-column-p' and and
3452 ;; `org-export-table-row-is-special-p' are predicates used to look for
3453 ;; meta-information about the table structure.
3454 ;;
3455 ;; `org-table-has-header-p' tells when the rows before the first rule
3456 ;; should be considered as table's header.
3457 ;;
3458 ;; `org-export-table-cell-width', `org-export-table-cell-alignment'
3459 ;; and `org-export-table-cell-borders' extract information from
3460 ;; a table-cell element.
3461 ;;
3462 ;; `org-export-table-dimensions' gives the number on rows and columns
3463 ;; in the table, ignoring horizontal rules and special columns.
3464 ;; `org-export-table-cell-address', given a table-cell object, returns
3465 ;; the absolute address of a cell. On the other hand,
3466 ;; `org-export-get-table-cell-at' does the contrary.
3467 ;;
3468 ;; `org-export-table-cell-starts-colgroup-p',
3469 ;; `org-export-table-cell-ends-colgroup-p',
3470 ;; `org-export-table-row-starts-rowgroup-p',
3471 ;; `org-export-table-row-ends-rowgroup-p',
3472 ;; `org-export-table-row-starts-header-p' and
3473 ;; `org-export-table-row-ends-header-p' indicate position of current
3474 ;; row or cell within the table.
3477 "Non-nil when TABLE has a special column.
3478 All special columns will be ignored during export."
3479 ;; The table has a special column when every first cell of every row
3480 ;; has an empty value or contains a symbol among "/", "#", "!", "$",
3481 ;; "*" "_" and "^". Though, do not consider a first row containing
3482 ;; only empty cells as special.
3498 "Non-nil when TABLE has an header.
3500 INFO is a plist used as a communication channel.
3502 A table has an header when it contains at least two row groups."
3505 table 'table-row
3513 info)))
3516 "Non-nil if TABLE-ROW is considered special.
3518 INFO is a plist used as the communication channel.
3520 All special rows will be ignored during export."
3524 ;; A row is special either when...
3526 ;; ... it starts with a field only containing "/",
3528 ;; ... the table contains a special column and the row start
3529 ;; with a marking character among, "^", "_", "$" or "!",
3533 ;; ... it contains only alignment cookies and empty cells.
3539 ;; Since VALUE is a secondary string, the following
3540 ;; checks avoid expanding it with `org-export-data'.
3552 "Return TABLE-ROW's group.
3554 INFO is a plist used as the communication channel.
3556 Return value is the group number, as an integer, or nil special
3557 rows and table rules. Group 1 is also table's header."
3574 "Return TABLE-CELL contents width.
3576 INFO is a plist used as the communication channel.
3578 Return value is the width given by the last width cookie in the
3579 same column as TABLE-CELL, or nil."
3584 cookie-width)
3588 ;; In a special row, try to find a width cookie at COLUMN.
3592 ;; The following checks avoid expanding unnecessarily the
3593 ;; cell with `org-export-data'
3601 ;; Ignore table rules.
3604 ;; Return value.
3605 cookie-width))
3608 "Return TABLE-CELL contents alignment.
3610 INFO is a plist used as the communication channel.
3612 Return alignment as specified by the last alignment cookie in the
3613 same column as TABLE-CELL. If no such cookie is found, a default
3614 alignment value will be deduced from fraction of numbers in the
3615 column (see `org-table-number-fraction' for more information).
3616 Possible values are `left', `right' and `center'."
3623 cookie-align)
3627 ;; In a special row, try to find an alignment cookie at
3628 ;; COLUMN.
3632 ;; Since VALUE is a secondary string, the following checks
3633 ;; avoid useless expansion through `org-export-data'.
3641 ;; Ignore table rules.
3643 ;; In a standard row, check if cell's contents are expressing
3644 ;; some kind of number. Increase NUMBER-CELLS accordingly.
3645 ;; Though, don't bother if an alignment cookie has already
3646 ;; defined cell's alignment.
3651 info)))
3656 ;; Return value. Alignment specified by cookies has precedence
3657 ;; over alignment deduced from cells contents.
3666 "Return TABLE-CELL borders.
3668 INFO is a plist used as a communication channel.
3670 Return value is a list of symbols, or nil. Possible values are:
3671 `top', `bottom', `above', `below', `left' and `right'. Note:
3672 `top' (resp. `bottom') only happen for a cell in the first
3673 row (resp. last row) of the table, ignoring table rules, if any.
3675 Returned borders ignore special rows."
3678 borders)
3679 ;; Top/above border? TABLE-CELL has a border above when a rule
3680 ;; used to demarcate row groups can be found above. Hence,
3681 ;; finding a rule isn't sufficient to push `above' in BORDERS:
3682 ;; another regular row has to be found above that rule.
3691 ;; Look at every row before the current one.
3693 ;; No rule above, or rule found starts the table (ignoring any
3694 ;; special row): TABLE-CELL is at the top of the table.
3697 ;; Bottom/below border? TABLE-CELL has a border below when next
3698 ;; non-regular row below is a rule.
3707 ;; Look at every row after the current one.
3709 ;; No rule below, or rule found ends the table (modulo some
3710 ;; special row): TABLE-CELL is at the bottom of the table.
3713 ;; Right/left borders? They can only be specified by column
3714 ;; groups. Column groups are defined in a row starting with "/".
3715 ;; Also a column groups row only contains "<", "<>", ">" or blank
3716 ;; cells.
3733 ;; There's a left border when previous cell, if
3734 ;; any, ends a group, or current one starts one.
3740 ;; There's a right border when next cell, if any,
3741 ;; starts a group, or current one ends one.
3748 ;; Table rows are read in reverse order so last column groups
3749 ;; row has precedence over any previous one.
3751 ;; Return value.
3752 borders))
3755 "Non-nil when TABLE-CELL is at the beginning of a row group.
3756 INFO is a plist used as a communication channel."
3757 ;; A cell starts a column group either when it is at the beginning
3758 ;; of a row (or after the special column, if any) or when it has
3759 ;; a left border.
3763 table-cell)
3767 "Non-nil when TABLE-CELL is at the end of a row group.
3768 INFO is a plist used as a communication channel."
3769 ;; A cell ends a column group either when it is at the end of a row
3770 ;; or when it has a right border.
3773 table-cell)
3777 "Non-nil when TABLE-ROW is at the beginning of a column group.
3778 INFO is a plist used as a communication channel."
3786 "Non-nil when TABLE-ROW is at the end of a column group.
3787 INFO is a plist used as a communication channel."
3795 "Non-nil when TABLE-ROW is the first table header's row.
3796 INFO is a plist used as a communication channel."
3803 "Non-nil when TABLE-ROW is the last table header's row.
3804 INFO is a plist used as a communication channel."
3811 "Return TABLE dimensions.
3813 INFO is a plist used as a communication channel.
3815 Return value is a CONS like (ROWS . COLUMNS) where
3816 ROWS (resp. COLUMNS) is the number of exportable
3817 rows (resp. columns)."
3819 ;; Set number of rows, and extract first one.
3821 table 'table-row
3826 ;; Set number of columns.
3828 ;; Return value.
3832 "Return address of a regular TABLE-CELL object.
3834 TABLE-CELL is the cell considered. INFO is a plist used as
3835 a communication channel.
3837 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3838 zero-based index. Only exportable cells are considered. The
3839 function returns nil for other cells."
3842 ;; Ignore cells in special rows or in special column.
3847 ;; Row number.
3850 table 'table-row
3856 ;; Column number.
3859 table-row 'table-cell
3866 "Return regular table-cell object at ADDRESS in TABLE.
3868 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3869 zero-based index. TABLE is a table type element. INFO is
3870 a plist used as a communication channel.
3872 If no table-cell, among exportable cells, is found at ADDRESS,
3873 return nil."
3876 ;; Row at (car address) or nil.
3879 table 'table-row
3885 'table-cell
3892 ;;;; For Tables Of Contents
3893 ;;
3894 ;; `org-export-collect-headlines' builds a list of all exportable
3895 ;; headline elements, maybe limited to a certain depth. One can then
3896 ;; easily parse it and transcode it.
3897 ;;
3898 ;; Building lists of tables, figures or listings is quite similar.
3899 ;; Once the generic function `org-export-collect-elements' is defined,
3900 ;; `org-export-collect-tables', `org-export-collect-figures' and
3901 ;; `org-export-collect-listings' can be derived from it.
3904 "Collect headlines in order to build a table of contents.
3906 INFO is a plist used as a communication channel.
3908 When non-nil, optional argument N must be an integer. It
3909 specifies the depth of the table of contents.
3911 Return a list of all exportable headlines as parsed elements."
3914 'headline
3916 ;; Strip contents from HEADLINE.
3919 info))
3922 "Collect referenceable elements of a determined type.
3924 TYPE can be a symbol or a list of symbols specifying element
3925 types to search. Only elements with a caption are collected.
3927 INFO is a plist used as a communication channel.
3929 When non-nil, optional argument PREDICATE is a function accepting
3930 one argument, an element of type TYPE. It returns a non-nil
3931 value when that element should be collected.
3933 Return a list of all elements found, in order of appearance."
3939 element))
3940 info))
3943 "Build a list of tables.
3944 INFO is a plist used as a communication channel.
3946 Return a list of table elements with a caption."
3950 "Build a list of figures.
3952 INFO is a plist used as a communication channel. PREDICATE is
3953 a function which accepts one argument: a paragraph element and
3954 whose return value is non-nil when that element should be
3955 collected.
3957 A figure is a paragraph type element, with a caption, verifying
3959 a vague concept that may depend on back-end.
3961 Return a list of elements recognized as figures."
3965 "Build a list of src blocks.
3967 INFO is a plist used as a communication channel.
3969 Return a list of src-block elements with a caption."
3973 ;;;; Topology
3974 ;;
3975 ;; Here are various functions to retrieve information about the
3976 ;; neighbourhood of a given element or object. Neighbours of interest
3977 ;; are direct parent (`org-export-get-parent'), parent headline
3978 ;; (`org-export-get-parent-headline'), first element containing an
3979 ;; object, (`org-export-get-parent-element'), parent table
3980 ;; (`org-export-get-parent-table'), previous element or object
3981 ;; (`org-export-get-previous-element') and next element or object
3982 ;; (`org-export-get-next-element').
3983 ;;
3984 ;; `org-export-get-genealogy' returns the full genealogy of a given
3985 ;; element or object, from closest parent to full parse tree.
3988 "Return BLOB parent or nil.
3989 BLOB is the element or object considered."
3993 "Return full genealogy relative to a given element or object.
3994 BLOB is the element or object being considered."
4001 "Return BLOB parent headline or nil.
4002 BLOB is the element or object being considered."
4006 parent))
4009 "Return first element containing OBJECT or nil.
4010 OBJECT is the object to consider."
4014 parent))
4017 "Return OBJECT parent table or nil.
4018 OBJECT is either a `table-cell' or `table-element' type object."
4022 parent))
4025 "Return previous element or object.
4026 BLOB is an element or object. Return previous element or object,
4027 a string, or nil."
4032 "Return next element or object.
4033 BLOB is an element or object. Return next element or object,
4034 a string, or nil."
4039 \f
4040 ;;; The Dispatcher
4041 ;;
4042 ;; `org-export-dispatch' is the standard interactive way to start an
4043 ;; export process. It uses `org-export-dispatch-ui' as a subroutine
4044 ;; for its interface. Most commons back-ends should have an entry in
4045 ;; it.
4048 "Export dispatcher for Org mode.
4050 It provides an access to common export related tasks in a buffer.
4051 Its interface comes in two flavours: standard and expert. While
4052 both share the same set of bindings, only the former displays the
4053 valid keys associations. Set `org-export-dispatch-use-expert-ui'
4054 to switch to one or the other.
4056 Return an error if key pressed has no associated command."
4061 org-export-dispatch-use-expert-ui))
4064 ;; Translate "C-a", "C-b"... into "a", "b"... Then take action
4065 ;; depending on user's key pressed.
4067 ;; Allow to quit with "q" key.
4069 ;; Export with `e-ascii' back-end.
4075 `(:ascii-charset
4084 ;; Export with `e-latex' back-end.
4085 (?L
4093 (?l
4096 (?p
4099 (?d
4103 ;; Export with `e-html' back-end.
4104 (?H
4109 ;; set major mode
4113 (?h
4116 (?b
4120 ;; Export with `e-odt' back-end.
4121 (?o
4124 (?O
4128 ;; Publishing facilities
4129 (?F
4131 (?P
4133 (?X
4137 org-e-publish-project-alist)))
4139 (?E
4141 ;; Undefined command.
4146 "Handle interface for `org-export-dispatch'.
4148 OPTIONS is a list containing current interactive options set for
4149 export. It can contain any of the following symbols:
4150 `body' toggles a body-only export
4151 `subtree' restricts export to current subtree
4152 `visible' restricts export to visible part of buffer.
4153 `force' force publishing files.
4155 EXPERTP, when non-nil, triggers expert UI. In that case, no help
4156 buffer is provided, but indications about currently active
4157 options are given in the prompt. Moreover, \[?] allows to switch
4158 back to standard interface.
4160 Return value is a list with key pressed as CAR and a list of
4161 final interactive export options as CDR."
4165 \[1] Body only: %s [2] Export scope: %s
4166 \[3] Visible only: %s [4] Force publishing: %s
4169 --- (ASCII/Latin-1/UTF-8 Export) -------------------------
4171 \[a/n/u] to TXT file [A/N/U] to temporary buffer
4173 --- (HTML Export) ----------------------------------------
4175 \[h] to HTML file [b] ... and open it
4176 \[H] to temporary buffer
4178 --- (LaTeX Export) ---------------------------------------
4180 \[l] to TEX file [L] to temporary buffer
4181 \[p] to PDF file [d] ... and open it
4183 --- (ODF Export) -----------------------------------------
4185 \[o] to ODT file [O] ... and open it
4187 --- (Publish) --------------------------------------------
4189 \[F] current file [P] current project
4190 \[X] a project [E] every project"
4203 ;; Read a character from command input, toggling interactive
4204 ;; options when applicable. PROMPT is the displayed prompt,
4205 ;; as a string.
4209 ;; Ignore non-standard characters (i.e. "M-a").
4211 ;; Help key: Switch back to standard interface if
4212 ;; expert UI was active.
4214 ;; Toggle export options.
4221 expertp))
4222 ;; Action selected: Send key and options back to
4223 ;; `org-export-dispatch'.
4225 ;; With expert UI, just read key with a fancy prompt. In standard
4226 ;; UI, display an intrusive help buffer.
4237 ;;; org-export.el ends here