1 #+TITLE: The New Org-mode Exporter Framework
2 #+OPTIONS: H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
3 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate hideblocks
4 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
5 #+TAGS: Write(w) Update(u) Fix(f) Check(c) noexport(n)
6 #+AUTHOR: John Henderson
7 #+EMAIL: jw.hendy[at]gmail[dot]com
9 #+STYLE: <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+LINK_UP: ../ox-overview.html
11 #+LINK_HOME: https://orgmode.org/worg/
12 #+EXCLUDE_TAGS: noexport
14 [[file:index.org][{Back to Worg's index}]]
18 As of release 8.0, Org-mode has transitioned to a new export framework, authored
19 primarily (/entirely?/) by Nicolas Goaziou...
23 Perhaps this could be filled in with some of the technical reasons and advantages
24 of the new exporter by Nicolas or someone else familiar with with it's inner workings?
28 For instructions on how to upgrade from the previous Org-mode exporter, see
29 [[file:../org-8.0.org][the upgrade guide]].
31 Nicolas' official announcement of the exporter may be viewed at the [[http://article.gmane.org/gmane.emacs.orgmode/65574][Org-mode mailing list
32 post]]. This document presents an overview of features, as well as a list of currently
33 supported exporter backends. [[https://orgmode.org/manual/Exporting.html#Exporting][Exporting]] and [[https://orgmode.org/manual/Publishing.html#Publishing][publishing]] are also documented in the [[https://orgmode.org/manual/][Org-mode
34 manual]]. See [[file:ox-docstrings.org][ox-docstrings]] and [[file:org-element-docstrings.org][org-element-docstrings]] for the extracted
35 docstrings from these two core libraries of the new Org-mode exporter, i.e.
36 for detailled technical information about the exporter framework.
38 * List of Org-mode exporters
40 Please find below a list of current Org-mode exporters, the location of the backend elisp
41 file (relative to downloaded Org-mode installation directory, =org=) and links Worg and
42 Org-mode manual documentation.
44 | *Name* | *Exporter location* | *Worg Tutorial* | *Org-mode Manual* |
45 |---------------+----------------------------------+----------------+----------------------------|
46 | ASCII | =./lisp/ox-ascii.el= | ox-ascii | [[https://orgmode.org/manual/ASCII_002fLatin_002d1_002fUTF_002d8-export.html#ASCII_002fLatin_002d1_002fUTF_002d8-export][ASCII/Latin-1/UTF-8 export]] |
47 | [[https://bitbucket.org/rivanvx/beamer/wiki/Home][Beamer]] | =./lisp/ox-beamer.el= | [[file:beamer/ox-beamer.org][ox-beamer]] | [[https://orgmode.org/manual/Beamer-export.html#Beamer-export][Beamer class export]] |
48 | HTML | =./lisp/ox-html.el= | ox-html | [[https://orgmode.org/manual/HTML-export.html#HTML-export][HTML export]] |
49 | [[https://en.wikipedia.org/wiki/ICalendar][iCalendar]] | =./lisp/ox-icalandar.el= | ox-icalendar | |
50 | [[http://www.latex-project.org/][LaTeX]] | =./lisp/ox-latex.el= | ox-latex | [[https://orgmode.org/manual/LaTeX-export.html#LaTeX-export][LaTeX export]] |
51 | [[http://manpages.bsd.lv/history.html][Man]] | =./lisp/ox-man.el= | ox-man | |
52 | [[http://daringfireball.net/projects/markdown/][Markdown]] | =./lisp/ox-md.el= | ox-md | |
53 | [[http://opendocumentformat.org/][ODT]] | =./lisp/ox-odt.el= | ox-odt | [[https://orgmode.org/manual/OpenDocument-Text-export.html#OpenDocument-Text-export][OpenDocument Text export]] |
54 | [[https://orgmode.org/manual/Publishing.html][Publishing]] | =./lisp/ox-publish.el= | ox-publish | [[https://orgmode.org/manual/Publishing.html#Publishing][Publishing]] |
55 | [[http://www.gnu.org/software/texinfo/][Texinfo]] | =./lisp/ox-texinfo.el= | ox-texinfo | |
56 |---------------+----------------------------------+----------------+----------------------------|
57 | [[http://www.atlassian.com/software/confluence/overview/team-collaboration-software][Confluence]] | =./contrib/lisp/ox-confluence.el= | ox-confluence | |
58 | [[http://imakewebthings.com/deck.js/][Deck.js]] | =./contrib/lisp/ox-deck.el= | ox-deck | |
59 | [[http://freemind.sourceforge.net/wiki/index.php/Main_Page][Freemind]] | =./contrib/lisp/ox-freemind.el= | ox-freemind | |
60 | [[http://www.gnu.org/software/groff/][Groff]] | =./contrib/lisp/ox-groff.el= | ox-groff | |
61 | [[http://www.ctan.org/pkg/koma-script][Koma Scrlttr2]] | =./contrib/lisp/ox-koma-letter.el= | ox-koma-letter | |
62 | [[http://www.rssboard.org/rss-specification][RSS]] | =./contrib/lisp/ox-rss.el= | ox-rss | |
63 | [[http://meyerweb.com/eric/tools/s5/][S5]] | =./contrib/lisp/ox-s5.el= | ox-s5 | |
64 | [[http://www.taskjuggler.org/][Taskjuggler]] | =./contrib/lisp/ox-taskjuggler.el= | [[file:taskjuggler/ox-taskjuggler.org][ox-taskjuggler]] | |
65 |---------------+----------------------------------+----------------+----------------------------|
66 | [[http://www.docbook.org/][DocBook]] | (1) | - | - |
68 - (1) DocBook export, available in previous Org-mode versions, has not currently been ported
69 to the new exporter, however the new =ox-texinfo= backend can generate DocBook
70 format. Once =file.texi= is created via =ox-texinfo=, simply execute:
73 makeinfo --docbook file.texi
77 * General Documentation
79 /This page is in progress. Please be patient as it is updated./
81 * TODO Add details about general export usage and information :noexport:
82 * TODO Migrate Nicolas' mailing list summary here :noexport:
84 Here is the [[http://article.gmane.org/gmane.emacs.orgmode/65574][email text]] to allow for easy reference in this document. The contents of his
85 email should end up in this document somehow or another, as this should serve as the
86 primary source of information in addition to the manual for the exporter in general.
88 If you migrate some information to this actual document, please delete it so that the quote below serves as a
91 *Remember:* This is just for general exporter information and usage; backend-specific
92 things should be housed in their appropriate repository. If the page doesn't exist, feel
93 free to create it. There's a template [[file:ox-template.org][here]].
100 1 To Whom Used the Experimental Version
103 .. 2.2 Drawer Handling
104 .. 2.3 Special Blocks
105 .. 2.4 Improved Asynchronous Export
107 .. 2.6 Cross Referencing
108 .. 2.7 Lists of Tables, Lists of Listings
114 .. 4.4 Forking a Back-End
121 I will install the new export framework along with a set of back-ends
122 Wednesday evening (UTC). Here are a few notes to help you make the
126 1 To Whom Used the Experimental Version
127 ═══════════════════════════════════════
129 The merge implies some renaming for symbols and files. More
130 precisely, “e-” is removed from symbols like variable names, functions
131 and back-ends and “org-e-” becomes “ox-” in files. To sum it up:
133 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
135 ───────────────────────────────────────────────────────────
138 org-export-latex-packages-alist org-latex-packages-alist
139 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
141 Be sure to check filters and requires in your configuration files.
147 Even though the internals are completely different, the new exporter
148 mostly behaves like its predecessor. There are only a few noticeable
155 New back-ends come with the new export engine:
157 • Markdown back-end (name: `md')
158 • Texinfo back-end (name: `texinfo')
159 • Man back-end (name: `man')
161 Most of the other back-ends have been rewritten from scratch, too.
167 By default, every drawer but “properties” and “logbook” has its
168 contents exported. See `org-export-with-drawers' variable.
174 The `org-special-blocks.el' library, which has been moved to
175 “contrib/”, is obsolete since its features are included in the new
179 2.4 Improved Asynchronous Export
180 ────────────────────────────────
182 Export can be asynchronous independently on the type of the source
183 or output (temporary buffer or file). A special interface, called
184 “The Export Stack”, is used to view the output. See
185 `org-export-in-background' variable.
191 All back-ends have support for “smart” quotes, according to
192 `org-export-default-language' value or the `LANGUAGE' specifications
193 in the buffer. See `org-export-with-smart-quotes'.
194 As of now, only “de”, “en”, “es” and “fr” languages are supported,
195 but it’s easy to add more. See `org-export-smart-quotes-alist'. Do
196 not hesitate to contribute more languages.
199 2.6 Cross Referencing
200 ─────────────────────
202 Export has now full support for cross references, through targets
203 and `#+NAME' attributes[1]. Pay attention to the following example.
210 │ #+CAPTION: Another table
211 │ #+NAME: other-table
217 │ Look at item [[itm]]! It happens after table [[other-table]].
220 When exported, the last line will be displayed as:
223 │ Look at item 1! It happens after table 2.
226 It doesn’t depend on the back-end used. It also references
227 footnotes, headlines, LaTeX environments…
230 2.7 Lists of Tables, Lists of Listings
231 ──────────────────────────────────────
233 There is support for lists of tables and lists of listings in some
234 back-ends with the following syntax:
252 There are two ways to install export back-ends.
254 1. You may customize `org-export-backends' variable. It contains
255 the list of back-ends that should always be available.
257 2. You can also simply require the back-end libraries
258 (e.g. `(require 'ox-icalendar)' for the iCalendar back-end).
260 Note that with method 1, the back-ends will be loaded only when the
261 export framework is used for the first time.
267 Previously, the export engine was configured through variables and
268 numerous hooks. Now, there are variables, only two hooks and
269 filters. One can also easily fork a new export back-end from an
276 The easiest way to browse configurable variables should be through
277 customize interface. Though, the old export framework is still
278 lurking in the Org shipped with Emacs.
279 As a consequence, calling “customize” will also load previous export
280 engine. It can lead to confusion as variables in both frameworks
281 share the same suffix. You will have to be careful and double check
282 the origin of each variable being considered.
283 Anyway, if you still want to go through this, the following command
284 will get you to the right starting point:
287 │ M-x customize-group RET org-export RET
290 However, I suggest to browse the source files and look after
297 Two hooks are run during the first steps of the export process. The
298 first one, `org-export-before-processing-hook' is called before
299 expanding macros, Babel code and include keywords in the buffer. The
300 second one, `org-export-before-parsing-hook', as its name suggests,
301 happens just before parsing the buffer.
302 Their main use is for heavy duties, that is duties involving
303 structural modifications of the document. For example, one may want
304 to remove every headline in the buffer during export. The following
305 code can achieve this:
308 │ 1 (defun my-headline-removal (backend)
309 │ 2 "Remove all headlines in the current buffer.
310 │ 3 BACKEND is the export back-end being used, as a symbol."
312 │ 5 (lambda () (delete-region (point) (progn (forward-line) (point))))))
313 │ 6 (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
316 Note that functions used in these hooks require a mandatory
317 argument, as shown at line 1.
323 Filters are lists of functions applied on a specific part of the
324 output from a given back-end. More explicitly, each time a back-end
325 transforms an Org object or element into another language, all
326 functions within a given filter type are called in turn on the string
327 produced. The string returned by the last function will be the one
328 used in the final output.
329 There are filters sets for each type of element or object, for plain
330 text, for the parse tree, for the export options and for the final
331 output. They are all named after the same scheme:
332 `org-export-filter-TYPE-functions', where `type' is the type targeted
334 For example, the following snippet allows me to use non-breaking
335 spaces in the Org buffer and get them translated into LaTeX without
336 using the `\nbsp' macro:
339 │ 1 (defun ngz-latex-filter-nobreaks (text backend info)
340 │ 2 "Ensure \" \" are properly handled in LaTeX export."
341 │ 3 (when (org-export-derived-backend-p backend 'latex)
342 │ 4 (replace-regexp-in-string " " "~" text)))
343 │ 5 (add-to-list 'org-export-filter-plain-text-functions
344 │ 6 'ngz-latex-filter-nobreaks)
347 Three arguments must be provided to a fiter (line 1): the code being
348 changed, the back-end used, and some information about the export
349 process. You can safely ignore the third argument for most purposes.
350 Note (line 3) the use of `org-export-derived-backend-p', which ensures
351 that the filter will only be applied when using `latex' back-end or
352 any other back-end derived from it (i.e. `beamer').
355 4.4 Forking a Back-End
356 ──────────────────────
358 This is obviously the most powerful customization, since you work
359 directly at the parser level. Indeed, complete export back-ends are
360 built as forks from other once (e.g. Markdown exporter is forked from
362 Forking a back-end means that if an element type is not transcoded
363 by the new back-end, it will be handled by the original one. Hence
364 you can extend specific parts of a back-end without too much work.
365 As an example, imagine we want the `ascii' back-end to display the
366 language used in a source block, when it is available, but only when
367 some attribute is non-nil, like the following:
370 │ #+ATTR_ASCII: :language t
373 Because the `ascii' back-end is lacking in that area, we are going
374 to create a new back-end, `my-ascii', that will do the job.
377 │ 1 (defun my-ascii-src-block (src-block contents info)
378 │ 2 "Transcode a SRC-BLOCK element from Org to ASCII.
379 │ 3 CONTENTS is nil. INFO is a plist used as a communication
382 │ 6 (org-export-read-attribute :attr_ascii src-block :language)))
383 │ 7 (if (not visiblep)
384 │ 8 (org-export-with-backend 'ascii src-block contents info)
385 │ 9 (let ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)))
388 │ 12 (if utf8p "╭──[ %s ]──\n%s╰────" ",--[ %s ]--\n%s`----")
389 │ 13 (org-element-property :language src-block)
390 │ 14 (replace-regexp-in-string
391 │ 15 "^" (if utf8p "│ " "| ")
392 │ 16 (org-element-normalize-string
393 │ 17 (org-export-format-code-default src-block info)))))))))
395 │ 19 (org-export-define-derived-backend my-ascii parent
396 │ 20 :translate-alist ((src-block . my-ascii-src-block)))
399 The `my-ascii-src-block' function looks at the attribute above the
400 element (line 6). If it isn’t true, it gives hand to the `ascii'
401 back-end (line 8). Otherwise, it creates a box around the code,
402 leaving room for the language. A fork of `ascii' back-end is then
403 created (line 19). It only changes its behaviour when translating
404 `src-block' type element (line 20). Now, all it takes to use the new
405 back-end is calling the following on a buffer:
408 │ (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
411 It is obviously possible to write an interactive function for this,
412 install it in the export dispatcher menu, and so on.
418 1. Although the old exporter files have been archived into
419 “contrib/” directory, they are not usable anymore. Org 7.9 will be
420 the last release to provide it.
422 2. As a consequence, three export back-ends are not available
423 anymore: Taskjuggler, XOXO and Docbook. About the latter, there is
424 a new back-end that produces Texinfo files, which can then be
425 converted into Docbook format with:
428 │ makeinfo --docbook file.texi
431 3. Export section from Org manual is now obsolete. It is being
432 rewritten, but until this task is completed, your best source of
433 information will still be the ML or the source files.
440 [1] Though, it will expect a caption to be properly numbered.