echo Impossible|sed 's/Im/To be /'

March 08, 2017

Emacs Org-mode format export to reStructuredText

Emacs Org-mode format export to reStructuredText

reStructuredText 使用經驗

工作上寫技術文件的比重就越來越高了,文件是很重要的溝通工具。依時間演進下所使用的工具如下:

LinuxSGML -> CJK-LaTex ChiLaTex -> DocBook -> OO.o -> CJK-LaTex -> reStructuredText

reST 我由 2009 年開始使用直到現在,投資報酬率很高,累積的工具也越來越多。其間也試用過 Markdown , 個人主觀經驗作為文件排版格式 reST 還是比較合適。

Markdown 原始設計,易讀的純文字檔,便於轉換成 xhtml html。就設計的概念及推廣實作它是非常成功的,但作為文件還是少了些特性,如表格、 目錄章節、索引、註腳、列印、出版等功能。但以網路流通性易學及多人協作上考量,它是目前首選。

Org-mode - Emacs 上的殺手級應用,作為 GTD 實踐工具,我由 2010 年開始使用。它大大的改善工作習慣及效率,以及時間掌握與應用。 隨著時間對 Org-mode 使用也走出了單純的 GTD 工具往簡報、Mind Map、Project Management、簡易試算表、簡易資料庫、文件加密、Literate programming 等使用面向。但文件排版與個人筆記我還是交給 reST + Latex + Sphinx。

最近我開始使用 org-mode + ox-rst 來產出 reST 文件。原因無他,就是 Emacs org-mode 實在是太方便及好用了。

Ox-Rst exports your Org documents to reStructuredText. Ox-Rst relies on the Org-mode 9.0 export framework.

一般來說,文件格式的轉換會有失真的現象。例如 html 轉 text,hyperlink 字型及顏色的特性就會失去。但 ox-rst 很巧妙的在 org-mode 語法上作了合宜的擴充,幾乎可以一對一轉換,強烈推薦給 reST 及 org-mode 的愛用者。

問題筆記

在使用上遇到了一個比較困擾的問題,就是 ^ 插入符號 Caret 及 _ 底線 Underscore 的使用,這兩個符號在 org-mode 上會特別解釋。情況如下:

model^rgb_led = modelrgbled
L^A T_E X = LATEX

如果要避免這個問題,在 org-mode 把 ^ 設定為不解釋即可,作法如下:

#+OPTIONS: ^:nil

reStructuredText 與 ox-rst 使用入門

ox-rst 是個 Emacs Org-mode 的延伸使用套件 GitHub ox-rst 官網 已經有很詳細的使用說明文件。但使用的關鍵還是在 reST 的語法熟悉上, 畢竟實際還是在寫 reST。以下是 OpenFoundry 上的兩篇介紹文,提供給有興趣的人參考。

Posted by Lloyd Huang in on March 08, 2017