| blob | 4f607b90bf1cb95a08f87da86f59aa11e52d33c1 |
1 ;;; org-export.el --- Generic Export Engine For Org
3 ;; Copyright (C) 2012 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation, either version 3 of the License, or
11 ;; (at your option) any later version.
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;; GNU General Public License for more details.
18 ;; You should have received a copy of the GNU General Public License
19 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
21 ;;; Commentary:
23 ;; This library implements a generic export engine for Org, built on
24 ;; its syntactical parser: Org Elements.
26 ;; Besides that parser, the generic exporter is made of three distinct
27 ;; parts:
29 ;; - The communication channel consists in a property list, which is
30 ;; created and updated during the process. Its use is to offer
31 ;; every piece of information, would it be about initial environment
32 ;; or contextual data, all in a single place. The exhaustive list
33 ;; of properties is given in "The Communication Channel" section of
34 ;; this file.
36 ;; - The transcoder walks the parse tree, ignores or treat as plain
37 ;; text elements and objects according to export options, and
38 ;; eventually calls back-end specific functions to do the real
39 ;; transcoding, concatenating their return value along the way.
41 ;; - The filter system is activated at the very beginning and the very
42 ;; end of the export process, and each time an element or an object
43 ;; has been converted. It is the entry point to fine-tune standard
44 ;; output from back-end transcoders.
46 ;; The core function is `org-export-as'. It returns the transcoded
47 ;; buffer as a string.
49 ;; In order to derive an exporter out of this generic implementation,
50 ;; one can define a transcode function for each element or object.
51 ;; Such function should return a string for the corresponding element,
52 ;; without any trailing space, or nil. It must accept three
53 ;; arguments:
54 ;; 1. the element or object itself,
55 ;; 2. its contents, or nil when it isn't recursive,
56 ;; 3. the property list used as a communication channel.
58 ;; If no such function is found, that element or object type will
59 ;; simply be ignored, along with any separating blank line. The same
60 ;; will happen if the function returns the nil value. If that
61 ;; function returns the empty string, the type will be ignored, but
62 ;; the blank lines will be kept.
64 ;; Contents, when not nil, are stripped from any global indentation
65 ;; (although the relative one is preserved). They also always end
66 ;; with a single newline character.
68 ;; These functions must follow a strict naming convention:
69 ;; `org-BACKEND-TYPE' where, obviously, BACKEND is the name of the
70 ;; export back-end and TYPE the type of the element or object handled.
72 ;; Moreover, two additional functions can be defined. On the one
73 ;; hand, `org-BACKEND-template' returns the final transcoded string,
74 ;; and can be used to add a preamble and a postamble to document's
75 ;; body. It must accept two arguments: the transcoded string and the
76 ;; property list containing export options. On the other hand,
77 ;; `org-BACKEND-plain-text', when defined, is to be called on every
78 ;; text not recognized as an element or an object. It must accept two
79 ;; arguments: the text string and the information channel.
81 ;; Any back-end can define its own variables. Among them, those
82 ;; customizables should belong to the `org-export-BACKEND' group.
83 ;; Also, a special variable, `org-BACKEND-option-alist', allows to
84 ;; define buffer keywords and "#+options:" items specific to that
85 ;; back-end. See `org-export-option-alist' for supported defaults and
86 ;; syntax.
88 ;; Tools for common tasks across back-ends are implemented in the
89 ;; penultimate part of this file. A dispatcher for standard back-ends
90 ;; is provided in the last one.
92 ;;; Code:
95 ;; Require major back-ends and publishing tools
103 \f
104 ;;; Internal Variables
106 ;; Among internal variables, the most important is
107 ;; `org-export-option-alist'. This variable define the global export
108 ;; options, shared between every exporter, and how they are acquired.
146 "Alist between export properties and ways to set them.
148 The CAR of the alist is the property name, and the CDR is a list
149 like (KEYWORD OPTION DEFAULT BEHAVIOUR) where:
151 KEYWORD is a string representing a buffer keyword, or nil.
152 OPTION is a string that could be found in an #+OPTIONS: line.
153 DEFAULT is the default value for the property.
154 BEHAVIOUR determine how Org should handle multiple keywords for
155 the same property. It is a symbol among:
156 nil Keep old value and discard the new one.
157 t Replace old value with the new one.
158 `space' Concatenate the values, separating them with a space.
159 `newline' Concatenate the values, separating them with
160 a newline.
161 `split' Split values at white spaces, and cons them to the
162 previous list.
164 KEYWORD and OPTION have precedence over DEFAULT.
166 All these properties should be back-end agnostic. For back-end
167 specific properties, define a similar variable named
168 `org-BACKEND-option-alist', replacing BACKEND with the name of
169 the appropriate back-end. You can also redefine properties
174 "List of in-buffer keywords that require special treatment.
175 These keywords are not directly associated to a property. The
176 way they are handled must be hard-coded into
228 "Alist between filters properties and initial values.
230 The key of each association is a property name accessible through
231 the communication channel its value is a configurable global
232 variable defining initial filters.
234 This list is meant to install user specified filters. Back-end
235 developers may install their own filters using
236 `org-BACKEND-filters-alist', where BACKEND is the name of the
237 considered back-end. Filters defined there will always be
238 prepended to the current list, so they always get applied
247 "Default rule for link matching an inline image.
248 This rule applies to links with no description. By default, it
249 will be considered as an inline image if it targets a local file
252 See `org-export-inline-image-p' for more information about
256 \f
257 ;;; User-configurable Variables
259 ;; Configuration for the masses.
261 ;; They should never be evaled directly, as their value is to be
262 ;; stored in a property list (cf. `org-export-option-alist').
265 "Options for exporting Org mode files."
270 "General options for export engine."
275 "Whether sub-trees with the ARCHIVE tag should be exported.
277 This can have three different values:
278 nil Do not export, pretend this tree is not present.
279 t Do export the entire tree.
280 `headline' Only export the headline, but skip the tree below it.
282 This option can also be set with the #+OPTIONS line,
291 "Non-nil means insert author name into the exported file.
292 This option can also be set with the #+OPTIONS line,
298 "Non-nil means the postamble should contain a creator sentence.
300 The sentence can be set in `org-export-creator-string' and
303 If the value is `comment' insert it as a comment."
313 emacs-version)
314 "String to insert at the end of the generated document."
319 "Non-nil means export contents of standard drawers.
321 When t, all drawers are exported. This may also be a list of
322 drawer names to export. This variable doesn't apply to
323 properties drawers.
325 This option can also be set with the #+OPTIONS line,
335 "Non-nil means insert author email into the exported file.
336 This option can also be set with the #+OPTIONS line,
342 "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
344 If the export target supports emphasizing text, the word will be
345 typeset in bold, italic, or underlined, respectively. Not all
346 export backends support this.
353 "Tags that exclude a tree from export.
355 All trees carrying any of these tags will be excluded from
356 export. This is without condition, so even subtrees inside that
357 carry one of the `org-export-select-tags' will be removed.
359 This option can also be set with the #+EXPORT_EXCLUDE_TAGS:
360 keyword."
367 This can be used to have pre-formatted text, fragments of code
368 etc. For example:
369 : ;; Some Lisp examples
370 : (while (defc cnt)
371 : (ding))
372 will be looking just like this in also HTML. See also the QUOTE
373 keyword. Not all export backends support this.
380 "Non-nil means Org footnotes should be exported.
381 This option can also be set with the #+OPTIONS line,
387 "The last level which is still exported as a headline.
389 Inferior levels will produce itemize lists when exported. Note
390 that a numeric prefix argument to an exporter function overrides
391 this setting.
398 "The default language for export and clocktable translations, as a string.
399 This may have an association in
400 `org-clock-clocktable-language-setup'."
405 "Non-nil means preserve all line breaks when exporting.
407 Normally, in HTML output paragraphs will be reformatted.
409 This option can also be set with the #+OPTIONS line,
415 "Non-nil means interpret entities when exporting.
418 Å.
420 For a list of supported names, see the constant `org-entities'
421 and the user option `org-entities-user'.
423 This option can also be set with the #+OPTIONS line,
429 "Non-nil means include priority cookies in export.
431 When nil, remove priority cookies for export.
433 This option can also be set with the #+OPTIONS line,
439 "Non-nil means add section numbers to headlines when exporting.
441 When set to an integer n, numbering will only happen for
442 headlines whose relative level is higher or equal to n.
444 This option can also be set with the #+OPTIONS line,
450 "Tags that select a tree for export.
452 If any such tag is found in a buffer, all trees that do not carry
453 one of these tags will be ignored during export. Inside trees
454 that are selected like this, you can still deselect a subtree by
455 tagging it with one of the `org-export-exclude-tags'.
457 This option can also be set with the #+EXPORT_SELECT_TAGS:
458 keyword."
465 When this option is turned on, these strings will be exported as:
467 Org HTML LaTeX
468 -----+----------+--------
470 -- – --
471 --- — ---
472 ... … \ldots
474 This option can also be set with the #+OPTIONS line,
482 When this option is turned on, you can use TeX-like syntax for
484 will be considered as a single item - so grouping with {} is
485 normally not needed. For example, the following things will be
486 parsed as single sub- or superscripts.
488 10^24 or 10^tau several digits will be considered 1 item.
489 10^-12 or 10^-tau a leading sign with digits or a word
490 x^2-y^3 will be read as x^2 - y^3, because items are
491 terminated by almost any nonword/nondigit char.
492 x_{i^2} or x^(2-i) braces or parenthesis do grouping.
494 Still, ambiguity is possible - so when in doubt use {} to enclose
495 the sub/superscript. If you set this variable to the symbol
496 `{}', the braces are *required* in order to trigger
497 interpretations as sub/superscript. This can be helpful in
500 This option can also be set with the #+OPTIONS line,
509 "Non-nil means create a table of contents in exported files.
511 The TOC contains headlines with levels up
512 to`org-export-headline-levels'. When an integer, include levels
513 up to N in the toc, this may then be different from
514 `org-export-headline-levels', but it will not be allowed to be
515 larger than the number of headline levels. When nil, no table of
516 contents is made.
518 This option can also be set with the #+OPTIONS line,
528 For example:
530 | Name | Address | Birthday |
531 |-------------+----------+-----------|
532 | Arthur Dent | England | 29.2.2100 |
539 "If nil, do not export tags, just remove them from headlines.
541 If this is the symbol `not-in-toc', tags will be removed from
542 table of contents entries, but still be shown in the headlines of
543 the document.
545 This option can also be set with the #+OPTIONS line,
554 "Non-nil means include TODO items for export.
555 This may have the following values:
556 t include tasks independent of state.
557 todo include only tasks that are not yet done.
558 done include only tasks that are already done.
559 nil remove all tasks before export
560 list of keywords keep only tasks with these keywords"
571 "Non-nil means insert a time stamp into the exported file.
572 The time stamp shows when the file was created.
574 This option can also be set with the #+OPTIONS line,
580 "If nil, do not export time stamps and associated keywords."
585 "Non-nil means include TODO keywords in export.
589 "Non-nil means allow #+BIND to define local variable values for export.
590 This is a potential security risk, which is why the user must
591 confirm the use of these lines."
599 "Alist between export snippets back-ends and exporter back-ends.
601 This variable allows to provide shortcuts for export snippets.
605 while every other back-end will ignore it."
613 "Coding system for the exported file."
618 "Non-nil means exported stuff will also be pushed onto the kill ring."
623 "The initial scope when exporting with `org-export-dispatch'.
624 This variable can be either set to `buffer' or `subtree'."
631 "Non-nil means show buffer after exporting to temp buffer.
632 When Org exports to a file, the buffer visiting that file is ever
633 shown, but remains buried. However, when exporting to
634 a temporary buffer, that buffer is popped up in a second window.
635 When this variable is nil, the buffer remains buried also in
636 these cases."
641 "Non-nil means using a non-intrusive `org-export-dispatch'.
642 In that case, no help buffer is displayed. Though, an indicator
646 considered for export\). Also, \[?] allows to switch back to
647 standard mode."
652 \f
653 ;;; The Communication Channel
655 ;; During export process, every function has access to a number of
656 ;; properties. They are of three types:
658 ;; 1. Environment options are collected once at the very beginning of
659 ;; the process, out of the original buffer and configuration.
660 ;; Collecting them is handled by `org-export-get-environment'
661 ;; function.
662 ;;
663 ;; Most environment options are defined through the
664 ;; `org-export-option-alist' variable.
665 ;;
666 ;; 2. Tree properties are extracted directly from the parsed tree,
667 ;; just before export, by `org-export-collect-tree-properties'.
668 ;;
669 ;; 3. Local options are updated during parsing, and their value
670 ;; depends on the level of recursion. For now, only `:ignore-list'
671 ;; belongs to that category.
673 ;; Here is the full list of properties available during transcode
674 ;; process, with their category (option, tree or local) and their
675 ;; value type.
677 ;; + `:author' :: Author's name.
678 ;; - category :: option
679 ;; - type :: string
681 ;; + `:back-end' :: Current back-end used for transcoding.
682 ;; - category :: tree
683 ;; - type :: symbol
685 ;; + `:creator' :: String to write as creation information.
686 ;; - category :: option
687 ;; - type :: string
689 ;; + `:date' :: String to use as date.
690 ;; - category :: option
691 ;; - type :: string
693 ;; + `:description' :: Description text for the current data.
694 ;; - category :: option
695 ;; - type :: string
697 ;; + `:email' :: Author's email.
698 ;; - category :: option
699 ;; - type :: string
701 ;; + `:exclude-tags' :: Tags for exclusion of subtrees from export
702 ;; process.
703 ;; - category :: option
704 ;; - type :: list of strings
706 ;; + `:footnote-definition-alist' :: Alist between footnote labels and
707 ;; their definition, as parsed data. Only non-inlined footnotes
708 ;; are represented in this alist. Also, every definition isn't
709 ;; guaranteed to be referenced in the parse tree. The purpose of
710 ;; this property is to preserve definitions from oblivion
711 ;; (i.e. when the parse tree comes from a part of the original
712 ;; buffer), it isn't meant for direct use in a back-end. To
713 ;; retrieve a definition relative to a reference, use
714 ;; `org-export-get-footnote-definition' instead.
715 ;; - category :: option
716 ;; - type :: alist (STRING . LIST)
718 ;; + `:headline-levels' :: Maximum level being exported as an
719 ;; headline. Comparison is done with the relative level of
720 ;; headlines in the parse tree, not necessarily with their
721 ;; actual level.
722 ;; - category :: option
723 ;; - type :: integer
725 ;; + `:headline-offset' :: Difference between relative and real level
726 ;; of headlines in the parse tree. For example, a value of -1
727 ;; means a level 2 headline should be considered as level
728 ;; 1 (cf. `org-export-get-relative-level').
729 ;; - category :: tree
730 ;; - type :: integer
732 ;; + `:headline-numbering' :: Alist between headlines and their
733 ;; numbering, as a list of numbers
734 ;; (cf. `org-export-get-headline-number').
735 ;; - category :: tree
736 ;; - type :: alist (INTEGER . LIST)
738 ;; + `:ignore-list' :: List of elements and objects that should be
739 ;; ignored during export.
740 ;; - category :: local
741 ;; - type :: list of elements and objects
743 ;; + `:input-file' :: Full path to input file, if any.
744 ;; - category :: option
745 ;; - type :: string or nil
747 ;; + `:keywords' :: List of keywords attached to data.
748 ;; - category :: option
749 ;; - type :: string
751 ;; + `:language' :: Default language used for translations.
752 ;; - category :: option
753 ;; - type :: string
755 ;; + `:macro-input-file' :: Macro returning file name of input file,
756 ;; or nil.
757 ;; - category :: option
758 ;; - type :: string or nil
760 ;; + `:parse-tree' :: Whole parse tree, available at any time during
761 ;; transcoding.
762 ;; - category :: global
763 ;; - type :: list (as returned by `org-element-parse-buffer')
765 ;; + `:preserve-breaks' :: Non-nil means transcoding should preserve
766 ;; all line breaks.
767 ;; - category :: option
768 ;; - type :: symbol (nil, t)
770 ;; + `:section-numbers' :: Non-nil means transcoding should add
771 ;; section numbers to headlines.
772 ;; - category :: option
773 ;; - type :: symbol (nil, t)
775 ;; + `:select-tags' :: List of tags enforcing inclusion of sub-trees
776 ;; in transcoding. When such a tag is present,
777 ;; subtrees without it are de facto excluded from
778 ;; the process. See `use-select-tags'.
779 ;; - category :: option
780 ;; - type :: list of strings
782 ;; + `:target-list' :: List of targets encountered in the parse tree.
783 ;; This is used to partly resolve "fuzzy" links
784 ;; (cf. `org-export-resolve-fuzzy-link').
785 ;; - category :: tree
786 ;; - type :: list of strings
788 ;; + `:time-stamp-file' :: Non-nil means transcoding should insert
789 ;; a time stamp in the output.
790 ;; - category :: option
791 ;; - type :: symbol (nil, t)
793 ;; + `:with-archived-trees' :: Non-nil when archived subtrees should
794 ;; also be transcoded. If it is set to the `headline' symbol,
795 ;; only the archived headline's name is retained.
796 ;; - category :: option
797 ;; - type :: symbol (nil, t, `headline')
799 ;; + `:with-author' :: Non-nil means author's name should be included
800 ;; in the output.
801 ;; - category :: option
802 ;; - type :: symbol (nil, t)
804 ;; + `:with-creator' :: Non-nild means a creation sentence should be
805 ;; inserted at the end of the transcoded string. If the value
806 ;; is `comment', it should be commented.
807 ;; - category :: option
808 ;; - type :: symbol (`comment', nil, t)
810 ;; + `:with-drawers' :: Non-nil means drawers should be exported. If
811 ;; its value is a list of names, only drawers with such names
812 ;; will be transcoded.
813 ;; - category :: option
814 ;; - type :: symbol (nil, t) or list of strings
816 ;; + `:with-email' :: Non-nil means output should contain author's
817 ;; email.
818 ;; - category :: option
819 ;; - type :: symbol (nil, t)
821 ;; + `:with-emphasize' :: Non-nil means emphasized text should be
822 ;; interpreted.
823 ;; - category :: option
824 ;; - type :: symbol (nil, t)
826 ;; + `:with-fixed-width' :: Non-nil if transcoder should interpret
827 ;; strings starting with a colon as a fixed-with (verbatim) area.
828 ;; - category :: option
829 ;; - type :: symbol (nil, t)
831 ;; + `:with-footnotes' :: Non-nil if transcoder should interpret
832 ;; footnotes.
833 ;; - category :: option
834 ;; - type :: symbol (nil, t)
836 ;; + `:with-priority' :: Non-nil means transcoding should include
837 ;; priority cookies.
838 ;; - category :: option
839 ;; - type :: symbol (nil, t)
841 ;; + `:with-special-strings' :: Non-nil means transcoding should
842 ;; interpret special strings in plain text.
843 ;; - category :: option
844 ;; - type :: symbol (nil, t)
846 ;; + `:with-sub-superscript' :: Non-nil means transcoding should
847 ;; interpret subscript and superscript. With a value of "{}",
848 ;; only interpret those using curly brackets.
849 ;; - category :: option
850 ;; - type :: symbol (nil, {}, t)
852 ;; + `:with-tables' :: Non-nil means transcoding should interpret
853 ;; tables.
854 ;; - category :: option
855 ;; - type :: symbol (nil, t)
857 ;; + `:with-tags' :: Non-nil means transcoding should keep tags in
858 ;; headlines. A `not-in-toc' value will remove them
859 ;; from the table of contents, if any, nonetheless.
860 ;; - category :: option
861 ;; - type :: symbol (nil, t, `not-in-toc')
863 ;; + `:with-tasks' :: Non-nil means transcoding should include
864 ;; headlines with a TODO keyword. A `todo' value
865 ;; will only include headlines with a todo type
866 ;; keyword while a `done' value will do the
867 ;; contrary. If a list of strings is provided, only
868 ;; tasks with keywords belonging to that list will
869 ;; be kept.
870 ;; - category :: option
871 ;; - type :: symbol (t, todo, done, nil) or list of strings
873 ;; + `:with-timestamps' :: Non-nil means transcoding should include
874 ;; time stamps and associated keywords. Otherwise, completely
875 ;; remove them.
876 ;; - category :: option
877 ;; - type :: symbol: (t, nil)
879 ;; + `:with-toc' :: Non-nil means that a table of contents has to be
880 ;; added to the output. An integer value limits its
881 ;; depth.
882 ;; - category :: option
883 ;; - type :: symbol (nil, t or integer)
885 ;; + `:with-todo-keywords' :: Non-nil means transcoding should
886 ;; include TODO keywords.
887 ;; - category :: option
888 ;; - type :: symbol (nil, t)
891 ;;;; Environment Options
893 ;; Environment options encompass all parameters defined outside the
894 ;; scope of the parsed data. They come from five sources, in
895 ;; increasing precedence order:
896 ;;
897 ;; - Global variables,
898 ;; - Buffer's attributes,
899 ;; - Options keyword symbols,
900 ;; - Buffer keywords,
901 ;; - Subtree properties.
903 ;; The central internal function with regards to environment options
904 ;; is `org-export-get-environment'. It updates global variables with
905 ;; "#+BIND:" keywords, then retrieve and prioritize properties from
906 ;; the different sources.
908 ;; The internal functions doing the retrieval are:
909 ;; `org-export-get-global-options',
910 ;; `org-export-get-buffer-attributes',
911 ;; `org-export-parse-option-keyword',
912 ;; `org-export-get-subtree-options' and
913 ;; `org-export-get-inbuffer-options'
915 ;; Also, `org-export-confirm-letbind' and `org-export-install-letbind'
916 ;; take care of the part relative to "#+BIND:" keywords.
919 "Collect export options from the current buffer.
921 Optional argument BACKEND is a symbol specifying which back-end
922 specific options to read, if any.
924 When optional argument SUBTREEP is non-nil, assume the export is
925 done against the current sub-tree.
927 Third optional argument EXT-PLIST is a property list with
928 external parameters overriding Org default settings, but still
929 inferior to file-local settings."
930 ;; First install #+BIND variables.
932 ;; Get and prioritize export options...
934 ;; ... from global variables...
936 ;; ... from buffer's attributes...
938 ;; ... from an external property list...
939 ext-plist
940 ;; ... from in-buffer settings...
942 backend
945 ;; ... and from subtree, when appropriate.
947 ;; Also install back-end symbol.
949 ;; Return plist.
950 options))
953 "Parse an OPTIONS line and return values as a plist.
954 Optional argument BACKEND is a symbol specifying which back-end
955 specific items to read, if any."
962 ;; Build an alist between #+OPTION: item and property-name.
967 all)))
968 plist)
973 options)
978 alist)
979 plist))
982 "Get export options in subtree at point.
984 Assume point is at subtree's beginning.
986 Return options as a plist."
994 plist :title
996 prop
1006 plist))
1009 "Return current buffer export options, as a plist.
1011 Optional argument BACKEND, when non-nil, is a symbol specifying
1012 which back-end specific options should also be read in the
1013 process.
1015 Optional argument FILES is a list of setup files names read so
1016 far, used to avoid circular dependencies.
1018 Assume buffer is in Org mode. Narrowing, if any, is ignored."
1022 ;; 1. Special keywords, as in `org-export-special-keywords'.
1035 ;; Avoid circular dependencies.
1047 val)
1055 ;; Value will be evaled. Leave it as-is.
1058 ;; Value has to be parsed for nested
1059 ;; macros.
1062 key
1065 ;; If user explicitly asks for
1066 ;; a newline, be sure to preserve it
1067 ;; from further filling with
1068 ;; `hard-newline'. Also replace
1069 ;; "\\n" with "\n", "\\\n" with "\\n"
1070 ;; and so on...
1077 restr)))))))))))
1079 ;; 2. Standard options, as in `org-export-option-alist'.
1081 ;; Also look for back-end specific options
1082 ;; if BACKEND is defined.
1088 ;; Build alist between keyword name and property name.
1092 all)))
1093 ;; Build regexp matching all keywords associated to export
1094 ;; options. Note: the search is case insensitive.
1107 plist prop
1108 ;; Handle value depending on specified BEHAVIOUR.
1121 ;; Parse keywords specified in `org-element-parsed-keywords'.
1129 plist prop
1132 org-element-parsed-keywords))
1133 ;; 3. Return final value.
1134 plist)))
1137 "Return properties related to buffer attributes, as a plist."
1140 ;; Store full path of input file name, or nil. For internal use.
1141 :input-file visited-file
1146 :macro-modification-time
1152 ;; Store input file name as a macro.
1154 ;; `:macro-date', `:macro-time' and `:macro-property' could as
1155 ;; well be initialized as tree properties, since they don't
1156 ;; depend on buffer properties. Though, it may be more logical
1157 ;; to keep them close to other ":macro-" properties.
1163 "Return global export options as a plist.
1165 Optional argument BACKEND, if non-nil, is a symbol specifying
1166 which back-end specific export options should also be read in the
1167 process."
1173 ;; Output value.
1174 plist)
1177 all)
1178 ;; Return value.
1179 plist))
1182 "Collect and store footnote definitions from current buffer in INFO.
1184 INFO is a plist containing export options.
1186 Footnotes definitions are stored as a alist whose CAR is
1187 footnote's label, as a string, and CDR the contents, as a parse
1188 tree. This alist will be consed to the value of
1189 `:footnote-definition-alist' in INFO, if any.
1191 The new plist is returned; use
1193 \(setq info (org-export-store-footnote-definitions info))
1195 to be sure to use the new value. INFO is modified by side
1196 effects."
1197 ;; Footnotes definitions must be collected in the original buffer,
1198 ;; as there's no insurance that they will still be in the parse
1199 ;; tree, due to some narrowing.
1201 info :footnote-definition-alist
1212 ;; Like `org-element-parse-buffer', but
1213 ;; makes sure the definition doesn't start
1214 ;; with a section element.
1219 alist))))
1220 alist))))
1224 "Can we use #+BIND values during export?
1225 By default this will ask for confirmation by the user, to divert
1226 possible security risks."
1235 "Install the values from #+BIND lines as local variables.
1236 Variables must be installed before in-buffer options are
1237 retrieved."
1244 letbind))))
1249 ;;;; Tree Properties
1251 ;; Tree properties are infromation extracted from parse tree. They
1252 ;; are initialized at the beginning of the transcoding process by
1253 ;; `org-export-collect-tree-properties'.
1255 ;; Dedicated functions focus on computing the value of specific tree
1256 ;; properties during initialization. Thus,
1257 ;; `org-export-populate-ignore-list' lists elements and objects that
1258 ;; should be skipped during export, `org-export-get-min-level' gets
1259 ;; the minimal exportable level, used as a basis to compute relative
1260 ;; level for headlines. Eventually
1261 ;; `org-export-collect-headline-numbering' builds an alist between
1262 ;; headlines and their numbering.
1265 "Extract tree properties from parse tree.
1267 DATA is the parse tree from which information is retrieved. INFO
1268 is a list holding export options.
1270 Following tree properties are set or updated:
1271 `:footnote-definition-alist' List of footnotes definitions in
1272 original buffer and current parse tree.
1274 `:headline-offset' Offset between true level of headlines and
1275 local level. An offset of -1 means an headline
1276 of level 2 should be considered as a level
1277 1 headline in the context.
1279 `:headline-numbering' Alist of all headlines as key an the
1280 associated numbering as value.
1282 `:ignore-list' List of elements that should be ignored during
1283 export.
1285 `:target-list' List of all targets in the parse tree."
1286 ;; Install the parse tree in the communication channel, in order to
1287 ;; use `org-export-get-genealogy' and al.
1289 ;; Get the list of elements and objects to ignore, and put it into
1290 ;; `:ignore-list'. Do not overwrite any user ignore that might have
1291 ;; been done during parse tree filtering.
1294 :ignore-list
1297 ;; Compute `:headline-offset' in order to be able to use
1298 ;; `org-export-get-relative-level'.
1302 ;; Update footnotes definitions list with definitions in parse tree.
1303 ;; This is required since buffer expansion might have modified
1304 ;; boundaries of footnote definitions contained in the parse tree.
1305 ;; This way, definitions in `footnote-definition-alist' are bound to
1306 ;; match those in the parse tree.
1309 data 'footnote-definition
1313 defs)))
1315 ;; Properties order doesn't matter: get the rest of the tree
1316 ;; properties.
1318 `(:target-list
1326 info))
1329 "Return minimum exportable headline's level in DATA.
1330 DATA is parsed tree as returned by `org-element-parse-buffer'.
1331 OPTIONS is a plist holding export options."
1342 ;; If no headline was found, for the sake of consistency, set
1343 ;; minimum level to 1 nonetheless.
1347 "Return numbering of all exportable headlines in a parse tree.
1349 DATA is the parse tree. OPTIONS is the plist holding export
1350 options.
1352 Return an alist whose key is an headline and value is its
1353 associated numbering \(in the shape of a list of numbers\)."
1356 data
1357 'headline
1362 headline
1364 for idx from 0 to org-export-max-depth
1368 options)))
1371 "Return list of elements and objects to ignore during export.
1373 DATA is the parse tree to traverse. OPTIONS is the plist holding
1374 export options.
1376 Return elements or objects to ignore as a list."
1381 ;; Collect ignored elements or objects into IGNORE-LIST.
1389 ;; If headline is archived but tree below has
1390 ;; to be skipped, add it to ignore list.
1393 ;; Move into recursive objects/elements.
1397 ;; Main call. First find trees containing a select tag, if any.
1399 ;; Return value.
1400 ignore))
1403 "Return list of headlines containing a select tag in their tree.
1404 DATA is parsed data as returned by `org-element-parse-buffer'.
1405 INFO is a plist holding export options."
1419 ;; When a select tag is found, mark as acceptable
1420 ;; full genealogy and every headline within the
1421 ;; tree.
1426 selected-trees))
1427 ;; Else, continue searching in tree, recursively.
1432 "Non-nil when element or object BLOB should be skipped during export.
1433 OPTIONS is the plist holding export options."
1435 ;; Check headline.
1444 ;; Ignore subtrees with an exclude tag.
1447 ;; Ignore subtrees without a select tag, when such tag is
1448 ;; found in the buffer.
1450 ;; Ignore commented sub-trees.
1452 ;; Ignore archived subtrees if `:with-archived-trees' is nil.
1454 ;; Ignore tasks, if specified by `:with-tasks' property.
1460 ;; Check time-stamp.
1462 ;; Check drawer.
1468 ;; Check table-row.
1470 ;; Check table-cell.
1477 \f
1478 ;;; The Transcoder
1480 ;; This function reads Org data (obtained with, i.e.
1481 ;; `org-element-parse-buffer') and transcodes it into a specified
1482 ;; back-end output. It takes care of updating local properties,
1483 ;; filtering out elements or objects according to export options and
1484 ;; organizing the output blank lines and white space are preserved.
1486 ;; Though, this function is inapropriate for secondary strings, which
1487 ;; require a fresh copy of the plist passed as INFO argument. Thus,
1488 ;; `org-export-secondary-string' is provided for that specific task.
1490 ;; Internally, three functions handle the filtering of objects and
1491 ;; elements during the export. In particular,
1492 ;; `org-export-ignore-element' marks an element or object so future
1493 ;; parse tree traversals skip it, `org-export-interpret-p' tells which
1494 ;; elements or objects should be seen as real Org syntax and
1495 ;; `org-export-expand' transforms the others back into their original
1496 ;; shape.
1499 "Convert DATA into current back-end format.
1501 DATA is a nested list as returned by `org-element-parse-buffer'.
1503 INFO is a plist holding export options and also used as
1504 a communication channel between elements when walking the nested
1505 list.
1507 Return transcoded string."
1509 ;; BLOB can be an element, an object, a string, or nil.
1513 ;; BLOB is a string. Check if the optional transcoder for plain
1514 ;; text exists, and call it in that case. Otherwise, simply
1515 ;; return string. Also update INFO and call
1516 ;; `org-export-filter-plain-text-functions'.
1523 info)))
1524 ;; BLOB is an element or an object.
1527 ;; 1. Determine the appropriate TRANSCODER.
1530 ;; 1.0 A full Org document is inserted.
1532 ;; 1.1. BLOB should be ignored.
1534 ;; 1.2. BLOB shouldn't be transcoded. Interpret it
1535 ;; back into Org syntax.
1537 ;; 1.3. Else apply naming convention.
1540 type))))
1542 ;; 2. Compute CONTENTS of BLOB.
1545 ;; Case 0. No transcoder or no contents: ignore BLOB.
1547 ;; Case 1. Transparently export an Org document.
1549 ;; Case 2. For a greater element.
1551 ;; Ignore contents of an archived tree
1552 ;; when `:with-archived-trees' is `headline'.
1558 ;; Case 3. For an element containing objects.
1562 blob
1563 ;; When normalizing contents of the first paragraph
1564 ;; in an item or a footnote definition, ignore
1565 ;; first line's indentation: there is none and it
1566 ;; might be misleading.
1572 info))))
1573 ;; 3. Transcode BLOB into RESULTS string.
1579 info))
1581 ;; 4. Return results.
1584 ;; No filter for a full document.
1586 ;; Otherwise, update INFO, append the same white space
1587 ;; between elements or objects as in the original buffer,
1588 ;; and call appropriate filters.
1598 info)))
1599 ;; Eventually return string.
1600 results)))))))
1604 "Convert SECONDARY string into current back-end target format.
1606 SECONDARY is a nested list as returned by
1607 `org-element-parse-secondary-string'. INFO is a plist used as
1608 a communication channel.
1610 Return transcoded string."
1611 ;; Make SECONDARY acceptable for `org-export-data'.
1616 "Non-nil if element or object BLOB should be interpreted as Org syntax.
1617 Check is done according to export options INFO, stored as
1618 a plist."
1620 ;; ... entities...
1622 ;; ... emphasis...
1624 ;; ... fixed-width areas.
1626 ;; ... footnotes...
1629 ;; ... sub/superscripts...
1635 ;; ... tables...
1640 "Expand a parsed element or object to its original state.
1641 BLOB is either an element or an object. CONTENTS is its
1642 contents, as a string or nil."
1644 blob contents))
1647 "Add ELEMENT to `:ignore-list' in INFO.
1649 Any element in `:ignore-list' will be skipped when using
1650 `org-element-map'. INFO is modified by side effects."
1654 \f
1655 ;;; The Filter System
1657 ;; Filters allow end-users to tweak easily the transcoded output.
1658 ;; They are the functional counterpart of hooks, as every filter in
1659 ;; a set is applied to the return value of the previous one.
1660 ;;
1661 ;; Every set is back-end agnostic. Although, a filter is always
1662 ;; called, in addition to the string it applies to, with the back-end
1663 ;; used as argument, so it's easy enough for the end-user to add
1664 ;; back-end specific filters in the set. The communication channel,
1665 ;; as a plist, is required as the third argument.
1666 ;;
1667 ;; Filters sets are defined below. There are of four types:
1668 ;;
1669 ;; - `org-export-filter-parse-tree-functions' applies directly on the
1670 ;; complete parsed tree. It's the only filters set that doesn't
1671 ;; apply to a string.
1672 ;; - `org-export-filter-final-output-functions' applies to the final
1673 ;; transcoded string.
1674 ;; - `org-export-filter-plain-text-functions' applies to any string
1675 ;; not recognized as Org syntax.
1676 ;; - `org-export-filter-TYPE-functions' applies on the string returned
1677 ;; after an element or object of type TYPE has been transcoded.
1678 ;;
1679 ;; All filters sets are applied through
1680 ;; `org-export-filter-apply-functions' function. Filters in a set are
1681 ;; applied in a LIFO fashion. It allows developers to be sure that
1682 ;; their filters will be applied first.
1683 ;;
1684 ;; Filters properties are installed in communication channel with
1685 ;; `org-export-install-filters' function.
1686 ;;
1687 ;; Eventually, a hook (`org-export-before-parsing-hook') is run just
1688 ;; before parsing to allow for heavy structure modifications.
1691 ;;;; Before Parsing Hook
1694 "Hook run before parsing an export buffer.
1695 This is run after include keywords have been expanded and Babel
1696 code executed, on a copy of original buffer's area being
1697 exported. Visibility is the same as in the original one. Point
1700 ;;;; Special Filters
1703 "List of functions applied to the parsed tree.
1704 Each filter is called with three arguments: the parse tree, as
1705 returned by `org-element-parse-buffer', the back-end, as
1706 a symbol, and the communication channel, as a plist. It must
1710 "List of functions applied to the transcoded string.
1711 Each filter is called with three arguments: the full transcoded
1712 string, the back-end, as a symbol, and the communication channel,
1713 as a plist. It must return a string that will be used as the
1717 "List of functions applied to plain text.
1718 Each filter is called with three arguments: a string which
1719 contains no Org syntax, the back-end, as a symbol, and the
1720 communication channel, as a plist. It must return a string or
1724 ;;;; Elements Filters
1727 "List of functions applied to a transcoded center block.
1728 Each filter is called with three arguments: the transcoded center
1729 block, as a string, the back-end, as a symbol, and the
1730 communication channel, as a plist. It must return a string or
1734 "List of functions applied to a transcoded drawer.
1735 Each filter is called with three arguments: the transcoded
1736 drawer, as a string, the back-end, as a symbol, and the
1737 communication channel, as a plist. It must return a string or
1741 "List of functions applied to a transcoded dynamic-block.
1742 Each filter is called with three arguments: the transcoded
1743 dynamic-block, as a string, the back-end, as a symbol, and the
1744 communication channel, as a plist. It must return a string or
1748 "List of functions applied to a transcoded headline.
1749 Each filter is called with three arguments: the transcoded
1750 headline, as a string, the back-end, as a symbol, and the
1751 communication channel, as a plist. It must return a string or
1755 "List of functions applied to a transcoded inlinetask.
1756 Each filter is called with three arguments: the transcoded
1757 inlinetask, as a string, the back-end, as a symbol, and the
1758 communication channel, as a plist. It must return a string or
1762 "List of functions applied to a transcoded plain-list.
1763 Each filter is called with three arguments: the transcoded
1764 plain-list, as a string, the back-end, as a symbol, and the
1765 communication channel, as a plist. It must return a string or
1769 "List of functions applied to a transcoded item.
1770 Each filter is called with three arguments: the transcoded item,
1771 as a string, the back-end, as a symbol, and the communication
1775 "List of functions applied to a transcoded comment.
1776 Each filter is called with three arguments: the transcoded
1777 comment, as a string, the back-end, as a symbol, and the
1778 communication channel, as a plist. It must return a string or
1782 "List of functions applied to a transcoded comment-comment.
1783 Each filter is called with three arguments: the transcoded
1784 comment-block, as a string, the back-end, as a symbol, and the
1785 communication channel, as a plist. It must return a string or
1789 "List of functions applied to a transcoded example-block.
1790 Each filter is called with three arguments: the transcoded
1791 example-block, as a string, the back-end, as a symbol, and the
1792 communication channel, as a plist. It must return a string or
1796 "List of functions applied to a transcoded export-block.
1797 Each filter is called with three arguments: the transcoded
1798 export-block, as a string, the back-end, as a symbol, and the
1799 communication channel, as a plist. It must return a string or
1803 "List of functions applied to a transcoded fixed-width.
1804 Each filter is called with three arguments: the transcoded
1805 fixed-width, as a string, the back-end, as a symbol, and the
1806 communication channel, as a plist. It must return a string or
1810 "List of functions applied to a transcoded footnote-definition.
1811 Each filter is called with three arguments: the transcoded
1812 footnote-definition, as a string, the back-end, as a symbol, and
1813 the communication channel, as a plist. It must return a string
1817 "List of functions applied to a transcoded horizontal-rule.
1818 Each filter is called with three arguments: the transcoded
1819 horizontal-rule, as a string, the back-end, as a symbol, and the
1820 communication channel, as a plist. It must return a string or
1824 "List of functions applied to a transcoded keyword.
1825 Each filter is called with three arguments: the transcoded
1826 keyword, as a string, the back-end, as a symbol, and the
1827 communication channel, as a plist. It must return a string or
1831 "List of functions applied to a transcoded latex-environment.
1832 Each filter is called with three arguments: the transcoded
1833 latex-environment, as a string, the back-end, as a symbol, and
1834 the communication channel, as a plist. It must return a string
1838 "List of functions applied to a transcoded babel-call.
1839 Each filter is called with three arguments: the transcoded
1840 babel-call, as a string, the back-end, as a symbol, and the
1841 communication channel, as a plist. It must return a string or
1845 "List of functions applied to a transcoded paragraph.
1846 Each filter is called with three arguments: the transcoded
1847 paragraph, as a string, the back-end, as a symbol, and the
1848 communication channel, as a plist. It must return a string or
1852 "List of functions applied to a transcoded property-drawer.
1853 Each filter is called with three arguments: the transcoded
1854 property-drawer, as a string, the back-end, as a symbol, and the
1855 communication channel, as a plist. It must return a string or
1859 "List of functions applied to a transcoded quote block.
1860 Each filter is called with three arguments: the transcoded quote
1861 block, as a string, the back-end, as a symbol, and the
1862 communication channel, as a plist. It must return a string or
1866 "List of functions applied to a transcoded quote-section.
1867 Each filter is called with three arguments: the transcoded
1868 quote-section, as a string, the back-end, as a symbol, and the
1869 communication channel, as a plist. It must return a string or
1873 "List of functions applied to a transcoded section.
1874 Each filter is called with three arguments: the transcoded
1875 section, as a string, the back-end, as a symbol, and the
1876 communication channel, as a plist. It must return a string or
1880 "List of functions applied to a transcoded special block.
1881 Each filter is called with three arguments: the transcoded
1882 special block, as a string, the back-end, as a symbol, and the
1883 communication channel, as a plist. It must return a string or
1887 "List of functions applied to a transcoded src-block.
1888 Each filter is called with three arguments: the transcoded
1889 src-block, as a string, the back-end, as a symbol, and the
1890 communication channel, as a plist. It must return a string or
1894 "List of functions applied to a transcoded table.
1895 Each filter is called with three arguments: the transcoded table,
1896 as a string, the back-end, as a symbol, and the communication
1900 "List of functions applied to a transcoded table-cell.
1901 Each filter is called with three arguments: the transcoded
1902 table-cell, as a string, the back-end, as a symbol, and the
1903 communication channel, as a plist. It must return a string or
1907 "List of functions applied to a transcoded table-row.
1908 Each filter is called with three arguments: the transcoded
1909 table-row, as a string, the back-end, as a symbol, and the
1910 communication channel, as a plist. It must return a string or
1914 "List of functions applied to a transcoded verse block.
1915 Each filter is called with three arguments: the transcoded verse
1916 block, as a string, the back-end, as a symbol, and the
1917 communication channel, as a plist. It must return a string or
1921 ;;;; Objects Filters
1924 "List of functions applied to a transcoded emphasis.
1925 Each filter is called with three arguments: the transcoded
1926 emphasis, as a string, the back-end, as a symbol, and the
1927 communication channel, as a plist. It must return a string or
1931 "List of functions applied to a transcoded entity.
1932 Each filter is called with three arguments: the transcoded
1933 entity, as a string, the back-end, as a symbol, and the
1934 communication channel, as a plist. It must return a string or
1938 "List of functions applied to a transcoded export-snippet.
1939 Each filter is called with three arguments: the transcoded
1940 export-snippet, as a string, the back-end, as a symbol, and the
1941 communication channel, as a plist. It must return a string or
1945 "List of functions applied to a transcoded footnote-reference.
1946 Each filter is called with three arguments: the transcoded
1947 footnote-reference, as a string, the back-end, as a symbol, and
1948 the communication channel, as a plist. It must return a string
1952 "List of functions applied to a transcoded inline-babel-call.
1953 Each filter is called with three arguments: the transcoded
1954 inline-babel-call, as a string, the back-end, as a symbol, and
1955 the communication channel, as a plist. It must return a string
1959 "List of functions applied to a transcoded inline-src-block.
1960 Each filter is called with three arguments: the transcoded
1961 inline-src-block, as a string, the back-end, as a symbol, and the
1962 communication channel, as a plist. It must return a string or
1966 "List of functions applied to a transcoded latex-fragment.
1967 Each filter is called with three arguments: the transcoded
1968 latex-fragment, as a string, the back-end, as a symbol, and the
1969 communication channel, as a plist. It must return a string or
1973 "List of functions applied to a transcoded line-break.
1974 Each filter is called with three arguments: the transcoded
1975 line-break, as a string, the back-end, as a symbol, and the
1976 communication channel, as a plist. It must return a string or
1980 "List of functions applied to a transcoded link.
1981 Each filter is called with three arguments: the transcoded link,
1982 as a string, the back-end, as a symbol, and the communication
1986 "List of functions applied to a transcoded macro.
1987 Each filter is called with three arguments: the transcoded macro,
1988 as a string, the back-end, as a symbol, and the communication
1992 "List of functions applied to a transcoded radio-target.
1993 Each filter is called with three arguments: the transcoded
1994 radio-target, as a string, the back-end, as a symbol, and the
1995 communication channel, as a plist. It must return a string or
1999 "List of functions applied to a transcoded statistics-cookie.
2000 Each filter is called with three arguments: the transcoded
2001 statistics-cookie, as a string, the back-end, as a symbol, and
2002 the communication channel, as a plist. It must return a string
2006 "List of functions applied to a transcoded subscript.
2007 Each filter is called with three arguments: the transcoded
2008 subscript, as a string, the back-end, as a symbol, and the
2009 communication channel, as a plist. It must return a string or
2013 "List of functions applied to a transcoded superscript.
2014 Each filter is called with three arguments: the transcoded
2015 superscript, as a string, the back-end, as a symbol, and the
2016 communication channel, as a plist. It must return a string or
2020 "List of functions applied to a transcoded target.
2021 Each filter is called with three arguments: the transcoded
2022 target, as a string, the back-end, as a symbol, and the
2023 communication channel, as a plist. It must return a string or
2027 "List of functions applied to a transcoded time-stamp.
2028 Each filter is called with three arguments: the transcoded
2029 time-stamp, as a string, the back-end, as a symbol, and the
2030 communication channel, as a plist. It must return a string or
2034 "List of functions applied to a transcoded verbatim.
2035 Each filter is called with three arguments: the transcoded
2036 verbatim, as a string, the back-end, as a symbol, and the
2037 communication channel, as a plist. It must return a string or
2041 "Call every function in FILTERS.
2042 Functions are called with arguments VALUE, current export
2043 back-end and INFO. Call is done in a LIFO fashion, to be sure
2044 that developer specified filters, if any, are called first."
2048 value)
2051 "Install filters properties in communication channel.
2053 INFO is a plist containing the current communication channel.
2055 Return the updated communication channel."
2057 ;; Install user defined filters with `org-export-filters-alist'.
2060 org-export-filters-alist)
2061 ;; Prepend back-end specific filters to that list.
2066 ;; Single values get consed, lists are prepended.
2071 plist key
2075 ;; Return new communication channel.
2079 \f
2080 ;;; Core functions
2082 ;; This is the room for the main function, `org-export-as', along with
2083 ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
2084 ;; They differ only by the way they output the resulting code.
2086 ;; `org-export-output-file-name' is an auxiliary function meant to be
2087 ;; used with `org-export-to-file'. With a given extension, it tries
2088 ;; to provide a canonical file name to write export output to.
2090 ;; Note that `org-export-as' doesn't really parse the current buffer,
2091 ;; but a copy of it (with the same buffer-local variables and
2092 ;; visibility), where include keywords are expanded and Babel blocks
2093 ;; are executed, if appropriate.
2094 ;; `org-export-with-current-buffer-copy' macro prepares that copy.
2096 ;; File inclusion is taken care of by
2097 ;; `org-export-expand-include-keyword' and
2098 ;; `org-export-prepare-file-contents'. Structure wise, including
2099 ;; a whole Org file in a buffer often makes little sense. For
2100 ;; example, if the file contains an headline and the include keyword
2101 ;; was within an item, the item should contain the headline. That's
2102 ;; why file inclusion should be done before any structure can be
2103 ;; associated to the file, that is before parsing.
2107 "Transcode current Org buffer into BACKEND code.
2109 If narrowing is active in the current buffer, only transcode its
2110 narrowed part.
2112 If a region is active, transcode that region.
2114 When optional argument SUBTREEP is non-nil, transcode the
2115 sub-tree at point, extracting information from the headline
2116 properties first.
2118 When optional argument VISIBLE-ONLY is non-nil, don't export
2119 contents of hidden elements.
2121 When optional argument BODY-ONLY is non-nil, only return body
2122 code, without preamble nor postamble.
2124 Optional argument EXT-PLIST, when provided, is a property list
2125 with external parameters overriding Org default settings, but
2126 still inferior to file-local settings.
2128 Optional argument NOEXPAND, when non-nil, prevents included files
2129 to be expanded and Babel code to be executed.
2131 Return code as a string."
2134 ;; Narrow buffer to an appropriate region or subtree for
2135 ;; parsing. If parsing subtree, be sure to remove main headline
2136 ;; too.
2144 ;; 1. Get export environment from original buffer. Store
2145 ;; original footnotes definitions in communication channel as
2146 ;; they might not be accessible anymore in a narrowed parse
2147 ;; tree. Also install user's and developer's filters.
2151 ;; 2. Get parse tree. Buffer isn't parsed directly.
2152 ;; Instead, a temporary copy is created, where include
2153 ;; keywords are expanded and code blocks are evaluated.
2159 ;; Setting `org-current-export-file' is
2160 ;; required by Org Babel to properly resolve
2161 ;; noweb references.
2167 ;; 3. Call parse-tree filters to get the final tree.
2171 ;; 4. Now tree is complete, compute its properties and add
2172 ;; them to communication channel.
2176 ;; 5. Eventually transcode TREE. Wrap the resulting string
2177 ;; into a template, if required. Eventually call
2178 ;; final-output filter.
2185 info)))
2186 ;; Maybe add final OUTPUT to kill ring, then return it.
2188 output)))))
2192 "Call `org-export-as' with output to a specified buffer.
2194 BACKEND is the back-end used for transcoding, as a symbol.
2196 BUFFER is the output buffer. If it already exists, it will be
2197 erased first, otherwise, it will be created.
2199 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2200 and NOEXPAND are similar to those used in `org-export-as', which
2201 see.
2203 Return buffer."
2205 backend subtreep visible-only body-only ext-plist noexpand))
2211 buffer))
2215 "Call `org-export-as' with output to a specified file.
2217 BACKEND is the back-end used for transcoding, as a symbol. FILE
2218 is the name of the output file, as a string.
2220 Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST
2221 and NOEXPAND are similar to those used in `org-export-as', which
2222 see.
2224 Return output file's name."
2225 ;; Checks for FILE permissions. `write-file' would do the same, but
2226 ;; we'd rather avoid needless transcoding of parse tree.
2228 ;; Insert contents to a temporary buffer and write it to FILE.
2230 backend subtreep visible-only body-only ext-plist noexpand)))
2235 ;; Return full path.
2236 file)
2239 "Return output file's name according to buffer specifications.
2241 EXTENSION is a string representing the output file extension,
2242 with the leading dot.
2244 With a non-nil optional argument SUBTREEP, try to determine
2246 of subtree at point.
2248 When optional argument PUB-DIR is set, use it as the publishing
2249 directory.
2251 Return file name as a string, or nil if it couldn't be
2252 determined."
2254 ;; File name may come from EXPORT_FILE_NAME subtree property,
2255 ;; assuming point is at beginning of said sub-tree.
2263 ;; File name may be extracted from buffer's associated
2264 ;; file, if any.
2266 ;; Can't determine file name on our own: Ask user.
2270 "Output file: " pub-dir nil nil nil
2273 ;; Build file name. Enforce EXTENSION over whatever user may have
2274 ;; come up with. PUB-DIR, if defined, always has precedence over
2275 ;; any provided path.
2280 extension))
2286 "Apply BODY in a copy of the current buffer.
2288 The copy preserves local variables and visibility of the original
2289 buffer.
2291 Point is at buffer's beginning when BODY is applied."
2301 ,original-buffer
2306 ov
2316 "Expand every include keyword in buffer.
2317 Optional argument INCLUDED is a list of included file names along
2318 with their line restriction, when appropriate. It is used to
2319 avoid infinite recursion. Optional argument DIR is the current
2320 working directory. It is used to properly resolve relative
2321 paths."
2328 ;; Extract arguments from keyword's value.
2342 ;; Minimal level of included file defaults to the child
2343 ;; level of the current headline, if any, or one. It
2344 ;; only applies is the file is meant to be included as
2345 ;; an Org one.
2353 ;; Remove keyword.
2357 ;; Check if files has already been parsed. Look after
2358 ;; inclusion lines too, as different parts of the same file
2359 ;; can be included too.
2368 ;; Protect sensitive contents with commas.
2374 ind-str contents ind-str))))
2379 ;; Protect sensitive contents with commas.
2386 ind-str env contents ind-str))))
2399 "Prepare the contents of FILE for inclusion and return them as a string.
2401 When optional argument LINES is a string specifying a range of
2402 lines, include only those lines.
2404 Optional argument IND, when non-nil, is an integer specifying the
2405 global indentation of returned contents. Since its purpose is to
2406 allow an included file to stay in the same environment it was
2407 created \(i.e. a list item), it doesn't apply past the first
2408 headline encountered.
2410 Optional argument MINLEVEL, when non-nil, is an integer
2411 specifying the level that any top-level headline in the included
2412 file should have."
2428 ;; Remove blank lines at beginning and end of contents. The logic
2429 ;; behind that removal is that blank lines around include keyword
2430 ;; override blank lines in included file.
2439 ;; If IND is set, preserve indentation of include keyword until
2440 ;; the first headline encountered.
2446 ;; Do not move footnote definitions out of column 0.
2452 ;; When MINLEVEL is specified, compute minimal level for headlines
2453 ;; in the file (CUR-MIN), and remove stars to each headline so
2454 ;; that headlines with minimal level have a level of MINLEVEL.
2463 ;; Only change stars, don't bother moving whole
2464 ;; sections.
2470 \f
2471 ;;; Tools For Back-Ends
2473 ;; A whole set of tools is available to help build new exporters. Any
2474 ;; function general enough to have its use across many back-ends
2475 ;; should be added here.
2477 ;; As of now, functions operating on footnotes, headlines, links,
2478 ;; macros, references, src-blocks, tables and tables of contents are
2479 ;; implemented.
2481 ;;;; For Export Snippets
2483 ;; Every export snippet is transmitted to the back-end. Though, the
2484 ;; latter will only retain one type of export-snippet, ignoring
2485 ;; others, based on the former's target back-end. The function
2486 ;; `org-export-snippet-backend' returns that back-end for a given
2487 ;; export-snippet.
2490 "Return EXPORT-SNIPPET targeted back-end as a symbol.
2491 Translation, with `org-export-snippet-translation-alist', is
2492 applied."
2496 back-end))))
2499 ;;;; For Footnotes
2501 ;; `org-export-collect-footnote-definitions' is a tool to list
2502 ;; actually used footnotes definitions in the whole parse tree, or in
2503 ;; an headline, in order to add footnote listings throughout the
2504 ;; transcoded data.
2506 ;; `org-export-footnote-first-reference-p' is a predicate used by some
2507 ;; back-ends, when they need to attach the footnote definition only to
2508 ;; the first occurrence of the corresponding label.
2510 ;; `org-export-get-footnote-definition' and
2511 ;; `org-export-get-footnote-number' provide easier access to
2512 ;; additional information relative to a footnote reference.
2515 "Return an alist between footnote numbers, labels and definitions.
2517 DATA is the parse tree from which definitions are collected.
2518 INFO is the plist used as a communication channel.
2520 Definitions are sorted by order of references. They either
2521 appear as Org data (transcoded with `org-export-data') or as
2522 a secondary string for inlined footnotes (transcoded with
2523 `org-export-secondary-string'). Unreferenced definitions are
2524 ignored."
2529 ;; Collect footnote number, label and definition in DATA.
2531 data 'footnote-reference
2538 def)
2539 num-alist)
2540 ;; Also search in definition for nested footnotes.
2543 ;; Don't enter footnote definitions since it will happen
2544 ;; when their first reference is found.
2550 "Non-nil when a footnote reference is the first one for its label.
2552 FOOTNOTE-REFERENCE is the footnote reference being considered.
2553 INFO is the plist used as a communication channel."
2555 ;; Anonymous footnotes are always a first reference.
2557 ;; Otherwise, return the first footnote with the same LABEL and
2558 ;; test if it is equal to FOOTNOTE-REFERENCE.
2563 data 'footnote-reference
2568 ;; If FN isn't inlined, be sure to traverse its
2569 ;; definition before resuming search. See
2570 ;; comments in `org-export-get-footnote-number'
2571 ;; for more information.
2575 ;; Don't enter footnote definitions since it will
2576 ;; happen when their first reference is found.
2579 footnote-reference)))))
2582 "Return definition of FOOTNOTE-REFERENCE as parsed data.
2583 INFO is the plist used as a communication channel."
2589 "Return number associated to a footnote.
2591 FOOTNOTE is either a footnote reference or a footnote definition.
2592 INFO is the plist used as a communication channel."
2594 seen-refs
2598 ;; Search footnote references through DATA, filling
2599 ;; SEEN-REFS along the way.
2601 data 'footnote-reference
2605 ;; Anonymous footnote match: return number.
2608 ;; Labels match: return number.
2611 ;; Anonymous footnote: it's always a new one. Also,
2612 ;; be sure to return nil from the `cond' so
2613 ;; `first-match' doesn't get us out of the loop.
2615 ;; Label not seen so far: add it so SEEN-REFS.
2616 ;;
2617 ;; Also search for subsequent references in footnote
2618 ;; definition so numbering following reading logic.
2619 ;; Note that we don't have to care about inline
2620 ;; definitions, since `org-element-map' already
2621 ;; traverse them at the right time.
2622 ;;
2623 ;; Once again, return nil to stay in the loop.
2628 nil))))
2629 ;; Don't enter footnote definitions since it will happen
2630 ;; when their first reference is found.
2635 ;;;; For Headlines
2637 ;; `org-export-get-relative-level' is a shortcut to get headline
2638 ;; level, relatively to the lower headline level in the parsed tree.
2640 ;; `org-export-get-headline-number' returns the section number of an
2641 ;; headline, while `org-export-number-to-roman' allows to convert it
2642 ;; to roman numbers.
2644 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
2645 ;; `org-export-last-sibling-p' are three useful predicates when it
2646 ;; comes to fulfill the `:headline-levels' property.
2649 "Return HEADLINE relative level within current parsed tree.
2650 INFO is a plist holding contextual information."
2655 "Non-nil when HEADLINE is considered as low level.
2657 INFO is a plist used as a communication channel.
2659 A low level headlines has a relative level greater than
2660 `:headline-levels' property value.
2662 Return value is the difference between HEADLINE relative level
2663 and the last level being considered as high enough, or nil."
2670 "Return HEADLINE numbering as a list of numbers.
2671 INFO is a plist holding contextual information."
2675 "Return a non-nil value if HEADLINE element should be numbered.
2676 INFO is a plist used as a communication channel."
2682 "Convert integer N into a roman numeral."
2695 res)))
2698 "Non-nil when HEADLINE is the first sibling in its sub-tree.
2699 INFO is the plist used as a communication channel."
2704 "Non-nil when HEADLINE is the last sibling in its sub-tree.
2705 INFO is the plist used as a communication channel."
2709 ;;;; For Links
2711 ;; `org-export-solidify-link-text' turns a string into a safer version
2712 ;; for links, replacing most non-standard characters with hyphens.
2714 ;; `org-export-get-coderef-format' returns an appropriate format
2715 ;; string for coderefs.
2717 ;; `org-export-inline-image-p' returns a non-nil value when the link
2718 ;; provided should be considered as an inline image.
2720 ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
2721 ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
2722 ;; returns an appropriate unique identifier when found, or nil.
2724 ;; `org-export-resolve-id-link' returns the first headline with
2725 ;; specified id or custom-id in parse tree, or nil when none was
2726 ;; found.
2728 ;; `org-export-resolve-coderef' associates a reference to a line
2729 ;; number in the element it belongs, or returns the reference itself
2730 ;; when the element isn't numbered.
2733 "Take link text S and make a safe target out of it."
2738 "Return format string for code reference link.
2739 PATH is the link path. DESC is its description."
2747 "Non-nil if LINK object points to an inline image.
2749 Optional argument is a set of RULES defining inline images. It
2750 is an alist where associations have the following shape:
2752 \(TYPE . REGEXP)
2754 Applying a rule means apply REGEXP against LINK's path when its
2755 type is TYPE. The function will return a non-nil value if any of
2756 the provided rules is non-nil. The default rule is
2757 `org-export-default-inline-image-rule'.
2759 This only applies to links without a description."
2768 rules))))
2771 "Return LINK destination.
2773 INFO is a plist holding contextual information.
2775 Return value can be an object, an element, or nil:
2777 - If LINK path matches a target object (i.e. <<path>>) or
2780 - If LINK path exactly matches the name affiliated keyword
2781 \(i.e. #+NAME: path) of an element, return that element.
2783 - If LINK path exactly matches any headline name, return that
2784 element. If more than one headline share that name, priority
2785 will be given to the one with the closest common ancestor, if
2786 any, or the first one in the parse tree otherwise.
2788 - Otherwise, return nil.
2793 ;; First try to find a matching "<<path>>" unless user specified
2794 ;; he was looking for an headline (path starts with a *
2795 ;; character).
2799 return target)))
2800 ;; Then try to find an element with a matching "#+NAME: path"
2801 ;; affiliated keyword.
2808 ;; Last case: link either points to an headline or to
2809 ;; nothingness. Try to find the source, with priority given to
2810 ;; headlines with the closest common ancestor. If such candidate
2811 ;; is found, return its beginning position as an unique
2812 ;; identifier, otherwise return nil.
2816 ;; Return first headline whose `:raw-value' property
2817 ;; is NAME in parse tree DATA, or nil.
2820 data 'headline
2824 name)
2825 headline))
2827 ;; Search among headlines sharing an ancestor with link,
2828 ;; from closest to farthest.
2836 ;; No match with a common ancestor: try the full parse-tree.
2840 "Return headline referenced as LINK destination.
2842 INFO is a plist used as a communication channel.
2844 Return value can be an headline element or nil. Assume LINK type
2852 headline))
2856 "Resolve a code reference REF.
2858 INFO is a plist used as a communication channel.
2860 Return associated line number in source code, or REF itself,
2861 depending on src-block or example element's switches."
2869 org-coderef-label-format)))
2873 ;; Element containing REF is found. Resolve it to either
2874 ;; a label or a line number, as needed.
2884 ;;;; For Macros
2886 ;; `org-export-expand-macro' simply takes care of expanding macros.
2889 "Expand MACRO and return it as a string.
2890 INFO is a plist holding export options."
2893 ;; User's macros are stored in the communication channel with
2894 ;; a ":macro-" prefix. If it's a string leave it as-is.
2895 ;; Otherwise, it's a secondary string that needs to be
2896 ;; expanded recursively.
2900 ;; Replace arguments in VALUE.
2907 ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
2910 ;; Return string.
2914 ;;;; For References
2916 ;; `org-export-get-ordinal' associates a sequence number to any object
2917 ;; or element.
2920 "Return ordinal number of an element or object.
2922 ELEMENT is the element or object considered. INFO is the plist
2923 used as a communication channel.
2925 Optional argument TYPES, when non-nil, is a list of element or
2926 object types, as symbols, that should also be counted in.
2927 Otherwise, only provided element's type is considered.
2929 Optional argument PREDICATE is a function returning a non-nil
2930 value if the current element or object should be counted in. It
2931 accepts two arguments: the element or object being considered and
2932 the plist used as a communication channel. This allows to count
2933 only a certain type of objects (i.e. inline images).
2935 Return value is a list of numbers if ELEMENT is an headline or an
2936 item. It is nil for keywords. It represents the footnote number
2937 for footnote definitions and footnote references. If ELEMENT is
2938 a target, return the same value as if ELEMENT was the closest
2939 table, item or headline containing the target. In any other
2940 case, return the sequence number of ELEMENT among elements or
2941 objects of the same type."
2942 ;; A target keyword, representing an invisible target, never has
2943 ;; a sequence number.
2945 ;; Ordinal of a target object refer to the ordinal of the closest
2946 ;; table, item, or headline containing the object.
2950 when
2954 table))
2955 return parent)))
2957 ;; Special case 1: An headline returns its number as a list.
2959 ;; Special case 2: An item returns its number as a list.
2963 struct
2970 ;; Increment counter until ELEMENT is found again.
2981 ;;;; For Src-Blocks
2983 ;; `org-export-get-loc' counts number of code lines accumulated in
2984 ;; src-block or example-block elements with a "+n" switch until
2985 ;; a given element, excluded. Note: "-n" switches reset that count.
2987 ;; `org-export-unravel-code' extracts source code (along with a code
2988 ;; references alist) from an `element-block' or `src-block' type
2989 ;; element.
2991 ;; `org-export-format-code' applies a formatting function to each line
2992 ;; of code, providing relative line number and code reference when
2993 ;; appropriate. Since it doesn't access the original element from
2994 ;; which the source code is coming, it expects from the code calling
2995 ;; it to know if lines should be numbered and if code references
2996 ;; should appear.
2998 ;; Eventually, `org-export-format-code-default' is a higher-level
2999 ;; function (it makes use of the two previous functions) which handles
3000 ;; line numbering and code references inclusion, and returns source
3001 ;; code in a format suitable for plain text or verbatim output.
3004 "Return accumulated lines of code up to ELEMENT.
3006 INFO is the plist used as a communication channel.
3008 ELEMENT is excluded from count."
3015 ;; ELEMENT is reached: Quit the loop.
3017 ;; Only count lines from src-block and example-block elements
3018 ;; with a "+n" or "-n" switch. A "-n" switch resets counter.
3022 ;; Accumulate locs or reset them.
3026 ;; Return nil to stay in the loop.
3027 nil)))
3029 ;; Return value.
3030 loc))
3033 "Clean source code and extract references out of it.
3035 ELEMENT has either a `src-block' an `example-block' type.
3037 Return a cons cell whose CAR is the source code, cleaned from any
3038 reference and protective comma and CDR is an alist between
3039 relative line number (integer) and name of code reference on that
3040 line (string)."
3042 ;; Get code and clean it. Remove blank lines at its
3043 ;; beginning and end. Also remove protective commas.
3049 ;; If appropriate, remove global indentation.
3053 ;; Free up the protected lines. Note: Org blocks
3054 ;; have commas at the beginning or every line.
3059 ;; Get format used for references.
3062 org-coderef-label-format)))
3063 ;; Build a regexp matching a loc with a reference.
3068 ;; Return value.
3070 ;; Code with references removed.
3076 ;; Ref line: remove ref, and signal its position in REFS.
3080 ;; Reference alist.
3081 refs)))
3084 "Format CODE by applying FUN line-wise and return it.
3086 CODE is a string representing the code to format. FUN is
3087 a function. It must accept three arguments: a line of
3088 code (string), the current line number (integer) or nil and the
3089 reference associated to the current line (string) or nil.
3091 Optional argument NUM-LINES can be an integer representing the
3092 number of code lines accumulated until the current code. Line
3093 numbers passed to FUN will take it into account. If it is nil,
3094 FUN's second argument will always be nil. This number can be
3095 obtained with `org-export-get-loc' function.
3097 Optional argument REF-ALIST can be an alist between relative line
3098 number (i.e. ignoring NUM-LINES) and the name of the code
3099 reference on it. If it is nil, FUN's third argument will always
3100 be nil. It can be obtained through the use of
3101 `org-export-unravel-code' function."
3113 "Return source code from ELEMENT, formatted in a standard way.
3115 ELEMENT is either a `src-block' or `example-block' element. INFO
3116 is a plist used as a communication channel.
3118 This function takes care of line numbering and code references
3119 inclusion. Line numbers, when applicable, appear at the
3120 beginning of the line, separated from the code by two white
3121 spaces. Code references, on the other hand, appear flushed to
3122 the right, separated by six white spaces from the widest line of
3123 code."
3124 ;; Extract code and references.
3130 ;; Handle line numbering.
3139 ;; Prepare references display, if required. Any reference
3140 ;; should start six columns after the widest line of code,
3141 ;; wrapped with parenthesis.
3146 code
3150 number-str
3151 loc
3157 num-start refs)))
3160 ;;;; For Tables
3162 ;; `org-export-table-has-special-column-p' and
3163 ;; `org-export-table-row-is-special-p' are predicates used to look for
3164 ;; meta-information about the table structure.
3166 ;; `org-export-table-cell-width', `org-export-table-cell-alignment'
3167 ;; and `org-export-table-cell-borders' extract information from
3168 ;; a table-cell element.
3170 ;; `org-export-table-dimensions' gives the number on rows and columns
3171 ;; in the table, ignoring horizontal rules and special columns.
3172 ;; `org-export-table-cell-address', given a table-cell object, returns
3173 ;; the absolute address of a cell. On the other hand,
3174 ;; `org-export-get-table-cell-at' does the contrary.
3177 "Non-nil when TABLE has a special column.
3178 All special columns will be ignored during export."
3179 ;; The table has a special column when every first cell of every row
3180 ;; has an empty value or contains a symbol among "/", "#", "!", "$",
3181 ;; "*" "_" and "^". Though, do not consider a first row containing
3182 ;; only empty cells as special.
3198 "Non-nil when TABLE has an header.
3200 INFO is a plist used as a communication channel.
3202 A table has an header when it contains at least two row groups."
3205 table 'table-row
3213 info)))
3216 "Non-nil if TABLE-ROW is considered special.
3218 INFO is a plist used as the communication channel.
3220 All special rows will be ignored during export."
3224 ;; A row is special either when...
3226 ;; ... it starts with a field only containing "/",
3228 ;; ... the table contains a special column and the row start
3229 ;; with a marking character among, "^", "_", "$" or "!",
3233 ;; ... it contains only alignment cookies and empty cells.
3249 "Return TABLE-ROW's group.
3251 INFO is a plist used as the communication channel.
3253 Return value is the group number, as an integer, or nil special
3254 rows and table rules. Group 1 is also table's header."
3271 "Return TABLE-CELL contents width.
3273 INFO is a plist used as the communication channel.
3275 Return value is the width given by the last width cookie in the
3276 same column as TABLE-CELL, or nil."
3282 cookie-width)
3286 ;; In a special row, try to find a width cookie at COLUMN.
3297 ;; Ignore table rules.
3300 ;; Return value.
3301 cookie-width))
3304 "Return TABLE-CELL contents alignment.
3306 INFO is a plist used as the communication channel.
3308 Return alignment as specified by the last alignment cookie in the
3309 same column as TABLE-CELL. If no such cookie is found, a default
3310 alignment value will be deduced from fraction of numbers in the
3311 column (see `org-table-number-fraction' for more information).
3312 Possible values are `left', `right' and `center'."
3320 cookie-align)
3324 ;; In a special row, try to find an alignment cookie at
3325 ;; COLUMN.
3336 ;; Ignore table rules.
3338 ;; In a standard row, check if cell's contents are expressing
3339 ;; some kind of number. Increase NUMBER-CELLS accordingly.
3340 ;; Though, don't bother if an alignment cookie has already
3341 ;; defined cell's alignment.
3350 ;; Return value. Alignment specified by cookies has precedence
3351 ;; over alignment deduced from cells contents.
3360 "Return TABLE-CELL borders.
3362 INFO is a plist used as a communication channel.
3364 Return value is a list of symbols, or nil. Possible values are:
3365 `top', `bottom', `above', `below', `left' and `right'. Note:
3366 `top' (resp. `bottom') only happen for a cell in the first
3367 row (resp. last row) of the table, ignoring table rules, if any.
3369 Returned borders ignore special rows."
3373 borders)
3374 ;; Top/above border? TABLE-CELL has a border above when a rule
3375 ;; used to demarcate row groups can be found above. Hence,
3376 ;; finding a rule isn't sufficient to push `above' in BORDERS:
3377 ;; another regular row has to be found above that rule.
3386 ;; Look at every row before the current one.
3388 ;; No rule above, or rule found starts the table (ignoring any
3389 ;; special row): TABLE-CELL is at the top of the table.
3392 ;; Bottom/below border? TABLE-CELL has a border below when next
3393 ;; non-regular row below is a rule.
3402 ;; Look at every row after the current one.
3404 ;; No rule below, or rule found ends the table (modulo some
3405 ;; special row): TABLE-CELL is at the bottom of the table.
3408 ;; Right/left borders? They can only be specified by column
3409 ;; groups. Column groups are defined in a row starting with "/".
3410 ;; Also a column groups row only contains "<", "<>", ">" or blank
3411 ;; cells.
3428 ;; There's a left border when previous cell, if
3429 ;; any, ends a group, or current one starts one.
3435 ;; There's a right border when next cell, if any,
3436 ;; starts a group, or current one ends one.
3443 ;; Table rows are read in reverse order so last column groups
3444 ;; row has precedence over any previous one.
3446 ;; Return value.
3447 borders))
3450 "Non-nil when TABLE-CELL is at the beginning of a row group.
3451 INFO is a plist used as a communication channel."
3452 ;; A cell starts a column group either when it is at the beginning
3453 ;; of a row (or after the special column, if any) or when it has
3454 ;; a left border.
3458 table-cell)
3462 "Non-nil when TABLE-CELL is at the end of a row group.
3463 INFO is a plist used as a communication channel."
3464 ;; A cell ends a column group either when it is at the end of a row
3465 ;; or when it has a right border.
3468 table-cell)
3472 "Non-nil when TABLE-ROW is at the beginning of a column group.
3473 INFO is a plist used as a communication channel."
3481 "Non-nil when TABLE-ROW is at the end of a column group.
3482 INFO is a plist used as a communication channel."
3490 "Non-nil when TABLE-ROW is the first table header's row.
3491 INFO is a plist used as a communication channel."
3498 "Non-nil when TABLE-ROW is the last table header's row.
3499 INFO is a plist used as a communication channel."
3506 "Return TABLE dimensions.
3508 INFO is a plist used as a communication channel.
3510 Return value is a CONS like (ROWS . COLUMNS) where
3511 ROWS (resp. COLUMNS) is the number of exportable
3512 rows (resp. columns)."
3514 ;; Set number of rows, and extract first one.
3516 table 'table-row
3521 ;; Set number of columns.
3523 ;; Return value.
3527 "Return address of a regular TABLE-CELL object.
3529 TABLE-CELL is the cell considered. INFO is a plist used as
3530 a communication channel.
3532 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3533 zero-based index. Only exportable cells are considered. The
3534 function returns nil for other cells."
3537 ;; Ignore cells in special rows or in special column.
3542 ;; Row number.
3545 table 'table-row
3551 ;; Column number.
3554 table-row 'table-cell
3561 "Return regular table-cell object at ADDRESS in TABLE.
3563 Address is a CONS cell (ROW . COLUMN), where ROW and COLUMN are
3564 zero-based index. TABLE is a table type element. INFO is
3565 a plist used as a communication channel.
3567 If no table-cell, among exportable cells, is found at ADDRESS,
3568 return nil."
3571 ;; Row at (car address) or nil.
3574 table 'table-row
3580 'table-cell
3587 ;;;; For Tables Of Contents
3589 ;; `org-export-collect-headlines' builds a list of all exportable
3590 ;; headline elements, maybe limited to a certain depth. One can then
3591 ;; easily parse it and transcode it.
3593 ;; Building lists of tables, figures or listings is quite similar.
3594 ;; Once the generic function `org-export-collect-elements' is defined,
3595 ;; `org-export-collect-tables', `org-export-collect-figures' and
3596 ;; `org-export-collect-listings' can be derived from it.
3599 "Collect headlines in order to build a table of contents.
3601 INFO is a plist used as a communication channel.
3603 When non-nil, optional argument N must be an integer. It
3604 specifies the depth of the table of contents.
3606 Return a list of all exportable headlines as parsed elements."
3609 'headline
3611 ;; Strip contents from HEADLINE.
3614 info))
3617 "Collect referenceable elements of a determined type.
3619 TYPE can be a symbol or a list of symbols specifying element
3620 types to search. Only elements with a caption or a name are
3621 collected.
3623 INFO is a plist used as a communication channel.
3625 When non-nil, optional argument PREDICATE is a function accepting
3626 one argument, an element of type TYPE. It returns a non-nil
3627 value when that element should be collected.
3629 Return a list of all elements found, in order of appearance."
3639 "Build a list of tables.
3641 INFO is a plist used as a communication channel.
3643 Return a list of table elements with a caption or a name
3644 affiliated keyword."
3648 "Build a list of figures.
3650 INFO is a plist used as a communication channel. PREDICATE is
3651 a function which accepts one argument: a paragraph element and
3652 whose return value is non-nil when that element should be
3653 collected.
3655 A figure is a paragraph type element, with a caption or a name,
3656 verifying PREDICATE. The latter has to be provided since
3659 Return a list of elements recognized as figures."
3663 "Build a list of src blocks.
3665 INFO is a plist used as a communication channel.
3667 Return a list of src-block elements with a caption or a name
3668 affiliated keyword."
3672 ;;;; Topology
3674 ;; Here are various functions to retrieve information about the
3675 ;; neighbourhood of a given element or object. Neighbours of interest
3676 ;; are direct parent (`org-export-get-parent'), parent headline
3677 ;; (`org-export-get-parent-headline'), parent paragraph
3678 ;; (`org-export-get-parent-paragraph'), previous element or object
3679 ;; (`org-export-get-previous-element') and next element or object
3680 ;; (`org-export-get-next-element').
3682 ;; All of these functions are just a specific use of the more generic
3683 ;; `org-export-get-genealogy', which returns the genealogy relative to
3684 ;; the element or object.
3687 "Return genealogy relative to a given element or object.
3688 BLOB is the element or object being considered. INFO is a plist
3689 used as a communication channel."
3694 ;; Walk DATA, looking for BLOB. GENEALOGY is the list of
3695 ;; parents of all elements in DATA.
3702 ;; If BLOB is an object and EL contains a secondary
3703 ;; string, be sure to check it.
3707 org-element-secondary-value-alist))))
3710 walk-data
3719 "Return BLOB parent or nil.
3720 BLOB is the element or object considered. INFO is a plist used
3721 as a communication channel."
3725 "Return BLOB parent headline or nil.
3726 BLOB is the element or object being considered. INFO is a plist
3727 used as a communication channel."
3732 nil))
3735 "Return OBJECT parent paragraph or nil.
3736 OBJECT is the object to consider. INFO is a plist used as
3737 a communication channel."
3742 nil))
3745 "Return OBJECT parent table or nil.
3746 OBJECT is either a `table-cell' or `table-element' type object.
3747 INFO is a plist used as a communication channel."
3752 nil))
3755 "Return previous element or object.
3757 BLOB is an element or object. INFO is a plist used as
3758 a communication channel.
3760 Return previous element or object, a string, or nil."
3765 "Return next element or object.
3767 BLOB is an element or object. INFO is a plist used as
3768 a communication channel.
3770 Return next element or object, a string, or nil."
3775 \f
3776 ;;; The Dispatcher
3778 ;; `org-export-dispatch' is the standard interactive way to start an
3779 ;; export process. It uses `org-export-dispatch-ui' as a subroutine
3780 ;; for its interface. Most commons back-ends should have an entry in
3781 ;; it.
3784 "Export dispatcher for Org mode.
3786 It provides an access to common export related tasks in a buffer.
3787 Its interface comes in two flavours: standard and expert. While
3788 both share the same set of bindings, only the former displays the
3789 valid keys associations. Set `org-export-dispatch-use-expert-ui'
3790 to switch to one or the other.
3792 Return an error if key pressed has no associated command."
3797 org-export-dispatch-use-expert-ui))
3800 ;; Translate "C-a", "C-b"... into "a", "b"... Then take action
3801 ;; depending on user's key pressed.
3803 ;; Allow to quit with "q" key.
3805 ;; Export with `e-ascii' back-end.
3811 `(:ascii-charset
3820 ;; Export with `e-latex' back-end.
3821 (?L
3836 ;; Export with `e-html' back-end.
3837 (?H
3842 ;; set major mode
3852 ;; Export with `e-odt' back-end.
3858 ;; Publishing facilities
3864 org-e-publish-project-alist)))
3867 ;; Undefined command.
3872 "Handle interface for `org-export-dispatch'.
3874 OPTIONS is a list containing current interactive options set for
3875 export. It can contain any of the following symbols:
3876 `body' toggles a body-only export
3877 `subtree' restricts export to current subtree
3878 `visible' restricts export to visible part of buffer.
3879 `force' force publishing files.
3881 EXPERTP, when non-nil, triggers expert UI. In that case, no help
3882 buffer is provided, but indications about currently active
3883 options are given in the prompt. Moreover, \[?] allows to switch
3884 back to standard interface.
3886 Return value is a list with key pressed as CAR and a list of
3887 final interactive export options as CDR."
3891 \[1] Body only: %s [2] Export scope: %s
3892 \[3] Visible only: %s [4] Force publishing: %s
3895 --- (ASCII/Latin-1/UTF-8 Export) -------------------------
3897 \[a/n/u] to TXT file [A/N/U] to temporary buffer
3899 --- (HTML Export) ----------------------------------------
3901 \[h] to HTML file [b] ... and open it
3902 \[H] to temporary buffer
3904 --- (LaTeX Export) ---------------------------------------
3906 \[l] to TEX file [L] to temporary buffer
3907 \[p] to PDF file [d] ... and open it
3909 --- (ODF Export) -----------------------------------------
3911 \[o] to ODT file [O] ... and open it
3913 --- (Publish) --------------------------------------------
3915 \[F] current file [P] current project
3916 \[X] a project [E] every project"
3929 ;; Read a character from command input, toggling interactive
3930 ;; options when applicable. PROMPT is the displayed prompt,
3931 ;; as a string.
3935 ;; Ignore non-standard characters (i.e. "M-a").
3937 ;; Help key: Switch back to standard interface if
3938 ;; expert UI was active.
3940 ;; Toggle export options.
3947 expertp))
3948 ;; Action selected: Send key and options back to
3949 ;; `org-export-dispatch'.
3951 ;; With expert UI, just read key with a fancy prompt. In standard
3952 ;; UI, display an intrusive help buffer.
3963 ;;; org-export.el ends here