#+TITLE: reStructuredText Back-End for Org Export Engine
#+AUTHOR: IGARASHI Masanao
#+EMAIL: syoux2@gmail.com
#+DATE: 2013/11/03 13:50
#+DESCRIPTION:
#+KEYWORDS:
#+LANGUAGE: en
#+OPTIONS: H:4 num:nil toc:t ::t |:t ^:t -:t f:t *:t <:t
#+OPTIONS: tex:t todo:t pri:nil tags:t texht:nil
#+OPTIONS: author:t creator:nil email:nil date:t
* Ox-Rst
*Ox-Rst* exports your [[http://orgmode.org][Org]] documents to reStructuredText.
Ox-Rst relies on the Org-mode 8.3 export framework.
* Configuration
Add the following in your init.el
#+BEGIN_SRC lisp
(require 'ox-rst)
#+END_SRC
* reStructuredText export
=ox-rst= export back-end generates reStructuredText syntax for
an Org mode buffer.
** reStructuredText commands
To export your org document to, press =C-c C-e=, and then =r=.
*** =C-c C-e r r (org-rst-export-to-rst)=
Export as a text file written in reStructured syntax.
For an Org file, =myfile.org=, the resulting file will be =myfile.rst=.
The file will be overwritten without warning.
*** =C-c C-e r R (org-rst-export-as-rst)=
Export as a temporary buffer. Do not create a file.
** Title, Author, E-Mail and Date
Org:
#+BEGIN_EXAMPLE
,#+TITLE: This is the title of the document
,#+AUTHOR: Author
,#+EMAIL: mailaddress@example.com
,#+DATE: 2013/12/31 00:00
,#+OPTIONS: author:t date:t email:t
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
This is the title of the document
==================================================================
:Author: Author
:Contact: mailaddress@example.com
:Date: 2013/12/31 00:00
#+END_SRC
** Headings
Org:
#+BEGIN_EXAMPLE
,* Heading 1
contents 1
,** Heading 1-1
contents 1-1
,*** Heading 1-1-3
contents 1-1-3
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
Heading 1
---------
contents 1
Heading 1-1
~~~~~~~~~~~
contents 1-1
Heading 1-1-3
^^^^^^^^^^^^^
contents 1-1-3
#+END_SRC
** Table of contents
Org:
#+BEGIN_EXAMPLE
,#+OPTIONS: toc:t
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. contents::
#+END_SRC
** Lists
Org:
#+BEGIN_EXAMPLE
,** Lord of the Rings
1. The attack of the Rohirrim
2. Eowyn's fight with the witch king
+ this was already my favorite scene in the book
+ I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
- on DVD only
He makes a really funny face when it happens.
But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:
- Elijah Wood :: He plays Frodo
- Sean Austin :: He plays Sam, Frodo's friend. I still remember
him very well from his role as Mikey Walsh in The Goonies.
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
Lord of the Rings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. The attack of the Rohirrim
2. Eowyn's fight with the witch king
- this was already my favorite scene in the book
- I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
- on DVD only
He makes a really funny face when it happens.
But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:
Elijah Wood
He plays Frodo
Sean Austin
He plays Sam, Frodo's friend. I still remember
him very well from his role as Mikey Walsh in The Goonies.
#+END_SRC
** Special Characters
Org:
#+BEGIN_EXAMPLE
special characters * asterisk \ backspace
.. reStructuredText comment line
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
special characters \* asterisk \\ backspace
\.. reStructuredText comment line
#+END_SRC
** Paragraphs
*note* Org line breaks =\\= will be ignored.
*** Verse block
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_VERSE
Great clouds overhead
Tiny black birds rise and fall
Snow covers Emacs
-- AlexSchroeder
,#+END_VERSE
#+END_EXAMPLE
reStructuredText Line Blocks:
#+BEGIN_SRC rst
| Great clouds overhead
| Tiny black birds rise and fall
| Snow covers Emacs
|
| -- AlexSchroeder
#+END_SRC
*** Quote block
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
,#+END_QUOTE
#+END_EXAMPLE
reStructuredText Literal Blocks:
#+BEGIN_SRC rst
::
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+ATTR_RST: :margin 4
,#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
,#+END_QUOTE
,#+ATTR_RST: :margin 8
,#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
,#+END_QUOTE
#+END_EXAMPLE
reStructuredText Block Quotes:
#+BEGIN_SRC rst
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+ATTR_RST: :directive note
,#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
,#+END_QUOTE
#+END_EXAMPLE
reStructuredText Directives:
#+BEGIN_SRC rst
.. note::
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+ATTR_RST: :directive sidebar :title sidebar title
,#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
,#+END_QUOTE
#+END_EXAMPLE
reStructuredText Directives with title:
#+BEGIN_SRC rst
.. sidebar:: sidebar title
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_SRC
*** Center block
Center block will not affect.
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_CENTER
center block
,#+END_CENTER
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
center block
#+END_SRC
** Literal examples
*** example block
Org:
#+BEGIN_EXAMPLE
,#+NAME: label
,#+BEGIN_EXAMPLE
example
,#+END EXAMPLE
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
::
:name: label
example
#+END_SRC
*** src block
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_SRC lisp
(require 'ox-rst)
,#+END SRC
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. code-block:: lisp
(require 'ox-rst)
#+END_SRC
** Emphasis and monospace
Org:
#+BEGIN_EXAMPLE
,*bold* /italic/ _underlined_ =code= ~verbatim~ +strike-through+
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
,**bold** *italic* underlined ``code`` ``verbatim`` strike-through
#+END_SRC
** Subscript and superscript
Org:
#+BEGIN_EXAMPLE
H_{2}O
E = mc^2
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
H\ :sub:`2`\ O
E = mc\ :sup:`2`\
#+END_SRC
** LaTeX fragments
Org:
#+BEGIN_EXAMPLE
If $a^2=b$ and \( b=2 \), then the solution must be
either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
If :math:`a^2=b` and :math:`b=2`, then the solution must be
either
.. math::
a=+\sqrt{2}
or
.. math::
a=-\sqrt{2}
.
#+END_SRC
** Horizontal rules
Org:
#+BEGIN_EXAMPLE
-----
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
------------
#+END_SRC
** Comment block
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_COMMENT
comment
,#+END_COMMENT
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
..
comment
#+END_SRC
** Images and Tables
*** Images
Org:
#+BEGIN_EXAMPLE
,#+ATTR_RST: :alt alternate text :align right
[[./image.jpg]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. image:: ./image.jpg
:alt: alternate text
:align: right
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+CAPTION: image caption
,#+ATTR_RST: :alt alternate text :align center :scale 50%
[[./image.jpg]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. figure:: ./image.jpg
:alt: alternate text
:align: center
:scale: 50%
image caption
#+END_SRC
*** Tables
Org:
#+BEGIN_EXAMPLE
| TOP1 | TOP2 | TOP3 |
| 1 | 2 | 3 |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table::
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+------+------+------+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
Org:
#+BEGIN_EXAMPLE
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1 | 2 | 3 |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table::
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+======+======+======+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
Org:
#+BEGIN_EXAMPLE
|------+------+------|
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1 | 2 | 3 |
|------+------+------|
| AAAA | BBBB | CCCC |
|------+------+------|
| END1 | END2 | END3 |
|------+------+------|
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table::
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+======+======+======+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+CAPTION: caption
,#+NAME: label
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1 | 2 | 3 |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table:: caption
:name: label
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+======+======+======+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
** Hyperlinks
*** External hyperlinks
Org:
#+BEGIN_EXAMPLE
[[http://orgmode.org][Org Mode]]
[[http://orgmode.org]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
`Org Mode `_
`http://orgmode.org`_
#+END_SRC
*** Internal links
Org:
#+BEGIN_EXAMPLE
Internal crossreferences, like [[example]]
<>
This is an example crossreference target.
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
Internal crossreferences, like `example`_
.. _example:
This is an example crossreference target.
#+END_SRC
** Export reStructuredText fragments
Org:
#+BEGIN_EXAMPLE
,#+RST: .. class:: alert
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. class:: alert
#+END_SRC