598 lines
11 KiB
Org Mode
598 lines
11 KiB
Org Mode
#+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/>`_
|
|
|
|
`http://orgmode.org`_
|
|
#+END_SRC
|
|
|
|
*** Internal links
|
|
|
|
Org:
|
|
#+BEGIN_EXAMPLE
|
|
Internal crossreferences, like [[example]]
|
|
|
|
<<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
|