自由軟件發布方法慣例

http://www.linux.org.tw/CLDP/OLD/Software-Release-Practice-HOWTO/t1.html

 

Abstract

本文檔詳細說明了如何發布一個Linux系統下的自由軟件項目。依據這些說明，您就可以讓用戶非常容易 的編譯并使用您的代碼，同時也可以讓其他熱心的開發人員很容易讀懂您的代碼并參與到您的項目中來， 并優化、改進她。 本文檔對與開發者來說應該算作是一本必讀教材。即使是有經驗的程序員在發布他們的軟件時也需要溫 習一下本文檔。另外本文檔會定期修訂以反映軟件發布實踐中更好的做法。

 

文中讲到文档的编写惯例

 

好的文檔編寫慣例

最重要的文檔編寫慣例就是多寫一些！很多程序員都輕視這些事情。但 是下面兩個理由可以讓您明白您必須去做文檔工作：

 

1. 文檔可以指導您的實踐。 寫文檔的最佳時機是在您一行代碼還沒有編寫 時就應該開始，此時您需要想想您打算做點什么。您會發現用自然語言思考 程序應該完成什么功能可以促使您從更高的層次考慮軟件是什么樣以及 她該如何工作。這種思考可以節省許多以后的時間。

2. 文檔是代碼的招牌。 許多程序員為他們的程序只提供了少的可憐、內 容匱乏、語言差勁的蹩腳文檔，這實際上等于向其他人展示說，寫這個文 檔的程序員對潛在用戶的需求也同樣會粗心大意、馬馬虎虎。相反，好的 文檔則會向其他人傳達出文檔背后的程序員是非常聰明、專業的人。如果 有一些類似的項目正在與您的競爭，一定要寫出好的文檔來，至少不能 讓潛在用戶瞥了兩眼您的文檔后就立即否定您的項目。

這份文檔雖然著眼于文檔編寫實踐，但并不是一份專門介紹如何寫出好文 檔的詳細講義。因此下面我們將重點介紹文檔格式和編寫工具的選取。

雖然開源社區長期的傳統就是擁有強大的文檔格式化工具，但是為數眾多 的文檔格式仍然使得整個系統的文檔支離破碎，很難用一種統一的方法全 局檢索和閱讀文檔。下面我們將先介紹各種流行的文檔格式的用途以及他 們的優劣，然后再給出一些編寫好文檔的建議。

現行的一些好的做法

這里將列出一些在開源軟件開發群體中流行的一些文檔格式。當我們文中 提到“展示”標記，就是指那些控制文檔顯示的標記（如字體）。當我們 提到“結構”標記，就是指那些描述文檔結構的標記（如段落、強調標記）。 當我們提到“索引化”，則是指從眾多文檔中萃取出可檢索的關鍵字集合 的過程，“索引化”可以幫助用戶在整個文檔中可靠的找出自己感興趣的 資料。

 

man手冊頁

這是最普通的文檔格式，來源于UNIX系統，是一種原始的“展示”標記格式。 man(1)命令提供了頁顯示和原始的搜索手段。這種格式不支持圖象、超鏈接 和“索引化”功能。不過這種格式轉化成Postscript進行打印的效果還不錯， 就是轉成HTML格式不太方便（主要是純文本）。man 的相關工具在各個Linux 系統中几乎都有。

手冊頁格式做為命令用法解釋或者短小的參考文檔還是不錯的，對一個有經 驗的用戶這樣做可以非常節省內存。那些有著復雜用戶界面和很多選項的程 序會讓系統負載非常重，如果交叉鏈接太多的文檔甚至會讓整個系統不堪重 負。（Man手冊格式不支持超文本鏈接）。

HTML文檔

自從1993－1994年互聯網流行起來后，HTML標記格式開始流行，這種標記格 式有一定的結構，也便于“展示”，還可通過網絡瀏覽器瀏覽，對圖象和超 級鏈接也有支持。不過自帶的“索引化”功能很有限，因此搜索引擎技朮得 到了大力的發展。這種格式也可以很好的被打印出來，相關的制作工具數不 勝數。

