exporters/ox-overview.org

   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
  13
  14 [[file:index.org][{Back to Worg's index}]]
  15
  16 * Introduction
  17
  18 As of release 8.0, Org-mode has transitioned to a new export framework, authored
  19 primarily (/entirely?/) by Nicolas Goaziou...
  20
  21 #+begin_example
  22
  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?
  25
  26 #+end_example
  27
  28 For instructions on how to upgrade from the previous Org-mode exporter, see
  29 [[file:../org-8.0.org][the upgrade guide]].
  30
  31 Nicolas' official announcement of the exporter may be viewed at the [[https://orgmode.org/list/876229nrxf.fsf@gmail.com][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.
  37
  38 * List of Org-mode exporters
  39
  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.
  43
  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)                              | -              | -                          |
  67
  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:
  71
  72 #+begin_example
  73 makeinfo --docbook file.texi
  74 #+end_example
  75
  76
  77 * General Documentation
  78
  79 /This page is in progress. Please be patient as it is updated./
  80
  81 * TODO Add details about general export usage and information      :noexport:
  82 * TODO Migrate Nicolas' mailing list summary here                  :noexport:
  83
  84 Here is the [[https://orgmode.org/list/876229nrxf.fsf@gmail.com][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.
  87
  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.
  90
  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]].
  94
  95 #+begin_quote
  96
  97 Table of Contents
  98 ─────────────────
  99
 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
 117
 118
 119       Hello,
 120
 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.
 124
 125
 126 1 To Whom Used the Experimental Version
 127 ═══════════════════════════════════════
 128
 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:
 132
 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        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 140
 141     Be sure to check filters and requires in your configuration files.
 142
 143
 144 2 What’s New
 145 ════════════
 146
 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.
 150
 151
 152 2.1 New Back-Ends
 153 ─────────────────
 154
 155     New back-ends come with the new export engine:
 156
 157   • Markdown back-end (name: `md')
 158   • Texinfo back-end (name: `texinfo')
 159   • Man back-end (name: `man')
 160
 161     Most of the other back-ends have been rewritten from scratch, too.
 162
 163
 164 2.2 Drawer Handling
 165 ───────────────────
 166
 167     By default, every drawer but “properties” and “logbook” has its
 168   contents exported.  See `org-export-with-drawers' variable.
 169
 170
 171 2.3 Special Blocks
 172 ──────────────────
 173
 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.
 177
 178
 179 2.4 Improved Asynchronous Export
 180 ────────────────────────────────
 181
 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.
 186
 187
 188 2.5 Smart Quotes
 189 ────────────────
 190
 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.
 197
 198
 199 2.6 Cross Referencing
 200 ─────────────────────
 201
 202     Export has now full support for cross references, through targets
 203   and `#+NAME' attributes[1].  Pay attention to the following example.
 204
 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   ╰────
 219
 220     When exported, the last line will be displayed as:
 221
 222   ╭────
 223   │ Look at item 1! It happens after table 2.
 224   ╰────
 225
 226     It doesn’t depend on the back-end used.  It also references
 227   footnotes, headlines, LaTeX environments…
 228
 229
 230 2.7 Lists of Tables, Lists of Listings
 231 ──────────────────────────────────────
 232
 233     There is support for lists of tables and lists of listings in some
 234   back-ends with the following syntax:
 235
 236   ╭────
 237   │ #+TOC: headlines
 238   ╰────
 239
 240   ╭────
 241   │ #+TOC: tables
 242   ╰────
 243
 244   ╭────
 245   │ #+TOC: listings
 246   ╰────
 247
 248
 249 3 Installation
 250 ══════════════
 251
 252     There are two ways to install export back-ends.
 253
 254   1. You may customize `org-export-backends' variable.  It contains
 255      the list of back-ends that should always be available.
 256
 257   2. You can also simply require the back-end libraries
 258      (e.g. `(require 'ox-icalendar)' for the iCalendar back-end).
 259
 260     Note that with method 1, the back-ends will be loaded only when the
 261   export framework is used for the first time.
 262
 263
 264 4 Configuration
 265 ═══════════════
 266
 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.
 271
 272
 273 4.1 Variables
 274 ─────────────
 275
 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:
 285
 286   ╭────
 287   │ M-x customize-group RET org-export RET
 288   ╰────
 289
 290     However, I suggest to browse the source files and look after
 291   `defcustom' entries.
 292
 293
 294 4.2 Hooks
 295 ─────────
 296
 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:
 306
 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   ╰────
 315
 316     Note that functions used in these hooks require a mandatory
 317   argument, as shown at line 1.
 318
 319
 320 4.3 Filters
 321 ───────────
 322
 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:
 337
 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   ╰────
 346
 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').
 353
 354
 355 4.4 Forking a Back-End
 356 ──────────────────────
 357
 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:
 368
 369   ╭────
 370   │ #+ATTR_ASCII: :language t
 371   ╰────
 372
 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.
 375
 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   ╰────
 398
 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:
 406
 407   ╭────
 408   │ (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
 409   ╰────
 410
 411     It is obviously possible to write an interactive function for this,
 412   install it in the export dispatcher menu, and so on.
 413
 414
 415 5 Caveats
 416 ═════════
 417
 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.
 421
 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:
 426
 427      ╭────
 428      │ makeinfo --docbook file.texi
 429      ╰────
 430
 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.
 434
 435
 436
 437 Footnotes
 438 ─────────
 439
 440 [1] Though, it will expect a caption to be properly numbered.
 441
 442 #+end_quote