Hi,
I once tried to write a tutorial for creating a derived backend, but
didn't find the time to finish it. I put the material so far below.
When I began writing my ox-blog exporter (github.com/roklein/ox-blog) I
think I began with the s5 exporter in org's source contrib/lisp/ox-s5.el.
If you need to export to a format an existing exporter already provides
(at least in part) you will want to create a derived exporter (using the
`org-export-define-derived-backend'). For a totally new format (e.g.
rtf) you' want to write an independent exporter using
`org-export-define-backend'.
Comprehensive documentation for both functions is provided in the source
code (lisp/ox.el)
The non-derived exporters for html and latex (lisp/ox-html.el and
lisp/ox-latex.el) are also very good as examples.
Best regards
Robert
* Minimal derived exporter
A minimal derived exporter providing capabilities of the HTML
exporter.
Please compare the code to the =org-export-define-backend= call in
=org-mode/lisp/ox-html.el=. The =:menu-entry= part is very similar,
in fact I copied the code for the menu entries from the =:menu-entry=
line downward omitting the =?h= and =?o= entries. The other change is
the key =2= instead of =h= for the original HTML exporter.
#+begin_src emacs-lisp :tangle ox-html-2.el
(require 'ox-html)
(org-export-define-derived-backend
'html-2 'html
:menu-entry
'(?2 Export w/ minimal derived HTML
((?H To temporary buffer org-html-export-as-html
(provide 'ox-html-2)
#+end_src
The derived back-end in the example calls the same exporting function
as the HTML back-end does for exporting to a temporary buffer,
=org-html-export-as-html=.
The minimal derived exporter is a new name and a menu entry for
calling the new exporter.
This exporter offers nothing the HTML exporter doesn't.
In the next example we will “write” an exporting function of our own
--- well, copy, rename, and adapt the =org-html-export-as-html=
function from =org-mode/lisp/ox-html.el=.
* Defining export for an org-mode element
In this example we will look at a derived backend which produces the
content of a weblog post in a temporary buffer.
Blogs at e.g. wordpress.com allow syntax highliging using the Syntax
Highlighter written by Alex Gorbatchev.
Our derived exporter will create the text of the blog post and source
code blocks will be marked up for Syntax Highlighter instead of
org-mode's internal mark-up.
You will have to copy the export in the temporary buffer and paste it
into the wordpress blog editor, though.[fn:: We will come back to
weblog exporting again, later. You might want to write a derived
exporter in this style for something you need every one in a while,
where you don't mind a bit of additional effort. For daily tasks you
will want something more elaborate. In web log exporting this would
include the exporter posting to the weblog.]
** Defining the derived backend.
At first we define the backend again. In comparison to the html-2
backend above the options to export to file and export to file and
open are removed.
In addition we have one entry in the =:translate-alist=: for exporting
source blocks the function =wp-dot-com-src-block= will be used.
#+begin_src emacs-lisp :tangle wp-dot-com-buffer.el
(require 'ox-html)
(org-export-define-derived-backend
'wp-dot-com-buffer 'html
:menu-entry
'(?3 Export w/ minimal derived HTML
((?H To temporary buffer org-wp-dot-com-export-as-html)))
:translate-alist
'((src-block . wp-dot-com-src-block)))
#+end_src
** language identifier mapping
The Syntax Highlighter uses sometimes other language identifiers for
source blocks than org-mode. For example, where org-mode uses =sh=,
Syntax Highlighter uses =bash=.
We're putting the mappings in an alist for later use.
#+begin_src emacs-lisp :tangle wp-dot-com-buffer.el
(defconst wp-dot-com-language-terms
'((R . r)
(emacs-lisp . lisp)
(elisp . lisp)
(sh . bash)))
; (cdr (assoc sh wp-dot-com-language-terms))
; (cdr (assoc (org-element-property :language src-block)
wp-dot-com-language-terms)
#+end_src
** exporting source code blocks
The source code exporting function, =wp-dot-com-src-block=, is
modelled on =org-html-src-block= in =org-mode/lisp/ox-html.el=.
To keep things simple, the caption and label code is deleted. The
language identifier is mapped using the mapping defined in the alist
above. The HTML-formatting of the source code is removed, instead of
=org-html-format-code= we use =org-export-unravel-code=. At last the
=pre= formatting in angles is changed to =code= in brackets.
#+begin_src emacs-lisp :tangle wp-dot-com-buffer.el
(defun wp-dot-com-src-block (src-block contents info)
Transcode a SRC-BLOCK element from Org to HTML.
CONTENTS holds the contents of the item. INFO is a plist holding
contextual information.
(if (org-export-read-attribute :attr_html src-block :textarea)
(org-html--textarea-block
