initial commit

README.org

@@ -0,0 +1,503 @@
+#+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.0 export framework.
+
+* Configuration
+
+  Add the following in your init.el
+
+#+BEGIN_SRC emacs-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_SRC org-mode
+#+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_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+This is the title of the document
+==================================================================
+
+    :Author: Author
+    :Contact: mailaddress@example.com
+    :Date: 2013/12/31 00:00
+#+END_SRC
+
+** Headings
+
+   Org:
+#+BEGIN_SRC org-mode
+* Heading 1
+
+contents 1
+
+** Heading 1-1
+
+contents 1-1
+
+*** Heading 1-1-3
+
+contents 1-1-3
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+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_SRC org-mode
+#+OPTIONS: toc:t
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+.. contents::
+
+#+END_SRC
+
+** Lists
+
+   Org:
+#+BEGIN_SRC org-mode
+** 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
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+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_SRC org-mode
+special characters * asterisk \ backspace
+.. reStructuredText comment line
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+special characters \* asterisk \\ backspace
+\.. reStructuredText comment line
+#+END_SRC
+
+** Paragraphs
+
+*note* Org line breaks =\\= will be ignored.
+
+*** Verse block
+
+   Org:
+#+BEGIN_SRC org-mode
+#+BEGIN_VERSE
+ Great clouds overhead
+      Tiny black birds rise and fall
+      Snow covers Emacs
+
+          -- AlexSchroeder
+#+END_VERSE
+#+END_SRC
+
+   reStructuredText Line Blocks:
+#+BEGIN_SRC rst-mode
+| Great clouds overhead
+|      Tiny black birds rise and fall
+|      Snow covers Emacs
+| 
+|          -- AlexSchroeder
+| 
+#+END_SRC
+
+*** Quote block
+
+   Org:
+#+BEGIN_SRC org-mode
+#+BEGIN_QUOTE
+Everything should be made as simple as possible,
+  but not any simpler -- Albert Einstein
+#+END_QUOTE
+#+END_SRC
+
+   reStructuredText Literal Blocks:
+#+BEGIN_SRC rst-mode
+::
+
+    Everything should be made as simple as possible,
+      but not any simpler -- Albert Einstein
+#+END_SRC
+
+   Org:
+#+BEGIN_SRC org-mode
+#+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_SRC
+
+   reStructuredText Block Quotes:
+#+BEGIN_SRC rst-mode
+    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_SRC org-mode
+#+ATTR_RST: :directive note
+#+BEGIN_QUOTE
+Everything should be made as simple as possible,
+but not any simpler -- Albert Einstein
+#+END_QUOTE
+#+END_SRC
+
+   reStructuredText Directives:
+#+BEGIN_SRC rst-mode
+.. note::
+
+    Everything should be made as simple as possible,
+    but not any simpler -- Albert Einstein
+#+END_SRC
+
+   Org:
+#+BEGIN_SRC org-mode
+#+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_SRC
+
+   reStructuredText Directives with title:
+#+BEGIN_SRC rst-mode
+.. 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_SRC org-mode
+#+BEGIN_CENTER
+center block
+#+END_CENTER
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+center block
+#+END_SRC
+
+** Literal examples
+
+*** example block
+
+   Org:
+#+BEGIN_SRC org-mode
+#+NAME: label
+#+BEGIN_EXAMPLE
+example
+#+END EXAMPLE
+#+END_SRC
+
+# maybe github org parser's bug
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+::
+    :name: label
+
+    example
+#+END_SRC
+
+*** src block
+
+   Org:
+#+BEGIN_SRC org-mode
+#+BEGIN_SRC org-mode
+(require 'ox-rst)
+#+END SRC
+#+END_SRC
+
+# maybe github org parser's bug
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+.. code-block:: org-mode
+
+    (require 'ox-rst)
+#+END_SRC
+
+** Emphasis and monospace
+
+   Org:
+#+BEGIN_SRC org-mode
+*bold* /italic/ _underlined_ =code= ~verbatim~ +strike-through+
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+**bold** *italic* underlined ``code`` ``verbatim`` strike-through
+#+END_SRC
+
+** Horizontal rules
+
+   Org:
+#+BEGIN_SRC org-mode
+-----
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+------------
+#+END_SRC
+
+
+** Comment block
+
+   Org:
+#+BEGIN_SRC org-mode
+#+BEGIN_COMMENT
+comment
+#+END_COMMENT
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+..
+    comment
+#+END_SRC
+
+** Images and Tables
+
+*** Images
+
+   Org:
+#+BEGIN_SRC org-mode
+#+ATTR_RST: :alt alternate text :align right
+[[./image.jpg]]
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+.. image:: ./image.jpg
+    :alt: alternate text
+    :align: right
+#+END_SRC
+
+   Org:
+#+BEGIN_SRC org-mode
+#+CAPTION: image caption
+#+NAME: label
+#+ATTR_RST: :alt alternate text :align center :scale 50%
+[[./image.jpg]]
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+.. figure:: ./image.jpg
+    :alt: alternate text
+    :align: center
+    :scale: 50%
+
+    image caption
+#+END_SRC
+
+
+*** Tables
+
+   Org:
+#+BEGIN_SRC org-mode
+|------+------+------|
+| TOP1 | TOP2 | TOP3 |
+|------+------+------|
+| 1    | 2    | 3    |
+|------+------+------|
+| AAAA | BBBB | CCCC |
+|------+------+------|
+| END1 | END2 | END3 |
+|------+------+------|
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+.. table::
+
+    +------+------+------+
+    | TOP1 | TOP2 | TOP3 |
+    +------+------+------+
+    | 1    | 2    | 3    |
+    +------+------+------+
+    | AAAA | BBBB | CCCC |
+    +------+------+------+
+    | END1 | END2 | END3 |
+    +------+------+------+
+#+END_SRC
+
+   Org:
+#+BEGIN_SRC org-mode
+#+CAPTION: caption
+#+NAME: label
+|------+------+------|
+| TOP1 | TOP2 | TOP3 |
+|------+------+------|
+| 1    | 2    | 3    |
+|------+------+------|
+| AAAA | BBBB | CCCC |
+|------+------+------|
+| END1 | END2 | END3 |
+|------+------+------|
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+.. table:: caption
+    :name: label
+
+    +------+------+------+
+    | TOP1 | TOP2 | TOP3 |
+    +------+------+------+
+    | 1    | 2    | 3    |
+    +------+------+------+
+    | AAAA | BBBB | CCCC |
+    +------+------+------+
+    | END1 | END2 | END3 |
+    +------+------+------+
+#+END_SRC
+
+** Hyperlinks
+
+   Org:
+#+BEGIN_SRC org-mode
+[[http://orgmode.org][Org Mode]]
+
+[[http://orgmode.org]]
+
+[[label]]
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+`Org Mode <http://orgmode.org/>`_
+
+`http://orgmode.org`_
+
+`label`_
+#+END_SRC
+
+** Export reStructuredText fragments
+
+   Org:
+#+BEGIN_SRC org-mode
+#+RST: .. class:: alert
+#+END_SRC
+
+   reStructuredText:
+#+BEGIN_SRC rst-mode
+.. class:: alert
+#+END_SRC