章 1. 概論

內容目錄
1.1. 快速上手
1.2. FreeBSD 說明文件集

歡迎參與 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, FDP)。維持優秀質量的文件對 FreeBSD 的成功來說十分重要,您的點滴貢獻都是十分寶貴的。

本文件描述:『 FDP 的架構有哪些』、『如何撰寫並提交文件』、 『如何有效運用工具來協助撰稿』。

歡迎大家對 FDP 做出貢獻。唯一的成員要求就有貢獻的意願。

本入門書指出如何:

1.1. 快速上手

在編輯 FreeBSD 說明文件之前,有一些準備工作要做。首先,請訂閱 FreeBSD 文件計劃郵件論壇。有些團隊成員也會出現在 EFnet#bsddocs IRC 頻道。這些人可以幫忙解決文件相關的問題。

  1. 安裝 textproc/docproj 套件或 Port。這個 meta-port 會安裝所有編輯和建置 FreeBSD 說明文件需要的軟體。

  2. ~/doc 安裝 FreeBSD 說明文件檔案庫的本地端工作副本 (請見 章 3, 工作副本)。

    % svn checkout https://svn.FreeBSD.org/doc/head ~/doc
  3. 設定文字編輯器:

    • 自動換行 (Word wrap) 設為 70 個字元。

    • Tab 定位點 (Tab stops) 設成 2。

    • 將行首每 8 個空白取代成 1 個 Tab。

    特定編輯器的設定方式列於 章 14, 編輯器設定

  4. 更新本地端工作副本

    % svn up ~/doc
  5. 編輯需要修改的說明文件檔案。如果檔案需要大幅度的編修,請先諮詢郵件論壇。

    標籤 (Tag) 和 Entity 的使用方式可以參考 章 8, XHTML 標籤章 9, DocBook 標籤

  6. 編輯完後,執行以下指令來檢查是否有問題:

    % igor -R filename.xml | less -RS

    檢查輸出並重新編輯檔案來修正顯示的錯誤,然後重新執行指令來找出剩下的問題。重複執行直到所有錯誤都解決完。

  7. 永遠要送出修正前請先做建置測試 (Build-test) 。在編輯的說明文件目錄最頂層執行 make,將會產生分頁的 HTML 格式 (Split HTML) 的文件。例如要建置 HTML 格式的英文版使用手冊,請在 en_US.ISO8859-1/books/handbook/ 目錄執行 make

  8. 修改並測試完後,產生 diff 檔

    % cd ~/doc
    % svn diff > bsdinstall.diff.txt

    設一個可辨識的檔名。如上例中,是使用手冊的 bsdinstall 部份的修改。

  9. 使用網頁版 問題回報 系統提交 diff 檔。如果使用網頁版,請輸入 [patch] 問題簡短描述 的概要 。選擇 docs 分類和 doc-bug類別。在訊息的主體中,輸入修正的簡短描述和其他相關的重要的細節。使用 [ Browse... ] 按鈕來附加 diff 檔。

本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢 <questions@FreeBSD.org>。

關於本文件的問題,請洽詢 <doc@FreeBSD.org>。