#+TITLE: reStructuredText Back-End for Org Export Engine #+AUTHOR: Masanao Igarashi #+EMAIL: [email protected] #+DATE: 2019/08/13 00:00 #+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 9.0 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: [email protected] ,#+DATE: 2019/08/13 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: [email protected]
  :Date: 2019/08/13 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

*** Special blocks

Org:

#+BEGIN_EXAMPLE ,#+BEGIN_caution This is the second line of the first paragraph. ,#+END_caution #+END_EXAMPLE

reStructuredText:

#+BEGIN_SRC rst .. caution::

  This is the second line of the first paragraph.

#+END_SRC

Org:

#+BEGIN_EXAMPLE ,#+ATTR_RST: :title This is a note admonition. ,#+BEGIN_note This is the second line of the first paragraph. ,#+END_note #+END_EXAMPLE

reStructuredText:

#+BEGIN_SRC rst .. note:: This is a note admonition.

  This is the second line of the first paragraph.

#+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 =verbatim= code +strike-through+ #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst ,bold italic underlined verbatim code 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

Comment block will disapper.

Org: #+BEGIN_EXAMPLE ,#+BEGIN_COMMENT comment ,#+END_COMMENT #+END_EXAMPLE

** 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 This is an <> cross reference target.

Internal cross references, like [[example]] #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst This is an _example cross reference target.

Internal cross references, like example_ #+END_SRC

Org: #+BEGIN_EXAMPLE ,* headline

Internal cross references, [[*headline]] #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst headline

Internal cross references, headline_ #+END_SRC

Org: #+BEGIN_EXAMPLE ,* headline :PROPERTIES: :CUSTOM_ID: customid :END:

Internal cross references, headline [[#customid]] #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst .. _customid:

headline

Internal cross references, headline customid_ #+END_SRC

Org: #+BEGIN_EXAMPLE ,#+NAME: sampletable | a | b | c | | 1 | 2 | 3 |

Internal cross references, label [[sampletable]] #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst .. table:: :name: sampletable

+---+---+---+
| a | b | c |
+---+---+---+
| 1 | 2 | 3 |
+---+---+---+

Internal cross references, label sampletable_ #+END_SRC

Org: #+BEGIN_EXAMPLE ,#+NAME: samplefigure [[./image.jpg]]

Internal cross references, label [[samplefigure]] #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst .. _samplefigure:

.. image:: ./image.jpg

Internal cross references, label samplefigure_ #+END_SRC

** Footnote

Org: #+BEGIN_EXAMPLE ,* footnote sample

Org mode[fn:org] is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

reStructuredText[fn:rest] is plaintext that uses simple and intuitive constructs to indicate the structure of a document.

[fn:org] org-mode [[http://orgmode.org]] [fn:rest] reStructuredText [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]] #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst footnote sample

Org mode [2]_ is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

reStructuredText [1]_ is plaintext that uses simple and intuitive constructs to indicate the structure of a document.

.. [1] reStructuredText http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>_

.. [2] org-mode http://orgmode.org <http://orgmode.org>_ #+END_SRC

** Export reStructuredText fragments

Org: #+BEGIN_EXAMPLE See also @@rst::meth:mypackage.mymodule.MyClass.mymethod()@@.

#+RST: .. class:: alert

,#+BEGIN_EXPORT rst .. class:: alert ,#+END_EXPORT #+END_EXAMPLE

reStructuredText: #+BEGIN_SRC rst See also :meth:mypackage.mymodule.MyClass.mymethod().

.. class:: alert

.. class:: alert #+END_SRC