寫文件要使用什麼工具？xelatex以及Docbook超簡介

在我心中，一個好的程式是那些不需要讀說明書就可以使用到它七成以上功能的那些。這類的程式多半會有相當精巧的設計，讓人得以輕鬆上手。然而，對大部分程式來說，一般人可能只能參透這個程式最主軸的幾成（三到五成吧）功能。這樣子其實是相當可惜的不是嗎？天生我才必有用，程式設計人員不可能會把沒有用的功能放在自己的程式裡面（「會心一笑」和「炫耀」在這裡都算是有用的功能）。

對於一個設計沒那麼精良的程式來說，程式設計人員自然有自己的私人筆記可以讓未來的自己了解自己程式有多少能耐；具有程式閱讀能力的人可以藉著程式碼來推敲程式的功能（但會很辛苦）；但對於一般人來說，探索新大陸可能不會是那麼有趣，甚至是一個相當折磨人的過程。或者是，有些人不太把握程式是否有能力去精確的達到某個目標，就索性不用了。使用者難過，程式傷心，如果開發者知道了那一定也會很失望吧？

這時候就需要文件來上場救援啦！一個文件可以指引使用者了解一個程式所具有的功能以及調用某功能所需要的操作步驟，也可以告訴使用者這個程式的系統需求或限制，甚至也可以作為開發人員和使用者的溝通橋樑（開發者的聯絡方式，FAQ等）。一個寫得很好的文件可以彌補使用者界面設計的缺陷，也可以用來增強已經設計得很棒的軟體（Tips & tricks）。

說了這麼多，總之想說不如開始尋找好用的文件寫作工具，來替BF解譯程式寫個文件（見這篇。BF見此Wiki條目）。講到寫文件，大家或許會直接想到使用所見即所得的文字編輯器（LibreOffice Writer, Calligra Words，MS Word, etc）。這類的工具可以讓開發人員在某個方向上很輕鬆的編輯他們的文件。這類的程式不需要複雜的設定，很快就可以上手，也可以很快的就排出一份中上程度的文件。然而，這類編輯器所產出的文件都不是純文字格式，無法隨心所欲的修改：需要安裝一個大傢伙才可以修改的可稱不上輕鬆！因此這類的工具不在考慮之列。雖然可憐，但得麻煩它們退到一邊了。

接下來剩下的知名工具只剩下Docbook和Latex了。這兩者有許多共通的，文書編輯軟體沒有的優點。首先，這些工具所需要的文件原始檔是純文字，可以在任何的地方做編修。當然，如果編修用的電腦上面沒有相關的工具組，就要憑著想像力來建構文件最後的樣貌了（所幸這並不會太困難）。其次，這兩者，尤其是Docbook，把文件的內容型態以及格式區分開來了。在使用那些文書處理軟體的時候，它們不會勉強使用者去區分格式以及內容。所以，使用者們就養成了「一邊寫文件一邊排版」的習慣，讓整個文件毫無章法的混在一起，也讓使用者無法專心於內容的撰寫。Docbook的文件原始碼則是xml的延伸，用以標記一段文字所代表的意義。用一句話來總結的話，文書處理軟體不會（也不需要）知道這段文字是程式碼、一般文字、還是按鍵、指令等；Docbook文件處理程式則可以透過Docbook原始檔知道某一段文字是不是一段註腳、或是注意事項等，再依據這些資訊來進行格式化。

總之接下來就是很難下的，Docbook與latex的抉擇了！由於我有機會撰寫中文文件，所以必須要選擇可以輕鬆處理中文的工具組...。就結論上來說，這兩者都無法像使用文書處理軟體一般的自然使用中文字型：Docbook如果要輸出到pdf檔，就要有恰當的中文字型檔，還要做一番設定，並且確定不支援OpenType特有的功能（ligature)；latex的部份，則可以使用xelatex+fontconfig或xelatex+xeCJK來進行編排，但要讓整個系統可以安穩的運作，則需要做一些設定：在Fedora 18裡面，安裝xelatex本身不保證所有的相依套件都安裝完成...

經過昨天晚上的一番測試，基本上的設定都已經了解了。目前我個人比較偏好Docbook那般有系統有結構而且沒有格式負擔的原始碼。在我看來xelatex仍然有一些格式與內文混合的情況，雖然說比word好很多。或許兩種都來試試看...

Docbook相關設定

Docbook是一個xml檔案。經由精心設計的xsl檔案，我們可以把Docbook文件轉換成純文字檔案，網頁檔等各式各樣的格式。使用下面的指令，就可以做到剛才所說的神奇轉換：

xsltproc xslFile docbookFile > outputFile

例如

#利用預設的參數產生html檔案
xsltproc /usr/share/sgml/docbook/xsl-stylesheets/html/\
 myDocument.xml > ./build/myDocument.html

然而若想要利用Docbook來產生pdf文件，則需要額外的步驟。目前流傳在Docbook使用者之間常用的製作pdf方法是，首先利用xsl把Docbook檔案轉換成Fomatting Object檔案：

xsltproc /usr/share/sgml/docbook/xsl-stylesheets/fo/\
 myDocument.xml > ./build/myDocument.fo

接著使用Apache基金會的fop來產生pdf檔：

#預設設定，英文文件沒問題！
fop -fo ./build/myDocument.fo -pdf ./build/myDocument.pdf

然而如果在文件中使用中文，就必須教育fop，讓它正確的使用我們好看的字型。雖然說最近的fop版本具有可以自己偵測系統字型的能力，但經過實測後發現fop的自動偵測無法正確的處理ttc字型（TrueType Collection）。不能自動就只好手動囉！說實話我搞不懂為什麼fop沒辦法自動的從ttc字型檔中選擇在Docbook中有使用到的字型。
首先，我們產生字型xml檔。該xml檔包含了所選定字型中所有字的形狀大小等資訊：

java -cp /usr/share/java/fop.jar:\
/usr/share/java/avalon-framework.jar:\
/usr/share/java/commons-io.jar:\
/usr/share/java/commons-logging.jar:\
/usr/share/java/xmlgraphics-commons.jar\
 org.apache.fop.fonts.apps.TTFReader
inputFont outputXml\
-ttcname familyName

接著，寫一個fop設定檔如下：

<!--config.foc-->
<fop version="1.0">
  <base>./</base>
  <strict-configuration>
    true
  </strict-configuration>
  <renderers>
    <renderer mime="application/pdf">
      <filterList>
        <value>flate</value>
      </filterList>
      <fonts>
        <font embed-url="/usr/share/fonts/wqy-microhei/wqy-microhei.ttc"
              metrics-url="wqymh.xml">
          <font-triplet name="WenQuanYi Micro Hei"
                        style="normal" weight="normal"/>
        </font>
        <!--可以在這裡添加喜歡的字型-->
        <auto-detect/>
        <!--神奇的自動偵測無法處理ttc，但可以處理ttf字型！-->
      </fonts>
    </renderer>
  </renderers>
</fop>

完成後執行

fop -fo a.fo -c config.foc -pdf a.pdf

xelatex設定

相對於Docbook的設定，xelatex的設定較為簡潔，但不是那麼有邏輯性：誰想得到texlive的打包人員沒有完美的解決相依性的問題？總之我用下面的指令安裝了相關的套件才得以進行測試：

sudo yum install texlive-xetex-bin texlive-xecjk
sudo yum install texlive
sudo yum install texlive-xetex-def
sudo yum install texlive-fontspec
sudo yum install texlive-euenc