編寫技術文檔,我想誰都遇到過。很多人都用MS Word,不可否認Word的功能確實非常強大,但是用Word有一些缺點無法避免:
1) 寫文檔的時候,不得不兼顧文檔的格式,這是件很頭痛的事情,至少對我來說。經常是最后不得不Review好幾遍,就是為了統一格式,即使使用模板也不能避免這個問題。
2) 無法進行有效的版本控制,因為Word保存的是二進制格式,這就不能使用CVS的版本控制功能,只能手工合并,這樣很容易出錯。雖然Word現在也可以保存成XML,但是看一下保存的文件就會發現,格式和內容混雜在一起,簡直沒法看。況且,版本控制的時候,我們注重的往往是內容,現在卻不得不處理大量的格式信息,至少我沒興趣把時間花在這個上面。
3) 可移植性問題,畢竟Word只能運行在Windows平臺上,即使可以保存為XML或者HTML,在其他平臺上你又如何編輯和打印呢?
4) 用盜版還是正版的問題,公司不得不考慮知識產權這個比較嚴肅的話題。
講到這里,很多人可能會自然而然的想到XML+XSLT+開源代碼。Docbook正是基于XSLT把內容和形式分開的思想開發的,它可以解決上述的所有問題。
那么到底什么是Docbook?
Docbook是一些標準和工具的集合。標準包括XML、DTD、XSL、XSL-FO和Docbook DTD(Docbook的核心),工具則包括XSLT Processor和XSL-FO Processor。這些標準和工具組成基于Docbook的發布系統。
Docbook原本是為了編寫和發布技術文檔而開發的,O'Reily是發起者之一,但實際上它也可以用于其他類型的文檔,因為它所定義的結構符合大部分現代書籍的格式。
Docbook的核心是Docbook DTD,這個標準是由OASIS的Docbook小組維護的。這個標準對文檔的結構進行了詳細的定義,譬如書(book元素)可以包含一個標題(title),若干的段落(para)和若干的章節(chapter),等等。這些都符合常規書籍的出版格式。
使用Docbook編寫文檔,實際上就是根據Docbook DTD編輯XML文件的過程。所有的內容都用標簽封裝起來,Docbook提供了十分詳盡的定義,幾乎任何內容都可以根據其用途找到對應的標簽。在編輯文檔的過程中,作者只需要關心內容,根本不會涉及到排版的問題。
要發布Docbook文檔,必須使用XSLT。專為Docbook使用的XSLT不屬于Docbook的核心,任何人都可以編寫自己的XSLT。當然,你不用真的自己寫(除非你有興趣),已經有人做了這方面的工作,你可以在SourceForge找到Norman Walsh開發的Docbook樣式單,寫這篇文章的時候,最新版本是1.67.2。
如果最終發布Docbook文檔,自然需要用到XSLT Processor和XSL-FO Processor這類的工具,可供選擇開源工具很多,像xsltproc、Xalan、FOP和PassiveTeX等等。這些工具實際上也是與Docbook無關的。因此不用浪費時間在網上找Docbook的專門工具,只要找到按標準實現的工具,就可以用來發布Docbook文檔。
總的來說,Docbook的發布流程是這樣的:
1) 編寫XML文檔;
2) 使用XSLT Processor把XML文檔轉換成HTML文檔,或者XSL-FO文檔;
3) 使用XSL-FO Processor將XSL-FO文檔轉換為PDF或者PS文件。
因此,Docbook有下列優點:
1) 內容與格式分離;
2) 內容高度結構化;
3) 平臺無關;
4) 發布過程可以自動化;
5) 易于版本控制;
6) 可以生成多種形式的文檔。
Docbook的缺點就是非WYSIWYG,編輯的時候不如Word那么直觀,直接編輯XML文件還是一件比較煩瑣的事情。但是這個問題并不嚴重,使用專門的XML編輯器就可以讓工作輕松很多,譬如Emacs就支持Docbook文檔的編輯。至于效果,使用工具生成最終文檔是非常快的。相對于它的優點而言,這點缺點又算的了什么呢。
參考資料:
Docbook
Docbook Publishing Model
安裝配置Docbook工具
制作Docbook文檔