Function: org-export-to-file

org-export-to-file is an autoloaded and byte-compiled function defined in ox.el.gz.

Signature

(org-export-to-file BACKEND FILE &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST POST-PROCESS)

Documentation

Call org-export-as with output to a specified file.

BACKEND is either an export back-end, as returned by, e.g., org-export-create-backend, or a symbol referring to a registered back-end. FILE is the name of the output file, as a string.

A non-nil optional argument ASYNC means the process should happen asynchronously. The resulting buffer will then be accessible through the org-export-stack interface.

Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and EXT-PLIST are similar to those used in org-export-as, which see.

Optional argument POST-PROCESS is called with FILE as its argument and happens asynchronously when ASYNC is non-nil. It 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
        async subtreep visible-only body-only ext-plist
        #'org-latex-compile)))

When expressed as an anonymous function, using lambda, POST-PROCESS needs to be quoted.

The function returns either a file name returned by POST-PROCESS, or FILE.

Source Code

;; Defined in /usr/src/emacs/lisp/org/ox.el.gz
;;;###autoload
(defun org-export-to-file
    (backend file &optional async subtreep visible-only body-only ext-plist
	     post-process)
  "Call `org-export-as' with output to a specified file.

BACKEND is either an export back-end, as returned by, e.g.,
`org-export-create-backend', or a symbol referring to
a registered back-end.  FILE is the name of the output file, as
a string.

A non-nil optional argument ASYNC means the process should happen
asynchronously.  The resulting buffer will then be accessible
through the `org-export-stack' interface.

Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and
EXT-PLIST are similar to those used in `org-export-as', which
see.

Optional argument POST-PROCESS is called with FILE as its
argument and happens asynchronously when ASYNC is non-nil.  It
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
        async subtreep visible-only body-only ext-plist
        #\\='org-latex-compile)))

When expressed as an anonymous function, using `lambda',
POST-PROCESS needs to be quoted.

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 ((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)
		(org-export-add-to-stack (expand-file-name file) backend))
	    `(let ((output
		    (org-export-as
		     ',backend ,subtreep ,visible-only ,body-only
		     ',ext-plist)))
	       (with-temp-buffer
		 (insert output)
                 ;; Ensure final newline.  This is what was done
                 ;; historically, when we used `write-file'.
                 ;; Note that adding a newline is only safe for
                 ;; non-binary data.
                 (unless (bolp) (insert "\n"))
		 (let ((coding-system-for-write ',encoding))
		   (write-region (point-min) (point-max) ,file)))
	       (or (ignore-errors (funcall ',post-process ,file)) ,file)))
        (let ((output (org-export-as
                       backend subtreep visible-only body-only ext-plist)))
          (with-temp-buffer
            (insert output)
            ;; Ensure final newline.  This is what was done
            ;; historically, when we used `write-file'.
            ;; Note that adding a newline is only safe for
            ;; non-binary data.
            (unless (bolp) (insert "\n"))
            (let ((coding-system-for-write encoding))
	      (write-region (point-min) (point-max) file)))
          (when (and (org-export--copy-to-kill-ring-p) (org-string-nw-p output))
            (org-kill-new output))
          ;; Get proper return value.
          (or (and (functionp post-process) (funcall post-process file))
	      file))))))