很少人用 rst (reStructuredText) 來當文件格式。

不過，rst 很棒！除了還看不懂 TeX 數式之外，幾乎適用於所有種類的文稿。可以用來寫日記、寫心得、寫報告、寫書。當然，rst 是「文稿」格式，所以不符合排版需要。但是，rst 可以轉成 LaTeX 再作後處理！

我用 rst 寫文稿寫了好多年；這個 blog 主要的稿子都是用 rst 寫就的。當然，本站的讀者看不到 rst markup (想想真可惜，rst 格式比較簡潔，也許以後改版加上 rst format download link?)，因為每發佈一次文章，後台就會把該文稿用 docutils 把 rst 格式轉為 HTML 格式。

docutils 是什麼？其實就是 rst 文稿處理器，現在已經算是 Python 世界裡 de facto 的文稿處理標準了。

docutils 為 rst 提供了好些轉換程式，讓 rst 非常好寫好用。可是，這樣還不能解放 rst 完整的威力！如果要用 rst 再強化我們的文稿撰寫效率，那就要自己寫程式轉檔，這樣才能載入批次威能，引入ベルカ式系統能力。

為了在撰寫 script 批次轉換 rst 檔為 HTML 的時候，可以把 docutils 組態寫在 script 本體裡面 (就不要再多一個 docutils.conf 組態檔啦，累贅)，就這麼作：

settings_overrides = {
    # general.
    'language_code': 'zh_tw',
    'input_encoding': 'utf-8',
    'output_encoding': 'utf-8',
    'footnote_backlinks': 1,
    'toc_backlinks': 'top',
    # html4css1 writer.
    'compact_lists': True,
    'embed_stylesheet': True,
    'stylesheet_path': os.path.splitext(__file__)[0]+'.css',
    'footnote_references': 'superscript',
}

src = "source text"
dst = "destination path"
writer_name = "html"

publish_file(
    source_path=src,
    destination_path=dst,
    writer_name=writer_name,
    settings_overrides=settings_overrides, )

快樂 docutils scripting！

docutils 是 Python 世界裡最強大、簡單、常用的 plaintext markup 語言與處理工具，定義了 reStructuredText 標記語言 (a.k.a rst)，並且開放完整的 API 供開發人員對 rst 進行操作。docutils 本身內建有幾種轉換程式，可以把 rst 轉換成 HTML, HTML S5 (由 HTML 及 JavaScript 所構成的投影片應用) 以及 LaTeX 等格式。

rst 功能強大，很適合用來撰寫網路文件。如果能夠進一步掌握 docutils API，更可以自行撰寫程式，把以 rst 寫成的文件轉換成任意的格式。我們能夠用 rst 來當作日常撰文的格式，在需要的時候用 docutils 所提供的指令稿轉換為 HTML, LaTeX 等檔案，或是利用 docutils API 輸出成我們自已想要的格式。

docutils API 很清楚地將 rst 的處理工作分成四個部分 (請參考 Docutils Hacker's Guide)：read, parse, trasform, write；讀析轉寫。我們關心的是輸出，只要實作自訂的 writer 即可。

這兩天花了幾個小時改出一個客製版的 docutils writer。修改的過程相當愉快，很順利地就從研究 docutils writer 的過程中了解了 docutils 內部的資料結構。經過 docutils 讀取、解析、轉換後的 rst 會變成一個樹狀結構，writer 將從根部的 document 節點一路巡訪到最後一個葉節點，完成整份文件的輸出動作。

如果有興趣研究 docutils writer 的話，可以從 docutils.writers.html4css1 開始讀起，再參考 docutils.nodes 裡面定義的節點與結構。用 docutils 來製作自己的 rst 轉檔程式會是一件簡單而有趣的事情。

Vim 7.0 on win32 的 reStructuredText syntax 檔，在 highlight inline markup 的時候不能接受 inline markup 裡只有單獨的字元，然後讓 highlight syntax 爛掉。

沒找到別人的解法，所以我拿 2004 年放出來的初版 rst.vim 裡的 syntax command 暫時對付一下，在 rst.vim 的 s:DefineInlineMarkup 函式最後面加上：

execute 'syn region rstInlineLiteral start="' . \
        a:start . '" end="' . a:end . '"'

(大概是在第 118 行的地方，要加在 endfunction 之前)。如此一來，Vim 會用最 aggresive 的方式 matching syntax，inline markup 裡的單獨字元便不再弄壞 highlighting 了。