自由軟件發布方法慣例

转载 2011年01月10日 11:22:00

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格式的文檔編寫, 這可以幫助他們省去以后將文檔格式轉檔的麻煩。

自由软件之父:苹果微软罪恶滔天

虽然已经年逾六旬,但理查德·斯托曼(Richard Stallman)显然没能做到“耳顺”。他会在任何时间、任何场合,以不容置疑的口吻,就自由软件与意见相左人士展开激辩。 “自由软件不等于开源软...

(转载)不完全解读 Emacs 编辑器—自由软件的旗舰

转载:不完全解读 Emacs 编辑器—自由软件的旗舰 L-Emacs 2008-11-17 21:41:10 阅读45 评论0   字号:大中小 订阅 作者: texnici...
  • Sinchb
  • Sinchb
  • 2011年05月18日 23:13
  • 2067

自由软件日--车库咖啡站

每年9月的第三周的周六,是世界自由软件日,这一天是全球自由软件爱好者们的狂欢节。全球各地的自由软件爱好者们,将在这一天举办各种庆祝活动!              今年的世界自由软件...

自由软件之父:“苹果公司罪大恶极”

“自由软件之父”理查德·斯托曼(Richard Stallman)         虽然已经年逾六旬,但理查德·斯托曼(Richard Stallman)显然没能做到“耳顺”。他会在任何时间、任...

英国GNU自由软件的斗士:Michael Meeks

     以下是GNU自由软件“黑客”(Hacker)Michael Meeks的近照:           在一般国人看来,GNU自由软件是”外来物“,对于为何...

自由软件:FastCopy同步功能,达到同步备份的效果

FastCopy是一款windows下的开源软件。主要是用于高效复制、删除来使用的。 但我们也可以利用它的同步(sync)功能,结合windows系统的自动任务来达到同步备份的效果。 FastCo...

使用autotools生成符合自由软件标准的Makefile

一直以来在开发中我都是使用自己手工编写的简单Makefile进行代码的编译的,编写一个简单的Makefile通常不太复杂,只需要设置一些编译条件的变量,objs列表,加上几行简单的代码即可。但是这样的...
  • syndro
  • syndro
  • 2011年05月10日 15:18
  • 237

自由软件数据库 PostgreSQL 简介

PostgreSQL 是一种非常复杂的对象-关系型数据库管理系统(ORDBMS), 也是目前功能最强大,特性最丰富和最复杂的自由软件数据库系统。有些特性甚至连商业数据库都不具备。这个起源于伯克利(BS...

【GNU】自由软件开发C&C++(环境安装篇)

【GNU】自由软件开发C&C++(环境安装篇)

自由软件之“父”—Richard. M. Stallman

Richard Stallman是自由软件运动的领袖,是GNU计划及自由软件基金会FSF(Free Software Foundation)的创立者。他为自由软件运动竖立了道德框架,被许多人誉为当今自...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:自由軟件發布方法慣例
举报原因:
原因补充:

(最多只允许输入30个字)