exporters/ox-overview.org

   1 #+TITLE:      The New Org-mode Exporter Framework
   2 #+AUTHOR:     John Henderson
   3 #+EMAIL:      jw.hendy[at]gmail[dot]com
   4 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
   6 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   7 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
   8 #+LANGUAGE:   en
   9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
  10 #+HTML_LINK_UP:    ../ox-overview.html
  11 #+HTML_LINK_HOME:  https://orgmode.org/worg/
  12 #+EXCLUDE_TAGS: noexport
  13
  14 # This file is released by its authors and contributors under the GNU
  15 # Free Documentation license v1.3 or later, code examples are released
  16 # under the GNU General Public License v3 or later.
  17
  18 [[file:index.org][{Back to Worg's index}]]
  19
  20 * Introduction
  21
  22 As of release 8.0, Org-mode has transitioned to a new export framework, authored
  23 primarily (/entirely?/) by Nicolas Goaziou...
  24
  25 #+begin_example
  26
  27 Perhaps this could be filled in with some of the technical reasons and advantages
  28 of the new exporter by Nicolas or someone else familiar with with it's inner workings?
  29
  30 #+end_example
  31
  32 For instructions on how to upgrade from the previous Org-mode exporter, see
  33 [[file:../org-8.0.org][the upgrade guide]].
  34
  35 Nicolas' official announcement of the exporter may be viewed at the [[https://orgmode.org/list/876229nrxf.fsf@gmail.com][Org-mode mailing list
  36 post]]. This document presents an overview of features, as well as a list of currently
  37 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
  38 manual]]. See [[file:ox-docstrings.org][ox-docstrings]] and [[file:org-element-docstrings.org][org-element-docstrings]] for the extracted
  39 docstrings from these two core libraries of the new Org-mode exporter, i.e.
  40 for detailled technical information about the exporter framework.
  41
  42 * List of Org-mode exporters
  43
  44 Please find below a list of current Org-mode exporters, the location of the backend elisp
  45 file (relative to downloaded Org-mode installation directory, =org=) and links Worg and
  46 Org-mode manual documentation.
  47
  48 | *Name*          | *Exporter location*                | *Worg Tutorial*  | *Org-mode Manual*            |
  49 |---------------+----------------------------------+----------------+----------------------------|
  50 | 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]] |
  51 | [[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]]        |
  52 | HTML          | =./lisp/ox-html.el=                | ox-html        | [[https://orgmode.org/manual/HTML-export.html#HTML-export][HTML export]]                |
  53 | [[https://en.wikipedia.org/wiki/ICalendar][iCalendar]]     | =./lisp/ox-icalandar.el=           | ox-icalendar   |                            |
  54 | [[http://www.latex-project.org/][LaTeX]]         | =./lisp/ox-latex.el=               | ox-latex       | [[https://orgmode.org/manual/LaTeX-export.html#LaTeX-export][LaTeX export]]               |
  55 | [[http://manpages.bsd.lv/history.html][Man]]           | =./lisp/ox-man.el=                 | ox-man         |                            |
  56 | [[http://daringfireball.net/projects/markdown/][Markdown]]      | =./lisp/ox-md.el=                  | ox-md          |                            |
  57 | [[http://opendocumentformat.org/][ODT]]           | =./lisp/ox-odt.el=                 | ox-odt         | [[https://orgmode.org/manual/OpenDocument-Text-export.html#OpenDocument-Text-export][OpenDocument Text export]]   |
  58 | [[https://orgmode.org/manual/Publishing.html][Publishing]]    | =./lisp/ox-publish.el=             | ox-publish     | [[https://orgmode.org/manual/Publishing.html#Publishing][Publishing]]                 |
  59 | [[http://www.gnu.org/software/texinfo/][Texinfo]]       | =./lisp/ox-texinfo.el=             | ox-texinfo     |                            |
  60 |---------------+----------------------------------+----------------+----------------------------|
  61 | [[http://www.atlassian.com/software/confluence/overview/team-collaboration-software][Confluence]]    | =./contrib/lisp/ox-confluence.el=  | ox-confluence  |                            |
  62 | [[http://imakewebthings.com/deck.js/][Deck.js]]       | =./contrib/lisp/ox-deck.el=        | ox-deck        |                            |
  63 | [[http://freemind.sourceforge.net/wiki/index.php/Main_Page][Freemind]]      | =./contrib/lisp/ox-freemind.el=    | ox-freemind    |                            |
  64 | [[http://www.gnu.org/software/groff/][Groff]]         | =./contrib/lisp/ox-groff.el=       | ox-groff       |                            |
  65 | [[http://www.ctan.org/pkg/koma-script][Koma Scrlttr2]] | =./contrib/lisp/ox-koma-letter.el= | ox-koma-letter |                            |
  66 | [[http://www.rssboard.org/rss-specification][RSS]]           | =./contrib/lisp/ox-rss.el=         | ox-rss         |                            |
  67 | [[http://meyerweb.com/eric/tools/s5/][S5]]            | =./contrib/lisp/ox-s5.el=          | ox-s5          |                            |
  68 | [[http://www.taskjuggler.org/][Taskjuggler]]   | =./contrib/lisp/ox-taskjuggler.el= | [[file:taskjuggler/ox-taskjuggler.org][ox-taskjuggler]] |                            |
  69 |---------------+----------------------------------+----------------+----------------------------|
  70 | [[http://www.docbook.org/][DocBook]]       | (1)                              | -              | -                          |
  71
  72 - (1) DocBook export, available in previous Org-mode versions, has not currently been ported
  73   to the new exporter, however the new =ox-texinfo= backend can generate DocBook
  74   format. Once =file.texi= is created via =ox-texinfo=, simply execute:
  75
  76 #+begin_example
  77 makeinfo --docbook file.texi
  78 #+end_example
  79
  80 * General Documentation
  81
  82 /This page is in progress. Please be patient as it is updated./
  83
  84 * TODO Add details about general export usage and information      :noexport:
  85 * TODO Migrate Nicolas' mailing list summary here                  :noexport:
  86
  87 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
  88 email should end up in this document somehow or another, as this should serve as the
  89 primary source of information in addition to the manual for the exporter in general.
  90
  91 If you migrate some information to this actual document, please delete it so that the quote below serves as a
  92 body of "todo" text.
  93
  94 *Remember:* This is just for general exporter information and usage; backend-specific
  95 things should be housed in their appropriate repository. If the page doesn't exist, feel
  96 free to create it. There's a template [[file:ox-template.org][here]].
  97
  98 #+begin_quote
  99
 100 Table of Contents
 101 ─────────────────
 102
 103 1 To Whom Used the Experimental Version
 104 2 What’s New
 105 .. 2.1 New Back-Ends
 106 .. 2.2 Drawer Handling
 107 .. 2.3 Special Blocks
 108 .. 2.4 Improved Asynchronous Export
 109 .. 2.5 Smart Quotes
 110 .. 2.6 Cross Referencing
 111 .. 2.7 Lists of Tables, Lists of Listings
 112 3 Installation
 113 4 Configuration
 114 .. 4.1 Variables
 115 .. 4.2 Hooks
 116 .. 4.3 Filters
 117 .. 4.4 Forking a Back-End
 118 5 Caveats
 119 6 Footnotes
 120
 121
 122       Hello,
 123
 124   I will install the new export framework along with a set of back-ends
 125 Wednesday evening (UTC).  Here are a few notes to help you make the
 126 transition.
 127
 128
 129 1 To Whom Used the Experimental Version
 130 ═══════════════════════════════════════
 131
 132     The merge implies some renaming for symbols and files. More
 133   precisely, “e-” is removed from symbols like variable names, functions
 134   and back-ends and “org-e-” becomes “ox-” in files. To sum it up:
 135
 136        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 137                   Old name                      New name
 138        ───────────────────────────────────────────────────────────
 139                    e-latex                       latex
 140                  org-e-latex                    ox-latex
 141         org-export-latex-packages-alist  org-latex-packages-alist
 142        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 143
 144     Be sure to check filters and requires in your configuration files.
 145
 146
 147 2 What’s New
 148 ════════════
 149
 150     Even though the internals are completely different, the new exporter
 151   mostly behaves like its predecessor.  There are only a few noticeable
 152   changes.
 153
 154
 155 2.1 New Back-Ends
 156 ─────────────────
 157
 158     New back-ends come with the new export engine:
 159
 160   • Markdown back-end (name: `md')
 161   • Texinfo back-end (name: `texinfo')
 162   • Man back-end (name: `man')
 163
 164     Most of the other back-ends have been rewritten from scratch, too.
 165
 166
 167 2.2 Drawer Handling
 168 ───────────────────
 169
 170     By default, every drawer but “properties” and “logbook” has its
 171   contents exported.  See `org-export-with-drawers' variable.
 172
 173
 174 2.3 Special Blocks
 175 ──────────────────
 176
 177     The `org-special-blocks.el' library, which has been moved to
 178   “contrib/”, is obsolete since its features are included in the new
 179   export framework.
 180
 181
 182 2.4 Improved Asynchronous Export
 183 ────────────────────────────────
 184
 185     Export can be asynchronous independently on the type of the source
 186   or output (temporary buffer or file).  A special interface, called
 187   “The Export Stack”, is used to view the output.  See
 188   `org-export-in-background' variable.
 189
 190
 191 2.5 Smart Quotes
 192 ────────────────
 193
 194     All back-ends have support for “smart” quotes, according to
 195   `org-export-default-language' value or the `LANGUAGE' specifications
 196   in the buffer.  See `org-export-with-smart-quotes'.
 197     As of now, only “de”, “en”, “es” and “fr” languages are supported,
 198   but it’s easy to add more.  See `org-export-smart-quotes-alist'.  Do
 199   not hesitate to contribute more languages.
 200
 201
 202 2.6 Cross Referencing
 203 ─────────────────────
 204
 205     Export has now full support for cross references, through targets
 206   and `#+NAME' attributes[1].  Pay attention to the following example.
 207
 208   ╭────
 209   │ #+CAPTION: A table
 210   │ #+NAME: table
 211   │ | a | b |
 212   │
 213   │ #+CAPTION: Another table
 214   │ #+NAME: other-table
 215   │ | c | d |
 216   │
 217   │ 1. <<itm>>item 1
 218   │ 2. item 2
 219   │
 220   │ Look at item [[itm]]! It happens after table [[other-table]].
 221   ╰────
 222
 223     When exported, the last line will be displayed as:
 224
 225   ╭────
 226   │ Look at item 1! It happens after table 2.
 227   ╰────
 228
 229     It doesn’t depend on the back-end used.  It also references
 230   footnotes, headlines, LaTeX environments…
 231
 232
 233 2.7 Lists of Tables, Lists of Listings
 234 ──────────────────────────────────────
 235
 236     There is support for lists of tables and lists of listings in some
 237   back-ends with the following syntax:
 238
 239   ╭────
 240   │ #+TOC: headlines
 241   ╰────
 242
 243   ╭────
 244   │ #+TOC: tables
 245   ╰────
 246
 247   ╭────
 248   │ #+TOC: listings
 249   ╰────
 250
 251
 252 3 Installation
 253 ══════════════
 254
 255     There are two ways to install export back-ends.
 256
 257   1. You may customize `org-export-backends' variable.  It contains
 258      the list of back-ends that should always be available.
 259
 260   2. You can also simply require the back-end libraries
 261      (e.g. `(require 'ox-icalendar)' for the iCalendar back-end).
 262
 263     Note that with method 1, the back-ends will be loaded only when the
 264   export framework is used for the first time.
 265
 266
 267 4 Configuration
 268 ═══════════════
 269
 270     Previously, the export engine was configured through variables and
 271   numerous hooks.  Now, there are variables, only two hooks and
 272   filters. One can also easily fork a new export back-end from an
 273   existing one.
 274
 275
 276 4.1 Variables
 277 ─────────────
 278
 279     The easiest way to browse configurable variables should be through
 280   customize interface.  Though, the old export framework is still
 281   lurking in the Org shipped with Emacs.
 282     As a consequence, calling “customize” will also load previous export
 283   engine.  It can lead to confusion as variables in both frameworks
 284   share the same suffix.  You will have to be careful and double check
 285   the origin of each variable being considered.
 286     Anyway, if you still want to go through this, the following command
 287   will get you to the right starting point:
 288
 289   ╭────
 290   │ M-x customize-group RET org-export RET
 291   ╰────
 292
 293     However, I suggest to browse the source files and look after
 294   `defcustom' entries.
 295
 296
 297 4.2 Hooks
 298 ─────────
 299
 300     Two hooks are run during the first steps of the export process.  The
 301   first one, `org-export-before-processing-hook' is called before
 302   expanding macros, Babel code and include keywords in the buffer.  The
 303   second one, `org-export-before-parsing-hook', as its name suggests,
 304   happens just before parsing the buffer.
 305     Their main use is for heavy duties, that is duties involving
 306   structural modifications of the document.  For example, one may want
 307   to remove every headline in the buffer during export.  The following
 308   code can achieve this:
 309
 310   ╭────
 311   │ 1  (defun my-headline-removal (backend)
 312   │ 2    "Remove all headlines in the current buffer.
 313   │ 3  BACKEND is the export back-end being used, as a symbol."
 314   │ 4    (org-map-entries
 315   │ 5     (lambda () (delete-region (point) (progn (forward-line) (point))))))
 316   │ 6  (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
 317   ╰────
 318
 319     Note that functions used in these hooks require a mandatory
 320   argument, as shown at line 1.
 321
 322
 323 4.3 Filters
 324 ───────────
 325
 326     Filters are lists of functions applied on a specific part of the
 327   output from a given back-end.  More explicitly, each time a back-end
 328   transforms an Org object or element into another language, all
 329   functions within a given filter type are called in turn on the string
 330   produced.  The string returned by the last function will be the one
 331   used in the final output.
 332     There are filters sets for each type of element or object, for plain
 333   text, for the parse tree, for the export options and for the final
 334   output.  They are all named after the same scheme:
 335   `org-export-filter-TYPE-functions', where `type' is the type targeted
 336   by the filter.
 337     For example, the following snippet allows me to use non-breaking
 338   spaces in the Org buffer and get them translated into LaTeX without
 339   using the `\nbsp' macro:
 340
 341   ╭────
 342   │ 1  (defun ngz-latex-filter-nobreaks (text backend info)
 343   │ 2    "Ensure \" \" are properly handled in LaTeX export."
 344   │ 3    (when (org-export-derived-backend-p backend 'latex)
 345   │ 4          (replace-regexp-in-string " " "~" text)))
 346   │ 5  (add-to-list 'org-export-filter-plain-text-functions
 347   │ 6               'ngz-latex-filter-nobreaks)
 348   ╰────
 349
 350     Three arguments must be provided to a fiter (line 1): the code being
 351   changed, the back-end used, and some information about the export
 352   process.  You can safely ignore the third argument for most purposes.
 353   Note (line 3) the use of `org-export-derived-backend-p', which ensures
 354   that the filter will only be applied when using `latex' back-end or
 355   any other back-end derived from it (i.e. `beamer').
 356
 357
 358 4.4 Forking a Back-End
 359 ──────────────────────
 360
 361     This is obviously the most powerful customization, since you work
 362   directly at the parser level.  Indeed, complete export back-ends are
 363   built as forks from other once (e.g. Markdown exporter is forked from
 364   the HTML one).
 365     Forking a back-end means that if an element type is not transcoded
 366   by the new back-end, it will be handled by the original one.  Hence
 367   you can extend specific parts of a back-end without too much work.
 368     As an example, imagine we want the `ascii' back-end to display the
 369   language used in a source block, when it is available, but only when
 370   some attribute is non-nil, like the following:
 371
 372   ╭────
 373   │ #+ATTR_ASCII: :language t
 374   ╰────
 375
 376     Because the `ascii' back-end is lacking in that area, we are going
 377   to create a new back-end, `my-ascii', that will do the job.
 378
 379   ╭────
 380   │  1  (defun my-ascii-src-block (src-block contents info)
 381   │  2    "Transcode a SRC-BLOCK element from Org to ASCII.
 382   │  3  CONTENTS is nil.  INFO is a plist used as a communication
 383   │  4  channel."
 384   │  5    (let ((visiblep
 385   │  6           (org-export-read-attribute :attr_ascii src-block :language)))
 386   │  7      (if (not visiblep)
 387   │  8          (org-export-with-backend 'ascii src-block contents info)
 388   │  9        (let ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)))
 389   │ 10          (concat
 390   │ 11           (format
 391   │ 12            (if utf8p "╭──[ %s ]──\n%s╰────" ",--[ %s ]--\n%s`----")
 392   │ 13            (org-element-property :language src-block)
 393   │ 14            (replace-regexp-in-string
 394   │ 15             "^" (if utf8p "│ " "| ")
 395   │ 16             (org-element-normalize-string
 396   │ 17              (org-export-format-code-default src-block info)))))))))
 397   │ 18
 398   │ 19  (org-export-define-derived-backend my-ascii parent
 399   │ 20    :translate-alist ((src-block . my-ascii-src-block)))
 400   ╰────
 401
 402     The `my-ascii-src-block' function looks at the attribute above the
 403   element (line 6).  If it isn’t true, it gives hand to the `ascii'
 404   back-end (line 8).  Otherwise, it creates a box around the code,
 405   leaving room for the language.  A fork of `ascii' back-end is then
 406   created (line 19).  It only changes its behaviour when translating
 407   `src-block' type element (line 20).  Now, all it takes to use the new
 408   back-end is calling the following on a buffer:
 409
 410   ╭────
 411   │ (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
 412   ╰────
 413
 414     It is obviously possible to write an interactive function for this,
 415   install it in the export dispatcher menu, and so on.
 416
 417
 418 5 Caveats
 419 ═════════
 420
 421   1. Although the old exporter files have been archived into
 422      “contrib/” directory, they are not usable anymore.  Org 7.9 will be
 423      the last release to provide it.
 424
 425   2. As a consequence, three export back-ends are not available
 426      anymore: Taskjuggler, XOXO and Docbook.  About the latter, there is
 427      a new back-end that produces Texinfo files, which can then be
 428      converted into Docbook format with:
 429
 430      ╭────
 431      │ makeinfo --docbook file.texi
 432      ╰────
 433
 434   3. Export section from Org manual is now obsolete.  It is being
 435      rewritten, but until this task is completed, your best source of
 436      information will still be the ML or the source files.
 437
 438
 439
 440 Footnotes
 441 ─────────
 442
 443 [1] Though, it will expect a caption to be properly numbered.
 444
 445 #+end_quote