Date: Sat, 25 Mar 2017 13:58:00 +0000 (UTC) From: Ruey-Cherng Yu <rcyu@FreeBSD.org> 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 Message-ID: <201703251358.v2PDw04e012908@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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$ --> <book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW"> - <info><title>FreeBSD 文件計畫入門書</title> + <info><title>給新貢獻人員的 FreeBSD 說明文件計畫入門書</title> - <author><orgname>FreeBSD 文件計劃</orgname></author> + <author><orgname>FreeBSD 說明文件計劃</orgname></author> <copyright><year>1998</year> <year>1999</year> <year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <holder role="mailto:doceng@FreeBSD.org">DocEng</holder></copyright> @@ -113,9 +113,9 @@ <abstract> - <para>感謝您參與 FreeBSD 文件計劃，您的點滴貢獻，都相當寶貴。</para> + <para>感謝您參與 FreeBSD 說明文件計劃，您的點滴貢獻，都相當寶貴。</para> - <para>本入手書內容包括：如何開始著手貢獻FreeBSD 文件計劃 (簡稱： <acronym>FDP</acronym> )的各項細節，以及會用到的一些工具、軟體 ，以及文件計畫的宗旨。</para> + <para>本入手書內容包括：如何開始著手貢獻 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, <acronym>FDP</acronym>) 的各項細節，以及會用到的一些工具、軟體 ，以及文件計畫的宗旨。</para> <para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para> </abstract> @@ -125,7 +125,7 @@ <title>序</title> <sect1 xml:id="preface-prompts"> - <title>Shell 提示符號(Prompts)</title> + <title>Shell 提示符號</title> <para>下表顯示出一般使用者帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt) ，來提醒您該用哪種帳號才對。</para> @@ -163,7 +163,7 @@ <thead> <row> <entry>代表意義</entry> - <entry>舉例</entry> + <entry>範例</entry> </row> </thead> @@ -221,7 +221,7 @@ The time is 09:18</screen></entry> </sect1> <sect1 xml:id="preface-notes"> - <title>注意、技巧、重要訊息、警告、與範例的運用。</title> + <title>注意、提示、重要、警告與範例</title> <para>出現在本文中的注意、警告、與範例。</para> @@ -242,7 +242,7 @@ The time is 09:18</screen></entry> </warning> <example> - <title>一個範例</title> + <title>範例的範本</title> <para>這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。</para> </example> @@ -290,7 +290,7 @@ The time is 09:18</screen></entry> <chapter version="5.0" xml:id="overview"> <title>概論</title> - <para>歡迎參與 FreeBSD 文件計劃( 簡稱 <acronym>FDP</acronym> ) 。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，您的點滴貢獻都是十分寶貴的。</para> + <para>歡迎參與 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, <acronym>FDP</acronym>)。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，您的點滴貢獻都是十分寶貴的。</para> <para>本文件描述：『 <acronym>FDP</acronym> 的架構有哪些』、『如何撰寫並提交文件』、 『如何有效運用工具來協助撰稿』。</para> @@ -304,30 +304,30 @@ The time is 09:18</screen></entry> </listitem> <listitem> - <para>安裝所需的文件工具和檔案</para> + <para>安裝所需的說明文件工具和檔案。</para> </listitem> <listitem> - <para>修改文件</para> + <para>修改說明文件。</para> </listitem> <listitem> - <para>提交修改以供審核並納入 FreeBSD 文件</para> + <para>提交修改以供審核並納入 FreeBSD 說明文件。</para> </listitem> </itemizedlist> <sect1 xml:id="overview-quick-start"> <title>快速上手</title> - <para>在編輯 FreeBSD 文件之前，有一些準備工作要做。 首先，請訂閱 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 文件計劃郵件論壇</link>。 有些團隊成員也會出現在<link xlink:href="http://www.efnet.org/">EFnet</link>的<literal>#bsddocs</literal>; <acronym>IRC</acronym> 頻道。這些人可以幫忙解決文件相關的問題。</para> + <para>在編輯 FreeBSD 說明文件之前，有一些準備工作要做。 首先，請訂閱 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 文件計劃郵件論壇</link>。 有些團隊成員也會出現在 <link xlink:href="http://www.efnet.org/">EFnet</link>; 的<literal>#bsddocs</literal> <acronym>IRC</acronym> 頻道。這些人可以幫忙解決文件相關的問題。</para> <procedure> <step> - <para>安裝 <package>textproc/docproj</package> 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。</para> + <para>安裝 <package>textproc/docproj</package> 套件或 Port。這個 meta-port 會安裝所有編輯和建置 FreeBSD 說明文件需要的軟體。</para> </step> <step> - <para>在<filename>~/doc</filename>安裝 FreeBSD 文件庫的本地端工作副本 ( 請見 <xref linkend="working-copy"/> )。</para> + <para>在 <filename>~/doc</filename> 安裝 FreeBSD 說明文件檔案庫的本地端工作副本 (請見 <xref linkend="working-copy"/>)。</para> <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> </step> @@ -337,15 +337,15 @@ The time is 09:18</screen></entry> <itemizedlist> <listitem> - <para>Word wrap 設為70個字元。</para> + <para>自動換行 (Word wrap) 設為 70 個字元。</para> </listitem> <listitem> - <para>Tab stops 設成 。</para> + <para>Tab 定位點 (Tab stops) 設成 2。</para> </listitem> <listitem> - <para>將句首每八個空白以一個 tab 替換。</para> + <para>將行首每 8 個空白取代成 1 個 Tab。</para> </listitem> </itemizedlist> @@ -359,9 +359,9 @@ The time is 09:18</screen></entry> </step> <step> - <para>編輯需要修改的文件檔案。如果檔案需要大幅度的編修，請先諮詢郵件論壇。</para> + <para>編輯需要修改的說明文件檔案。如果檔案需要大幅度的編修，請先諮詢郵件論壇。</para> - <para>標籤 ( tag ) 和 entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>. 。</para> + <para>標籤 (Tag) 和 Entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>. 。</para> </step> <step> @@ -373,58 +373,58 @@ The time is 09:18</screen></entry> </step> <step> - <para>修正送出前請先建構測試 (build-test ) 。在編輯的文件目錄最頂層執行 <userinput>make</userinput>，將會產生 split HTML 格式的文件。例如要建構 <acronym>HTML</acronym> 格式的英文版使用手冊，請在 <filename>en_US.ISO8859-1/books/handbook/</filename> 目錄執行 <command>make</command> 。</para> + <para><emphasis>永遠要</emphasis>送出修正前請先做建置測試 (Build-test) 。在編輯的說明文件目錄最頂層執行 <userinput>make</userinput>，將會產生分頁的 HTML 格式 (Split HTML) 的文件。例如要建置 <acronym>HTML</acronym> 格式的英文版使用手冊，請在 <filename>en_US.ISO8859-1/books/handbook/</filename> 目錄執行 <command>make</command> 。</para> </step> <step> - <para>修改並測試完後，產生<quote>diff 檔</quote>：</para> + <para>修改並測試完後，產生 <quote>diff 檔</quote>：</para> <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput> <prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> - <para>設一個可辨識的檔名。如上例中，是使用手冊的<filename>bsdinstall</filename> 部份的修改。</para> + <para>設一個可辨識的檔名。如上例中，是使用手冊的 <filename>bsdinstall</filename> 部份的修改。</para> </step> <step> - <para>使用網頁版 <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">Problem Report</link> 系統提交 diff 檔。 如果使用網頁版，請輸入<emphasis>[修正檔] <replaceable>問題簡短描述</replaceable></emphasis>的概要 。選擇 <literal>docs</literal> 分類和 <literal>doc-bug</literal>類別。在訊息的主體中，輸入修正的簡短描述和其他相關的重要的細節。使用<guibutton>[ Browse... ]</guibutton> 按鈕來附加 diff 檔。</para> + <para>使用網頁版 <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">問題回報</link> 系統提交 diff 檔。 如果使用網頁版，請輸入 <emphasis>[patch] <replaceable>問題簡短描述</replaceable></emphasis> 的概要 。選擇 <literal>docs</literal> 分類和 <literal>doc-bug</literal>類別。在訊息的主體中，輸入修正的簡短描述和其他相關的重要的細節。使用 <guibutton>[ Browse... ]</guibutton> 按鈕來附加 diff 檔。</para> </step> </procedure> </sect1> <sect1 xml:id="overview-doc"> - <title>FreeBSD 文件組</title> + <title>FreeBSD 說明文件集</title> - <para><acronym>FDP</acronym> 負責四類 FreeBSD 文件</para> + <para><acronym>FDP</acronym> 負責四類 FreeBSD 說明文件。</para> <itemizedlist> <listitem> - <para><emphasis>使用手冊</emphasis>： 使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para> + <para><emphasis>使用手冊 (Handbook)</emphasis>：使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para> </listitem> <listitem> - <para><emphasis>FAQ</emphasis> 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para> + <para><emphasis>常見問答集 (FAQ)</emphasis>：主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para> </listitem> <listitem> - <para><emphasis>線上手冊 ( manual pages )</emphasis>:英文版的系統 manual 並不是由 <acronym>FDP</acronym> 所撰寫的，因為它們是屬於 base system 的部份。 然而，<acronym>FDP</acronym> 可以修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。</para> + <para><emphasis>操作手冊 (Manual page)</emphasis>：英文版的系統手冊並不是由 <acronym>FDP</acronym> 所撰寫的，因為它們是屬於基礎系統 (Base system) 的部份。 然而，<acronym>FDP</acronym> 可以修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。</para> </listitem> <listitem> - <para><emphasis>網站</emphasis>: 這是 FreeBSD 在網路上的主要部份，位於 <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link>; 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方</para> + <para><emphasis>網站</emphasis>：這是 FreeBSD 在網路上的主要部份，位於 <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link>; 以及許多其他鏡像站 (Mirror)。這網站是許多人第一次接觸 FreeBSD 的地方</para> </listitem> </itemizedlist> <para>翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯</para> - <para>FreeBSD 網站、使用手冊、和 <acronym>FAQ</acronym> 的文件原始碼可以在 <literal>https://svn.FreeBSD.org/doc/</literal>; 的文件庫取得。</para> + <para>FreeBSD 網站、使用手冊、和 <acronym>FAQ</acronym> 的文件原始碼可以在 <literal>https://svn.FreeBSD.org/doc/</literal>; 的文件檔案庫取得。</para> <para>線上手冊的原始碼則是在 <literal>https://svn.FreeBSD.org/base/</literal>; 的原始碼庫可以取得。</para> - <para>文件提交訊息可以用 <command>svn log</command> 察看。 提交訊息也會保存在<uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>。</para>; + <para>說明文件提交訊息可以用 <command>svn log</command> 察看。 提交訊息也會封存在 <uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>。</para>; - <para>這些儲存庫的網頁版位於<link xlink:href="https://svnweb.FreeBSD.org/doc/"/>; 和 <link xlink:href="https://svnweb.FreeBSD.org/base/"/>。</para>; + <para>這些儲存庫的網頁版位於 <link xlink:href="https://svnweb.FreeBSD.org/doc/"/>; 和 <link xlink:href="https://svnweb.FreeBSD.org/base/"/>。</para>; - <para>許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 <acronym>FDP</acronym> 的檔案中。其他一些文件則是作者希望放在他處。<acronym>FDP</acronym> 會盡力提供這些文件的連結。</para> + <para>許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 <acronym>FDP</acronym> 的檔案中。其他一些說明文件則是作者希望放在他處。<acronym>FDP</acronym> 會盡力提供這些說明文件的連結。</para> </sect1> </chapter> @@ -463,17 +463,17 @@ The time is 09:18</screen></entry> <chapter version="5.0" xml:id="tools"> <title>工具</title> - <para>有些工具軟體用來管理 FreeBSD 文件，並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。</para> + <para>有些工具軟體用來管理 FreeBSD 說明文件，並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。</para> <sect1 xml:id="tools-required"> <title>必備工具</title> - <para>從 Ports Collection 安裝 <package>textproc/docproj</package>。這個 <emphasis>組合型 port (meta-port)</emphasis> 會安裝處理 FreeBSD 文件需要的所有應用程式。以下列出特定元件的進一步說明。</para> + <para>從 Port 套件集安裝 <package>textproc/docproj</package>。這個 <emphasis>meta-port</emphasis> 會安裝處理 FreeBSD 說明文件需要的所有應用程式。以下列出特定元件的進一步說明。</para> <sect2> <title><acronym>DTD</acronym>s 與 <acronym>Entities</acronym></title> - <para>FreeBSD 文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 組。這些都會經由 <package>textproc/docproj</package> port 來安裝。</para> + <para>FreeBSD 說明文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 集合。這些都會經由 <package>textproc/docproj</package> Port 來安裝。</para> <variablelist> <varlistentry> @@ -488,7 +488,7 @@ The time is 09:18</screen></entry> <term xml:lang="en">DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml</package>)</term> <listitem> - <para>DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。</para> + <para>DocBook 設計來製作技術說明文件的標記語言版本。FreeBSD 說明文件是以 DocBook 來撰寫。</para> </listitem> </varlistentry> @@ -504,9 +504,9 @@ The time is 09:18</screen></entry> </sect1> <sect1 xml:id="tools-optional"> - <title>輔助工具</title> + <title>選用工具</title> - <para>不一定得裝下列的應用程式才行，但是，出的格式也更具彈性。</para> + <para>以下應用程式並非必要，但有了可讓在說明文件的作業上更簡單或提升能力。</para> <sect2> <title>軟體</title> @@ -565,149 +565,78 @@ The time is 09:18</screen></entry> <chapter version="5.0" xml:id="working-copy"> <title>工作副本</title> - <para xml:lang="en">The <emphasis>working copy</emphasis> 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.</para> - - <para xml:lang="en">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.</para> - - <para xml:lang="en"><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link> - is used to manage the FreeBSD documentation files. It is installed - by <package>textproc/docproj</package> as one of - the required applications.</para> + <para><emphasis>工作副本 (Working copy)</emphasis> 指的是已下載到本地電腦的 FreeBSD 說明文件樹檔案庫，所有對工作副本的更改會經過測試後再以修補檔 (Patch) 的格式提交到主要檔案庫。</para> + + <para>完整的說明文件樹副本會佔據 700 MB 的磁碟空間，要有空間能夠儲存暫存檔及各種輸出格式的測試版本需要 1 GB 的空間。</para> + + <para>FreeBSD 說明文件檔案使用 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link> 來管理，由於 <application>Subversion</application> 為 <package>textproc/docproj</package> 的必要應用程式之一，所以會隨著 <package>textproc/docproj</package> 一併安裝。</para> <sect1 xml:id="working-copy-doc-and-src"> - <title xml:lang="en">Documentation and Manual Pages</title> + <title>說明文件與操作手冊</title> - <para xml:lang="en">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 <acronym>FDP</acronym>'s - territory. Two repositories are involved: - <literal>doc</literal> for the books and articles, and - <literal>base</literal> for the operating system and manual - pages. To edit manual pages, the <literal>base</literal> - repository must be checked out separately.</para> - - <para xml:lang="en">Repositories may contain multiple versions of documentation - and source code. New modifications are almost always made only - to the latest version, called <literal>head</literal>.</para> + <para>FreeBSD 說明文件不只有書籍與文章，還有所有指令與設定檔的操作手冊 (Manual page) 也是文件的一部份，其中也有一部份是 <acronym>FDP</acronym> 的地盤。相關的檔案庫有兩個：<literal>doc</literal> 中有書籍與文章，而 <literal>base</literal> 中有作業系統以及操作手冊。要編輯操作手冊則必須另外取出 (Checkout) <literal>base</literal> 檔案庫。</para> + + <para>檔案庫中可能會含有數個版本的說明文件與原始碼。新的修改幾乎都只對最新版本 <literal>head</literal> 做更新。</para> </sect1> <sect1 xml:id="working-copy-choosing-directory"> - <title xml:lang="en">Choosing a Directory</title> + <title>選擇一個目錄</title> - <para xml:lang="en">FreeBSD documentation is traditionally stored in - <filename>/usr/doc/</filename>, and system - source code with manual pages in - <filename>/usr/src/</filename>. 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 <filename>~/doc</filename> - and <filename>~/src</filename>, both - subdirectories of the user's home directory.</para> + <para>FreeBSD 說明文件一般會儲存在 <filename>/usr/doc/</filename>，而系統原始碼及操作手冊則會存在 <filename>/usr/src/</filename>。這些目錄樹可改放在其他地方，使用者可能會為了避免與現有在主要目錄的資料搞混，把工作副本放在其他的地方。以下的例子會放在 <filename>~/doc</filename> 以及 <filename>~/src</filename> 兩個在使用者家目錄下的目錄。</para> </sect1> <sect1 xml:id="working-copy-checking-out"> - <title xml:lang="en">Checking Out a Copy</title> + <title>取出一份副本</title> - <para xml:lang="en">A download of a working copy from the repository is called - a <emphasis>checkout</emphasis>, and done with - <command>svn checkout</command>. This example checks out a - copy of the latest version (<literal>head</literal>) of - the main documentation tree:</para> + <para>從檔案庫下載工作副本的動作稱作 <emphasis>取出 (Checkout)</emphasis>，使用 <command>svn checkout</command> 來完成。本範例會取出主要說明文件樹最新版本的副本：</para> <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> - <para xml:lang="en">A checkout of the source code to work on manual pages is - very similar:</para> + <para>取出原始碼編輯操作手冊的動作非常相似：</para> <screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> </sect1> <sect1 xml:id="working-copy-updating"> - <title xml:lang="en">Updating a Working Copy</title> + <title>更新工作副本</title> - <para xml:lang="en">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 - <command>svn update</command> on the directory containing the - local working copy:</para> + <para>在 FreeBSD 檔案庫中的文件與檔案每天都會更改，人們會修改檔案與提交變更的頻率非常快，即使取出 (Checkout) 只過小一段時間，本地的工作副本可能就與主要 FreeBSD 檔案庫有差異了。要更新本地版本以同步對主要檔案庫的變更可在有本地工作副本的目錄下使用 <command>svn update</command>：</para> <screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> - <para xml:lang="en">Get in the protective habit of using - <command>svn update</command> 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.</para> + <para>養成良好的習慣在編輯文件檔前先執行 <command>svn update</command>，可能會有其他人才剛編輯完該檔案，本地工作副本在尚未更新前不會有最後的變更內容，編輯最新版本的檔案會比將舊版本地檔案與新版檔案庫檔案合併來的簡單多了。</para> </sect1> <sect1 xml:id="working-copy-revert"> - <title xml:lang="en">Reverting Changes</title> + <title>還原變更</title> - <para xml:lang="en">Sometimes it turns out that changes were - not necessary after all, or the writer just wants to start over. - Files can be <quote>reset</quote> to their unchanged form with - <command>svn revert</command>. For example, to erase the edits - made to <filename>chapter.xml</filename> and reset it to - unmodified form:</para> + <para>有時才做完的變更可能就變的不需要了，或者作者剛想要重新搛寫。檔案可使以使用 <command>svn revert</command> 來<quote>重設</quote>成尚未被修改刪的狀態，舉例來說，要清除所有對 <filename>chapter.xml</filename> 的修改然後還原到未修改的版本可：</para> <screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen> </sect1> <sect1 xml:id="working-copy-making-diff"> - <title xml:lang="en">Making a Diff</title> + <title>比對差異</title> - <para xml:lang="en">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 <emphasis>diff</emphasis> files are produced - by redirecting the output of <command>svn diff</command> into a - file:</para> + <para>在編輯一個檔案或數個檔案完成之後，需將本地工作副本與 FreeBSD 檔案庫的差異儲存到一個檔案然後提交。這些 <emphasis>差異 (Diff)</emphasis> 檔可透過將 <command>svn diff</command> 的輸出轉向到檔案來建立： </para> <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> <prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> - <para xml:lang="en">Give the file a meaningful name that identifies the - contents. The example above is for spelling fixes to the whole - documentation tree.</para> - - <para xml:lang="en">If the diff file is to be submitted with the web - <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a FreeBSD - problem report</link></quote> interface, add a - <filename>.txt</filename> extension to give the earnest and - simple-minded web form a clue that the contents are plain - text.</para> + <para>給檔案取一個有意義的名字來辨識這次修改的內容，上述範例為例則是要修正整個說明文件樹的拼寫。</para> - <para xml:lang="en">Be careful: <command>svn diff</command> 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:</para> + <para>若 diff 檔要使用網站的 <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a FreeBSD problem report</link></quote> 介面來提交，請加上 <filename>.txt</filename> 副檔名來給認真又單純的網頁表單可以辨識其內容為純文字的線索。</para> + + <para>請小心：<command>svn diff</command> 會產生所有在目前目錄及其子目錄的變更差異，若在該工作副本中有已經編輯過的檔案還沒有要提交，請列出需要比較差異的檔案清單：</para> <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> <prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen> </sect1> <sect1 xml:id="working-copy-subversion-references"> - <title xml:lang="en"><application>Subversion</application> References</title> + <title><application>Subversion</application> 參考文獻</title> - <para xml:lang="en">These examples show very basic usage of - <application>Subversion</application>. More detail is available - in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link> - and the <link xlink:href="http://subversion.apache.org/docs/">Subversion - documentation</link>.</para> + <para>以下範例會示範 <application>Subversion</application> 的基本用法，要取得更多資訊可至 <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link> 與 <link xlink:href="http://subversion.apache.org/docs/">Subversion 說明文件</link>。</para> </sect1> </chapter> @@ -744,49 +673,37 @@ The time is 09:18</screen></entry> $FreeBSD$ --> <chapter version="5.0" xml:id="structure"> - <title xml:lang="en">Documentation Directory Structure</title> + <title>說明文件目錄結構</title> - <para xml:lang="en">Files and directories in the - <filename>doc/</filename> tree follow a - structure meant to:</para> + <para>在 <filename>doc/</filename> 樹中的檔案與目錄需要遵守特定結構是因為：</para> <orderedlist> <listitem> - <para xml:lang="en">Make it easy to automate converting the document to other - formats.</para> + <para>讓自動轉換說明文件到各種格式更簡單。</para> </listitem> <listitem> - <para xml:lang="en">Promote consistency between the different documentation - organizations, to make it easier to switch between working on - different documents.</para> + <para>促進不同說明文件組織之間的一致性，以便更輕鬆的在不同說明文件之間切換。</para> </listitem> <listitem> - <para xml:lang="en">Make it easy to decide where in the tree new documentation - should be placed.</para> + <para>可以很容易的決定新的說明文件應該放在文件樹中的哪個位置。</para> </listitem> </orderedlist> - <para xml:lang="en">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.</para> + <para>除此之外，說明文件樹必須能容納各種不同語言與編碼的說明文件。很重要的一點是，說明文件樹結構不應強制任何特定默認或文化的偏好。</para> <sect1 xml:id="structure-top"> - <title xml:lang="en">The Top Level, - <filename>doc/</filename></title> + <title>最上層，<filename>doc/</filename></title> - <para xml:lang="en">There are two types of directory under - <filename>doc/</filename>, each with very - specific directory names and meanings.</para> + <para>在 <filename>doc/</filename> 底下有兩種類型的目錄，兩種都有非常明確的目錄名稱與意義。</para> <informaltable pgwide="1" frame="none"> <tgroup cols="2"> <thead> <row> - <entry xml:lang="en">Directory</entry> - <entry xml:lang="en">Usage</entry> + <entry>目錄</entry> + <entry>用途</entry> </row> </thead> @@ -795,31 +712,14 @@ The time is 09:18</screen></entry> <entry valign="top" xml:lang="en"> <filename>share</filename></entry> - <entry xml:lang="en">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 - <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> infrastructure are in - <filename>share/mk</filename>, while - the additional <acronym>XML</acronym> support files - (such as the FreeBSD extended DocBook - <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry> + <entry>含有未特定用於各說明文件翻譯與編碼的檔案。其子目錄更進一步將不同資訊的分類，例如，構成 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 基礎設施的檔案放置於 <filename>share/mk</filename>，而額外的 <acronym>XML</acronym> 支援檔 (如 FreeBSD 延伸的 DocBook <acronym>DTD</acronym>) 則放在 <filename>share/xml</filename>。</entry> </row> <row> <entry valign="top" xml:lang="en"> <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> - <entry xml:lang="en">One directory exists for each available translation - and encoding of the documentation, for example - <filename>en_US.ISO8859-1/</filename> - and <filename>zh_TW.UTF-8/</filename>. - 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.</entry> + <entry>每一個目錄代表可用的說明文件翻譯與編碼，例如 <filename>en_US.ISO8859-1/</filename> 及 <filename>zh_TW.UTF-8/</filename>。名稱雖然長，但完整表達語言與編碼可以避免未來當一個翻譯團隊要以不同編碼提供同一個語言的說明文件造成的問題，這也同時避免往後要切換成萬國碼 (Unicode) 可能造成的問題。</entry> </row> </tbody> </tgroup> @@ -827,20 +727,16 @@ The time is 09:18</screen></entry> </sect1> <sect1 xml:id="structure-locale"> - <title xml:lang="en">The - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> - Directories</title> - - <para xml:lang="en">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.</para> + <title><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> 目錄</title> + + <para>這些目錄中含有說明文件。在此階層說明文件分成三個分類，使用不同的目錄名稱來代表。</para> <informaltable pgwide="1" frame="none"> <tgroup cols="2"> <thead> <row> - <entry xml:lang="en">Directory</entry> - <entry xml:lang="en">Usage</entry> + <entry>目錄</entry> + <entry>用途</entry> </row> </thead> @@ -849,168 +745,89 @@ The time is 09:18</screen></entry> <entry valign="top" xml:lang="en"> <filename>articles</filename></entry> - <entry xml:lang="en">Documentation marked up as a DocBook - <tag>article</tag> (or equivalent). Reasonably - short, and broken up into sections. Normally only - available as one <acronym>XHTML</acronym> file.</entry> + <entry>以 DocBook <tag>article</tag> (或同等級) 標記的說明文件。非常短，且會分成幾個小節，通常取得時只會有一個 <acronym>XHTML</acronym> 檔案。</entry> </row> <row> <entry valign="top" xml:lang="en"><filename>books</filename></entry> - <entry xml:lang="en">Documentation marked up as a DocBook - <tag>book</tag> (or equivalent). Book length, - and broken up into chapters. Normally available as both - one large <acronym>XHTML</acronym> file (for people with - fast connections, or who want to print it easily from a - browser) and as a collection of linked, smaller - files.</entry> + <entry>以 DocBook <tag>book</tag> (或同等級) 標記的說明文件。有跟書籍一樣的長度，會分成數個章。通常取得時會包含一個大型的 <acronym>XHTML</acronym> 檔 (供有較快連線速度的人使用，或者那些想直接在瀏覽器列印的人) 與數個連結的較小的檔案。</entry> </row> <row> <entry valign="top" xml:lang="en"> <filename>man</filename></entry> - <entry xml:lang="en">For translations of the system manual pages. This - directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename> - directories, corresponding to the sections that have - been translated.</entry> + <entry>供系統操作手冊 (Manual page) 翻譯使用。這個目錄會包含一個或多個 <filename role="directory">man<replaceable>n</replaceable></filename> 目錄來對應已經翻譯的章節。</entry> </row> </tbody> </tgroup> </informaltable> - <para xml:lang="en">Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> - directory will have all of these subdirectories. It depends - on how much translation has been accomplished by that - translation team.</para> + <para>並非所有 <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> 的目錄都會有這些子目錄，這要看該翻譯團隊已經完成了多少翻譯來決定。</para> </sect1> <sect1 xml:id="structure-document"> - <title xml:lang="en">Document-Specific Information</title> + <title>文件特定資訊</title> - <para xml:lang="en">This section contains specific notes about particular - documents managed by the FDP.</para> + <para>本節內含有關由 FDP 所管理的特定文件的特定注意事項。</para> <sect2> - <title xml:lang="en">The Handbook</title> + <title>使用手冊 (Handbook)</title> <subtitle xml:lang="en"><filename>books/handbook/</filename></subtitle> - <para xml:lang="en">The Handbook is written in DocBook <acronym>XML</acronym> - using the FreeBSD DocBook extended <acronym>DTD</acronym>.</para> + <para>操作手冊是以使用 FreeBSD DocBook 擴充 <acronym>DTD</acronym> 的 DocBook <acronym>XML</acronym> 所撰寫。</para> - <para xml:lang="en">The Handbook is organized as a DocBook - <tag>book</tag>. The book is divided into - <tag>part</tag>s, each of which contains several - <tag>chapter</tag>s. <tag>chapter</tag>s are - further subdivided into sections (<tag>sect1</tag>) - and subsections (<tag>sect2</tag>, - <tag>sect3</tag>) and so on.</para> + <para>使用手冊使用 DocBook <tag>book</tag> 來組織，整個手冊區分成數個部份 (<tag>part</tag>)，每個部份中內含數個章 (<tag>chapter</tag>)，而章 (<tag>chapter</tag>) 又更進一步的細分成數個節 (<tag>sect1</tag>) 與小節 (<tag>sect2</tag>, <tag>sect3</tag>) 以此類推。</para> <sect3> - <title xml:lang="en">Physical Organization</title> + <title>實體組織結構</title> - <para xml:lang="en">There are a number of files and directories within the - <filename>handbook</filename> directory.</para> + <para>在 <filename>handbook</filename> 目錄中有數個檔案及目錄。</para> <note> - <para xml:lang="en">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 - <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para> + <para>使用手冊的組織結構可能會隨時改變，本文件所詳述的組織結構可能會與現況不盡相同。有關使用手冊組織結構的問題可張貼到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>。</para> </note> <sect4> <title xml:lang="en"><filename>Makefile</filename></title> - <para xml:lang="en">The <filename>Makefile</filename> defines some - variables that affect how the <acronym>XML</acronym> - source is converted to other formats, and lists the - various source files that make up the Handbook. It then - includes the standard <filename>doc.project.mk</filename>, - to bring in the rest of the code that handles converting - documents from one format to another.</para> + <para><filename>Makefile</filename> 定義了一些會影響 <acronym>XML</acronym> 原始碼要如何轉換至其他格式的變數，並列出產生使用手冊所需的各原始檔，接著會引用可處理在各種文件格式轉換的標準 <filename>doc.project.mk</filename> 程式碼。</para> </sect4> <sect4> <title xml:lang="en"><filename>book.xml</filename></title> - <para xml:lang="en">This is the top level document in the Handbook. It - contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE - declaration</link>, as well as the elements that - describe the Handbook's structure.</para> - - <para xml:lang="en"><filename>book.xml</filename> uses <link linkend="xml-primer-parameter-entities">parameter - entities</link> to load in the files with the - <filename>.ent</filename> extension. These files - (described later) then define <link linkend="xml-primer-general-entities">general - entities</link> that are used throughout the rest of the - Handbook.</para> + <para>此為使用手冊的最上層文件，其中包含了使用手冊的 <link linkend="xml-primer-doctype-declaration">DOCTYPE 宣告</link>以及用來描述使用手冊結構的元素。</para> + + <para><filename>book.xml</filename> 會使用 <link linkend="xml-primer-parameter-entities">參數 Entities</link> 來載入 <filename>.ent</filename> 副檔名的檔案。這些檔案 (稍後會詳述) 接著會定義使用手冊剩下篇幅會使用的 <link linkend="xml-primer-general-entities">一般 Entities</link>。</para> </sect4> <sect4> <title xml:lang="en"><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title> - <para xml:lang="en">Each chapter in the Handbook is stored in a file - called <filename>chapter.xml</filename> in a separate - directory from the other chapters. Each directory is - named after the value of the <literal>id</literal> - attribute on the <tag>chapter</tag> - element.</para> + <para>每個在使用手冊的章會儲存成名稱為 <filename>chapter.xml</filename> 的檔案，分別放在不同的目錄中。每個目錄均是以在 <tag>chapter</tag> 元素中 <literal>id</literal> 屬性中的值來命名。</para> - <para xml:lang="en">For example, if one of the chapter files - contains:</para> + <para>例如，若有一章的檔案內容為：</para> <programlisting xml:lang="en"><tag class="starttag">chapter id="kernelconfig"</tag> ... <tag class="endtag">chapter</tag></programlisting> - <para xml:lang="en">Then it will be called - <filename>chapter.xml</filename> in the - <filename>kernelconfig</filename> directory. In general, - the entire contents of the chapter are in this one - file.</para> - - <para xml:lang="en">When the <acronym>XHTML</acronym> version of the - Handbook is produced, this will yield - <filename>kernelconfig.html</filename>. This is because - of the <literal>id</literal> value, and is not related to - the name of the directory.</para> - - <para xml:lang="en">In earlier versions of the Handbook, the files were - stored in the same directory as - <filename>book.xml</filename>, and named after the value - of the <literal>id</literal> attribute on the file's - <tag>chapter</tag> element. Now, it is possible - to include images in each chapter. Images for each - Handbook chapter are stored within <filename>share/images/books/handbook</filename>. - The localized version of these images should be - placed in the same directory as the <acronym>XML</acronym> - 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.</para> - - <para xml:lang="en">A brief look will show that there are many directories - with individual <filename>chapter.xml</filename> files, - including <filename>basics/chapter.xml</filename>, - <filename>introduction/chapter.xml</filename>, and - <filename>printing/chapter.xml</filename>.</para> + <para>那麼放置這個 <filename>chapter.xml</filename> 的目錄則會命名為 <filename>kernelconfig</filename>。一般來說一章的所有內容會存放在這一個檔案。</para> + + <para>當有 <acronym>XHTML</acronym> 版本的使用手冊之後，也會用這個檔產出 <filename>kernelconfig.html</filename>，這個名稱是根據 <literal>id</literal> 的值而定，與目錄名稱無關。</para> + + <para>在早期版本的使用手冊，檔案皆儲存在與 <filename>book.xml</filename> 相同的目錄中，而名稱會以 <tag>chapter</tag> 元素中的 <literal>id</literal> 屬性的值來命名。現在可在每個章節之中引用圖片，每個使用手冊章節的圖片會儲存在 <filename>share/images/books/handbook</filename>，而在地化版本的圖片應放在與每個章節 <acronym>XML</acronym> 原始碼相同的目錄。命名空間會衝突是必然的，但以目錄多、檔案少與目錄少、檔案多的結構相比，目錄多、檔案少會較容易處理命名空間衝突的問題。</para> + + <para>簡單來說會有很多個內含 <filename>chapter.xml</filename> 檔案的目錄，例如 <filename>basics/chapter.xml</filename>, <filename>introduction/chapter.xml</filename> 以及 <filename>printing/chapter.xml</filename>。</para> <important> - <para xml:lang="en">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.</para> + <para>請勿以在使用手冊中的章節順序來命名章節或目錄，因為順序是會隨使用手冊重新組織後的內容改變的。重新組織結構應不需要去重新命名檔案，除非整個章節的階層被提升或下降。</para> </important> - <para xml:lang="en">The <filename>chapter.xml</filename> files are not - complete <acronym>XML</acronym> documents that can be - built individually. They can only be built - as parts of the whole Handbook.</para> + <para><filename>chapter.xml</filename> 檔案並不是可以被單獨建置的完整 <acronym>XML</acronym> 文件，只能做為使用手冊的一部份來建置。</para> </sect4> </sect3> </sect2> @@ -1050,75 +867,63 @@ The time is 09:18</screen></entry> $FreeBSD$ --> <chapter version="5.0" xml:id="doc-build"> - <title xml:lang="en">The Documentation Build Process</title> + <title>說明文件建置流程</title> - <para xml:lang="en">This chapter covers organization of the documentation build - process and how <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to control it.</para> + <para>本章內容涵蓋了說明文件建置流程以及如何使用 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來控制如何建置。</para> <sect1 xml:id="doc-build-rendering"> - <title xml:lang="en">Rendering DocBook into Output</title> + <title>繪製 Docbook 為其他格式</title> - <para xml:lang="en">Different types of output can be produced from a single - DocBook source file. The type of output desired is set with the - <varname>FORMATS</varname> variable. A list of known formats is - stored in <varname>KNOWN_FORMATS</varname>:</para> + <para>從單一個 DocBook 原始檔可以產生各種不同類型的輸出，想要輸出的類型可用 <varname>FORMATS</varname> 變數來設定。已知的格式清單列在 <varname>KNOWN_FORMATS</varname> 中：</para> <screen xml:id="doc-build-rendering-known-formats" xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> <prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput></screen> <table xml:id="doc-build-rendering-common-formats" frame="none"> - <title xml:lang="en">Common Output Formats</title> + <title>常見輸出格式</title> <tgroup cols="3"> <thead> <row> - <entry xml:lang="en"><varname>FORMATS</varname> Value</entry> - <entry xml:lang="en">File Type</entry> - <entry xml:lang="en">Description</entry> + <entry><varname>FORMATS</varname> 值</entry> + <entry>檔案類型</entry> + <entry>說明</entry> </row> </thead> <tbody> <row> <entry xml:lang="en"><literal>html</literal></entry> - <entry xml:lang="en"><acronym>HTML</acronym>, one file</entry> - <entry xml:lang="en">A single <filename>book.html</filename> or - <filename>article.html</filename>.</entry> + <entry><acronym>HTML</acronym>，單檔</entry> + <entry>單一 <filename>book.html</filename> 或 <filename>article.html</filename>。</entry> </row> <row> <entry xml:lang="en"><literal>html-split</literal></entry> - <entry xml:lang="en"><acronym>HTML</acronym>, multiple files</entry> - <entry xml:lang="en">Multiple <acronym>HTML</acronym> files, one for - each chapter or section, for use on a typical web - site.</entry> + <entry><acronym>HTML</acronym>，多檔</entry> + <entry>多個 <acronym>HTML</acronym> 檔案，每個章或節一個檔案，供一般網站使用。</entry> </row> <row> <entry xml:lang="en"><literal>pdf</literal></entry> <entry xml:lang="en"><acronym>PDF</acronym></entry> - <entry xml:lang="en">Portable Document Format</entry> + <entry>可攜的文件格式</entry> </row> </tbody> </tgroup> </table> - <para xml:lang="en">The default output format can vary by document, but is - usually <literal>html-split</literal>. Other formats are chosen - by setting <varname>FORMATS</varname> to a specific value. - Multiple output formats can be created at a single time by - setting <varname>FORMATS</varname> to a list of formats.</para> + <para>預設輸出的格式會依文件而有所不同，但同常是 <literal>html-split</literal>。其他格式可設定 <varname>FORMATS</varname> 為特定值來選擇。在 <varname>FORMATS</varname> 設定所需格式的清單可一次輸出多個格式。</para> <example xml:id="doc-build-formats-example-html"> - <title xml:lang="en">Build a Single HTML Output File</title> + <title>建置單頁 HTML 輸出檔</title> <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> <prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen> </example> <example xml:id="doc-build-formats-example-html-split-pdf"> - <title xml:lang="en">Build HTML-Split and <acronym>PDF</acronym> Output - Files</title> + <title>建置分頁 HTML 及 <acronym>PDF</acronym> 輸出檔</title> <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> <prompt>%</prompt> <userinput>make FORMATS="html-split pdf"</userinput></screen> @@ -1126,67 +931,51 @@ The time is 09:18</screen></entry> </sect1> <sect1 xml:id="doc-build-toolset"> - <title xml:lang="en">The FreeBSD Documentation Build Toolset</title> + <title>FreeBSD 說明文件建置工具集</title> - <para xml:lang="en">These are the tools used to build and install the - <acronym>FDP</acronym> documentation.</para> + <para>建置與安裝 <acronym>FDP</acronym> 說明文件會使用到以下工具。</para> <itemizedlist> <listitem> - <para xml:lang="en">The primary build tool is <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, specifically - <application>Berkeley Make</application>.</para> + <para>主要的建置工具為 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>，特別是 <application>Berkeley Make</application>。</para> </listitem> <listitem> - <para xml:lang="en">Package building is handled by FreeBSD's - <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para>套件建置會使用 FreeBSD 的 <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> 來處理。</para> </listitem> <listitem> - <para xml:lang="en"><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to create compressed versions of - the document. <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> archives are also supported. - <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used for package building.</para> + <para><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> 用來建立壓縮版的文件，也支援 <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> 封存。<citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 則用在套件建置。</para> </listitem> <listitem> - <para xml:lang="en"><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to install the - documentation.</para> + <para><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> 用來安裝說明文件。</para> </listitem> </itemizedlist> </sect1> <sect1 xml:id="doc-build-makefiles"> - <title xml:lang="en">Understanding <filename>Makefile</filename>s in the - Documentation Tree</title> + <title>了解在說明文件樹中的 <filename>Makefile</filename></title> - <para xml:lang="en">There are three main types of <filename>Makefile</filename>s - in the FreeBSD Documentation Project tree.</para> + <para>在 FreeBSD 說明文件計劃樹底下的 <filename>Makefile</filename> 主要有三個類型。</para> <itemizedlist> <listitem> - <para xml:lang="en"><link linkend="sub-make">Subdirectory - <filename>Makefile</filename>s</link> simply pass - commands to those directories below them.</para> + <para><link linkend="sub-make">子目錄的 <filename>Makefile</filename></link> 傳遞指令給在其所在目錄底下的目錄。</para> </listitem> <listitem> - <para xml:lang="en"><link linkend="doc-make">Documentation - <filename>Makefile</filename>s</link> describe the - documents that are produced from this - directory.</para> + <para><link linkend="doc-make">說明文件的 <filename>Makefile</filename>s</link> 用來描述要如何在其所在目錄產生文件。</para> </listitem> <listitem> - <para xml:lang="en"><link linkend="make-includes"><application>Make</application> - includes</link> are the glue that perform the document - production, and are usually of the form - <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para> + <para><link linkend="make-includes"><application>Make</application> 引用檔</link> 會連結一些產生文件所需的程式，通常為 <filename>doc.<replaceable>xxx</replaceable>.mk</filename>。</para> </listitem> </itemizedlist> <sect2 xml:id="sub-make"> - <title xml:lang="en">Subdirectory <filename>Makefile</filename>s</title> + <title>子目錄的 <filename>Makefile</filename></title> <para xml:lang="en">These <filename>Makefile</filename>s usually take the form of:</para> @@ -1244,13 +1033,11 @@ DOC_PREFIX?= ${.CURDIR}/.. </sect2> <sect2 xml:id="doc-make"> - <title xml:lang="en">Documentation <filename>Makefile</filename>s</title> + <title>說明文件的 <filename>Makefile</filename></title> - <para xml:lang="en">These <filename>Makefile</filename>s set <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> - variables that describe how to build the documentation - contained in that directory.</para> + <para>這些 <filename>Makefile</filename> 用來設定 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 變數來描述要如何建置在該目錄中的說明文件。</para> - <para xml:lang="en">Here is an example:</para> + <para>這裡有一個例子：</para> <programlisting xml:lang="en">MAINTAINER=nik@FreeBSD.org @@ -1268,34 +1055,18 @@ DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> - <para xml:lang="en">The <varname>MAINTAINER</varname> variable allows - committers to claim ownership of a document in the FreeBSD - Documentation Project, and take responsibility for maintaining - it.</para> + <para><varname>MAINTAINER</varname> 變數讓提交者可以聲明文件在 FreeBSD 說明文件計劃中的所有權，並負責維護該文件。</para> + + <para><varname>DOC</varname> 是由此目錄會建立的主要文件的名稱 (不需要 <filename>.xml</filename> 副檔名)。<varname>SRCS</varname> 會列出產生文件所需的各別檔案，此處也應引用要在重新建置 (Rebuild) 使用的重要的檔案。</para> - <para xml:lang="en"><varname>DOC</varname> is the name (sans the - <filename>.xml</filename> extension) of the main document - created by this directory. <varname>SRCS</varname> 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.</para> - - <para xml:lang="en"><varname>FORMATS</varname> indicates the default formats - that should be built for this document. - <varname>INSTALL_COMPRESSED</varname> is the default list of - compression techniques that should be used in the document - build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by - default, should be non-empty if only compressed documents are - desired in the build.</para> + <para><varname>FORMATS</varname> 用來指定此份文件建置時預設應採用的格式。<varname>INSTALL_COMPRESSED</varname> 是為在文件建置時預設要使用的壓縮技術清單。<varname>INSTALL_ONLY_COMPRESS</varname> 預設為空值的，若在建置時只想要產生壓縮後的文件則改成非空值。</para> - <para xml:lang="en">The <varname>DOC_PREFIX</varname> and include statements - should be familiar already.</para> + <para><varname>DOC_PREFIX</varname> 以及 include 敘述句應不需再說明了。</para> </sect2> </sect1> <sect1 xml:id="make-includes"> - <title xml:lang="en">FreeBSD Documentation Project - <application>Make</application> Includes</title> + <title>FreeBSD 說明文件計劃 <application>Make</application> 引用檔</title> <para xml:lang="en"><citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes are best explained by inspection of the code. Here are the system include files:</para> @@ -1347,7 +1118,7 @@ PRI_LANG?= en_US.ISO8859-1 <sect3> - <title xml:lang="en">Variables</title> + <title>變數</title> <para xml:lang="en"><varname>DOCFORMAT</varname> and <varname>MAINTAINER</varname> are assigned default values, @@ -1372,7 +1143,7 @@ PRI_LANG?= en_US.ISO8859-1 </sect3> <sect3> - <title xml:lang="en">Conditionals</title> + <title>條件</title> <para xml:lang="en">The <literal>.if defined(DOC)</literal> line is an example of a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> conditional which, like in other @@ -1397,7 +1168,7 @@ PRI_LANG?= en_US.ISO8859-1 describe the most important features.</para> <sect3> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201703251358.v2PDw04e012908>