;;; ox.el --- Generic Export Engine for Org Mode
-;; Copyright (C) 2012-2013 Free Software Foundation, Inc.
+;; Copyright (C) 2012-2016 Free Software Foundation, Inc.
;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
;; Keywords: outlines, hypermedia, calendar, wp
"Alist between export properties and ways to set them.
The CAR of the alist is the property name, and the CDR is a list
-like (KEYWORD OPTION DEFAULT BEHAVIOUR) where:
+like (KEYWORD OPTION DEFAULT BEHAVIOR) where:
KEYWORD is a string representing a buffer keyword, or nil. Each
property defined this way can also be set, during subtree
property).
OPTION is a string that could be found in an #+OPTIONS: line.
DEFAULT is the default value for the property.
-BEHAVIOUR determines how Org should handle multiple keywords for
+BEHAVIOR determines how Org should handle multiple keywords for
the same property. It is a symbol among:
nil Keep old value and discard the new one.
t Replace old value with the new one.
:group 'org-export-general
:type '(choice
(const :tag "No creator sentence" nil)
- (const :tag "Sentence as a comment" 'comment)
+ (const :tag "Sentence as a comment" comment)
(const :tag "Insert the sentence" t)))
(defcustom org-export-with-date t
"The last level which is still exported as a headline.
Inferior levels will usually produce itemize or enumerate lists
-when exported, but back-end behaviour may differ.
+when exported, but back-end behavior may differ.
This option can also be set with the OPTIONS keyword,
e.g. \"H:2\"."
(defcustom org-export-with-sub-superscripts t
"Non-nil means interpret \"_\" and \"^\" for export.
+If you want to control how Org displays those characters, see
+`org-use-sub-superscripts'. `org-export-with-sub-superscripts'
+used to be an alias for `org-use-sub-superscripts' in Org <8.0,
+it is not anymore.
+
When this option is turned on, you can use TeX-like syntax for
-sub- and superscripts. Several characters after \"_\" or \"^\"
-will be considered as a single item - so grouping with {} is
-normally not needed. For example, the following things will be
-parsed as single sub- or superscripts.
+sub- and superscripts and see them exported correctly.
+
+You can also set the option with #+OPTIONS: ^:t
+
+Several characters after \"_\" or \"^\" will be considered as a
+single item - so grouping with {} is normally not needed. For
+example, the following things will be parsed as single sub- or
+superscripts:
10^24 or 10^tau several digits will be considered 1 item.
10^-12 or 10^-tau a leading sign with digits or a word
terminated by almost any nonword/nondigit char.
x_{i^2} or x^(2-i) braces or parenthesis do grouping.
-Still, ambiguity is possible - so when in doubt use {} to enclose
-the sub/superscript. If you set this variable to the symbol
-`{}', the braces are *required* in order to trigger
-interpretations as sub/superscript. This can be helpful in
-documents that need \"_\" frequently in plain text.
-
-This option can also be set with the OPTIONS keyword,
-e.g. \"^:nil\"."
+Still, ambiguity is possible. So when in doubt, use {} to enclose
+the sub/superscript. If you set this variable to the symbol `{}',
+the braces are *required* in order to trigger interpretations as
+sub/superscript. This can be helpful in documents that need \"_\"
+frequently in plain text."
:group 'org-export-general
+ :version "24.4"
+ :package-version '(Org . "8.0")
:type '(choice
(const :tag "Interpret them" t)
(const :tag "Curly brackets only" {})
This variable allows to provide shortcuts for export snippets.
-For example, with a value of '\(\(\"h\" . \"html\"\)\), the
+For example, with a value of \((\"h\" . \"html\")), the
HTML back-end will recognize the contents of \"@@h:<b>@@\" as
HTML code while every other back-end will ignore it."
:group 'org-export-general
:type 'coding-system)
(defcustom org-export-copy-to-kill-ring 'if-interactive
- "Should we push exported content to the kill ring?"
+ "Non-nil means pushing export output to the kill ring.
+This variable is ignored during asynchronous export."
:group 'org-export-general
:version "24.3"
:type '(choice
(defcustom org-export-show-temporary-export-buffer t
"Non-nil means show buffer after exporting to temp buffer.
-When Org exports to a file, the buffer visiting that file is ever
+When Org exports to a file, the buffer visiting that file is never
shown, but remains buried. However, when exporting to
a temporary buffer, that buffer is popped up in a second window.
When this variable is nil, the buffer remains buried also in
the current subtree, \"v\" when only visible elements are
considered for export, \"f\" when publishing functions should be
passed the FORCE argument and \"a\" when the export should be
-asynchronous). Also, \[?] allows to switch back to standard
+asynchronous). Also, [?] allows to switch back to standard
mode."
:group 'org-export-general
:version "24.4"
Menu entry for the export dispatcher. It should be a list
like:
- '(KEY DESCRIPTION-OR-ORDINAL ACTION-OR-MENU)
+ (KEY DESCRIPTION-OR-ORDINAL ACTION-OR-MENU)
where :
If it is an alist, associations should follow the
pattern:
- '(KEY DESCRIPTION ACTION)
+ (KEY DESCRIPTION ACTION)
where KEY, DESCRIPTION and ACTION are described above.
Valid values include:
- '(?m \"My Special Back-end\" my-special-export-function)
+ (?m \"My Special Back-end\" my-special-export-function)
or
- '(?l \"Export to LaTeX\"
- \(?p \"As PDF file\" org-latex-export-to-pdf)
- \(?o \"As PDF file and open\"
- \(lambda (a s v b)
- \(if a (org-latex-export-to-pdf t s v b)
- \(org-open-file
- \(org-latex-export-to-pdf nil s v b)))))))
+ (?l \"Export to LaTeX\"
+ (?p \"As PDF file\" org-latex-export-to-pdf)
+ (?o \"As PDF file and open\"
+ (lambda (a s v b)
+ (if a (org-latex-export-to-pdf t s v b)
+ (org-open-file
+ (org-latex-export-to-pdf nil s v b)))))))
or the following, which will be added to the previous
sub-menu,
- '(?l 1
- \((?B \"As TEX buffer (Beamer)\" org-beamer-export-as-latex)
- \(?P \"As PDF file (Beamer)\" org-beamer-export-to-pdf)))
+ (?l 1
+ ((?B \"As TEX buffer (Beamer)\" org-beamer-export-as-latex)
+ (?P \"As PDF file (Beamer)\" org-beamer-export-to-pdf)))
:options-alist
As an example, here is how one could define \"my-latex\" back-end
as a variant of `latex' back-end with a custom template function:
- \(org-export-define-derived-backend 'my-latex 'latex
- :translate-alist '((template . my-latex-template-fun)))
+ (org-export-define-derived-backend \\='my-latex \\='latex
+ :translate-alist \\='((template . my-latex-template-fun)))
The back-end could then be called with, for example:
- \(org-export-to-buffer 'my-latex \"*Test my-latex*\")"
+ (org-export-to-buffer \\='my-latex \"*Test my-latex*\")"
(declare (indent 2))
(let (blocks filters menu-entry options transcoders contents)
(while (keywordp (car body))
;; - category :: tree
;; - type :: list of elements and objects
;;
+;; + `:input-buffer' :: Name of input buffer.
+;; - category :: option
+;; - type :: string
+;;
;; + `:input-file' :: Full path to input file, if any.
;; - category :: option
;; - type :: string or nil
;; - category :: option
;; - type :: string
;;
+;; + `:output-file' :: Full path to output file, if any.
+;; - category :: option
+;; - type :: string or nil
+;;
;; + `:parse-tree' :: Whole parse tree, available at any time during
;; transcoding.
;; - category :: option
;; Make sure point is at a heading.
(if (org-at-heading-p) (org-up-heading-safe) (org-back-to-heading t))
;; Take care of EXPORT_TITLE. If it isn't defined, use headline's
- ;; title as its fallback value.
+ ;; title (with no todo keyword, priority cookie or tag) as its
+ ;; fallback value.
(when (setq prop (or (org-entry-get (point) "EXPORT_TITLE")
- (progn (looking-at org-todo-line-regexp)
- (org-match-string-no-properties 3))))
+ (progn (looking-at org-complex-heading-regexp)
+ (org-match-string-no-properties 4))))
(setq plist
(plist-put
plist :title
((member keyword org-element-document-properties)
(org-element-parse-secondary-string
value (org-element-restriction 'keyword)))
- ;; If BEHAVIOUR is `split' expected value is
+ ;; If BEHAVIOR is `split' expected value is
;; a list of strings, not a string.
((eq (nth 4 option) 'split) (org-split-string value))
(t value)))))))))
(t
;; Options in `org-export-options-alist'.
(dolist (property (funcall find-properties key))
- (let ((behaviour (nth 4 (assq property options))))
+ (let ((behavior (nth 4 (assq property options))))
(setq plist
(plist-put
plist property
;; Handle value depending on specified
- ;; BEHAVIOUR.
- (case behaviour
+ ;; BEHAVIOR.
+ (case behavior
(space
(if (not (plist-get plist property))
(org-trim val)
(when (stringp value)
(setq plist
(plist-put plist property
- (org-element-parse-secondary-string
- value (org-element-restriction 'keyword))))))))))
+ (or (org-element-parse-secondary-string
+ value (org-element-restriction 'keyword))
+ ;; When TITLE keyword sets an empty
+ ;; string, make sure it doesn't
+ ;; appear as nil in the plist.
+ (and (eq property :title) ""))))))))))
(defun org-export--get-buffer-attributes ()
"Return properties related to buffer attributes, as a plist."
;; Store full path of input file name, or nil. For internal use.
(let ((visited-file (buffer-file-name (buffer-base-buffer))))
(list :input-file visited-file
- :title (if (not visited-file) (buffer-name (buffer-base-buffer))
- (file-name-sans-extension
- (file-name-nondirectory visited-file))))))
+ :input-buffer (buffer-name (buffer-base-buffer)))))
(defun org-export--get-global-options (&optional backend)
"Return global export options as a plist.
(all (append (and backend (org-export-get-all-options backend))
org-export-options-alist)))
(dolist (cell all plist)
- (let ((prop (car cell))
- (default-value (nth 3 cell)))
- (unless (or (not default-value) (plist-member plist prop))
+ (let ((prop (car cell)))
+ (unless (plist-member plist prop)
(setq plist
(plist-put
plist
prop
- ;; Eval default value provided. If keyword is
+ ;; Evaluate default value provided. If keyword is
;; a member of `org-element-document-properties',
;; parse it as a secondary string before storing it.
(let ((value (eval (nth 3 cell))))
- (if (not (stringp value)) value
- (let ((keyword (nth 1 cell)))
- (if (member keyword org-element-document-properties)
- (org-element-parse-secondary-string
- value (org-element-restriction 'keyword))
- value)))))))))))
+ (if (and (stringp value)
+ (member (nth 1 cell)
+ org-element-document-properties))
+ (org-element-parse-secondary-string
+ value (org-element-restriction 'keyword))
+ value)))))))))
(defun org-export--list-bound-variables ()
"Return variables bound from BIND keywords in current buffer.
;; Return value in appropriate order of appearance.
(nreverse (funcall collect-bind nil nil)))))
+;; defsubst org-export-get-parent must be defined before first use,
+;; was originally defined in the topology section
+
+(defsubst org-export-get-parent (blob)
+ "Return BLOB parent or nil.
+BLOB is the element or object considered."
+ (org-element-property :parent blob))
;;;; Tree Properties
;;
options.
Return an alist whose key is a headline and value is its
-associated numbering \(in the shape of a list of numbers\) or nil
+associated numbering \(in the shape of a list of numbers) or nil
for a footnotes section."
(let ((numbering (make-vector org-export-max-depth 0)))
(org-element-map data 'headline
DATA is a parse tree, an element or an object or a secondary
string. INFO is a plist holding export options.
-Return transcoded string."
- (let ((memo (gethash data (plist-get info :exported-data) 'no-memo)))
- (if (not (eq memo 'no-memo)) memo
+Return a string."
+ (or (gethash data (plist-get info :exported-data))
(let* ((type (org-element-type data))
(results
(cond
;; Secondary string.
((not type)
(mapconcat (lambda (obj) (org-export-data obj info)) data ""))
- ;; Element/Object without contents or, as a special case,
- ;; headline with archive tag and archived trees restricted
- ;; to title only.
+ ;; Element/Object without contents or, as a special
+ ;; case, headline with archive tag and archived trees
+ ;; restricted to title only.
((or (not (org-element-contents data))
(and (eq type 'headline)
(eq (plist-get info :with-archived-trees) 'headline)
(lambda (element) (org-export-data element info))
(org-element-contents
(if (or greaterp objectp) data
- ;; Elements directly containing objects
- ;; must have their indentation normalized
- ;; first.
+ ;; Elements directly containing
+ ;; objects must have their indentation
+ ;; normalized first.
(org-element-normalize-contents
data
- ;; When normalizing contents of the first
- ;; paragraph in an item or a footnote
- ;; definition, ignore first line's
- ;; indentation: there is none and it
- ;; might be misleading.
+ ;; When normalizing contents of the
+ ;; first paragraph in an item or
+ ;; a footnote definition, ignore
+ ;; first line's indentation: there is
+ ;; none and it might be misleading.
(when (eq type 'paragraph)
(let ((parent (org-export-get-parent data)))
(and
(puthash
data
(cond
- ((not results) nil)
+ ((not results) "")
((memq type '(org-data plain-text nil)) results)
- ;; Append the same white space between elements or objects as in
- ;; the original buffer, and call appropriate filters.
+ ;; Append the same white space between elements or objects
+ ;; as in the original buffer, and call appropriate filters.
(t
(let ((results
(org-export-filter-apply-functions
(if (memq type org-element-all-elements)
(concat (org-element-normalize-string results)
(make-string post-blank ?\n))
- (concat results (make-string post-blank ? ))))
+ (concat results (make-string post-blank ?\s))))
info)))
results)))
- (plist-get info :exported-data))))))
+ (plist-get info :exported-data)))))
(defun org-export-data-with-backend (data backend info)
"Convert DATA into BACKEND format.
narrowing of the original buffer. If a region was active in
BUFFER, contents will be narrowed to that region instead.
-The resulting function can be evaled at a later time, from
+The resulting function can be evaluated at a later time, from
another buffer, effectively cloning the original buffer there.
The function assumes BUFFER's major mode is `org-mode'."
(org-export-install-filters
(org-combine-plists
info (org-export-get-environment backend subtreep ext-plist))))
+ ;; Special case: provide original file name or buffer name as
+ ;; default value for :title property.
+ (unless (plist-get info :title)
+ (plist-put
+ info :title
+ (let ((file (plist-get info :input-file)))
+ (if file (file-name-sans-extension (file-name-nondirectory file))
+ (plist-get info :input-buffer)))))
;; Expand export-specific set of macros: {{{author}}},
;; {{{date}}}, {{{email}}} and {{{title}}}. It must be done
;; once regular macros have been expanded, since document
;; Populate OPTIONS and KEYWORDS.
(dolist (entry (cond ((eq backend 'default) org-export-options-alist)
((org-export-backend-p backend)
- (org-export-get-all-options backend))
- (t (org-export-get-all-options
+ (org-export-backend-options backend))
+ (t (org-export-backend-options
(org-export-get-backend backend)))))
(let ((keyword (nth 1 entry))
(option (nth 2 entry)))
Optional argument IND, when non-nil, is an integer specifying the
global indentation of returned contents. Since its purpose is to
allow an included file to stay in the same environment it was
-created \(i.e. a list item), it doesn't apply past the first
+created \(i.e., a list item), it doesn't apply past the first
headline encountered.
Optional argument MINLEVEL, when non-nil, is an integer
Optional argument is a set of RULES defining inline images. It
is an alist where associations have the following shape:
- \(TYPE . REGEXP)
+ (TYPE . REGEXP)
Applying a rule means apply REGEXP against LINK's path when its
type is TYPE. The function will return a non-nil value if any of
- If LINK path matches a target object (i.e. <<path>>) return it.
- If LINK path exactly matches the name affiliated keyword
- \(i.e. #+NAME: path) of an element, return that element.
+ (i.e. #+NAME: path) of an element, return that element.
- If LINK path exactly matches any headline name, return that
element. If more than one headline share that name, priority
"Return TABLE-ROW number.
INFO is a plist used as a communication channel. Return value is
zero-based and ignores separators. The function returns nil for
-special colums and separators."
+special columns and separators."
(when (and (eq (org-element-property :type table-row) 'standard)
(not (org-export-table-row-is-special-p table-row info)))
(let ((number 0))
(defconst org-export-smart-quotes-regexps
(list
;; Possible opening quote at beginning of string.
- "\\`\\([\"']\\)\\(\\w\\|\\s.\\|\\s_\\)"
+ "\\`\\([\"']\\)\\(\\w\\|\\s.\\|\\s_\\|\\s(\\)"
;; Possible closing quote at beginning of string.
"\\`\\([\"']\\)\\(\\s-\\|\\s)\\|\\s.\\)"
;; Possible apostrophe at beginning of string.
;;;; Topology
;;
;; Here are various functions to retrieve information about the
-;; neighbourhood of a given element or object. Neighbours of interest
+;; neighborhood of a given element or object. Neighbors of interest
;; are direct parent (`org-export-get-parent'), parent headline
;; (`org-export-get-parent-headline'), first element containing an
;; object, (`org-export-get-parent-element'), parent table
;; `org-export-get-genealogy' returns the full genealogy of a given
;; element or object, from closest parent to full parse tree.
-(defsubst org-export-get-parent (blob)
- "Return BLOB parent or nil.
-BLOB is the element or object considered."
- (org-element-property :parent blob))
-
+;; defsubst org-export-get-parent must be defined before first use
(defun org-export-get-genealogy (blob)
"Return full genealogy relative to a given element or object.
(defmacro org-export-async-start (fun &rest body)
"Call function FUN on the results returned by BODY evaluation.
-BODY evaluation happens in an asynchronous process, from a buffer
-which is an exact copy of the current one.
+FUN is an anonymous function of one argument. BODY evaluation
+happens in an asynchronous process, from a buffer which is an
+exact copy of the current one.
Use `org-export-add-to-stack' in FUN in order to register results
in the stack.
(kill-buffer proc-buffer))))
(org-export-add-to-stack proc-buffer nil p)
(ding)
- (message "Process '%s' exited abnormally" p))
+ (message "Process `%s' exited abnormally" p))
(unless org-export-async-debug
(delete-file ,,temp-file)))))))))))))
from BUFFER, with point at its beginning. Export back-ends can
use it to set a major mode there, e.g,
- \(defun org-latex-export-as-latex
- \(&optional async subtreep visible-only body-only ext-plist)
- \(interactive)
- \(org-export-to-buffer 'latex \"*Org LATEX Export*\"
+ (defun org-latex-export-as-latex
+ (&optional async subtreep visible-only body-only ext-plist)
+ (interactive)
+ (org-export-to-buffer \\='latex \"*Org LATEX Export*\"
async subtreep visible-only body-only ext-plist (lambda () (LaTeX-mode))))
This function returns BUFFER."
a string.
A non-nil optional argument ASYNC means the process should happen
-asynchronously. The resulting buffer file then be accessible
+asynchronously. The resulting buffer will then be accessible
through the `org-export-stack' interface.
Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and
has to return a file name, or nil. Export back-ends can use this
to send the output file through additional processing, e.g,
- \(defun org-latex-export-to-latex
- \(&optional async subtreep visible-only body-only ext-plist)
- \(interactive)
- \(let ((outfile (org-export-output-file-name \".tex\" subtreep)))
- \(org-export-to-file 'latex outfile
+ (defun org-latex-export-to-latex
+ (&optional async subtreep visible-only body-only ext-plist)
+ (interactive)
+ (let ((outfile (org-export-output-file-name \".tex\" subtreep)))
+ (org-export-to-file \\='latex outfile
async subtreep visible-only body-only ext-plist
- \(lambda (file) (org-latex-compile file)))
+ (lambda (file) (org-latex-compile file)))
The function returns either a file name returned by POST-PROCESS,
or FILE."
(declare (indent 2))
(if (not (file-writable-p file)) (error "Output file not writable")
- (let ((encoding (or org-export-coding-system buffer-file-coding-system)))
+ (let ((ext-plist (org-combine-plists `(:output-file ,file) ext-plist))
+ (encoding (or org-export-coding-system buffer-file-coding-system)))
(if async
(org-export-async-start
`(lambda (file)
"Export dispatcher for Org mode.
It provides an access to common export related tasks in a buffer.
-Its interface comes in two flavours: standard and expert.
+Its interface comes in two flavors: standard and expert.
While both share the same set of bindings, only the former
displays the valid keys associations in a dedicated buffer.
SPC and DEL (resp. C-n and C-p) keys.
Set variable `org-export-dispatch-use-expert-ui' to switch to one
-flavour or the other.
+flavor or the other.
When ARG is \\[universal-argument], repeat the last export action, with the same set
of options used back then, on the current buffer.
EXPERTP, when non-nil, triggers expert UI. In that case, no help
buffer is provided, but indications about currently active
-options are given in the prompt. Moreover, \[?] allows to switch
+options are given in the prompt. Moreover, [?] allows to switch
back to standard interface."
(let* ((fontify-key
(lambda (key &optional access-key)
(concat
;; Options are hard-coded.
(format "[%s] Body only: %s [%s] Visible only: %s
-\[%s] Export scope: %s [%s] Force publishing: %s
-\[%s] Async export: %s\n\n"
+[%s] Export scope: %s [%s] Force publishing: %s
+[%s] Async export: %s\n\n"
(funcall fontify-key "C-b" t)
(funcall fontify-value
(if (memq 'body options) "On " "Off"))