Pandoc 是一款命令行轉檔軟體。不過和一般人對轉檔軟體的印象不同,它所轉換的對象不是影片,而是標記語言。
Pandoc 能將 Markdown、reStructuredText、textile、HTML、DocBook、LaTeX 格式轉換為……
Windows 與 Mac OS X 使用者,請從下面的網頁下載安裝: https://code.google.com/p/pandoc/downloads/list
至於 Linux 與 BSD 使用者,請檢查您的套件庫,從套件庫安裝即可。倘若套件庫版本過舊,官網也有提供使用源碼包安裝的方式。詳情請參看這頁: https://johnmacfarlane.net/pandoc/installing.html
前面說過了,Pandoc 是款命令行軟體,所以請打開終端機,咱們開始下指令吧。
先看下面這行:
pandoc demo.rst -o demo.md
這就是最簡單的 Pandoc 用法。
pandoc
是 Pandoc 的主程式,Pandoc 的所有操作都是透過這個程式執行的。demo.rst
指定了轉檔時的輸入檔案,-o demo.md
則是輸出檔案。如果不用 -o
參數指定輸出檔名,Pandoc 就會直接將結果輸出到標準輸出上(一般說來,這是指終端機上)。
Pandoc 會透過副檔名,自動判斷輸入與輸出的檔案格式。像上面那一行,輸入檔案會被自動視為 reStructuredText 而輸出檔案則會被自動視為 markdown。
您也可以透過 -f 與 -t 參數強制指定輸入與輸出的格式,比方說:
pandoc demo.txt -o output.txt -f markdown -t html
以上這句指令,會將輸入檔案「demo.txt」視為 markdown 格式,並將它轉為 html 格式後,存到 output.txt 位置上。
-f、-t 後面可接哪些格式名稱?請參看這裡: https://johnmacfarlane.net/pandoc/README.html#general-options
在 Pandoc 支援的格式中,想用 Pandoc 產生 pdf 檔又多了幾個小撇步,讓我試好久,請聽我說明解釋。
pandoc 的 PDF 產生功能是透過 LaTeX 來做的,所以除了主程式外,使用前還得先裝別的外掛程式。在 Linux 上,這個程式就是 texlive 包,請自行抓來裝。如果光裝 texlive 包 Pandoc 轉 pdf 時還是跑不起來,就將 texlive-cjk 包和 texlive-xetex 包也裝上,這樣就該沒問題了。
兩個包合計將近 500 MB,真是夠大的……
裝好了之後,就請立刻執行看看吧:
pandoc demo.rst -o demo.pdf
若您的 demo.rst 是純英文的,照上面操作就可以順利產生 pdf 檔案了。然而如果原始文件檔中含有其他字元(比方說中文字),執行之後 pdf 產生不出來,反而會吐出「Undefined control sequence」如何如何的錯誤訊息,這是因為預設的 latex 引擎不支援中文的緣故。
為了解決這個問題,必須改用能支援 Unicode 的 xelatex 引擎。
此外預設的字型也不包括中文,為了順利顯示,這邊還需要另外指定中文字型。總之就是下面這行(指定的字型是文泉驛微米黑,您可以替換成您希望的。請記得用英文名稱):
pandoc demo.rst -o demo.pdf --latex-engine=xelatex -V mainfont="WenQuanYi Micro Hei"
如此一來就能順利產生出中文的 pdf 檔案了。
不過,儘管順利產生了 pdf,但某些問題依然存在(比方說中文的 line break),這些東西必須透過校調模版才能解決。接下來筆者會介紹一下 Pandoc 的模版,但關於如何用 XeTeX 設定中文 pdf 文件已經超出本文範圍,網路上有很多這方面資料,個人推荐新手參考這一頁來修改模版:https://electronic-blue.wikidot.com/doc:xetex
模版 (template) 是用來告訴 Pandoc,它應該要用什麼格式來產生目的檔案用的。
說得更具體一點:字型如何?字要多大?頁面寬度多寬?加重語氣時要用黑體還是斜體?……這些都有賴模版進行設定。
不同的目標檔案格式,其模版的基本格式也不一樣。比方說 html 的模版就會是 CSS 與 html 的混合,latex 就是 .tex 格式……諸如此類。此外,模版中還會混有 pandoc 專屬的內部程式碼。
嗯……這樣說好像很複雜。不過只要擁有相應格式的撰寫經驗,修改預設模版其實並不難,試試看就知道了。但第一步,您要先找到這些模版被放在哪裡。
在我的 (Linux) 電腦上,預設模版被堆放在這個位置:
/usr/share/pandoc-1.9.2/templates
您也可以用以下指令叫出某格式的模版,來閱讀或另存:
pandoc -D html | less #
閱讀 html 格式的模版
pandoc -D html > mytemplate.txt #
另存到 mytemplate.txt
中
得到範本後,就可以依樣畫葫蘆地修改他們了。
怎麼修改等會兒再說。總之,當您將模版修改好後,就可以透過 --template 參數套用它。如同下面這行:
pandoc demo.rst -o demo.html --template=mytemplate.txt
您可以用模版功能來進行絕大多數的格式自定義,自由度相當高。至於少部份無法透過模版架構進行自訂的東西,在 Pandoc 指令後方往往也能追加一些特殊參數來處理。具體有哪些參數可用,還請參看官網的參數列表:https://johnmacfarlane.net/pandoc/README.html#options
如果您剛剛試著看過任何一個 Pandoc 模版,這時恐怕正感到頭暈,因為模版裡面堆滿了錢……不,應該說是「$」符號。這些「$」符號被兩兩成對地運用著,像我們平常使用括號那樣夾著某些東西。
這就是 Pandoc 所使用的模版巨集語句!包括以下幾種:
1. if 判斷→ $if(變數名)$ $else$ $endif$
2. for 迴圈→ $for(變數名)$ $endfor$
3. 變數→ $變數名$
有這些東西就能玩出很多花樣了,比方說:
$if(largefontsize)$ font-size: $largefontsize$; $endif$
這行表示,當使用者有指定 largefontsize 時,才將 font-size: $largefontsize$; 這行寫入 CSS 中……哎,可玩的東西很多啦。
說了那麼多,那麼該如何將變數具體指定為某個值呢?
我們回來看看 pdf 篇最後的範例:
pandoc demo.rst -o demo.pdf --latex-engine=xelatex -V mainfont="WenQuanYi Micro Hei"
這行中,「-V mainfont=...」也可以寫成「--veriable mainfont=...」。更直接點說,這段指令將一個名叫 mainfont 的變數,設定為 "WenQuanYi Micro Hei" 的值……
這樣應該完全理解了吧?變數就是如此了。
您可以看看官方說明 (https://johnmacfarlane.net/pandoc/README.html#templates),內容和我這邊寫的差不多;不過下面多了些常見變數的命名與介紹,那些東西我就不費事重複了,需要變數資料的人請自己查一下。
Pandoc 轉檔很方便,但程式本身還是有些問題。至少在筆者的經驗中,1.9.2 版透過命令行輸入時,若輸入的字串中包含任何非英文字元,就會報錯。
但這並不是 Pandoc 內部不能處理非英文路徑,而似乎是 Pandoc 的「命令行介面」不能傳入非英文字元,這理由在下也搞不清楚。
如果不幸碰上,稍微更名一下就能將它給繞過了。
以下是推荐的閱讀清單。