From owner-svn-doc-all@freebsd.org Sat Mar 25 13:58:01 2017 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 5EE38D1C178; Sat, 25 Mar 2017 13:58:01 +0000 (UTC) (envelope-from rcyu@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id D85C010A3; Sat, 25 Mar 2017 13:58:00 +0000 (UTC) (envelope-from rcyu@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v2PDw0lB012910; Sat, 25 Mar 2017 13:58:00 GMT (envelope-from rcyu@FreeBSD.org) Received: (from rcyu@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v2PDw04e012908; Sat, 25 Mar 2017 13:58:00 GMT (envelope-from rcyu@FreeBSD.org) Message-Id: <201703251358.v2PDw04e012908@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: rcyu set sender to rcyu@FreeBSD.org using -f From: Ruey-Cherng Yu Date: Sat, 25 Mar 2017 13:58:00 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50085 - head/zh_TW.UTF-8/books/fdp-primer X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 25 Mar 2017 13:58:01 -0000 Author: rcyu Date: Sat Mar 25 13:57:59 2017 New Revision: 50085 URL: https://svnweb.freebsd.org/changeset/doc/50085 Log: -Translated all TOC. -Translated following chapters 3. The Working Copy 4. Documentation Directory Structure 5. The Documentation Build Process 5.2. The FreeBSD Documentation Build Toolset -Fix translations Submitted by: cwlin0416@gmail.com Differential Revision: https://reviews.freebsd.org/D10132 Modified: head/zh_TW.UTF-8/books/fdp-primer/book.xml head/zh_TW.UTF-8/books/fdp-primer/zh_TW.po Modified: head/zh_TW.UTF-8/books/fdp-primer/book.xml ============================================================================== --- head/zh_TW.UTF-8/books/fdp-primer/book.xml Sat Mar 25 04:30:55 2017 (r50084) +++ head/zh_TW.UTF-8/books/fdp-primer/book.xml Sat Mar 25 13:57:59 2017 (r50085) @@ -59,10 +59,10 @@ $FreeBSD$ --> - FreeBSD 文件計畫入門書 + 給新貢獻人員的 FreeBSD 說明文件計畫入門書 - FreeBSD 文件計劃 + FreeBSD 說明文件計劃 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 DocEng @@ -113,9 +113,9 @@ - 感謝您參與 FreeBSD 文件計劃，您的點滴貢獻，都相當寶貴。 + 感謝您參與 FreeBSD 說明文件計劃，您的點滴貢獻，都相當寶貴。 - 本入手書內容包括：如何開始著手貢獻FreeBSD 文件計劃 (簡稱： FDP )的各項細節，以及會用到的一些工具、軟體 ，以及文件計畫的宗旨。 + 本入手書內容包括：如何開始著手貢獻 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, FDP) 的各項細節，以及會用到的一些工具、軟體 ，以及文件計畫的宗旨。 本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。 @@ -125,7 +125,7 @@ 序 - Shell 提示符號(Prompts) + Shell 提示符號 下表顯示出一般使用者帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt) ，來提醒您該用哪種帳號才對。 @@ -163,7 +163,7 @@ 代表意義 - 舉例 + 範例 @@ -221,7 +221,7 @@ The time is 09:18 - 注意、技巧、重要訊息、警告、與範例的運用。 + 注意、提示、重要、警告與範例 出現在本文中的注意、警告、與範例。 @@ -242,7 +242,7 @@ The time is 09:18 - 一個範例 + 範例的範本 這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。 @@ -290,7 +290,7 @@ The time is 09:18 概論 - 歡迎參與 FreeBSD 文件計劃( 簡稱 FDP ) 。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，您的點滴貢獻都是十分寶貴的。 + 歡迎參與 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, FDP)。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，您的點滴貢獻都是十分寶貴的。 本文件描述：『 FDP 的架構有哪些』、『如何撰寫並提交文件』、 『如何有效運用工具來協助撰稿』。 @@ -304,30 +304,30 @@ The time is 09:18 - 安裝所需的文件工具和檔案 + 安裝所需的說明文件工具和檔案。 - 修改文件 + 修改說明文件。 - 提交修改以供審核並納入 FreeBSD 文件 + 提交修改以供審核並納入 FreeBSD 說明文件。 快速上手 - 在編輯 FreeBSD 文件之前，有一些準備工作要做。 首先，請訂閱 FreeBSD 文件計劃郵件論壇。 有些團隊成員也會出現在EFnet的#bsddocs IRC 頻道。這些人可以幫忙解決文件相關的問題。 + 在編輯 FreeBSD 說明文件之前，有一些準備工作要做。 首先，請訂閱 FreeBSD 文件計劃郵件論壇。 有些團隊成員也會出現在 EFnet 的#bsddocs IRC 頻道。這些人可以幫忙解決文件相關的問題。 - 安裝 textproc/docproj 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。 + 安裝 textproc/docproj 套件或 Port。這個 meta-port 會安裝所有編輯和建置 FreeBSD 說明文件需要的軟體。 - 在~/doc安裝 FreeBSD 文件庫的本地端工作副本 ( 請見 )。 + 在 ~/doc 安裝 FreeBSD 說明文件檔案庫的本地端工作副本 (請見 )。 % svn checkout https://svn.FreeBSD.org/doc/head ~/doc @@ -337,15 +337,15 @@ The time is 09:18 - Word wrap 設為70個字元。 + 自動換行 (Word wrap) 設為 70 個字元。 - Tab stops 設成 。 + Tab 定位點 (Tab stops) 設成 2。 - 將句首每八個空白以一個 tab 替換。 + 將行首每 8 個空白取代成 1 個 Tab。 @@ -359,9 +359,9 @@ The time is 09:18 - 編輯需要修改的文件檔案。如果檔案需要大幅度的編修，請先諮詢郵件論壇。 + 編輯需要修改的說明文件檔案。如果檔案需要大幅度的編修，請先諮詢郵件論壇。 - 標籤 ( tag ) 和 entity 的使用方式可以參考 和 . 。 + 標籤 (Tag) 和 Entity 的使用方式可以參考 和 . 。 @@ -373,58 +373,58 @@ The time is 09:18 - 修正送出前請先建構測試 (build-test ) 。在編輯的文件目錄最頂層執行 make，將會產生 split HTML 格式的文件。例如要建構 HTML 格式的英文版使用手冊，請在 en_US.ISO8859-1/books/handbook/ 目錄執行 make 。 + 永遠要送出修正前請先做建置測試 (Build-test) 。在編輯的說明文件目錄最頂層執行 make，將會產生分頁的 HTML 格式 (Split HTML) 的文件。例如要建置 HTML 格式的英文版使用手冊，請在 en_US.ISO8859-1/books/handbook/ 目錄執行 make 。 - 修改並測試完後，產生diff 檔： + 修改並測試完後，產生 diff 檔： % cd ~/doc % svn diff > bsdinstall.diff.txt - 設一個可辨識的檔名。如上例中，是使用手冊的bsdinstall 部份的修改。 + 設一個可辨識的檔名。如上例中，是使用手冊的 bsdinstall 部份的修改。 - 使用網頁版 Problem Report 系統提交 diff 檔。 如果使用網頁版，請輸入[修正檔] 問題簡短描述的概要 。選擇 docs 分類和 doc-bug類別。在訊息的主體中，輸入修正的簡短描述和其他相關的重要的細節。使用[ Browse... ] 按鈕來附加 diff 檔。 + 使用網頁版 問題回報 系統提交 diff 檔。 如果使用網頁版，請輸入 [patch] 問題簡短描述 的概要 。選擇 docs 分類和 doc-bug類別。在訊息的主體中，輸入修正的簡短描述和其他相關的重要的細節。使用 [ Browse... ] 按鈕來附加 diff 檔。 - FreeBSD 文件組 + FreeBSD 說明文件集 - FDP 負責四類 FreeBSD 文件 + FDP 負責四類 FreeBSD 說明文件。 - 使用手冊： 使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。 + 使用手冊 (Handbook)：使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。 - FAQ 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。 + 常見問答集 (FAQ)：主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。 - 線上手冊 ( manual pages ):英文版的系統 manual 並不是由 FDP 所撰寫的，因為它們是屬於 base system 的部份。 然而，FDP 可以修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。 + 操作手冊 (Manual page)：英文版的系統手冊並不是由 FDP 所撰寫的，因為它們是屬於基礎系統 (Base system) 的部份。 然而，FDP 可以修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。 - 網站: 這是 FreeBSD 在網路上的主要部份，位於 http://www.FreeBSD.org/ 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方 + 網站：這是 FreeBSD 在網路上的主要部份，位於 http://www.FreeBSD.org/ 以及許多其他鏡像站 (Mirror)。這網站是許多人第一次接觸 FreeBSD 的地方 翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯 - FreeBSD 網站、使用手冊、和 FAQ 的文件原始碼可以在 https://svn.FreeBSD.org/doc/ 的文件庫取得。 + FreeBSD 網站、使用手冊、和 FAQ 的文件原始碼可以在 https://svn.FreeBSD.org/doc/ 的文件檔案庫取得。 線上手冊的原始碼則是在 https://svn.FreeBSD.org/base/ 的原始碼庫可以取得。 - 文件提交訊息可以用 svn log 察看。 提交訊息也會保存在http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all。 + 說明文件提交訊息可以用 svn log 察看。 提交訊息也會封存在 http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all。 - 這些儲存庫的網頁版位於 和 。 + 這些儲存庫的網頁版位於 和 。 - 許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 FDP 的檔案中。其他一些文件則是作者希望放在他處。FDP 會盡力提供這些文件的連結。 + 許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 FDP 的檔案中。其他一些說明文件則是作者希望放在他處。FDP 會盡力提供這些說明文件的連結。 @@ -463,17 +463,17 @@ The time is 09:18 工具 - 有些工具軟體用來管理 FreeBSD 文件，並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。 + 有些工具軟體用來管理 FreeBSD 說明文件，並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。 必備工具 - 從 Ports Collection 安裝 textproc/docproj。這個 組合型 port (meta-port) 會安裝處理 FreeBSD 文件需要的所有應用程式。以下列出特定元件的進一步說明。 + 從 Port 套件集安裝 textproc/docproj。這個 meta-port 會安裝處理 FreeBSD 說明文件需要的所有應用程式。以下列出特定元件的進一步說明。 <acronym>DTD</acronym>s 與 <acronym>Entities</acronym> - FreeBSD 文件使用幾種文件類型定義 (DTDs) 與 XML entities 組。這些都會經由 textproc/docproj port 來安裝。 + FreeBSD 說明文件使用幾種文件類型定義 (DTDs) 與 XML entities 集合。這些都會經由 textproc/docproj Port 來安裝。 @@ -488,7 +488,7 @@ The time is 09:18 DocBook DTD (textproc/docbook-xml) - DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。 + DocBook 設計來製作技術說明文件的標記語言版本。FreeBSD 說明文件是以 DocBook 來撰寫。 @@ -504,9 +504,9 @@ The time is 09:18 - 輔助工具 + 選用工具 - 不一定得裝下列的應用程式才行，但是，出的格式也更具彈性。 + 以下應用程式並非必要，但有了可讓在說明文件的作業上更簡單或提升能力。 軟體 @@ -565,149 +565,78 @@ The time is 09:18 工作副本 - The working copy is a copy of the FreeBSD - repository documentation tree downloaded onto the local computer. - Changes are made to the local working copy, tested, and then - submitted as patches to be committed to the main - repository. - - A full copy of the documentation tree can occupy 700 megabytes - of disk space. Allow for a full gigabyte of space to have room - for temporary files and test versions of various output - formats. - - Subversion - is used to manage the FreeBSD documentation files. It is installed - by textproc/docproj as one of - the required applications. + 工作副本 (Working copy) 指的是已下載到本地電腦的 FreeBSD 說明文件樹檔案庫，所有對工作副本的更改會經過測試後再以修補檔 (Patch) 的格式提交到主要檔案庫。 + + 完整的說明文件樹副本會佔據 700 MB 的磁碟空間，要有空間能夠儲存暫存檔及各種輸出格式的測試版本需要 1 GB 的空間。 + + FreeBSD 說明文件檔案使用 Subversion 來管理，由於 Subversion 為 textproc/docproj 的必要應用程式之一，所以會隨著 textproc/docproj 一併安裝。 - Documentation and Manual Pages + 說明文件與操作手冊 - FreeBSD documentation is not just books and articles. Manual - pages for all the commands and configuration files are also part - of the documentation, and part of the FDP's - territory. Two repositories are involved: - doc for the books and articles, and - base for the operating system and manual - pages. To edit manual pages, the base - repository must be checked out separately. - - Repositories may contain multiple versions of documentation - and source code. New modifications are almost always made only - to the latest version, called head. + FreeBSD 說明文件不只有書籍與文章，還有所有指令與設定檔的操作手冊 (Manual page) 也是文件的一部份，其中也有一部份是 FDP 的地盤。相關的檔案庫有兩個：doc 中有書籍與文章，而 base 中有作業系統以及操作手冊。要編輯操作手冊則必須另外取出 (Checkout) base 檔案庫。 + + 檔案庫中可能會含有數個版本的說明文件與原始碼。新的修改幾乎都只對最新版本 head 做更新。 - Choosing a Directory + 選擇一個目錄 - FreeBSD documentation is traditionally stored in - /usr/doc/, and system - source code with manual pages in - /usr/src/. These - directory trees are relocatable, and users may want to put the - working copies in other locations to avoid interfering with - existing information in the main directories. The examples - that follow use ~/doc - and ~/src, both - subdirectories of the user's home directory. + FreeBSD 說明文件一般會儲存在 /usr/doc/，而系統原始碼及操作手冊則會存在 /usr/src/。這些目錄樹可改放在其他地方，使用者可能會為了避免與現有在主要目錄的資料搞混，把工作副本放在其他的地方。以下的例子會放在 ~/doc 以及 ~/src 兩個在使用者家目錄下的目錄。 - Checking Out a Copy + 取出一份副本 - A download of a working copy from the repository is called - a checkout, and done with - svn checkout. This example checks out a - copy of the latest version (head) of - the main documentation tree: + 從檔案庫下載工作副本的動作稱作 取出 (Checkout)，使用 svn checkout 來完成。本範例會取出主要說明文件樹最新版本的副本： % svn checkout https://svn.FreeBSD.org/doc/head ~/doc - A checkout of the source code to work on manual pages is - very similar: + 取出原始碼編輯操作手冊的動作非常相似： % svn checkout https://svn.FreeBSD.org/base/head ~/src - Updating a Working Copy + 更新工作副本 - The documents and files in the FreeBSD repository change daily. - People modify files and commit changes frequently. Even a short - time after an initial checkout, there will already be - differences between the local working copy and the main FreeBSD - repository. To update the local version with the changes that - have been made to the main repository, use - svn update on the directory containing the - local working copy: + 在 FreeBSD 檔案庫中的文件與檔案每天都會更改，人們會修改檔案與提交變更的頻率非常快，即使取出 (Checkout) 只過小一段時間，本地的工作副本可能就與主要 FreeBSD 檔案庫有差異了。要更新本地版本以同步對主要檔案庫的變更可在有本地工作副本的目錄下使用 svn update： % svn update ~/doc - Get in the protective habit of using - svn update before editing document files. - Someone else may have edited that file very recently, and the - local working copy will not include the latest changes until it - has been updated. Editing the newest version of a file is much - easier than trying to combine an older, edited local file with - the newer version from the repository. + 養成良好的習慣在編輯文件檔前先執行 svn update，可能會有其他人才剛編輯完該檔案，本地工作副本在尚未更新前不會有最後的變更內容，編輯最新版本的檔案會比將舊版本地檔案與新版檔案庫檔案合併來的簡單多了。 - Reverting Changes + 還原變更 - Sometimes it turns out that changes were - not necessary after all, or the writer just wants to start over. - Files can be reset to their unchanged form with - svn revert. For example, to erase the edits - made to chapter.xml and reset it to - unmodified form: + 有時才做完的變更可能就變的不需要了，或者作者剛想要重新搛寫。檔案可使以使用 svn revert 來重設成尚未被修改刪的狀態，舉例來說，要清除所有對 chapter.xml 的修改然後還原到未修改的版本可： % svn revert chapter.xml - Making a Diff + 比對差異 - After edits to a file or group of files are completed, the - differences between the local working copy and the version on - the FreeBSD repository must be collected into a single file for - submission. These diff files are produced - by redirecting the output of svn diff into a - file: + 在編輯一個檔案或數個檔案完成之後，需將本地工作副本與 FreeBSD 檔案庫的差異儲存到一個檔案然後提交。這些 差異 (Diff) 檔可透過將 svn diff 的輸出轉向到檔案來建立： % cd ~/doc % svn diff > doc-fix-spelling.diff - Give the file a meaningful name that identifies the - contents. The example above is for spelling fixes to the whole - documentation tree. - - If the diff file is to be submitted with the web - Submit a FreeBSD - problem report interface, add a - .txt extension to give the earnest and - simple-minded web form a clue that the contents are plain - text. + 給檔案取一個有意義的名字來辨識這次修改的內容，上述範例為例則是要修正整個說明文件樹的拼寫。 - Be careful: svn diff includes all changes - made in the current directory and any subdirectories. If there - are files in the working copy with edits that are not ready to - be submitted yet, provide a list of only the files that are to - be included: + 若 diff 檔要使用網站的 Submit a FreeBSD problem report 介面來提交，請加上 .txt 副檔名來給認真又單純的網頁表單可以辨識其內容為純文字的線索。 + + 請小心：svn diff 會產生所有在目前目錄及其子目錄的變更差異，若在該工作副本中有已經編輯過的檔案還沒有要提交，請列出需要比較差異的檔案清單： % cd ~/doc % svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff - <application>Subversion</application> References + <application>Subversion</application> 參考文獻 - These examples show very basic usage of - Subversion. More detail is available - in the Subversion Book - and the Subversion - documentation. + 以下範例會示範 Subversion 的基本用法，要取得更多資訊可至 Subversion Book 與 Subversion 說明文件。 @@ -744,49 +673,37 @@ The time is 09:18 $FreeBSD$ --> - Documentation Directory Structure + 說明文件目錄結構 - Files and directories in the - doc/ tree follow a - structure meant to: + 在 doc/ 樹中的檔案與目錄需要遵守特定結構是因為： - Make it easy to automate converting the document to other - formats. + 讓自動轉換說明文件到各種格式更簡單。 - Promote consistency between the different documentation - organizations, to make it easier to switch between working on - different documents. + 促進不同說明文件組織之間的一致性，以便更輕鬆的在不同說明文件之間切換。 - Make it easy to decide where in the tree new documentation - should be placed. + 可以很容易的決定新的說明文件應該放在文件樹中的哪個位置。 - In addition, the documentation tree must accommodate - documents in many different languages and encodings. It is - important that the documentation tree structure does not enforce - any particular defaults or cultural preferences. + 除此之外，說明文件樹必須能容納各種不同語言與編碼的說明文件。很重要的一點是，說明文件樹結構不應強制任何特定默認或文化的偏好。 - The Top Level, - <filename>doc/</filename> + 最上層，<filename>doc/</filename> - There are two types of directory under - doc/, each with very - specific directory names and meanings. + 在 doc/ 底下有兩種類型的目錄，兩種都有非常明確的目錄名稱與意義。 - Directory - Usage + 目錄 + 用途 @@ -795,31 +712,14 @@ The time is 09:18 share - Contains files that are not specific to the various - translations and encodings of the documentation. - Contains subdirectories to further categorize the - information. For example, the files that comprise the - make1 infrastructure are in - share/mk, while - the additional XML support files - (such as the FreeBSD extended DocBook - DTD) are in share/xml. + 含有未特定用於各說明文件翻譯與編碼的檔案。其子目錄更進一步將不同資訊的分類，例如，構成 make1 基礎設施的檔案放置於 share/mk，而額外的 XML 支援檔 (如 FreeBSD 延伸的 DocBook DTD) 則放在 share/xml。 lang.encoding - One directory exists for each available translation - and encoding of the documentation, for example - en_US.ISO8859-1/ - and zh_TW.UTF-8/. - The names are long, but by fully specifying the language - and encoding we prevent any future headaches when a - translation team wants to provide documentation in the - same language but in more than one encoding. This also - avoids problems that might be caused by a future switch - to Unicode. + 每一個目錄代表可用的說明文件翻譯與編碼，例如 en_US.ISO8859-1/ 及 zh_TW.UTF-8/。名稱雖然長，但完整表達語言與編碼可以避免未來當一個翻譯團隊要以不同編碼提供同一個語言的說明文件造成的問題，這也同時避免往後要切換成萬國碼 (Unicode) 可能造成的問題。 @@ -827,20 +727,16 @@ The time is 09:18 - The - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> - Directories - - These directories contain the documents themselves. The - documentation is split into up to three more categories at - this level, indicated by the different directory names. + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> 目錄 + + 這些目錄中含有說明文件。在此階層說明文件分成三個分類，使用不同的目錄名稱來代表。 - Directory - Usage + 目錄 + 用途 @@ -849,168 +745,89 @@ The time is 09:18 articles - Documentation marked up as a DocBook - article (or equivalent). Reasonably - short, and broken up into sections. Normally only - available as one XHTML file. + 以 DocBook article (或同等級) 標記的說明文件。非常短，且會分成幾個小節，通常取得時只會有一個 XHTML 檔案。 books - Documentation marked up as a DocBook - book (or equivalent). Book length, - and broken up into chapters. Normally available as both - one large XHTML file (for people with - fast connections, or who want to print it easily from a - browser) and as a collection of linked, smaller - files. + 以 DocBook book (或同等級) 標記的說明文件。有跟書籍一樣的長度，會分成數個章。通常取得時會包含一個大型的 XHTML 檔 (供有較快連線速度的人使用，或者那些想直接在瀏覽器列印的人) 與數個連結的較小的檔案。 man - For translations of the system manual pages. This - directory will contain one or more mann - directories, corresponding to the sections that have - been translated. + 供系統操作手冊 (Manual page) 翻譯使用。這個目錄會包含一個或多個 mann 目錄來對應已經翻譯的章節。 - Not every lang.encoding - directory will have all of these subdirectories. It depends - on how much translation has been accomplished by that - translation team. + 並非所有 lang.encoding 的目錄都會有這些子目錄，這要看該翻譯團隊已經完成了多少翻譯來決定。 - Document-Specific Information + 文件特定資訊 - This section contains specific notes about particular - documents managed by the FDP. + 本節內含有關由 FDP 所管理的特定文件的特定注意事項。 - The Handbook + 使用手冊 (Handbook) books/handbook/ - The Handbook is written in DocBook XML - using the FreeBSD DocBook extended DTD. + 操作手冊是以使用 FreeBSD DocBook 擴充 DTD 的 DocBook XML 所撰寫。 - The Handbook is organized as a DocBook - book. The book is divided into - parts, each of which contains several - chapters. chapters are - further subdivided into sections (sect1) - and subsections (sect2, - sect3) and so on. + 使用手冊使用 DocBook book 來組織，整個手冊區分成數個部份 (part)，每個部份中內含數個章 (chapter)，而章 (chapter) 又更進一步的細分成數個節 (sect1) 與小節 (sect2, sect3) 以此類推。 - Physical Organization + 實體組織結構 - There are a number of files and directories within the - handbook directory. + 在 handbook 目錄中有數個檔案及目錄。 - The Handbook's organization may change over time, and - this document may lag in detailing the organizational - changes. Post questions about Handbook organization to the - FreeBSD documentation project mailing list. + 使用手冊的組織結構可能會隨時改變，本文件所詳述的組織結構可能會與現況不盡相同。有關使用手冊組織結構的問題可張貼到 FreeBSD documentation project mailing list。 <filename>Makefile</filename> - The Makefile defines some - variables that affect how the XML - source is converted to other formats, and lists the - various source files that make up the Handbook. It then - includes the standard doc.project.mk, - to bring in the rest of the code that handles converting - documents from one format to another. + Makefile 定義了一些會影響 XML 原始碼要如何轉換至其他格式的變數，並列出產生使用手冊所需的各原始檔，接著會引用可處理在各種文件格式轉換的標準 doc.project.mk 程式碼。 <filename>book.xml</filename> - This is the top level document in the Handbook. It - contains the Handbook's DOCTYPE - declaration, as well as the elements that - describe the Handbook's structure. - - book.xml uses parameter - entities to load in the files with the - .ent extension. These files - (described later) then define general - entities that are used throughout the rest of the - Handbook. + 此為使用手冊的最上層文件，其中包含了使用手冊的 DOCTYPE 宣告以及用來描述使用手冊結構的元素。 + + book.xml 會使用 參數 Entities 來載入 .ent 副檔名的檔案。這些檔案 (稍後會詳述) 接著會定義使用手冊剩下篇幅會使用的 一般 Entities。 <filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename> - Each chapter in the Handbook is stored in a file - called chapter.xml in a separate - directory from the other chapters. Each directory is - named after the value of the id - attribute on the chapter - element. + 每個在使用手冊的章會儲存成名稱為 chapter.xml 的檔案，分別放在不同的目錄中。每個目錄均是以在 chapter 元素中 id 屬性中的值來命名。 - For example, if one of the chapter files - contains: + 例如，若有一章的檔案內容為： chapter id="kernelconfig" ... chapter - Then it will be called - chapter.xml in the - kernelconfig directory. In general, - the entire contents of the chapter are in this one - file. - - When the XHTML version of the - Handbook is produced, this will yield - kernelconfig.html. This is because - of the id value, and is not related to - the name of the directory. - - In earlier versions of the Handbook, the files were - stored in the same directory as - book.xml, and named after the value - of the id attribute on the file's - chapter element. Now, it is possible - to include images in each chapter. Images for each - Handbook chapter are stored within share/images/books/handbook. - The localized version of these images should be - placed in the same directory as the XML - sources for each chapter. Namespace collisions are - inevitable, and it is easier to work with several - directories with a few files in them than it is to work - with one directory that has many files in it. - - A brief look will show that there are many directories - with individual chapter.xml files, - including basics/chapter.xml, - introduction/chapter.xml, and - printing/chapter.xml. + 那麼放置這個 chapter.xml 的目錄則會命名為 kernelconfig。一般來說一章的所有內容會存放在這一個檔案。 + + 當有 XHTML 版本的使用手冊之後，也會用這個檔產出 kernelconfig.html，這個名稱是根據 id 的值而定，與目錄名稱無關。 + + 在早期版本的使用手冊，檔案皆儲存在與 book.xml 相同的目錄中，而名稱會以 chapter 元素中的 id 屬性的值來命名。現在可在每個章節之中引用圖片，每個使用手冊章節的圖片會儲存在 share/images/books/handbook，而在地化版本的圖片應放在與每個章節 XML 原始碼相同的目錄。命名空間會衝突是必然的，但以目錄多、檔案少與目錄少、檔案多的結構相比，目錄多、檔案少會較容易處理命名空間衝突的問題。 + + 簡單來說會有很多個內含 chapter.xml 檔案的目錄，例如 basics/chapter.xml, introduction/chapter.xml 以及 printing/chapter.xml。 - Do not name chapters or directories after - their ordering within the Handbook. This ordering can - change as the content within the Handbook is - reorganized. Reorganization should be possible without - renaming files, unless entire chapters are being - promoted or demoted within the hierarchy. + 請勿以在使用手冊中的章節順序來命名章節或目錄，因為順序是會隨使用手冊重新組織後的內容改變的。重新組織結構應不需要去重新命名檔案，除非整個章節的階層被提升或下降。 - The chapter.xml files are not - complete XML documents that can be - built individually. They can only be built - as parts of the whole Handbook. + chapter.xml 檔案並不是可以被單獨建置的完整 XML 文件，只能做為使用手冊的一部份來建置。 @@ -1050,75 +867,63 @@ The time is 09:18 $FreeBSD$ --> - The Documentation Build Process + 說明文件建置流程 - This chapter covers organization of the documentation build - process and how make1 is used to control it. + 本章內容涵蓋了說明文件建置流程以及如何使用 make1 來控制如何建置。 - Rendering DocBook into Output + 繪製 Docbook 為其他格式 - Different types of output can be produced from a single - DocBook source file. The type of output desired is set with the - FORMATS variable. A list of known formats is - stored in KNOWN_FORMATS: + 從單一個 DocBook 原始檔可以產生各種不同類型的輸出，想要輸出的類型可用 FORMATS 變數來設定。已知的格式清單列在 KNOWN_FORMATS 中： % cd ~/doc/en_US.ISO8859-1/books/handbook % make -V KNOWN_FORMATS - Common Output Formats + 常見輸出格式 - FORMATS Value - File Type - Description + FORMATS 值 + 檔案類型 + 說明 html - HTML, one file - A single book.html or - article.html. + HTML，單檔 + 單一 book.html 或 article.html。 html-split - HTML, multiple files - Multiple HTML files, one for - each chapter or section, for use on a typical web - site. + HTML，多檔 + 多個 HTML 檔案，每個章或節一個檔案，供一般網站使用。 pdf PDF - Portable Document Format + 可攜的文件格式
- The default output format can vary by document, but is - usually html-split. Other formats are chosen - by setting FORMATS to a specific value. - Multiple output formats can be created at a single time by - setting FORMATS to a list of formats. + 預設輸出的格式會依文件而有所不同，但同常是 html-split。其他格式可設定 FORMATS 為特定值來選擇。在 FORMATS 設定所需格式的清單可一次輸出多個格式。 - Build a Single HTML Output File + 建置單頁 HTML 輸出檔 % cd ~/doc/en_US.ISO8859-1/books/handbook % make FORMATS=html - Build HTML-Split and <acronym>PDF</acronym> Output - Files + 建置分頁 HTML 及 <acronym>PDF</acronym> 輸出檔 % cd ~/doc/en_US.ISO8859-1/books/handbook % make FORMATS="html-split pdf" @@ -1126,67 +931,51 @@ The time is 09:18 - The FreeBSD Documentation Build Toolset + FreeBSD 說明文件建置工具集 - These are the tools used to build and install the - FDP documentation. + 建置與安裝 FDP 說明文件會使用到以下工具。 - The primary build tool is make1, specifically - Berkeley Make. + 主要的建置工具為 make1，特別是 Berkeley Make。 - Package building is handled by FreeBSD's - pkg-create8. + 套件建置會使用 FreeBSD 的 pkg-create8 來處理。 - gzip1 is used to create compressed versions of - the document. bzip21 archives are also supported. - tar1 is used for package building. + gzip1 用來建立壓縮版的文件，也支援 bzip21 封存。tar1 則用在套件建置。 - install1 is used to install the - documentation. + install1 用來安裝說明文件。 - Understanding <filename>Makefile</filename>s in the - Documentation Tree + 了解在說明文件樹中的 <filename>Makefile</filename> - There are three main types of Makefiles - in the FreeBSD Documentation Project tree. + 在 FreeBSD 說明文件計劃樹底下的 Makefile 主要有三個類型。 - Subdirectory - Makefiles simply pass - commands to those directories below them. + 子目錄的 Makefile 傳遞指令給在其所在目錄底下的目錄。 - Documentation - Makefiles describe the - documents that are produced from this - directory. + 說明文件的 Makefiles 用來描述要如何在其所在目錄產生文件。 - Make - includes are the glue that perform the document - production, and are usually of the form - doc.xxx.mk. + Make 引用檔 會連結一些產生文件所需的程式，通常為 doc.xxx.mk。 - Subdirectory <filename>Makefile</filename>s + 子目錄的 <filename>Makefile</filename> These Makefiles usually take the form of: @@ -1244,13 +1033,11 @@ DOC_PREFIX?= ${.CURDIR}/.. - Documentation <filename>Makefile</filename>s + 說明文件的 <filename>Makefile</filename> - These Makefiles set make1 - variables that describe how to build the documentation - contained in that directory. + 這些 Makefile 用來設定 make1 變數來描述要如何建置在該目錄中的說明文件。 - Here is an example: + 這裡有一個例子： MAINTAINER=nik@FreeBSD.org @@ -1268,34 +1055,18 @@ DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk" - The MAINTAINER variable allows - committers to claim ownership of a document in the FreeBSD - Documentation Project, and take responsibility for maintaining - it. + MAINTAINER 變數讓提交者可以聲明文件在 FreeBSD 說明文件計劃中的所有權，並負責維護該文件。 + + DOC 是由此目錄會建立的主要文件的名稱 (不需要 .xml 副檔名)。SRCS 會列出產生文件所需的各別檔案，此處也應引用要在重新建置 (Rebuild) 使用的重要的檔案。 - DOC is the name (sans the - .xml extension) of the main document - created by this directory. SRCS lists all - the individual files that make up the document. This should - also include important files in which a change should result - in a rebuild. - - FORMATS indicates the default formats - that should be built for this document. - INSTALL_COMPRESSED is the default list of - compression techniques that should be used in the document - build. INSTALL_ONLY_COMPRESS, empty by - default, should be non-empty if only compressed documents are - desired in the build. + FORMATS 用來指定此份文件建置時預設應採用的格式。INSTALL_COMPRESSED 是為在文件建置時預設要使用的壓縮技術清單。INSTALL_ONLY_COMPRESS 預設為空值的，若在建置時只想要產生壓縮後的文件則改成非空值。 - The DOC_PREFIX and include statements - should be familiar already. + DOC_PREFIX 以及 include 敘述句應不需再說明了。 - FreeBSD Documentation Project - <application>Make</application> Includes + FreeBSD 說明文件計劃 <application>Make</application> 引用檔 make1 includes are best explained by inspection of the code. Here are the system include files: @@ -1347,7 +1118,7 @@ PRI_LANG?= en_US.ISO8859-1 - Variables + 變數 DOCFORMAT and MAINTAINER are assigned default values, @@ -1372,7 +1143,7 @@ PRI_LANG?= en_US.ISO8859-1 - Conditionals + 條件 The .if defined(DOC) line is an example of a make1 conditional which, like in other @@ -1397,7 +1168,7 @@ PRI_LANG?= en_US.ISO8859-1 describe the most important features. *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***