歡迎參與 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, FDP)。維持優秀質量的文件對 FreeBSD 的成功來說十分重要,您的點滴貢獻都是十分寶貴的。
本文件描述:『 FDP 的架構有哪些』、『如何撰寫並提交文件』、 『如何有效運用工具來協助撰稿』。
歡迎大家對 FDP 做出貢獻。唯一的成員要求就有貢獻的意願。
本入門書指出如何:
瞭解有哪些文件是由 FDP 所維護的。
安裝所需的說明文件工具和檔案。
修改說明文件。
提交修改以供審核並納入 FreeBSD 說明文件。
在編輯 FreeBSD 說明文件之前,有一些準備工作要做。首先,請訂閱 FreeBSD 文件計劃郵件論壇。有些團隊成員也會出現在 EFnet 的#bsddocs
IRC 頻道。這些人可以幫忙解決文件相關的問題。
安裝 textproc/docproj 套件或 Port。這個 meta-port 會安裝所有編輯和建置 FreeBSD 說明文件需要的軟體。
在 ~/doc
安裝 FreeBSD 說明文件檔案庫的本地端工作副本 (請見 章 3, 工作副本)。
%
svn checkout https://svn.FreeBSD.org/doc/head
~/doc
設定文字編輯器:
自動換行 (Word wrap) 設為 70 個字元。
Tab 定位點 (Tab stops) 設成 2。
將行首每 8 個空白取代成 1 個 Tab。
特定編輯器的設定方式列於 章 14, 編輯器設定。
更新本地端工作副本
%
svn up
~/doc
編輯需要修改的說明文件檔案。如果檔案需要大幅度的編修,請先諮詢郵件論壇。
標籤 (Tag) 和 Entity 的使用方式可以參考 章 8, XHTML 標籤 和 章 9, DocBook 標籤。
編輯完後,執行以下指令來檢查是否有問題:
%
igor -R filename.xml | less -RS
檢查輸出並重新編輯檔案來修正顯示的錯誤,然後重新執行指令來找出剩下的問題。重複執行直到所有錯誤都解決完。
永遠要送出修正前請先做建置測試 (Build-test) 。在編輯的說明文件目錄最頂層執行 make
,將會產生分頁的 HTML 格式 (Split HTML) 的文件。例如要建置 HTML 格式的英文版使用手冊,請在 en_US.ISO8859-1/books/handbook/
目錄執行 make
。
修改並測試完後,產生 “diff 檔”:
%
cd ~/doc
%
svn diff >
bsdinstall
.diff.txt
設一個可辨識的檔名。如上例中,是使用手冊的 bsdinstall
部份的修改。
使用網頁版 問題回報 系統提交 diff 檔。如果使用網頁版,請輸入 [patch] 問題簡短描述
的概要 。選擇 docs
分類和 doc-bug
類別。在訊息的主體中,輸入修正的簡短描述和其他相關的重要的細節。使用 按鈕來附加 diff 檔。
本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/。
若有 FreeBSD 方面疑問,請先閱讀
FreeBSD 相關文件,如不能解決的話,再洽詢
<questions@FreeBSD.org>。
關於本文件的問題,請洽詢
<doc@FreeBSD.org>。