Fix more broken links
[worg.git] / exporters / ox-overview.org
blobf572caa9dfd2341474488aea99718a72b7a6fc4a
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
8 #+LANGUAGE:   en
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}]]
16 * Introduction
18 As of release 8.0, Org-mode has transitioned to a new export framework, authored
19 primarily (/entirely?/) by Nicolas Goaziou...
21 #+begin_example
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?
26 #+end_example
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:
72 #+begin_example
73 makeinfo --docbook file.texi
74 #+end_example
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
89 body of "todo" text.
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]].
95 #+begin_quote
97 Table of Contents
98 ─────────────────
100 1 To Whom Used the Experimental Version
101 2 What’s New
102 .. 2.1 New Back-Ends
103 .. 2.2 Drawer Handling
104 .. 2.3 Special Blocks
105 .. 2.4 Improved Asynchronous Export
106 .. 2.5 Smart Quotes
107 .. 2.6 Cross Referencing
108 .. 2.7 Lists of Tables, Lists of Listings
109 3 Installation
110 4 Configuration
111 .. 4.1 Variables
112 .. 4.2 Hooks
113 .. 4.3 Filters
114 .. 4.4 Forking a Back-End
115 5 Caveats
116 6 Footnotes
119       Hello,
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
123 transition.
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        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
134                   Old name                      New name
135        ───────────────────────────────────────────────────────────
136                    e-latex                       latex
137                  org-e-latex                    ox-latex
138         org-export-latex-packages-alist  org-latex-packages-alist
139        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
141     Be sure to check filters and requires in your configuration files.
144 2 What’s New
145 ════════════
147     Even though the internals are completely different, the new exporter
148   mostly behaves like its predecessor.  There are only a few noticeable
149   changes.
152 2.1 New Back-Ends
153 ─────────────────
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.
164 2.2 Drawer Handling
165 ───────────────────
167     By default, every drawer but “properties” and “logbook” has its
168   contents exported.  See `org-export-with-drawers' variable.
171 2.3 Special Blocks
172 ──────────────────
174     The `org-special-blocks.el' library, which has been moved to
175   “contrib/”, is obsolete since its features are included in the new
176   export framework.
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.
188 2.5 Smart Quotes
189 ────────────────
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.
205   ╭────
206   │ #+CAPTION: A table
207   │ #+NAME: table
208   │ | a | b |
209   │
210   │ #+CAPTION: Another table
211   │ #+NAME: other-table
212   │ | c | d |
213   │
214   │ 1. <<itm>>item 1
215   │ 2. item 2
216   │
217   │ Look at item [[itm]]! It happens after table [[other-table]].
218   ╰────
220     When exported, the last line will be displayed as:
222   ╭────
223   │ Look at item 1! It happens after table 2.
224   ╰────
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:
236   ╭────
237   │ #+TOC: headlines
238   ╰────
240   ╭────
241   │ #+TOC: tables
242   ╰────
244   ╭────
245   │ #+TOC: listings
246   ╰────
249 3 Installation
250 ══════════════
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.
264 4 Configuration
265 ═══════════════
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
270   existing one.
273 4.1 Variables
274 ─────────────
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:
286   ╭────
287   │ M-x customize-group RET org-export RET
288   ╰────
290     However, I suggest to browse the source files and look after
291   `defcustom' entries.
294 4.2 Hooks
295 ─────────
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:
307   ╭────
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."
311   │ 4    (org-map-entries
312   │ 5     (lambda () (delete-region (point) (progn (forward-line) (point))))))
313   │ 6  (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
314   ╰────
316     Note that functions used in these hooks require a mandatory
317   argument, as shown at line 1.
320 4.3 Filters
321 ───────────
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
333   by the filter.
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:
338   ╭────
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)
345   ╰────
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
361   the HTML one).
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:
369   ╭────
370   │ #+ATTR_ASCII: :language t
371   ╰────
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.
376   ╭────
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
380   │  4  channel."
381   │  5    (let ((visiblep
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)))
386   │ 10          (concat
387   │ 11           (format
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)))))))))
394   │ 18
395   │ 19  (org-export-define-derived-backend my-ascii parent
396   │ 20    :translate-alist ((src-block . my-ascii-src-block)))
397   ╰────
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:
407   ╭────
408   │ (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
409   ╰────
411     It is obviously possible to write an interactive function for this,
412   install it in the export dispatcher menu, and so on.
415 5 Caveats
416 ═════════
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:
427      ╭────
428      │ makeinfo --docbook file.texi
429      ╰────
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.
437 Footnotes
438 ─────────
440 [1] Though, it will expect a caption to be properly numbered.
442 #+end_quote