HTML標記語言非常靈活，非常適用于各種文檔。實際上她太靈活了，甚至可 以展示Man手冊頁格式的信息。不過問題在于她很難自動檢索，因為這種格 式中太多的標記被用于描述“展示”信息，而鮮有標記描述文檔的結構。

Texinfo文檔

Texinfo格式是自由軟件基金會推荐使用的格式。她是在強大的Tex格式引擎 上建立的一套宏。擁有許多結構信息和部分表示信息。可以用Emacs瀏覽， 或者用專門的info程序閱讀。這個格式支持超級鏈接，但是不支持圖象﹔ 無論是打印出來還是在線閱讀都可以很好的“索引化”﹔如果您裝了某個 Texinfo格式的文檔，該文檔的信息就被整合到系統的全局目錄表中。這種 格式還可以很好的被轉換為Postscript格式和HTML格式，相關工具在大多數 Linux系統中都是預先安裝好的，當然您也可以從自由軟件基金會的網站上下載(http://www.gnu.org)。

Texinfo有著很好的設計，非常適合于完全字符編排的書籍和小的在線文檔， 但是和HTML格式一樣，她也是一種兩棲格式──既有表示“結構”的標記， 又有表示“展示”的標記，“展示”標記給文檔進一步處理帶來了一些麻煩。

DocBook格式

DocBook是一種強大且精巧的基于SGML（當前XML的前身）的標記格式。和 前面几種文檔結構不同，這個標記格式只包含“結構”信息，而沒有“展 示”信息。她可以很好的支持圖片和超級鏈接﹔支持“索引化”﹔很易于 轉換成HTML格式和便于打印的Postscript格式（而且隨著工具功能的增強， 打印效果還可進一步提高）。該格式的文檔和相關工具可以從DocBook的網站(http://www.docbook.org)下載。

DocBook在處理大而復雜的文檔中表現出眾﹔她被特意設計成可以支持各 種技朮文檔并可以將他們用不同的輸出格式“展示”出來。不過她的回溯 功能非常復雜，工具也沒有完全發展成熟（雖然進步很快），入門級的文 檔非常少而且常常寫得很混亂。

也許未來會有些更好的做法

2000年7月，世界一些重要的開放源碼項目開發組（包括GNOME、KDE、自由軟 件基金會、Linux文檔項目組、開源首創）在加州Monterey舉行了高級首腦會 議。該次會議的重要議題就是試圖建立一套共同的工作慣例和共同的文檔交流 格式，以便為自由軟件制作出更丰富、更統一的文檔資源。

具體的來說，會議的目標就是要制定一種文檔包的標准，使得當某文檔被裝入 系統中后，文檔包就立即被集成到整個系統的搜索數據庫中，系統可以通過某 種一致的手段查找、搜索各種文檔。實際上GNOME和KDE組已經開始在朝這個方 向努力了，大家都明白這并非是一種標記語言就可以解決的問題，而需要建立 一套結構化的系統體系。

會議簽署了一個意向文件，清晰的指出一些關鍵的開源項目正在著手或者已經 采納使用Docbook格式做為項目文檔的首選格式。

與會者最后也決定了采用“Dublin core”元數據格式（一種根據庫管理程序開 發的與數字資料索引有關地國際標准）做為文檔搜索的標准，這個標准的細節 正在制定中，因此最終DocBook標記中會添加一些信息用于支持嵌入DocBook文 檔的Dublin Core元數據。

目標是明確的，基于索引標記和Dublin core元數據可以提高DocBook文檔的自動 搜索能力，從而使得DocBook的用途如虎添翼。雖然還有一些工作尚未完成，但 是它們將會被不斷填充進整個體系中。老的基于描述的標記語言文檔所剩下的日 子已經不多了。（本文檔在2000年8月已經有了DocBook格式的版本。）

因此新的開源項目應該注意這種動向，如果現在就采用DocBook格式的文檔編寫， 這可以幫助他們省去以后將文檔格式轉檔的麻煩。