Differential D10132 Diff 26647 head/zh_TW.UTF-8/books/fdp-primer/book.xml

Changeset View

Standalone View

head/zh_TW.UTF-8/books/fdp-primer/book.xml

This file is larger than 256 KB, so syntax highlighting is disabled by default.

Show First 20 Lines • Show All 53 Lines • ▼ Show 20 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,		HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN		STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW">		<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>		<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>

<pubdate role="rcs" xml:lang="en">$FreeBSD$</pubdate>		<pubdate role="rcs" xml:lang="en">$FreeBSD$</pubdate>

<releaseinfo xml:lang="en">$FreeBSD$</releaseinfo>		<releaseinfo xml:lang="en">$FreeBSD$</releaseinfo>


Show All 34 Lines	<para xml:lang="en">THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE		TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH		USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.</para>		DAMAGE.</para>
</important>		</important>
</legalnotice>		</legalnotice>


<abstract>		<abstract>
<para>感謝您參與 FreeBSD 文件計劃，您的點滴貢獻，都相當寶貴。</para>		<para>感謝您參與 FreeBSD 說明文件計劃，您的點滴貢獻，都相當寶貴。</para>

<para>本入手書內容包括：如何開始著手貢獻FreeBSD 文件計劃 (簡稱： <acronym>FDP</acronym> )的各項細節，以及會用到的一些工具、軟體，以及文件計畫的宗旨。</para>		<para>本入手書內容包括：如何開始著手貢獻 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, <acronym>FDP</acronym>) 的各項細節，以及會用到的一些工具、軟體，以及文件計畫的宗旨。</para>

<para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para>		<para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para>
</abstract>		</abstract>
</info>		</info>

<preface xml:id="preface">		<preface xml:id="preface">
<title>序</title>		<title>序</title>

<sect1 xml:id="preface-prompts">		<sect1 xml:id="preface-prompts">
<title>Shell 提示符號(Prompts)</title>		<title>Shell 提示符號</title>

<para>下表顯示出一般使用者帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt) ，來提醒您該用哪種帳號才對。</para>		<para>下表顯示出一般使用者帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt) ，來提醒您該用哪種帳號才對。</para>

<informaltable frame="none" pgwide="1">		<informaltable frame="none" pgwide="1">
<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry>帳號</entry>		<entry>帳號</entry>
Show All 21 Lines	<sect1 xml:id="preface-conventions">

<para>下表為本書中所使用編排風格方式</para>		<para>下表為本書中所使用編排風格方式</para>

<informaltable frame="none" pgwide="1">		<informaltable frame="none" pgwide="1">
<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry>代表意義</entry>		<entry>代表意義</entry>
<entry>舉例</entry>		<entry>範例</entry>
</row>		</row>
</thead>		</thead>

<tbody>		<tbody>
<row>		<row>
<entry>指令</entry>		<entry>指令</entry>
<entry>使用 <command>ls -l</command> 來列出所有的檔案。</entry>		<entry>使用 <command>ls -l</command> 來列出所有的檔案。</entry>
</row>		</row>
▲ Show 20 Lines • Show All 41 Lines • ▼ Show 20 Lines	The time is 09:18</screen></entry>
<entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry>		<entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>
</sect1>		</sect1>

<sect1 xml:id="preface-notes">		<sect1 xml:id="preface-notes">
<title>注意、技巧、重要訊息、警告、與範例的運用。</title>		<title>注意、提示、重要、警告與範例</title>

<para>出現在本文中的注意、警告、與範例。</para>		<para>出現在本文中的注意、警告、與範例。</para>

<note>		<note>
<para>注意：表示需要注意的事項，其中包括您需要注意的事情，因為這些事情可能會影響到操作結果。</para>		<para>注意：表示需要注意的事項，其中包括您需要注意的事情，因為這些事情可能會影響到操作結果。</para>
</note>		</note>

<tip>		<tip>
<para>提示：提供可能對您有用的資訊，例如簡化操作方式的技巧說明。</para>		<para>提示：提供可能對您有用的資訊，例如簡化操作方式的技巧說明。</para>
</tip>		</tip>

<important>		<important>
<para>重要：表示要特別注意的事情。一般來說，它們會包括操作指令時需要加的額外參數。</para>		<para>重要：表示要特別注意的事情。一般來說，它們會包括操作指令時需要加的額外參數。</para>
</important>		</important>

<warning>		<warning>
<para>警告：表示警告事項，比如如果您不則可能導致的損失。這些損失可能是對您或硬體造成實際傷害，也可能是無法估計的損害，例如一時疏忽而刪除重要檔案...。</para>		<para>警告：表示警告事項，比如如果您不則可能導致的損失。這些損失可能是對您或硬體造成實際傷害，也可能是無法估計的損害，例如一時疏忽而刪除重要檔案...。</para>
</warning>		</warning>

<example>		<example>
<title>一個範例</title>		<title>範例的範本</title>

<para>這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。</para>		<para>這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。</para>
</example>		</example>
</sect1>		</sect1>

<sect1 xml:id="preface-acknowledgements">		<sect1 xml:id="preface-acknowledgements">
<title>感謝</title>		<title>感謝</title>

Show All 31 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="overview">		<chapter version="5.0" xml:id="overview">
<title>概論</title>		<title>概論</title>

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

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

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

<para>本入門書指出如何：</para>		<para>本入門書指出如何：</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para>瞭解有哪些文件是由 <acronym>FDP</acronym> 所維護的。</para>		<para>瞭解有哪些文件是由 <acronym>FDP</acronym> 所維護的。</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>安裝所需的文件工具和檔案</para>		<para>安裝所需的說明文件工具和檔案。</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>修改文件</para>		<para>修改說明文件。</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>提交修改以供審核並納入 FreeBSD 文件</para>		<para>提交修改以供審核並納入 FreeBSD 說明文件。</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

<sect1 xml:id="overview-quick-start">		<sect1 xml:id="overview-quick-start">
<title>快速上手</title>		<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>		<procedure>
<step>		<step>
<para>安裝 <package>textproc/docproj</package> 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。</para>		<para>安裝 <package>textproc/docproj</package> 套件或 Port。這個 meta-port 會安裝所有編輯和建置 FreeBSD 說明文件需要的軟體。</para>
</step>		</step>

<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>		<screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
</step>		</step>

<step>		<step>
<para>設定文字編輯器：</para>		<para>設定文字編輯器：</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para>Word wrap 設為70個字元。</para>		<para>自動換行 (Word wrap) 設為 70 個字元。</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Tab stops 設成。</para>		<para>Tab 定位點 (Tab stops) 設成 2。</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>將句首每八個空白以一個 tab 替換。</para>		<para>將行首每 8 個空白取代成 1 個 Tab。</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

<para>特定編輯器的設定方式列於 <xref linkend="editor-config"/>。</para>		<para>特定編輯器的設定方式列於 <xref linkend="editor-config"/>。</para>
</step>		</step>

<step>		<step>
<para>更新本地端工作副本</para>		<para>更新本地端工作副本</para>

<screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>		<screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
</step>		</step>

<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>

<step>		<step>
<para>編輯完後，執行以下指令來檢查是否有問題：</para>		<para>編輯完後，執行以下指令來檢查是否有問題：</para>

<screen><prompt>%</prompt> <userinput>igor -R filename.xml \| less -RS</userinput></screen>		<screen><prompt>%</prompt> <userinput>igor -R filename.xml \| less -RS</userinput></screen>

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

<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>

<step>		<step>
<para>修改並測試完後，產生<quote>diff 檔</quote>：</para>		<para>修改並測試完後，產生 <quote>diff 檔</quote>：</para>

<screen><prompt>%</prompt> <userinput>cd ~/doc</userinput>		<screen><prompt>%</prompt> <userinput>cd ~/doc</userinput>
<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>		<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>

<para>設一個可辨識的檔名。如上例中，是使用手冊的<filename>bsdinstall</filename> 部份的修改。</para>		<para>設一個可辨識的檔名。如上例中，是使用手冊的 <filename>bsdinstall</filename> 部份的修改。</para>
</step>		</step>

<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>		</step>
</procedure>		</procedure>
</sect1>		</sect1>

<sect1 xml:id="overview-doc">		<sect1 xml:id="overview-doc">
<title>FreeBSD 文件組</title>		<title>FreeBSD 說明文件集</title>

<para><acronym>FDP</acronym> 負責四類 FreeBSD 文件</para>		<para><acronym>FDP</acronym> 負責四類 FreeBSD 說明文件。</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><emphasis>使用手冊</emphasis>：使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para>		<para><emphasis>使用手冊 (Handbook)</emphasis>：使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><emphasis>FAQ</emphasis> 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para>		<para><emphasis>常見問答集 (FAQ)</emphasis>：主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para>
</listitem>		</listitem>

<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>

<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>		</listitem>
</itemizedlist>		</itemizedlist>

<para>翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯</para>		<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>線上手冊的原始碼則是在 <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>		</sect1>
</chapter>		</chapter>


<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.		<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

Redistribution and use in source (SGML DocBook) and 'compiled' forms		Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without		(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
Show All 22 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="tools">		<chapter version="5.0" xml:id="tools">
<title>工具</title>		<title>工具</title>

<para>有些工具軟體用來管理 FreeBSD 文件，並將他轉換成不同的輸出格式。有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。</para>		<para>有些工具軟體用來管理 FreeBSD 說明文件，並將他轉換成不同的輸出格式。有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。</para>

<sect1 xml:id="tools-required">		<sect1 xml:id="tools-required">
<title>必備工具</title>		<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>		<sect2>
<title><acronym>DTD</acronym>s 與 <acronym>Entities</acronym></title>		<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>		<variablelist>
<varlistentry>		<varlistentry>
<term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)</term>		<term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)</term>

<listitem>		<listitem>
<para><acronym>XHTML</acronym> 是全球資訊網的一種標記語言，也是整個 FreeBSD 網站所使用的格式。</para>		<para><acronym>XHTML</acronym> 是全球資訊網的一種標記語言，也是整個 FreeBSD 網站所使用的格式。</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry>		<varlistentry>
<term xml:lang="en">DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml</package>)</term>		<term xml:lang="en">DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml</package>)</term>

<listitem>		<listitem>
<para>DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。</para>		<para>DocBook 設計來製作技術說明文件的標記語言版本。FreeBSD 說明文件是以 DocBook 來撰寫。</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry>		<varlistentry>
<term>ISO 8879 entities (<package>textproc/iso8879</package>)</term>		<term>ISO 8879 entities (<package>textproc/iso8879</package>)</term>

<listitem>		<listitem>
<para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用，包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para>		<para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用，包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>
</variablelist>		</variablelist>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="tools-optional">		<sect1 xml:id="tools-optional">
<title>輔助工具</title>		<title>選用工具</title>

<para>不一定得裝下列的應用程式才行，但是，出的格式也更具彈性。</para>		<para>以下應用程式並非必要，但有了可讓在說明文件的作業上更簡單或提升能力。</para>

<sect2>		<sect2>
<title>軟體</title>		<title>軟體</title>

<variablelist>		<variablelist>

<varlistentry>		<varlistentry>
<term><application>Vim</application> (<package>editors/vim</package>)</term>		<term><application>Vim</application> (<package>editors/vim</package>)</term>
▲ Show 20 Lines • Show All 42 Lines • ▼ Show 20 Lines	<!-- Copyright (c) 2013 Warren Block
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,		OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.		EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="working-copy">		<chapter version="5.0" xml:id="working-copy">
<title>工作副本</title>		<title>工作副本</title>

<para xml:lang="en">The <emphasis>working copy</emphasis> is a copy of the FreeBSD		<para><emphasis>工作副本 (Working copy)</emphasis> 指的是已下載到本地電腦的 FreeBSD 說明文件樹檔案庫，所有對工作副本的更改會經過測試後再以修補檔 (Patch) 的格式提交到主要檔案庫。</para>
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		<para>完整的說明文件樹副本會佔據 700 MB 的磁碟空間，要有空間能夠儲存暫存檔及各種輸出格式的測試版本需要 1 GB 的空間。</para>
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>		<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>
is used to manage the FreeBSD documentation files. It is installed
by <package>textproc/docproj</package> as one of
the required applications.</para>

<sect1 xml:id="working-copy-doc-and-src">		<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		<para>FreeBSD 說明文件不只有書籍與文章，還有所有指令與設定檔的操作手冊 (Manual page) 也是文件的一部份，其中也有一部份是 <acronym>FDP</acronym> 的地盤。相關的檔案庫有兩個：<literal>doc</literal> 中有書籍與文章，而 <literal>base</literal> 中有作業系統以及操作手冊。要編輯操作手冊則必須另外取出 (Checkout) <literal>base</literal> 檔案庫。</para>
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		<para>檔案庫中可能會含有數個版本的說明文件與原始碼。新的修改幾乎都只對最新版本 <literal>head</literal> 做更新。</para>
and source code. New modifications are almost always made only
to the latest version, called <literal>head</literal>.</para>
</sect1>		</sect1>

<sect1 xml:id="working-copy-choosing-directory">		<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		<para>FreeBSD 說明文件一般會儲存在 <filename>/usr/doc/</filename>，而系統原始碼及操作手冊則會存在 <filename>/usr/src/</filename>。這些目錄樹可改放在其他地方，使用者可能會為了避免與現有在主要目錄的資料搞混，把工作副本放在其他的地方。以下的例子會放在 <filename>~/doc</filename> 以及 <filename>~/src</filename> 兩個在使用者家目錄下的目錄。</para>
<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>
</sect1>		</sect1>

<sect1 xml:id="working-copy-checking-out">		<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		<para>從檔案庫下載工作副本的動作稱作 <emphasis>取出 (Checkout)</emphasis>，使用 <command>svn checkout</command> 來完成。本範例會取出主要說明文件樹最新版本的副本：</para>
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>

<screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>		<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		<para>取出原始碼編輯操作手冊的動作非常相似：</para>
very similar:</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>		<screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
</sect1>		</sect1>

<sect1 xml:id="working-copy-updating">		<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.		<para>在 FreeBSD 檔案庫中的文件與檔案每天都會更改，人們會修改檔案與提交變更的頻率非常快，即使取出 (Checkout) 只過小一段時間，本地的工作副本可能就與主要 FreeBSD 檔案庫有差異了。要更新本地版本以同步對主要檔案庫的變更可在有本地工作副本的目錄下使用 <command>svn update</command>：</para>
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>

<screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>		<screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>

<para xml:lang="en">Get in the protective habit of using		<para>養成良好的習慣在編輯文件檔前先執行 <command>svn update</command>，可能會有其他人才剛編輯完該檔案，本地工作副本在尚未更新前不會有最後的變更內容，編輯最新版本的檔案會比將舊版本地檔案與新版檔案庫檔案合併來的簡單多了。</para>
<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>
</sect1>		</sect1>

<sect1 xml:id="working-copy-revert">		<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		<para>有時才做完的變更可能就變的不需要了，或者作者剛想要重新搛寫。檔案可使以使用 <command>svn revert</command> 來<quote>重設</quote>成尚未被修改刪的狀態，舉例來說，要清除所有對 <filename>chapter.xml</filename> 的修改然後還原到未修改的版本可：</para>
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>

<screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen>		<screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen>
</sect1>		</sect1>

<sect1 xml:id="working-copy-making-diff">		<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		<para>在編輯一個檔案或數個檔案完成之後，需將本地工作副本與 FreeBSD 檔案庫的差異儲存到一個檔案然後提交。這些 <emphasis>差異 (Diff)</emphasis> 檔可透過將 <command>svn diff</command> 的輸出轉向到檔案來建立： </para>
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>

<screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>		<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>		<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		<para>給檔案取一個有意義的名字來辨識這次修改的內容，上述範例為例則是要修正整個說明文件樹的拼寫。</para>
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		<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>
<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 xml:lang="en">Be careful: <command>svn diff</command> includes all changes		<para>請小心：<command>svn diff</command> 會產生所有在目前目錄及其子目錄的變更差異，若在該工作副本中有已經編輯過的檔案還沒有要提交，請列出需要比較差異的檔案清單：</para>
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>

<screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>		<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>		<prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen>
</sect1>		</sect1>

<sect1 xml:id="working-copy-subversion-references">		<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		<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>
<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>
</sect1>		</sect1>
</chapter>		</chapter>


<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.		<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

Redistribution and use in source (SGML DocBook) and 'compiled' forms		Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without		(SGML HTML, PDF, PostScript, RTF and so forth) with or without
Show All 20 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,		HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN		STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="structure">		<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		<para>在 <filename>doc/</filename> 樹中的檔案與目錄需要遵守特定結構是因為：</para>
<filename>doc/</filename> tree follow a
structure meant to:</para>

<orderedlist>		<orderedlist>
<listitem>		<listitem>
<para xml:lang="en">Make it easy to automate converting the document to other		<para>讓自動轉換說明文件到各種格式更簡單。</para>
formats.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en">Promote consistency between the different documentation		<para>促進不同說明文件組織之間的一致性，以便更輕鬆的在不同說明文件之間切換。</para>
organizations, to make it easier to switch between working on
different documents.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en">Make it easy to decide where in the tree new documentation		<para>可以很容易的決定新的說明文件應該放在文件樹中的哪個位置。</para>
should be placed.</para>
</listitem>		</listitem>
</orderedlist>		</orderedlist>

<para xml:lang="en">In addition, the documentation tree must accommodate		<para>除此之外，說明文件樹必須能容納各種不同語言與編碼的說明文件。很重要的一點是，說明文件樹結構不應強制任何特定默認或文化的偏好。</para>
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>

<sect1 xml:id="structure-top">		<sect1 xml:id="structure-top">
<title xml:lang="en">The Top Level,		<title>最上層，<filename>doc/</filename></title>
<filename>doc/</filename></title>

<para xml:lang="en">There are two types of directory under		<para>在 <filename>doc/</filename> 底下有兩種類型的目錄，兩種都有非常明確的目錄名稱與意義。</para>
<filename>doc/</filename>, each with very
specific directory names and meanings.</para>

<informaltable pgwide="1" frame="none">		<informaltable pgwide="1" frame="none">
<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry xml:lang="en">Directory</entry>		<entry>目錄</entry>
<entry xml:lang="en">Usage</entry>		<entry>用途</entry>
</row>		</row>
</thead>		</thead>

<tbody>		<tbody>
<row>		<row>
<entry valign="top" xml:lang="en">		<entry valign="top" xml:lang="en">
<filename>share</filename></entry>		<filename>share</filename></entry>

<entry xml:lang="en">Contains files that are not specific to the various		<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>
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>
</row>		</row>

<row>		<row>
<entry valign="top" xml:lang="en">		<entry valign="top" xml:lang="en">
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>		<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>

<entry xml:lang="en">One directory exists for each available translation		<entry>每一個目錄代表可用的說明文件翻譯與編碼，例如 <filename>en_US.ISO8859-1/</filename> 及 <filename>zh_TW.UTF-8/</filename>。名稱雖然長，但完整表達語言與編碼可以避免未來當一個翻譯團隊要以不同編碼提供同一個語言的說明文件造成的問題，這也同時避免往後要切換成萬國碼 (Unicode) 可能造成的問題。</entry>
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>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>
</sect1>		</sect1>

<sect1 xml:id="structure-locale">		<sect1 xml:id="structure-locale">
<title xml:lang="en">The		<title><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> 目錄</title>
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename>
Directories</title>

<para xml:lang="en">These directories contain the documents themselves. The		<para>這些目錄中含有說明文件。在此階層說明文件分成三個分類，使用不同的目錄名稱來代表。</para>
documentation is split into up to three more categories at
this level, indicated by the different directory names.</para>

<informaltable pgwide="1" frame="none">		<informaltable pgwide="1" frame="none">
<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry xml:lang="en">Directory</entry>		<entry>目錄</entry>
<entry xml:lang="en">Usage</entry>		<entry>用途</entry>
</row>		</row>
</thead>		</thead>

<tbody>		<tbody>
<row>		<row>
<entry valign="top" xml:lang="en">		<entry valign="top" xml:lang="en">
<filename>articles</filename></entry>		<filename>articles</filename></entry>

<entry xml:lang="en">Documentation marked up as a DocBook		<entry>以 DocBook <tag>article</tag> (或同等級) 標記的說明文件。非常短，且會分成幾個小節，通常取得時只會有一個 <acronym>XHTML</acronym> 檔案。</entry>
<tag>article</tag> (or equivalent). Reasonably
short, and broken up into sections. Normally only
available as one <acronym>XHTML</acronym> file.</entry>
</row>		</row>

<row>		<row>
<entry valign="top" xml:lang="en"><filename>books</filename></entry>		<entry valign="top" xml:lang="en"><filename>books</filename></entry>

<entry xml:lang="en">Documentation marked up as a DocBook		<entry>以 DocBook <tag>book</tag> (或同等級) 標記的說明文件。有跟書籍一樣的長度，會分成數個章。通常取得時會包含一個大型的 <acronym>XHTML</acronym> 檔 (供有較快連線速度的人使用，或者那些想直接在瀏覽器列印的人) 與數個連結的較小的檔案。</entry>
<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>
</row>		</row>

<row>		<row>
<entry valign="top" xml:lang="en">		<entry valign="top" xml:lang="en">
<filename>man</filename></entry>		<filename>man</filename></entry>

<entry xml:lang="en">For translations of the system manual pages. This		<entry>供系統操作手冊 (Manual page) 翻譯使用。這個目錄會包含一個或多個 <filename role="directory">man<replaceable>n</replaceable></filename> 目錄來對應已經翻譯的章節。</entry>
directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename>
directories, corresponding to the sections that have
been translated.</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>

<para xml:lang="en">Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>		<para>並非所有 <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> 的目錄都會有這些子目錄，這要看該翻譯團隊已經完成了多少翻譯來決定。</para>
directory will have all of these subdirectories. It depends
on how much translation has been accomplished by that
translation team.</para>
</sect1>		</sect1>

<sect1 xml:id="structure-document">		<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		<para>本節內含有關由 FDP 所管理的特定文件的特定注意事項。</para>
documents managed by the FDP.</para>

<sect2>		<sect2>
<title xml:lang="en">The Handbook</title>		<title>使用手冊 (Handbook)</title>

<subtitle xml:lang="en"><filename>books/handbook/</filename></subtitle>		<subtitle xml:lang="en"><filename>books/handbook/</filename></subtitle>

<para xml:lang="en">The Handbook is written in DocBook <acronym>XML</acronym>		<para>操作手冊是以使用 FreeBSD DocBook 擴充 <acronym>DTD</acronym> 的 DocBook <acronym>XML</acronym> 所撰寫。</para>
using the FreeBSD DocBook extended <acronym>DTD</acronym>.</para>

<para xml:lang="en">The Handbook is organized as a DocBook		<para>使用手冊使用 DocBook <tag>book</tag> 來組織，整個手冊區分成數個部份 (<tag>part</tag>)，每個部份中內含數個章 (<tag>chapter</tag>)，而章 (<tag>chapter</tag>) 又更進一步的細分成數個節 (<tag>sect1</tag>) 與小節 (<tag>sect2</tag>, <tag>sect3</tag>) 以此類推。</para>
<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>

<sect3>		<sect3>
<title xml:lang="en">Physical Organization</title>		<title>實體組織結構</title>

<para xml:lang="en">There are a number of files and directories within the		<para>在 <filename>handbook</filename> 目錄中有數個檔案及目錄。</para>
<filename>handbook</filename> directory.</para>

<note>		<note>
<para xml:lang="en">The Handbook's organization may change over time, and		<para>使用手冊的組織結構可能會隨時改變，本文件所詳述的組織結構可能會與現況不盡相同。有關使用手冊組織結構的問題可張貼到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>。</para>
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>
</note>		</note>

<sect4>		<sect4>
<title xml:lang="en"><filename>Makefile</filename></title>		<title xml:lang="en"><filename>Makefile</filename></title>

<para xml:lang="en">The <filename>Makefile</filename> defines some		<para><filename>Makefile</filename> 定義了一些會影響 <acronym>XML</acronym> 原始碼要如何轉換至其他格式的變數，並列出產生使用手冊所需的各原始檔，接著會引用可處理在各種文件格式轉換的標準 <filename>doc.project.mk</filename> 程式碼。</para>
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>
</sect4>		</sect4>

<sect4>		<sect4>
<title xml:lang="en"><filename>book.xml</filename></title>		<title xml:lang="en"><filename>book.xml</filename></title>

<para xml:lang="en">This is the top level document in the Handbook. It		<para>此為使用手冊的最上層文件，其中包含了使用手冊的 <link linkend="xml-primer-doctype-declaration">DOCTYPE 宣告</link>以及用來描述使用手冊結構的元素。</para>
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		<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>
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>
</sect4>		</sect4>

<sect4>		<sect4>
<title xml:lang="en"><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>		<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		<para>每個在使用手冊的章會儲存成名稱為 <filename>chapter.xml</filename> 的檔案，分別放在不同的目錄中。每個目錄均是以在 <tag>chapter</tag> 元素中 <literal>id</literal> 屬性中的值來命名。</para>
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 xml:lang="en">For example, if one of the chapter files		<para>例如，若有一章的檔案內容為：</para>
contains:</para>

<programlisting xml:lang="en"><tag class="starttag">chapter id="kernelconfig"</tag>		<programlisting xml:lang="en"><tag class="starttag">chapter id="kernelconfig"</tag>
...		...
<tag class="endtag">chapter</tag></programlisting>		<tag class="endtag">chapter</tag></programlisting>

<para xml:lang="en">Then it will be called		<para>那麼放置這個 <filename>chapter.xml</filename> 的目錄則會命名為 <filename>kernelconfig</filename>。一般來說一章的所有內容會存放在這一個檔案。</para>
<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		<para>當有 <acronym>XHTML</acronym> 版本的使用手冊之後，也會用這個檔產出 <filename>kernelconfig.html</filename>，這個名稱是根據 <literal>id</literal> 的值而定，與目錄名稱無關。</para>
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		<para>在早期版本的使用手冊，檔案皆儲存在與 <filename>book.xml</filename> 相同的目錄中，而名稱會以 <tag>chapter</tag> 元素中的 <literal>id</literal> 屬性的值來命名。現在可在每個章節之中引用圖片，每個使用手冊章節的圖片會儲存在 <filename>share/images/books/handbook</filename>，而在地化版本的圖片應放在與每個章節 <acronym>XML</acronym> 原始碼相同的目錄。命名空間會衝突是必然的，但以目錄多、檔案少與目錄少、檔案多的結構相比，目錄多、檔案少會較容易處理命名空間衝突的問題。</para>
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		<para>簡單來說會有很多個內含 <filename>chapter.xml</filename> 檔案的目錄，例如 <filename>basics/chapter.xml</filename>, <filename>introduction/chapter.xml</filename> 以及 <filename>printing/chapter.xml</filename>。</para>
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>

<important>		<important>
<para xml:lang="en">Do not name chapters or directories after		<para>請勿以在使用手冊中的章節順序來命名章節或目錄，因為順序是會隨使用手冊重新組織後的內容改變的。重新組織結構應不需要去重新命名檔案，除非整個章節的階層被提升或下降。</para>
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>
</important>		</important>

<para xml:lang="en">The <filename>chapter.xml</filename> files are not		<para><filename>chapter.xml</filename> 檔案並不是可以被單獨建置的完整 <acronym>XML</acronym> 文件，只能做為使用手冊的一部份來建置。</para>
complete <acronym>XML</acronym> documents that can be
built individually. They can only be built
as parts of the whole Handbook.</para>
</sect4>		</sect4>
</sect3>		</sect3>
</sect2>		</sect2>
</sect1>		</sect1>
</chapter>		</chapter>


<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.		<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.
Show All 23 Lines	<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,		HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN		STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="doc-build">		<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		<para>本章內容涵蓋了說明文件建置流程以及如何使用 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來控制如何建置。</para>
process and how <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to control it.</para>

<sect1 xml:id="doc-build-rendering">		<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		<para>從單一個 DocBook 原始檔可以產生各種不同類型的輸出，想要輸出的類型可用 <varname>FORMATS</varname> 變數來設定。已知的格式清單列在 <varname>KNOWN_FORMATS</varname> 中：</para>
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>

<screen xml:id="doc-build-rendering-known-formats" xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>		<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>		<prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput></screen>

<table xml:id="doc-build-rendering-common-formats" frame="none">		<table xml:id="doc-build-rendering-common-formats" frame="none">
<title xml:lang="en">Common Output Formats</title>		<title>常見輸出格式</title>

<tgroup cols="3">		<tgroup cols="3">
<thead>		<thead>
<row>		<row>
<entry xml:lang="en"><varname>FORMATS</varname> Value</entry>		<entry><varname>FORMATS</varname> 值</entry>
<entry xml:lang="en">File Type</entry>		<entry>檔案類型</entry>
<entry xml:lang="en">Description</entry>		<entry>說明</entry>
</row>		</row>
</thead>		</thead>

<tbody>		<tbody>
<row>		<row>
<entry xml:lang="en"><literal>html</literal></entry>		<entry xml:lang="en"><literal>html</literal></entry>
<entry xml:lang="en"><acronym>HTML</acronym>, one file</entry>		<entry><acronym>HTML</acronym>，單檔</entry>
<entry xml:lang="en">A single <filename>book.html</filename> or		<entry>單一 <filename>book.html</filename> 或 <filename>article.html</filename>。</entry>
<filename>article.html</filename>.</entry>
</row>		</row>

<row>		<row>
<entry xml:lang="en"><literal>html-split</literal></entry>		<entry xml:lang="en"><literal>html-split</literal></entry>
<entry xml:lang="en"><acronym>HTML</acronym>, multiple files</entry>		<entry><acronym>HTML</acronym>，多檔</entry>
<entry xml:lang="en">Multiple <acronym>HTML</acronym> files, one for		<entry>多個 <acronym>HTML</acronym> 檔案，每個章或節一個檔案，供一般網站使用。</entry>
each chapter or section, for use on a typical web
site.</entry>
</row>		</row>

<row>		<row>
<entry xml:lang="en"><literal>pdf</literal></entry>		<entry xml:lang="en"><literal>pdf</literal></entry>
<entry xml:lang="en"><acronym>PDF</acronym></entry>		<entry xml:lang="en"><acronym>PDF</acronym></entry>
<entry xml:lang="en">Portable Document Format</entry>		<entry>可攜的文件格式</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</table>		</table>

<para xml:lang="en">The default output format can vary by document, but is		<para>預設輸出的格式會依文件而有所不同，但同常是 <literal>html-split</literal>。其他格式可設定 <varname>FORMATS</varname> 為特定值來選擇。在 <varname>FORMATS</varname> 設定所需格式的清單可一次輸出多個格式。</para>
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>

<example xml:id="doc-build-formats-example-html">		<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>		<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
<prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen>		<prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen>
</example>		</example>

<example xml:id="doc-build-formats-example-html-split-pdf">		<example xml:id="doc-build-formats-example-html-split-pdf">
<title xml:lang="en">Build HTML-Split and <acronym>PDF</acronym> Output		<title>建置分頁 HTML 及 <acronym>PDF</acronym> 輸出檔</title>
Files</title>

<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>		<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>		<prompt>%</prompt> <userinput>make FORMATS="html-split pdf"</userinput></screen>
</example>		</example>
</sect1>		</sect1>

<sect1 xml:id="doc-build-toolset">		<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		<para>建置與安裝 <acronym>FDP</acronym> 說明文件會使用到以下工具。</para>
<acronym>FDP</acronym> documentation.</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en">The primary build tool is <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, specifically		<para>主要的建置工具為 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>，特別是 <application>Berkeley Make</application>。</para>
<application>Berkeley Make</application>.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en">Package building is handled by FreeBSD's		<para>套件建置會使用 FreeBSD 的 <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> 來處理。</para>
<citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to create compressed versions of		<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>
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>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to install the		<para><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> 用來安裝說明文件。</para>
documentation.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect1>		</sect1>

<sect1 xml:id="doc-build-makefiles">		<sect1 xml:id="doc-build-makefiles">

<title xml:lang="en">Understanding <filename>Makefile</filename>s in the		<title>了解在說明文件樹中的 <filename>Makefile</filename></title>
Documentation Tree</title>

<para xml:lang="en">There are three main types of <filename>Makefile</filename>s		<para>在 FreeBSD 說明文件計劃樹底下的 <filename>Makefile</filename> 主要有三個類型。</para>
in the FreeBSD Documentation Project tree.</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en"><link linkend="sub-make">Subdirectory		<para><link linkend="sub-make">子目錄的 <filename>Makefile</filename></link> 傳遞指令給在其所在目錄底下的目錄。</para>
<filename>Makefile</filename>s</link> simply pass
commands to those directories below them.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><link linkend="doc-make">Documentation		<para><link linkend="doc-make">說明文件的 <filename>Makefile</filename>s</link> 用來描述要如何在其所在目錄產生文件。</para>
<filename>Makefile</filename>s</link> describe the
documents that are produced from this
directory.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><link linkend="make-includes"><application>Make</application>		<para><link linkend="make-includes"><application>Make</application> 引用檔</link> 會連結一些產生文件所需的程式，通常為 <filename>doc.<replaceable>xxx</replaceable>.mk</filename>。</para>
includes</link> are the glue that perform the document
production, and are usually of the form
<filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

<sect2 xml:id="sub-make">		<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		<para xml:lang="en">These <filename>Makefile</filename>s usually take the form
of:</para>		of:</para>

<programlisting xml:lang="en">SUBDIR =articles		<programlisting xml:lang="en">SUBDIR =articles
SUBDIR+=books		SUBDIR+=books

COMPAT_SYMLINK = en		COMPAT_SYMLINK = en
▲ Show 20 Lines • Show All 41 Lines • ▼ Show 20 Lines	directory.</para>

<para xml:lang="en">The final line includes the FreeBSD Documentation Project's		<para xml:lang="en">The final line includes the FreeBSD Documentation Project's
project-wide <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> system file		project-wide <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> system file
<filename>doc.project.mk</filename> which is the glue which		<filename>doc.project.mk</filename> which is the glue which
converts these variables into build instructions.</para>		converts these variables into build instructions.</para>
</sect2>		</sect2>

<sect2 xml:id="doc-make">		<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>		<para>這些 <filename>Makefile</filename> 用來設定 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 變數來描述要如何建置在該目錄中的說明文件。</para>
variables that describe how to build the documentation
contained in that directory.</para>

<para xml:lang="en">Here is an example:</para>		<para>這裡有一個例子：</para>

<programlisting xml:lang="en">MAINTAINER=nik@FreeBSD.org		<programlisting xml:lang="en">MAINTAINER=nik@FreeBSD.org

DOC?= book		DOC?= book

FORMATS?= html-split html		FORMATS?= html-split html

INSTALL_COMPRESSED?= gz		INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=		INSTALL_ONLY_COMPRESSED?=

# SGML content		# SGML content
SRCS= book.xml		SRCS= book.xml

DOC_PREFIX?= ${.CURDIR}/../../..		DOC_PREFIX?= ${.CURDIR}/../../..

.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>		.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>

<para xml:lang="en">The <varname>MAINTAINER</varname> variable allows		<para><varname>MAINTAINER</varname> 變數讓提交者可以聲明文件在 FreeBSD 說明文件計劃中的所有權，並負責維護該文件。</para>
committers to claim ownership of a document in the FreeBSD
Documentation Project, and take responsibility for maintaining
it.</para>

<para xml:lang="en"><varname>DOC</varname> is the name (sans the		<para><varname>DOC</varname> 是由此目錄會建立的主要文件的名稱 (不需要 <filename>.xml</filename> 副檔名)。<varname>SRCS</varname> 會列出產生文件所需的各別檔案，此處也應引用要在重新建置 (Rebuild) 使用的重要的檔案。</para>
<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		<para><varname>FORMATS</varname> 用來指定此份文件建置時預設應採用的格式。<varname>INSTALL_COMPRESSED</varname> 是為在文件建置時預設要使用的壓縮技術清單。<varname>INSTALL_ONLY_COMPRESS</varname> 預設為空值的，若在建置時只想要產生壓縮後的文件則改成非空值。</para>
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 xml:lang="en">The <varname>DOC_PREFIX</varname> and include statements		<para><varname>DOC_PREFIX</varname> 以及 include 敘述句應不需再說明了。</para>
should be familiar already.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="make-includes">		<sect1 xml:id="make-includes">
<title xml:lang="en">FreeBSD Documentation Project		<title>FreeBSD 說明文件計劃 <application>Make</application> 引用檔</title>
<application>Make</application> Includes</title>

<para xml:lang="en"><citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes are best explained by inspection of		<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>		the code. Here are the system include files:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en"><filename>doc.project.mk</filename> is the main project		<para xml:lang="en"><filename>doc.project.mk</filename> is the main project
include file, which includes all the following include		include file, which includes all the following include
Show All 35 Lines
.endif		.endif
.endif		.endif

.include "doc.subdir.mk"		.include "doc.subdir.mk"
.include "doc.install.mk"</programlisting>		.include "doc.install.mk"</programlisting>

<sect3>		<sect3>

<title xml:lang="en">Variables</title>		<title>變數</title>

<para xml:lang="en"><varname>DOCFORMAT</varname> and		<para xml:lang="en"><varname>DOCFORMAT</varname> and
<varname>MAINTAINER</varname> are assigned default values,		<varname>MAINTAINER</varname> are assigned default values,
if these are not set by the document make file.</para>		if these are not set by the document make file.</para>

<para xml:lang="en"><varname>PREFIX</varname> is the prefix under which the		<para xml:lang="en"><varname>PREFIX</varname> is the prefix under which the
<link linkend="tools">documentation building tools</link>		<link linkend="tools">documentation building tools</link>
are installed. For normal package and port installation,		are installed. For normal package and port installation,
this is <filename>/usr/local</filename>.</para>		this is <filename>/usr/local</filename>.</para>

<para xml:lang="en"><varname>PRI_LANG</varname> should be set to whatever		<para xml:lang="en"><varname>PRI_LANG</varname> should be set to whatever
language and encoding is natural amongst users these		language and encoding is natural amongst users these
documents are being built for. US English is the		documents are being built for. US English is the
default.</para>		default.</para>

<note>		<note>
<para xml:lang="en"><varname>PRI_LANG</varname> does not affect which		<para xml:lang="en"><varname>PRI_LANG</varname> does not affect which
documents can, or even will, be built. Its main use is		documents can, or even will, be built. Its main use is
creating links to commonly referenced documents into the		creating links to commonly referenced documents into the
FreeBSD documentation install root.</para>		FreeBSD documentation install root.</para>
</note>		</note>
</sect3>		</sect3>

<sect3>		<sect3>
<title xml:lang="en">Conditionals</title>		<title>條件</title>

<para xml:lang="en">The <literal>.if defined(DOC)</literal> line is an		<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		example of a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> conditional which, like in other
programs, defines behavior if some condition is true or if		programs, defines behavior if some condition is true or if
it is false. <literal>defined</literal> is a function which		it is false. <literal>defined</literal> is a function which
returns whether the variable given is defined or not.</para>		returns whether the variable given is defined or not.</para>

<para xml:lang="en"><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,		<para xml:lang="en"><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
tests whether the <varname>DOCFORMAT</varname> variable is		tests whether the <varname>DOCFORMAT</varname> variable is
<literal>"docbook"</literal>, and in this case, includes		<literal>"docbook"</literal>, and in this case, includes
<filename>doc.docbook.mk</filename>.</para>		<filename>doc.docbook.mk</filename>.</para>

<para xml:lang="en">The two <literal>.endif</literal>s close the two above		<para xml:lang="en">The two <literal>.endif</literal>s close the two above
conditionals, marking the end of their application.</para>		conditionals, marking the end of their application.</para>
</sect3>		</sect3>
</sect2>		</sect2>

<sect2>		<sect2>
<title xml:lang="en"><filename>doc.subdir.mk</filename></title>		<title xml:lang="en"><filename>doc.subdir.mk</filename></title>

<para xml:lang="en">This file is too long to explain in detail. These notes		<para xml:lang="en">This file is too long to explain in detail. These notes
describe the most important features.</para>		describe the most important features.</para>

<sect3>		<sect3>
<title xml:lang="en">Variables</title>		<title>變數</title>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en"><varname>SUBDIR</varname> is a list of		<para xml:lang="en"><varname>SUBDIR</varname> is a list of
subdirectories that the build process should go further		subdirectories that the build process should go further
down into.</para>		down into.</para>
</listitem>		</listitem>

Show All 10 Lines	<listitem>
the		the
<link linkend="sub-make">Subdirectory Makefile</link>		<link linkend="sub-make">Subdirectory Makefile</link>
section.</para>		section.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect3>		</sect3>

<sect3>		<sect3>
<title xml:lang="en">Targets and Macros</title>		<title>目標與巨集</title>

<para xml:lang="en">Dependencies are described by		<para xml:lang="en">Dependencies are described by
<literal><replaceable>target</replaceable>:		<literal><replaceable>target</replaceable>:
<replaceable>dependency1 dependency2		<replaceable>dependency1 dependency2
...</replaceable></literal> tuples, where to build		...</replaceable></literal> tuples, where to build
<literal>target</literal>, the given		<literal>target</literal>, the given
dependencies must be built first.</para>		dependencies must be built first.</para>

Show All 33 Lines	<para xml:lang="en">In the above, <buildtarget xml:lang="en">clean</buildtarget> will use
executed the instruction		executed the instruction
<command>rm -f ${CLEANFILES}</command>. In effect, this		<command>rm -f ${CLEANFILES}</command>. In effect, this
causes <buildtarget xml:lang="en">clean</buildtarget> to go further and		causes <buildtarget xml:lang="en">clean</buildtarget> to go further and
further down the directory tree, deleting built files as it		further down the directory tree, deleting built files as it
goes <emphasis>down</emphasis>, not on the way back		goes <emphasis>down</emphasis>, not on the way back
up.</para>		up.</para>

<sect4>		<sect4>
<title xml:lang="en">Provided Targets</title>		<title>已提供的目標</title>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en"><buildtarget xml:lang="en">install</buildtarget> and		<para xml:lang="en"><buildtarget xml:lang="en">install</buildtarget> and
<buildtarget xml:lang="en">package</buildtarget> both go down the		<buildtarget xml:lang="en">package</buildtarget> both go down the
directory tree calling the real versions of themselves		directory tree calling the real versions of themselves
in the subdirectories		in the subdirectories
(<buildtarget xml:lang="en">realinstall</buildtarget> and		(<buildtarget xml:lang="en">realinstall</buildtarget> and
<buildtarget xml:lang="en">realpackage</buildtarget>		<buildtarget xml:lang="en">realpackage</buildtarget>
respectively).</para>		respectively).</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> removes files		<para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> removes files
created by the build process (and goes down the		created by the build process (and goes down the
directory tree too).		directory tree too).
<buildtarget xml:lang="en">cleandir</buildtarget> does the same, and		<buildtarget xml:lang="en">cleandir</buildtarget> does the same, and
also removes the object directory, if any.</para>		also removes the object directory, if any.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect4>		</sect4>
</sect3>		</sect3>

<sect3>		<sect3>
<title xml:lang="en">More on Conditionals</title>		<title>更多條件</title>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en"><literal>exists</literal> is another condition		<para xml:lang="en"><literal>exists</literal> is another condition
function which returns true if the given file		function which returns true if the given file
exists.</para>		exists.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><literal>empty</literal> returns true if the given		<para xml:lang="en"><literal>empty</literal> returns true if the given
variable is empty.</para>		variable is empty.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><literal>target</literal> returns true if the given		<para xml:lang="en"><literal>target</literal> returns true if the given
target does not already exist.</para>		target does not already exist.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect3>		</sect3>

<sect3>		<sect3>
<title xml:lang="en">Looping Constructs in <command>make		<title>在 <command>make (.for)</command> 中的迴圈結構</title>
(.for)</command></title>

<para xml:lang="en"><literal>.for</literal> provides a way to repeat a set		<para xml:lang="en"><literal>.for</literal> provides a way to repeat a set
of instructions for each space-separated element in a		of instructions for each space-separated element in a
variable. It does this by assigning a variable to contain		variable. It does this by assigning a variable to contain
the current element in the list being examined.</para>		the current element in the list being examined.</para>

<programlisting xml:lang="en">_SUBDIRUSE: .USE		<programlisting xml:lang="en">_SUBDIRUSE: .USE
.for entry in ${SUBDIR}		.for entry in ${SUBDIR}
▲ Show 20 Lines • Show All 48 Lines • ▼ Show 20 Lines
<chapter version="5.0" xml:id="the-website">		<chapter version="5.0" xml:id="the-website">
<title>網站</title>		<title>網站</title>

<para>FreeBSD 網站是 FreeBSD 文件的一部份。網站的檔案儲存在文件樹目錄，此例中是 <filename>~/doc</filename>，的 <filename>en_US.ISO8859-1/htdocs</filename> 子目錄。</para>		<para>FreeBSD 網站是 FreeBSD 文件的一部份。網站的檔案儲存在文件樹目錄，此例中是 <filename>~/doc</filename>，的 <filename>en_US.ISO8859-1/htdocs</filename> 子目錄。</para>

<sect1 xml:id="the-website-env">		<sect1 xml:id="the-website-env">
<title>環境變數</title>		<title>環境變數</title>

<para>有些環境變數控制網站的建構或安裝，和裝到哪個目錄</para>		<para xml:lang="en">Several environment variables control which parts of the
		web site are built or installed, and to which
		directories.</para>

<tip>		<tip>
<para xml:lang="en">The web build system uses <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and considers		<para xml:lang="en">The web build system uses <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and considers
variables to be set when they have been defined, even if they		variables to be set when they have been defined, even if they
are empty. The examples here show the recommended ways of		are empty. The examples here show the recommended ways of
defining and using these variables. Setting or defining these		defining and using these variables. Setting or defining these
variables with other values or methods might lead to		variables with other values or methods might lead to
unexpected surprises.</para>		unexpected surprises.</para>
▲ Show 20 Lines • Show All 64 Lines • ▼ Show 20 Lines	</listitem>
<para xml:lang="en"><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,		<para xml:lang="en"><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
and <varname>ENGLISH_ONLY</varname> are <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables		and <varname>ENGLISH_ONLY</varname> are <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables
and can be set in <filename>/etc/make.conf</filename>,		and can be set in <filename>/etc/make.conf</filename>,
<filename>Makefile.inc</filename>, as environment variables on		<filename>Makefile.inc</filename>, as environment variables on
the command line, or in dot files.</para>		the command line, or in dot files.</para>
</sect1>		</sect1>

<sect1 xml:id="the-website-build">		<sect1 xml:id="the-website-build">
<title xml:lang="en">Building and Installing the Web Pages</title>		<title>建置並安裝網頁</title>

<para xml:lang="en">Having obtained the documentation and web site source files,		<para xml:lang="en">Having obtained the documentation and web site source files,
the web site can be built.</para>		the web site can be built.</para>

<para xml:lang="en">An actual installation of the web site is run as the <systemitem class="username">root</systemitem>		<para xml:lang="en">An actual installation of the web site is run as the <systemitem class="username">root</systemitem>
user because the permissions on the web server directory will		user because the permissions on the web server directory will
not allow files to be installed by an unprivileged user.		not allow files to be installed by an unprivileged user.
For testing, it can be useful to install the files as a normal		For testing, it can be useful to install the files as a normal
user to a temporary directory.</para>		user to a temporary directory.</para>

<para xml:lang="en">In these examples, the web site files are built by user		<para xml:lang="en">In these examples, the web site files are built by user
<systemitem class="username">jru</systemitem> in their home		<systemitem class="username">jru</systemitem> in their home
directory, <filename>~/doc</filename>, with a full path of		directory, <filename>~/doc</filename>, with a full path of
<filename>/usr/home/jru/doc</filename>.</para>		<filename>/usr/home/jru/doc</filename>.</para>

<tip>		<tip>
<para xml:lang="en">The web site build uses the <filename>INDEX</filename>		<para xml:lang="en">The web site build uses the <filename>INDEX</filename>
from the Ports Collection and might fail if that file or		from the Ports Collection and might fail if that file or
<filename>/usr/ports</filename> is not		<filename>/usr/ports</filename> is not
present. The simplest approach is to install the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/ports.html#ports-tree">Ports		present. The simplest approach is to install the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/ports.html#ports-tree">Ports
Collection</link>.</para>		Collection</link>.</para>
</tip>		</tip>

<example xml:id="the-website-examples-build">		<example xml:id="the-website-examples-build">
<title xml:lang="en">Build the Full Web Site and All Documents</title>		<title>建置完整網站與所有說明文件</title>

<para xml:lang="en">Build the web site and all documents. The resulting files		<para xml:lang="en">Build the web site and all documents. The resulting files
are left in the document tree:</para>		are left in the document tree:</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>		<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
<prompt>%</prompt> <userinput>make all</userinput></screen>		<prompt>%</prompt> <userinput>make all</userinput></screen>
</example>		</example>

<example xml:id="the-website-examples-buildinstall-englishonly">		<example xml:id="the-website-examples-buildinstall-englishonly">
<title xml:lang="en">Build Only the Web Site in English</title>		<title>只建置英文版網站</title>

<para xml:lang="en">Build the web site only, in English, as user		<para xml:lang="en">Build the web site only, in English, as user
<systemitem class="username">jru</systemitem>, and install		<systemitem class="username">jru</systemitem>, and install
the resulting files into <filename>/tmp/www</filename> for		the resulting files into <filename>/tmp/www</filename> for
testing:</para>		testing:</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>		<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
<prompt>%</prompt> <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen>		<prompt>%</prompt> <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen>
▲ Show 20 Lines • Show All 77 Lines • ▼ Show 20 Lines	Include etc/apache24/Includes/*.conf</programlisting>
version. Fully testing the local site will require		version. Fully testing the local site will require
temporarily setting <acronym>DNS</acronym> so		temporarily setting <acronym>DNS</acronym> so
<literal>www.FreeBSD.org</literal> resolves to		<literal>www.FreeBSD.org</literal> resolves to
<literal>localhost</literal> or the local		<literal>localhost</literal> or the local
<acronym>IP</acronym> address.</para>		<acronym>IP</acronym> address.</para>
</example>		</example>

<example xml:id="the-website-examples-buildinstall">		<example xml:id="the-website-examples-buildinstall">
<title xml:lang="en">Build and Install the Web Site</title>		<title>建置並安裝網站</title>

<para xml:lang="en">Build the web site and all documents as user		<para xml:lang="en">Build the web site and all documents as user
<systemitem class="username">jru</systemitem>. Install the		<systemitem class="username">jru</systemitem>. Install the
resulting files as		resulting files as
<systemitem class="username">root</systemitem> into the		<systemitem class="username">root</systemitem> into the
default directory,		default directory,
<filename>/root/public_html</filename>:</para>		<filename>/root/public_html</filename>:</para>

▲ Show 20 Lines • Show All 43 Lines • ▼ Show 20 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,		HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN		STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="xml-primer">		<chapter version="5.0" xml:id="xml-primer">
<title xml:lang="en">XML Primer</title>		<title>XML 入門</title>

<para xml:lang="en">Most <acronym>FDP</acronym> documentation is written with		<para xml:lang="en">Most <acronym>FDP</acronym> documentation is written with
markup languages based on <acronym>XML</acronym>. This chapter		markup languages based on <acronym>XML</acronym>. This chapter
explains what that means, how to read and understand the		explains what that means, how to read and understand the
documentation source, and the <acronym>XML</acronym> techniques		documentation source, and the <acronym>XML</acronym> techniques
used.</para>		used.</para>

<para xml:lang="en">Portions of this section were inspired by Mark Galassi's		<para xml:lang="en">Portions of this section were inspired by Mark Galassi's
▲ Show 20 Lines • Show All 120 Lines • ▼ Show 20 Lines	allowed to appear in the same place).</para>
<para xml:lang="en">Most contributions to the Documentation		<para xml:lang="en">Most contributions to the Documentation
Project will be content marked up in either		Project will be content marked up in either
<acronym>XHTML</acronym> or DocBook, rather than alterations to		<acronym>XHTML</acronym> or DocBook, rather than alterations to
the schemas. For this reason, this book will not touch on how		the schemas. For this reason, this book will not touch on how
to write a vocabulary.</para>		to write a vocabulary.</para>
</sect1>		</sect1>

<sect1 xml:id="xml-primer-elements">		<sect1 xml:id="xml-primer-elements">
<title xml:lang="en">Elements, Tags, and Attributes</title>		<title>元素、標籤與屬性</title>

<para xml:lang="en">All the vocabularies written in <acronym>XML</acronym> share		<para xml:lang="en">All the vocabularies written in <acronym>XML</acronym> share
certain characteristics. This is hardly surprising, as the		certain characteristics. This is hardly surprising, as the
philosophy behind <acronym>XML</acronym> will inevitably show		philosophy behind <acronym>XML</acronym> will inevitably show
through. One of the most obvious manifestations of this		through. One of the most obvious manifestations of this
philosophy is that of <emphasis>content</emphasis> and		philosophy is that of <emphasis>content</emphasis> and
<emphasis>elements</emphasis>.</para>		<emphasis>elements</emphasis>.</para>

Show All 39 Lines	<para xml:lang="en">A tag is used to identify where a particular element starts,
different names for the tags.</para>		different names for the tags.</para>

<para xml:lang="en">For an element called		<para xml:lang="en">For an element called
<replaceable>element-name</replaceable> the start tag will		<replaceable>element-name</replaceable> the start tag will
normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>.		normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>.
The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para>		The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para>

<example>		<example>
<title xml:lang="en">Using an Element (Start and End Tags)</title>		<title>使用元素 (開始與結束標籤)</title>

<para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating		<para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating
that the content enclosed by the element is a paragraph,		that the content enclosed by the element is a paragraph,
called <tag>p</tag>.</para>		called <tag>p</tag>.</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for		<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for
the 'p' element, and it will end with the end tag for the 'p'		the 'p' element, and it will end with the end tag for the 'p'
element.<tag class="endtag">p</tag>		element.<tag class="endtag">p</tag>

<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting>		<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">Some elements have no content. For example, in		<para xml:lang="en">Some elements have no content. For example, in
<acronym>XHTML</acronym>, a horizontal line can be included in		<acronym>XHTML</acronym>, a horizontal line can be included in
the document. For these <quote>empty</quote> elements,		the document. For these <quote>empty</quote> elements,
<acronym>XML</acronym> introduced a shorthand form that is		<acronym>XML</acronym> introduced a shorthand form that is
completely equivalent to the two-tag version:</para>		completely equivalent to the two-tag version:</para>

<example>		<example>
<title xml:lang="en">Using an Element Without Content</title>		<title>使用沒有內容的元素</title>

<para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating a		<para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating a
horizontal rule, called <tag>hr</tag>. This element		horizontal rule, called <tag>hr</tag>. This element
does not wrap content, so it looks like this:</para>		does not wrap content, so it looks like this:</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>		<programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
<tag class="starttag">hr</tag><tag class="endtag">hr</tag>		<tag class="starttag">hr</tag><tag class="endtag">hr</tag>

Show All 10 Lines	from the previous paragraph.<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">As shown above, elements can contain other elements. In the		<para xml:lang="en">As shown above, elements can contain other elements. In the
book example earlier, the book element contained all the chapter		book example earlier, the book element contained all the chapter
elements, which in turn contained all the paragraph elements,		elements, which in turn contained all the paragraph elements,
and so on.</para>		and so on.</para>

<example>		<example>
<title xml:lang="en">Elements Within Elements; <tag>em</tag></title>		<title>在元素中的元素; <tag>em</tag></title>

<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some		<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some
of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting>		of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">The grammar consists of rules that describe which elements		<para xml:lang="en">The grammar consists of rules that describe which elements
can contain other elements, and exactly what they can		can contain other elements, and exactly what they can
contain.</para>		contain.</para>
Show All 39 Lines	keep it in mind.</para>

<para xml:lang="en">The <tag class="attribute">align</tag> attribute can		<para xml:lang="en">The <tag class="attribute">align</tag> attribute can
take one of four defined values, <literal>left</literal>,		take one of four defined values, <literal>left</literal>,
<literal>center</literal>, <literal>right</literal> and		<literal>center</literal>, <literal>right</literal> and
<literal>justify</literal>. If the attribute is not specified		<literal>justify</literal>. If the attribute is not specified
then the default is <literal>left</literal>.</para>		then the default is <literal>left</literal>.</para>

<example>		<example>
<title xml:lang="en">Using an Element with an Attribute</title>		<title>使用元素的屬性</title>

<programlisting xml:lang="en"><tag class="starttag">p align="left"</tag>The inclusion of the align attribute		<programlisting xml:lang="en"><tag class="starttag">p align="left"</tag>The inclusion of the align attribute
on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag>		on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag>

<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting>		<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">Some attributes only take specific values, such as		<para xml:lang="en">Some attributes only take specific values, such as
<literal>left</literal> or <literal>justify</literal>. Others		<literal>left</literal> or <literal>justify</literal>. Others
allow any value.</para>		allow any value.</para>

<example>		<example>
<title xml:lang="en">Single Quotes Around Attributes</title>		<title>屬性的單引號</title>

<programlisting xml:lang="en"><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting>		<programlisting xml:lang="en"><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">Attribute values in <acronym>XML</acronym> must be enclosed		<para xml:lang="en">Attribute values in <acronym>XML</acronym> must be enclosed
in either single or double quotes. Double quotes are		in either single or double quotes. Double quotes are
traditional. Single quotes are useful when the attribute value		traditional. Single quotes are useful when the attribute value
contains double quotes.</para>		contains double quotes.</para>

<para xml:lang="en">Information about attributes, elements, and tags is stored		<para xml:lang="en">Information about attributes, elements, and tags is stored
in catalog files. The Documentation Project uses standard		in catalog files. The Documentation Project uses standard
DocBook catalogs and includes additional catalogs for		DocBook catalogs and includes additional catalogs for
FreeBSD-specific features. Paths to the catalog files are defined		FreeBSD-specific features. Paths to the catalog files are defined
in an environment variable so they can be found by the document		in an environment variable so they can be found by the document
build tools.</para>		build tools.</para>

<sect2>		<sect2>
<title xml:lang="en">To Do…</title>		<title>待辦事項...</title>

<para xml:lang="en">Before running the examples in this document, install		<para xml:lang="en">Before running the examples in this document, install
<package>textproc/docproj</package> from		<package>textproc/docproj</package> from
the FreeBSD Ports Collection. This is a		the FreeBSD Ports Collection. This is a
<emphasis>meta-port</emphasis> that downloads and installs		<emphasis>meta-port</emphasis> that downloads and installs
the standard programs and supporting files needed by the		the standard programs and supporting files needed by the
Documentation Project. <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> users must use		Documentation Project. <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> users must use
<command>rehash</command> for the shell to recognize new		<command>rehash</command> for the shell to recognize new
▲ Show 20 Lines • Show All 66 Lines • ▼ Show 20 Lines	example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script \| style \| meta \| link \| object \| isindex)* , ((title , (script \| style \| meta \| link \| object \| isindex)* , (base , (script \| style \| meta \| link \| object \| isindex))?) \| (base , (script \| style \| meta \| link \| object \| isindex) , title , (script \| style \| meta \| link \| object \| isindex)*))), got ()</screen>
<step>		<step>
<para xml:lang="en">Replace the <tag>title</tag> element.</para>		<para xml:lang="en">Replace the <tag>title</tag> element.</para>
</step>		</step>
</procedure>		</procedure>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="xml-primer-doctype-declaration">		<sect1 xml:id="xml-primer-doctype-declaration">
<title xml:lang="en">The DOCTYPE Declaration</title>		<title>DOCTYPE 宣告</title>

<para xml:lang="en">The beginning of each document can specify the name of the		<para xml:lang="en">The beginning of each document can specify the name of the
<acronym>DTD</acronym> to which the document conforms. This		<acronym>DTD</acronym> to which the document conforms. This
DOCTYPE declaration is used by <acronym>XML</acronym> parsers to		DOCTYPE declaration is used by <acronym>XML</acronym> parsers to
identify the <acronym>DTD</acronym> and ensure that the document		identify the <acronym>DTD</acronym> and ensure that the document
does conform to it.</para>		does conform to it.</para>

<para xml:lang="en">A typical declaration for a document written to conform with		<para xml:lang="en">A typical declaration for a document written to conform with
▲ Show 20 Lines • Show All 72 Lines • ▼ Show 20 Lines	example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script \| style \| meta \| link \| object \| isindex)* , ((title , (script \| style \| meta \| link \| object \| isindex)* , (base , (script \| style \| meta \| link \| object \| isindex))?) \| (base , (script \| style \| meta \| link \| object \| isindex) , title , (script \| style \| meta \| link \| object \| isindex)*))), got ()</screen>
<listitem>		<listitem>
<para xml:lang="en">Ends the declaration and returns to the		<para xml:lang="en">Ends the declaration and returns to the
document.</para>		document.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>
</variablelist>		</variablelist>

<sect2>		<sect2>
<title xml:lang="en">Formal Public Identifiers		<title>正式公用識別碼 (<acronym>FPI</acronym>)</title>
(<acronym>FPI</acronym>s)</title>

<indexterm significance="preferred" xml:lang="en">		<indexterm significance="preferred" xml:lang="en">
<primary>Formal Public Identifier</primary>		<primary>Formal Public Identifier</primary>
</indexterm>		</indexterm>

<note>		<note>
<para xml:lang="en">It is not necessary to know this, but it is useful		<para xml:lang="en">It is not necessary to know this, but it is useful
background, and might help debug problems when the		background, and might help debug problems when the
▲ Show 20 Lines • Show All 92 Lines • ▼ Show 20 Lines	<listitem>
<para xml:lang="en">An <acronym>ISO</acronym> two-character code that		<para xml:lang="en">An <acronym>ISO</acronym> two-character code that
identifies the native language for the file.		identifies the native language for the file.
<literal>EN</literal> is used for English.</para>		<literal>EN</literal> is used for English.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>
</variablelist>		</variablelist>

<sect3>		<sect3>
<title xml:lang="en"><filename>catalog</filename> Files</title>		<title><filename>catalog</filename> 檔案</title>

<para xml:lang="en">With the syntax above, an <acronym>XML</acronym>		<para xml:lang="en">With the syntax above, an <acronym>XML</acronym>
processor needs to have some way of turning the		processor needs to have some way of turning the
<acronym>FPI</acronym> into the name of the file containing		<acronym>FPI</acronym> into the name of the file containing
the <acronym>DTD</acronym>. A catalog file (typically		the <acronym>DTD</acronym>. A catalog file (typically
called <filename>catalog</filename>) contains lines that map		called <filename>catalog</filename>) contains lines that map
<acronym>FPI</acronym>s to filenames. For example, if the		<acronym>FPI</acronym>s to filenames. For example, if the
catalog file contained the line:</para>		catalog file contained the line:</para>
Show All 12 Lines	<para xml:lang="en">Examine the contents of
<filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.		<filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
This is the catalog file for the <acronym>XHTML</acronym>		This is the catalog file for the <acronym>XHTML</acronym>
<acronym>DTD</acronym>s that were installed as part of the		<acronym>DTD</acronym>s that were installed as part of the
<package>textproc/docproj</package> port.</para>		<package>textproc/docproj</package> port.</para>
</sect3>		</sect3>
</sect2>		</sect2>

<sect2 xml:id="xml-primer-fpi-alternatives">		<sect2 xml:id="xml-primer-fpi-alternatives">
<title xml:lang="en">Alternatives to <acronym>FPI</acronym>s</title>		<title><acronym>FPI</acronym> 的替代方案</title>

<para xml:lang="en">Instead of using an <acronym>FPI</acronym> to indicate the		<para xml:lang="en">Instead of using an <acronym>FPI</acronym> to indicate the
<acronym>DTD</acronym> to which the document conforms (and		<acronym>DTD</acronym> to which the document conforms (and
therefore, which file on the system contains the		therefore, which file on the system contains the
<acronym>DTD</acronym>), the filename can be explicitly		<acronym>DTD</acronym>), the filename can be explicitly
specified.</para>		specified.</para>

<para xml:lang="en">The syntax is slightly different:</para>		<para xml:lang="en">The syntax is slightly different:</para>
Show All 9 Lines	will be provided as a filename.</para>
<para xml:lang="en">Using <acronym>FPI</acronym>s is preferred for reasons of		<para xml:lang="en">Using <acronym>FPI</acronym>s is preferred for reasons of
portability. If the <literal>SYSTEM</literal> identifier is		portability. If the <literal>SYSTEM</literal> identifier is
used, then the <acronym>DTD</acronym> must be provided and		used, then the <acronym>DTD</acronym> must be provided and
kept in the same location for everyone.</para>		kept in the same location for everyone.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="xml-primer-xml-escape">		<sect1 xml:id="xml-primer-xml-escape">
<title xml:lang="en">Escaping Back to <acronym>XML</acronym></title>		<title>跳脫回 <acronym>XML</acronym></title>

<para xml:lang="en">Some of the underlying <acronym>XML</acronym> syntax can be		<para xml:lang="en">Some of the underlying <acronym>XML</acronym> syntax can be
useful within documents. For example, comments can be included		useful within documents. For example, comments can be included
in the document, and will be ignored by the parser. Comments		in the document, and will be ignored by the parser. Comments
are entered using <acronym>XML</acronym> syntax. Other uses for		are entered using <acronym>XML</acronym> syntax. Other uses for
<acronym>XML</acronym> syntax will be shown later.</para>		<acronym>XML</acronym> syntax will be shown later.</para>

<para xml:lang="en"><acronym>XML</acronym> sections begin with a		<para xml:lang="en"><acronym>XML</acronym> sections begin with a
<literal><!</literal> tag and end with a		<literal><!</literal> tag and end with a
<literal>></literal>. These sections contain instructions		<literal>></literal>. These sections contain instructions
for the parser rather than elements of the document. Everything		for the parser rather than elements of the document. Everything
between these tags is <acronym>XML</acronym> syntax. The		between these tags is <acronym>XML</acronym> syntax. The
<link linkend="xml-primer-doctype-declaration">DOCTYPE		<link linkend="xml-primer-doctype-declaration">DOCTYPE
declaration</link> shown earlier is an example of		declaration</link> shown earlier is an example of
<acronym>XML</acronym> syntax included in the document.</para>		<acronym>XML</acronym> syntax included in the document.</para>

</sect1>		</sect1>

<sect1 xml:id="xml-primer-comments">		<sect1 xml:id="xml-primer-comments">
<title xml:lang="en">Comments</title>		<title>註解</title>

<para xml:lang="en">An <acronym>XML</acronym> document may contain comments.		<para xml:lang="en">An <acronym>XML</acronym> document may contain comments.
They may appear anywhere as long as they are not inside tags.		They may appear anywhere as long as they are not inside tags.
They are even allowed in some locations inside the		They are even allowed in some locations inside the
<acronym>DTD</acronym> (e.g., between <link linkend="xml-primer-entities">entity		<acronym>DTD</acronym> (e.g., between <link linkend="xml-primer-entities">entity
declarations</link>).</para>		declarations</link>).</para>

<para xml:lang="en"><acronym>XML</acronym> comments start with the string		<para xml:lang="en"><acronym>XML</acronym> comments start with the string
<quote><literal><!--</literal></quote> and end with the		<quote><literal><!--</literal></quote> and end with the
string <quote><literal>--></literal></quote>.</para>		string <quote><literal>--></literal></quote>.</para>

<para xml:lang="en">Here are some examples of valid <acronym>XML</acronym>		<para xml:lang="en">Here are some examples of valid <acronym>XML</acronym>
comments:</para>		comments:</para>

<example>		<example>
<title xml:lang="en"><acronym>XML</acronym> Generic Comments</title>		<title><acronym>XML</acronym> 通用註解</title>

<programlisting xml:lang="en"><!-- This is inside the comment -->		<programlisting xml:lang="en"><!-- This is inside the comment -->

<!--This is another comment-->		<!--This is another comment-->

<!-- This is how you		<!-- This is how you
write multiline comments -->		write multiline comments -->

<p>A simple <!-- Comment inside an element's content --> paragraph.</p></programlisting>		<p>A simple <!-- Comment inside an element's content --> paragraph.</p></programlisting>
</example>		</example>

<para xml:lang="en"><acronym>XML</acronym> comments may contain any strings		<para xml:lang="en"><acronym>XML</acronym> comments may contain any strings
except <quote><literal>--</literal></quote>:</para>		except <quote><literal>--</literal></quote>:</para>

<example>		<example>
<title xml:lang="en">Erroneous <acronym>XML</acronym> Comment</title>		<title>錯誤的<acronym>XML</acronym> 註解</title>

<programlisting xml:lang="en"><!-- This comment--is wrong --></programlisting>		<programlisting xml:lang="en"><!-- This comment--is wrong --></programlisting>
</example>		</example>

<sect2>		<sect2>
<title xml:lang="en">To Do…</title>		<title>待辦事項...</title>

<procedure>		<procedure>
<step>		<step>
<para xml:lang="en">Add some comments to		<para xml:lang="en">Add some comments to
<filename>example.xml</filename>, and check that the file		<filename>example.xml</filename>, and check that the file
still validates using <command>xmllint</command>.</para>		still validates using <command>xmllint</command>.</para>
</step>		</step>

<step>		<step>
<para xml:lang="en">Add some invalid comments to		<para xml:lang="en">Add some invalid comments to
<filename>example.xml</filename>, and see the error		<filename>example.xml</filename>, and see the error
messages that <command>xmllint</command> gives when it		messages that <command>xmllint</command> gives when it
encounters an invalid comment.</para>		encounters an invalid comment.</para>
</step>		</step>
</procedure>		</procedure>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="xml-primer-entities">		<sect1 xml:id="xml-primer-entities">
<title xml:lang="en">Entities</title>		<title>Entities</title>

<para xml:lang="en">Entities are a mechanism for assigning names to chunks of		<para xml:lang="en">Entities are a mechanism for assigning names to chunks of
content. As an <acronym>XML</acronym> parser processes a		content. As an <acronym>XML</acronym> parser processes a
document, any entities it finds are replaced by the content of		document, any entities it finds are replaced by the content of
the entity.</para>		the entity.</para>

<para xml:lang="en">This is a good way to have re-usable, easily changeable		<para xml:lang="en">This is a good way to have re-usable, easily changeable
chunks of content in <acronym>XML</acronym> documents. It is		chunks of content in <acronym>XML</acronym> documents. It is
also the only way to include one marked up file inside another		also the only way to include one marked up file inside another
using <acronym>XML</acronym>.</para>		using <acronym>XML</acronym>.</para>

<para xml:lang="en">There are two types of entities for two different		<para xml:lang="en">There are two types of entities for two different
situations: <emphasis>general entities</emphasis> and		situations: <emphasis>general entities</emphasis> and
<emphasis>parameter entities</emphasis>.</para>		<emphasis>parameter entities</emphasis>.</para>

<sect2 xml:id="xml-primer-general-entities">		<sect2 xml:id="xml-primer-general-entities">
<title xml:lang="en">General Entities</title>		<title>一般 Entities</title>

<para xml:lang="en">General entities are used to assign names to reusable		<para xml:lang="en">General entities are used to assign names to reusable
chunks of text. These entities can only be used in the		chunks of text. These entities can only be used in the
document. They cannot be used in an		document. They cannot be used in an
<acronym>XML</acronym> context.</para>		<acronym>XML</acronym> context.</para>

<para xml:lang="en">To include the text of a general entity in the document,		<para xml:lang="en">To include the text of a general entity in the document,
include		include
Show All 23 Lines	<p>A simple <!-- Comment inside an element's content --> paragraph.</p></programlisting>
general entities: <literal>&lt;</literal> and		general entities: <literal>&lt;</literal> and
<literal>&amp;</literal>.</para>		<literal>&amp;</literal>.</para>

<para xml:lang="en">General entities can only be defined within an		<para xml:lang="en">General entities can only be defined within an
<acronym>XML</acronym> context. Such definitions are usually		<acronym>XML</acronym> context. Such definitions are usually
done immediately after the DOCTYPE declaration.</para>		done immediately after the DOCTYPE declaration.</para>

<example>		<example>
<title xml:lang="en">Defining General Entities</title>		<title>定義一般 Entities</title>

<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"		<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [		"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY current.version "3.0-RELEASE">		<!ENTITY current.version "3.0-RELEASE">
<!ENTITY last.version "2.2.7-RELEASE">		<!ENTITY last.version "2.2.7-RELEASE">
]></programlisting>		]></programlisting>

<para xml:lang="en">The DOCTYPE declaration has been extended by adding a		<para xml:lang="en">The DOCTYPE declaration has been extended by adding a
square bracket at the end of the first line. The two		square bracket at the end of the first line. The two
entities are then defined over the next two lines, the		entities are then defined over the next two lines, the
square bracket is closed, and then the DOCTYPE declaration		square bracket is closed, and then the DOCTYPE declaration
is closed.</para>		is closed.</para>

<para xml:lang="en">The square brackets are necessary to indicate that the		<para xml:lang="en">The square brackets are necessary to indicate that the
DTD indicated by the DOCTYPE declaration is being		DTD indicated by the DOCTYPE declaration is being
extended.</para>		extended.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="xml-primer-parameter-entities">		<sect2 xml:id="xml-primer-parameter-entities">
<title xml:lang="en">Parameter Entities</title>		<title>參數 Entities</title>

<para xml:lang="en">Parameter entities, like		<para xml:lang="en">Parameter entities, like
<link linkend="xml-primer-general-entities">general		<link linkend="xml-primer-general-entities">general
entities</link>, are used to assign names to reusable chunks		entities</link>, are used to assign names to reusable chunks
of text. But parameter entities can only be used within an		of text. But parameter entities can only be used within an
<link linkend="xml-primer-xml-escape">XML		<link linkend="xml-primer-xml-escape">XML
context</link>.</para>		context</link>.</para>

<para xml:lang="en">Parameter entity definitions are similar to those for		<para xml:lang="en">Parameter entity definitions are similar to those for
general entities. However, parameter entries are included		general entities. However, parameter entries are included
with		with
<literal>%<replaceable>entity-name</replaceable>;</literal>.		<literal>%<replaceable>entity-name</replaceable>;</literal>.
The definition also includes the <literal>%</literal> between		The definition also includes the <literal>%</literal> between
the <literal>ENTITY</literal> keyword and the name of the		the <literal>ENTITY</literal> keyword and the name of the
entity.</para>		entity.</para>

<para xml:lang="en">For a mnemonic, think		<para xml:lang="en">For a mnemonic, think
<quote><emphasis>P</emphasis>arameter entities use the		<quote><emphasis>P</emphasis>arameter entities use the
<emphasis>P</emphasis>ercent symbol</quote>.</para>		<emphasis>P</emphasis>ercent symbol</quote>.</para>

<example>		<example>
<title xml:lang="en">Defining Parameter Entities</title>		<title>定義參數 Entities</title>

<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"		<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [		"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % param.some "some">		<!ENTITY % param.some "some">
<!ENTITY % param.text "text">		<!ENTITY % param.text "text">
<!ENTITY % param.new "%param.some more %param.text">		<!ENTITY % param.new "%param.some more %param.text">

<!-- %param.new now contains "some more text" -->		<!-- %param.new now contains "some more text" -->
]></programlisting>		]></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2>		<sect2>
<title xml:lang="en">To Do…</title>		<title>待辦事項...</title>

<procedure>		<procedure>
<step>		<step>
<para xml:lang="en">Add a general entity to		<para xml:lang="en">Add a general entity to
<filename>example.xml</filename>.</para>		<filename>example.xml</filename>.</para>

<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"		<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [		"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
▲ Show 20 Lines • Show All 60 Lines • ▼ Show 20 Lines	<para xml:lang="en">A normalized copy of the document with entities
expanded is produced in <filename>example.html</filename>,		expanded is produced in <filename>example.html</filename>,
ready to load into a web browser.</para>		ready to load into a web browser.</para>
</step>		</step>
</procedure>		</procedure>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="xml-primer-include">		<sect1 xml:id="xml-primer-include">
<title xml:lang="en">Using Entities to Include Files</title>		<title>在引用檔使用 Entities</title>

<para xml:lang="en">Both		<para xml:lang="en">Both
<link linkend="xml-primer-general-entities">general</link> and		<link linkend="xml-primer-general-entities">general</link> and
<link linkend="xml-primer-parameter-entities">parameter</link>		<link linkend="xml-primer-parameter-entities">parameter</link>
entities are particularly useful for including one file inside		entities are particularly useful for including one file inside
another.</para>		another.</para>

<sect2 xml:id="xml-primer-include-using-gen-entities">		<sect2 xml:id="xml-primer-include-using-gen-entities">
<title xml:lang="en">Using General Entities to Include Files</title>		<title>在引用檔使用一般 Entities</title>

<para xml:lang="en">Consider some content for an <acronym>XML</acronym> book		<para xml:lang="en">Consider some content for an <acronym>XML</acronym> book
organized into files, one file per chapter, called		organized into files, one file per chapter, called
<filename>chapter1.xml</filename>,		<filename>chapter1.xml</filename>,
<filename>chapter2.xml</filename>, and so forth, with a		<filename>chapter2.xml</filename>, and so forth, with a
<filename>book.xml</filename> that will contain these		<filename>book.xml</filename> that will contain these
chapters.</para>		chapters.</para>

<para xml:lang="en">In order to use the contents of these files as the values		<para xml:lang="en">In order to use the contents of these files as the values
for entities, they are declared with the		for entities, they are declared with the
<literal>SYSTEM</literal> keyword. This directs the		<literal>SYSTEM</literal> keyword. This directs the
<acronym>XML</acronym> parser to include the contents of the		<acronym>XML</acronym> parser to include the contents of the
named file as the value of the entity.</para>		named file as the value of the entity.</para>

<example>		<example>
<title xml:lang="en">Using General Entities to Include Files</title>		<title>在引用檔使用一般 Entities</title>

<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"		<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [		"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY chapter.1 SYSTEM "chapter1.xml">		<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">		<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">		<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!-- And so forth -->		<!-- And so forth -->
]>		]>
Show All 15 Lines	<para xml:lang="en">When using general entities to include other files
<emphasis>must not</emphasis> start with a DOCTYPE		<emphasis>must not</emphasis> start with a DOCTYPE
declaration. This is a syntax error because entities are		declaration. This is a syntax error because entities are
low-level constructs and they are resolved before any		low-level constructs and they are resolved before any
parsing happens.</para>		parsing happens.</para>
</warning>		</warning>
</sect2>		</sect2>

<sect2>		<sect2>
<title xml:lang="en">Using Parameter Entities to Include Files</title>		<title>在引用檔使用參數 Entities</title>

<para xml:lang="en">Parameter entities can only be used inside an		<para xml:lang="en">Parameter entities can only be used inside an
<acronym>XML</acronym> context. Including a file in an		<acronym>XML</acronym> context. Including a file in an
<acronym>XML</acronym> context can be used		<acronym>XML</acronym> context can be used
to ensure that general entities are reusable.</para>		to ensure that general entities are reusable.</para>

<para xml:lang="en">Suppose that there are many chapters in the document, and		<para xml:lang="en">Suppose that there are many chapters in the document, and
these chapters were reused in two different books, each book		these chapters were reused in two different books, each book
organizing the chapters in a different fashion.</para>		organizing the chapters in a different fashion.</para>

<para xml:lang="en">The entities could be listed at the top of each book, but		<para xml:lang="en">The entities could be listed at the top of each book, but
that quickly becomes cumbersome to manage.</para>		that quickly becomes cumbersome to manage.</para>

<para xml:lang="en">Instead, place the general entity definitions inside one		<para xml:lang="en">Instead, place the general entity definitions inside one
file, and use a parameter entity to include that file within		file, and use a parameter entity to include that file within
the document.</para>		the document.</para>

<example>		<example>
<title xml:lang="en">Using Parameter Entities to Include Files</title>		<title>在引用檔使用參數 Entities</title>

<para xml:lang="en">Place the entity definitions in a separate file		<para xml:lang="en">Place the entity definitions in a separate file
called <filename>chapters.ent</filename> and		called <filename>chapters.ent</filename> and
containing this text:</para>		containing this text:</para>

<programlisting xml:lang="en"><!ENTITY chapter.1 SYSTEM "chapter1.xml">		<programlisting xml:lang="en"><!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">		<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml"></programlisting>		<!ENTITY chapter.3 SYSTEM "chapter3.xml"></programlisting>
Show All 17 Lines	<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
&chapter.1;		&chapter.1;
&chapter.2;		&chapter.2;
&chapter.3;		&chapter.3;
<tag class="endtag">html</tag></programlisting>		<tag class="endtag">html</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2>		<sect2>
<title xml:lang="en">To Do…</title>		<title>待辦事項...</title>

<sect3>		<sect3>
<title xml:lang="en">Use General Entities to Include Files</title>		<title>在引用檔使用一般 Entities</title>

<procedure>		<procedure>
<step>		<step>
<para xml:lang="en">Create three files, <filename>para1.xml</filename>,		<para xml:lang="en">Create three files, <filename>para1.xml</filename>,
<filename>para2.xml</filename>, and		<filename>para2.xml</filename>, and
<filename>para3.xml</filename>.</para>		<filename>para3.xml</filename>.</para>

<para xml:lang="en">Put content like this in each file:</para>		<para xml:lang="en">Put content like this in each file:</para>
▲ Show 20 Lines • Show All 41 Lines • ▼ Show 20 Lines	<step>
<filename>para<replaceable>n</replaceable>.xml</filename>		<filename>para<replaceable>n</replaceable>.xml</filename>
files have been included in		files have been included in
<filename>example.html</filename>.</para>		<filename>example.html</filename>.</para>
</step>		</step>
</procedure>		</procedure>
</sect3>		</sect3>

<sect3>		<sect3>
<title xml:lang="en">Use Parameter Entities to Include Files</title>		<title>在引用檔使用參數 Entities</title>

<note>		<note>
<para xml:lang="en">The previous steps must have completed before this		<para xml:lang="en">The previous steps must have completed before this
step.</para>		step.</para>
</note>		</note>

<procedure>		<procedure>
<step>		<step>
▲ Show 20 Lines • Show All 46 Lines • ▼ Show 20 Lines	<step>
<filename>example.html</filename>.</para>		<filename>example.html</filename>.</para>
</step>		</step>
</procedure>		</procedure>
</sect3>		</sect3>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="xml-primer-marked-sections">		<sect1 xml:id="xml-primer-marked-sections">
<title xml:lang="en">Marked Sections</title>		<title>已標記小節</title>

<para xml:lang="en"><acronym>XML</acronym> provides a mechanism to indicate that		<para xml:lang="en"><acronym>XML</acronym> provides a mechanism to indicate that
particular pieces of the document should be processed in a		particular pieces of the document should be processed in a
special way. These are called		special way. These are called
<quote>marked sections</quote>.</para>		<quote>marked sections</quote>.</para>

<example>		<example>
<title xml:lang="en">Structure of a Marked Section</title>		<title>已標記的結構</title>

<programlisting xml:lang="en"><![<replaceable>KEYWORD</replaceable>[		<programlisting xml:lang="en"><![<replaceable>KEYWORD</replaceable>[
Contents of marked section		Contents of marked section
]]></programlisting>		]]></programlisting>
</example>		</example>

<para xml:lang="en">As expected of an <acronym>XML</acronym> construct, a marked		<para xml:lang="en">As expected of an <acronym>XML</acronym> construct, a marked
section starts with <literal><!</literal>.</para>		section starts with <literal><!</literal>.</para>

<para xml:lang="en">The first square bracket begins the marked section.</para>		<para xml:lang="en">The first square bracket begins the marked section.</para>

<para xml:lang="en"><replaceable>KEYWORD</replaceable> describes how this marked		<para xml:lang="en"><replaceable>KEYWORD</replaceable> describes how this marked
section is to be processed by the parser.</para>		section is to be processed by the parser.</para>

<para xml:lang="en">The second square bracket indicates the start of the		<para xml:lang="en">The second square bracket indicates the start of the
marked section's content.</para>		marked section's content.</para>

<para xml:lang="en">The marked section is finished by closing the two square		<para xml:lang="en">The marked section is finished by closing the two square
brackets, and then returning to the document context from the		brackets, and then returning to the document context from the
<acronym>XML</acronym> context with		<acronym>XML</acronym> context with
<literal>></literal>.</para>		<literal>></literal>.</para>

<sect2 xml:id="xml-primer-marked-section-keywords">		<sect2 xml:id="xml-primer-marked-section-keywords">
<title xml:lang="en">Marked Section Keywords</title>		<title>已標記關鍵字</title>

<sect3 xml:id="xml-primer-cdata">		<sect3 xml:id="xml-primer-cdata">
<title xml:lang="en"><literal>CDATA</literal></title>		<title xml:lang="en"><literal>CDATA</literal></title>

<para xml:lang="en">These keywords denote the marked sections		<para xml:lang="en">These keywords denote the marked sections
<emphasis>content model</emphasis>, and allow you to change		<emphasis>content model</emphasis>, and allow you to change
it from the default.</para>		it from the default.</para>

Show All 21 Lines	<para xml:lang="en">When using <literal>CDATA</literal> in examples of
the content of <literal>CDATA</literal> is not validated.		the content of <literal>CDATA</literal> is not validated.
The included text must be check with other means. For		The included text must be check with other means. For
example, the content could be written in another document,		example, the content could be written in another document,
validated, and then pasted into the		validated, and then pasted into the
<literal>CDATA</literal> section.</para>		<literal>CDATA</literal> section.</para>
</note>		</note>

<example>		<example>
<title xml:lang="en">Using a <literal>CDATA</literal> Marked		<title>使用 <literal>CDATA</literal> 已標記小節</title>
Section</title>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Here is an example of how to include some text that contains		<programlisting xml:lang="en"><tag class="starttag">para</tag>Here is an example of how to include some text that contains
many <tag class="starttag">literal</tag>&lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;<tag class="endtag">literal</tag>		many <tag class="starttag">literal</tag>&lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;<tag class="endtag">literal</tag>
symbols. The sample text is a fragment of		symbols. The sample text is a fragment of
<tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and		<tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and
<tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag>		<tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag>

<tag class="starttag">programlisting</tag><![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the		<tag class="starttag">programlisting</tag><![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the
elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle		elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle
brackets are used so many times, it is simpler to say the whole		brackets are used so many times, it is simpler to say the whole
example is a CDATA marked section than to use the entity names for		example is a CDATA marked section than to use the entity names for
the left and right angle brackets throughout.<tag class="endtag">p</tag>		the left and right angle brackets throughout.<tag class="endtag">p</tag>

<tag class="starttag">ul</tag>		<tag class="starttag">ul</tag>
<tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag>		<tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag>
<tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag>		<tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag>
<tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag>		<tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag>
<tag class="endtag">ul</tag>		<tag class="endtag">ul</tag>

<tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting>		<tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting>
</example>		</example>
</sect3>		</sect3>

<sect3 xml:id="xml-primer-include-ignore">		<sect3 xml:id="xml-primer-include-ignore">
<title xml:lang="en"><literal>INCLUDE</literal> and		<title><literal>INCLUDE</literal> 與 <literal>IGNORE</literal></title>
<literal>IGNORE</literal></title>

<para xml:lang="en">When the keyword is <literal>INCLUDE</literal>, then the		<para xml:lang="en">When the keyword is <literal>INCLUDE</literal>, then the
contents of the marked section will be processed. When the		contents of the marked section will be processed. When the
keyword is <literal>IGNORE</literal>, the marked section		keyword is <literal>IGNORE</literal>, the marked section
is ignored and will not be processed. It will not appear in		is ignored and will not be processed. It will not appear in
the output.</para>		the output.</para>

<example>		<example>
<title xml:lang="en">Using <literal>INCLUDE</literal> and		<title>在已標記小節中使用 <literal>INCLUDE</literal> 及 <literal>IGNORE</literal></title>
<literal>IGNORE</literal> in Marked Sections</title>

<programlisting xml:lang="en"><![INCLUDE[		<programlisting xml:lang="en"><![INCLUDE[
This text will be processed and included.		This text will be processed and included.
]]>		]]>

<![IGNORE[		<![IGNORE[
This text will not be processed or included.		This text will not be processed or included.
]]></programlisting>		]]></programlisting>
Show All 25 Lines	<para xml:lang="en">Create an entity file that defines general entities to
always takes effect. So the inclusion of the chapter is		always takes effect. So the inclusion of the chapter is
controlled with the corresponding parameter entity. Set to		controlled with the corresponding parameter entity. Set to
<literal>INCLUDE</literal>, the first general entity		<literal>INCLUDE</literal>, the first general entity
definition will be read and the second one will be ignored.		definition will be read and the second one will be ignored.
Set to <literal>IGNORE</literal>, the first definition will		Set to <literal>IGNORE</literal>, the first definition will
be ignored and the second one will take effect.</para>		be ignored and the second one will take effect.</para>

<example>		<example>
<title xml:lang="en">Using a Parameter Entity to Control a Marked		<title>使用參數 Entities 來控制已標記小節</title>
Section</title>

<programlisting xml:lang="en"><!ENTITY % electronic.copy "INCLUDE">		<programlisting xml:lang="en"><!ENTITY % electronic.copy "INCLUDE">

<![%electronic.copy;[		<![%electronic.copy;[
<!ENTITY chap.preface SYSTEM "preface.xml">		<!ENTITY chap.preface SYSTEM "preface.xml">
]]>		]]>

<!ENTITY chap.preface ""></programlisting>		<!ENTITY chap.preface ""></programlisting>

<para xml:lang="en">When producing the hard-copy version, change the		<para xml:lang="en">When producing the hard-copy version, change the
parameter entity's definition to:</para>		parameter entity's definition to:</para>

<programlisting xml:lang="en"><!ENTITY % electronic.copy "IGNORE"></programlisting>		<programlisting xml:lang="en"><!ENTITY % electronic.copy "IGNORE"></programlisting>
</example>		</example>
</sect3>		</sect3>
</sect2>		</sect2>

<sect2>		<sect2>
<title xml:lang="en">To Do…</title>		<title>待辦事項...</title>

<procedure>		<procedure>
<step>		<step>
<para xml:lang="en">Modify <filename>entities.ent</filename> to		<para xml:lang="en">Modify <filename>entities.ent</filename> to
contain the following:</para>		contain the following:</para>

<programlisting xml:lang="en"><!ENTITY version "1.1">		<programlisting xml:lang="en"><!ENTITY version "1.1">
<!ENTITY % conditional.text "IGNORE">		<!ENTITY % conditional.text "IGNORE">
Show All 19 Lines	<para xml:lang="en">Normalize <filename>example.xml</filename>
example, to control generating printed or online		example, to control generating printed or online
text.</para>		text.</para>
</step>		</step>
</procedure>		</procedure>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="xml-primer-conclusion">		<sect1 xml:id="xml-primer-conclusion">
<title xml:lang="en">Conclusion</title>		<title>結論</title>

<para xml:lang="en">That is the conclusion of this <acronym>XML</acronym>		<para xml:lang="en">That is the conclusion of this <acronym>XML</acronym>
primer. For reasons of space and complexity, several things		primer. For reasons of space and complexity, several things
have not been covered in depth (or at all). However, the		have not been covered in depth (or at all). However, the
previous sections cover enough <acronym>XML</acronym> to		previous sections cover enough <acronym>XML</acronym> to
introduce the organization of the <acronym>FDP</acronym>		introduce the organization of the <acronym>FDP</acronym>
documentation.</para>		documentation.</para>
</sect1>		</sect1>
Show All 27 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,		HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN		STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="xhtml-markup">		<chapter version="5.0" xml:id="xhtml-markup">
<title xml:lang="en"><acronym>XHTML</acronym> Markup</title>		<title><acronym>XHTML</acronym> 標籤</title>

<sect1 xml:id="xhtml-markup-introduction">		<sect1 xml:id="xhtml-markup-introduction">
<title xml:lang="en">Introduction</title>		<title>簡介</title>

<para xml:lang="en">This chapter describes usage of the <acronym>XHTML</acronym>		<para xml:lang="en">This chapter describes usage of the <acronym>XHTML</acronym>
markup language used for the FreeBSD web site.</para>		markup language used for the FreeBSD web site.</para>

<para xml:lang="en"><acronym>XHTML</acronym> is the <acronym>XML</acronym>		<para xml:lang="en"><acronym>XHTML</acronym> is the <acronym>XML</acronym>
version of the HyperText Markup Language, the markup language of		version of the HyperText Markup Language, the markup language of
choice on the World Wide Web. More information can be found at		choice on the World Wide Web. More information can be found at
<uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>		<uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>
Show All 33 Lines	<chapter version="5.0" xml:id="xhtml-markup">
can occur within a block element, and does not cause a line		can occur within a block element, and does not cause a line
break. A <emphasis>block</emphasis> element, by comparison,		break. A <emphasis>block</emphasis> element, by comparison,
will cause a line break (and other processing) when it is		will cause a line break (and other processing) when it is
encountered.</para>		encountered.</para>
</note>		</note>
</sect1>		</sect1>

<sect1 xml:id="xhtml-markup-fpi">		<sect1 xml:id="xhtml-markup-fpi">
<title xml:lang="en">Formal Public Identifier (<acronym>FPI</acronym>)</title>		<title>正式公用識別碼 (<acronym>FPI</acronym>)</title>

<para xml:lang="en">There are a number of <acronym>XHTML</acronym>		<para xml:lang="en">There are a number of <acronym>XHTML</acronym>
<acronym>FPI</acronym>s, depending upon the version, or		<acronym>FPI</acronym>s, depending upon the version, or
<emphasis>level</emphasis> of <acronym>XHTML</acronym> to which		<emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
a document conforms. Most <acronym>XHTML</acronym> documents on		a document conforms. Most <acronym>XHTML</acronym> documents on
the FreeBSD web site comply with the transitional version of		the FreeBSD web site comply with the transitional version of
<acronym>XHTML</acronym> 1.0.</para>		<acronym>XHTML</acronym> 1.0.</para>

<programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>		<programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
</sect1>		</sect1>

<sect1 xml:id="xhtml-markup-sectional-elements">		<sect1 xml:id="xhtml-markup-sectional-elements">
<title xml:lang="en">Sectional Elements</title>		<title>分節元素</title>

<para xml:lang="en">An <acronym>XHTML</acronym> document is normally split into		<para xml:lang="en">An <acronym>XHTML</acronym> document is normally split into
two sections. The first section, called the		two sections. The first section, called the
<emphasis>head</emphasis>, contains meta-information about the		<emphasis>head</emphasis>, contains meta-information about the
document, such as its title, the name of the author, the parent		document, such as its title, the name of the author, the parent
document, and so on. The second section, the		document, and so on. The second section, the
<emphasis>body</emphasis>, contains content that will be		<emphasis>body</emphasis>, contains content that will be
displayed to the user.</para>		displayed to the user.</para>

<para xml:lang="en">These sections are indicated with <tag>head</tag>		<para xml:lang="en">These sections are indicated with <tag>head</tag>
and <tag>body</tag> elements respectively. These		and <tag>body</tag> elements respectively. These
elements are contained within the top-level		elements are contained within the top-level
<tag>html</tag> element.</para>		<tag>html</tag> element.</para>

<example>		<example>
<title xml:lang="en">Normal <acronym>XHTML</acronym> Document		<title>一般的 <acronym>XHTML</acronym> 文件結構</title>
Structure</title>

<programlisting xml:lang="en"><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>		<programlisting xml:lang="en"><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<tag class="starttag">head</tag>		<tag class="starttag">head</tag>
<tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag>		<tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag>
<tag class="endtag">head</tag>		<tag class="endtag">head</tag>

<tag class="starttag">body</tag>		<tag class="starttag">body</tag>

…		…

<tag class="endtag">body</tag>		<tag class="endtag">body</tag>
<tag class="endtag">html</tag></programlisting>		<tag class="endtag">html</tag></programlisting>
</example>		</example>
</sect1>		</sect1>

<sect1 xml:id="xhtml-markup-block-elements">		<sect1 xml:id="xhtml-markup-block-elements">
<title xml:lang="en">Block Elements</title>		<title>區塊元素</title>

<sect2 xml:id="xhtml-markup-block-elements-headings">		<sect2 xml:id="xhtml-markup-block-elements-headings">
<title xml:lang="en">Headings</title>		<title>標題</title>

<para xml:lang="en"><acronym>XHTML</acronym> has tags to denote headings in		<para xml:lang="en"><acronym>XHTML</acronym> has tags to denote headings in
the document at up to six different levels.</para>		the document at up to six different levels.</para>

<para xml:lang="en">The largest and most prominent heading is		<para xml:lang="en">The largest and most prominent heading is
<tag>h1</tag>, then <tag>h2</tag>,		<tag>h1</tag>, then <tag>h2</tag>,
continuing down to <tag>h6</tag>.</para>		continuing down to <tag>h6</tag>.</para>

<para xml:lang="en">The element's content is the text of the heading.</para>		<para xml:lang="en">The element's content is the text of the heading.</para>

<example>		<example>
<title xml:lang="en"><tag>h1</tag>, <tag>h2</tag>,		<title><tag>h1</tag>, <tag>h2</tag>, 以及其他標題標籤</title>
and Other Header Tags</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag>		<programlisting xml:lang="en"><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag>

<!-- Document introduction goes here -->		<!-- Document introduction goes here -->

<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag>		<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag>

<!-- Content for the first section goes here -->		<!-- Content for the first section goes here -->
Show All 10 Lines	<!-- Content for the second section goes here --></programlisting>
<para xml:lang="en">Generally, an <acronym>XHTML</acronym> page should have		<para xml:lang="en">Generally, an <acronym>XHTML</acronym> page should have
one first level heading (<tag>h1</tag>). This can		one first level heading (<tag>h1</tag>). This can
contain many second level headings (<tag>h2</tag>),		contain many second level headings (<tag>h2</tag>),
which can in turn contain many third level headings. Do not		which can in turn contain many third level headings. Do not
leave gaps in the numbering.</para>		leave gaps in the numbering.</para>
</sect2>		</sect2>

<sect2 xml:id="xhtml-markup-block-elements-paragraphs">		<sect2 xml:id="xhtml-markup-block-elements-paragraphs">
<title xml:lang="en">Paragraphs</title>		<title>段落</title>

<para xml:lang="en"><acronym>XHTML</acronym> supports a single paragraph		<para xml:lang="en"><acronym>XHTML</acronym> supports a single paragraph
element, <tag>p</tag>.</para>		element, <tag>p</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>p</tag> Example</title>		<title><tag>p</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It can contain just about any		<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It can contain just about any
other element.<tag class="endtag">p</tag></programlisting>		other element.<tag class="endtag">p</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="xhtml-markup-block-elements-block-quotations">		<sect2 xml:id="xhtml-markup-block-elements-block-quotations">
<title xml:lang="en">Block Quotations</title>		<title>區塊引言</title>

<para xml:lang="en">A block quotation is an extended quotation from another		<para xml:lang="en">A block quotation is an extended quotation from another
document that will appear in a separate paragraph.</para>		document that will appear in a separate paragraph.</para>

<example>		<example>
<title xml:lang="en"><tag>blockquote</tag> Example</title>		<title><tag>blockquote</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag>		<programlisting xml:lang="en"><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag>

<tag class="starttag">blockquote</tag>We the People of the United States, in Order to form		<tag class="starttag">blockquote</tag>We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic		a more perfect Union, establish Justice, insure domestic
Tranquility, provide for the common defence, promote the general		Tranquility, provide for the common defence, promote the general
Welfare, and secure the Blessings of Liberty to ourselves and our		Welfare, and secure the Blessings of Liberty to ourselves and our
Posterity, do ordain and establish this Constitution for the		Posterity, do ordain and establish this Constitution for the
United States of America.<tag class="endtag">blockquote</tag></programlisting>		United States of America.<tag class="endtag">blockquote</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="xhtml-markup-block-elements-lists">		<sect2 xml:id="xhtml-markup-block-elements-lists">
<title xml:lang="en">Lists</title>		<title>清單</title>

<para xml:lang="en"><acronym>XHTML</acronym> can present the user with three		<para xml:lang="en"><acronym>XHTML</acronym> can present the user with three
types of lists: ordered, unordered, and definition.</para>		types of lists: ordered, unordered, and definition.</para>

<para xml:lang="en">Entries in an ordered list will be numbered, while entries		<para xml:lang="en">Entries in an ordered list will be numbered, while entries
in an unordered list will be preceded by bullet points.		in an unordered list will be preceded by bullet points.
Definition lists have two sections for each entry. The first		Definition lists have two sections for each entry. The first
section is the term being defined, and the second section is		section is the term being defined, and the second section is
Show All 11 Lines	or more <tag>p</tag> elements.</para>

<para xml:lang="en">Definition lists contain definition terms		<para xml:lang="en">Definition lists contain definition terms
(<tag>dt</tag>) and definition descriptions		(<tag>dt</tag>) and definition descriptions
(<tag>dd</tag>). A definition term can only contain		(<tag>dd</tag>). A definition term can only contain
inline elements. A definition description can contain other		inline elements. A definition description can contain other
block elements.</para>		block elements.</para>

<example>		<example>
<title xml:lang="en"><tag>ul</tag> and		<title><tag>ul</tag> 與 <tag>ol</tag> 範例</title>
<tag>ol</tag> Example</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>An unordered list. Listitems will probably be		<programlisting xml:lang="en"><tag class="starttag">p</tag>An unordered list. Listitems will probably be
preceded by bullets.<tag class="endtag">p</tag>		preceded by bullets.<tag class="endtag">p</tag>

<tag class="starttag">ul</tag>		<tag class="starttag">ul</tag>
<tag class="starttag">li</tag>First item<tag class="endtag">li</tag>		<tag class="starttag">li</tag>First item<tag class="endtag">li</tag>

<tag class="starttag">li</tag>Second item<tag class="endtag">li</tag>		<tag class="starttag">li</tag>Second item<tag class="endtag">li</tag>
Show All 13 Lines	<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag>		<tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag>

<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third		<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third
item.<tag class="endtag">p</tag><tag class="endtag">li</tag>		item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
<tag class="endtag">ol</tag></programlisting>		<tag class="endtag">ol</tag></programlisting>
</example>		</example>

<example>		<example>
<title xml:lang="en">Definition Lists with <tag>dl</tag></title>		<title>使用 <tag>dl</tag> 列定義清單</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">dl</tag>		<programlisting xml:lang="en"><tag class="starttag">dl</tag>
<tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag>		<tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag>

<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag>		<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag>

<tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag>		<tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag>

<tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag>		<tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag>

<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag>		<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag>

<tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag>		<tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag>

<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag>		<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
<tag class="endtag">dl</tag></programlisting>		<tag class="endtag">dl</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="xhtml-markup-block-elements-preformatted-text">		<sect2 xml:id="xhtml-markup-block-elements-preformatted-text">
<title xml:lang="en">Pre-formatted Text</title>		<title>已預排文字</title>

<para xml:lang="en">Pre-formatted text is shown to the user exactly as it is		<para xml:lang="en">Pre-formatted text is shown to the user exactly as it is
in the file. Text is shown in a fixed font. Multiple spaces		in the file. Text is shown in a fixed font. Multiple spaces
and line breaks are shown exactly as they are in the		and line breaks are shown exactly as they are in the
file.</para>		file.</para>

<para xml:lang="en">Wrap pre-formatted text in the <tag>pre</tag>		<para xml:lang="en">Wrap pre-formatted text in the <tag>pre</tag>
element.</para>		element.</para>

<example>		<example>
<title xml:lang="en"><tag>pre</tag> Example</title>		<title><tag>pre</tag> 範例</title>

<para xml:lang="en">For example, the <tag>pre</tag> tags could be		<para xml:lang="en">For example, the <tag>pre</tag> tags could be
used to mark up an email message:</para>		used to mark up an email message:</para>

<programlisting xml:lang="en"><tag class="starttag">pre</tag> From: nik@FreeBSD.org		<programlisting xml:lang="en"><tag class="starttag">pre</tag> From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org		To: freebsd-doc@FreeBSD.org
Subject: New documentation available		Subject: New documentation available

Show All 14 Lines	<para xml:lang="en">Keep in mind that <literal><</literal> and
<literal>&gt;</literal> was used in place of		<literal>&gt;</literal> was used in place of
<literal>></literal>, too. Watch out for the special		<literal>></literal>, too. Watch out for the special
characters that may appear in text copied from a plain-text		characters that may appear in text copied from a plain-text
source, like an email message or program code.</para>		source, like an email message or program code.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="xhtml-markup-block-elements-tables">		<sect2 xml:id="xhtml-markup-block-elements-tables">
<title xml:lang="en">Tables</title>		<title>表格</title>

<para xml:lang="en">Mark up tabular information using the		<para xml:lang="en">Mark up tabular information using the
<tag>table</tag> element. A table consists of one or		<tag>table</tag> element. A table consists of one or
more table rows (<tag>tr</tag>), each containing one		more table rows (<tag>tr</tag>), each containing one
or more cells of table data (<tag>td</tag>). Each		or more cells of table data (<tag>td</tag>). Each
cell can contain other block elements, such as paragraphs or		cell can contain other block elements, such as paragraphs or
lists. It can also contain another table (this nesting can		lists. It can also contain another table (this nesting can
repeat indefinitely). If the cell only contains one paragraph		repeat indefinitely). If the cell only contains one paragraph
then the <tag>p</tag>element is not needed.</para>		then the <tag>p</tag>element is not needed.</para>

<example>		<example>
<title xml:lang="en">Simple Use of <tag>table</tag></title>		<title><tag>table</tag> 的簡單用法</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag>		<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag>

<tag class="starttag">table</tag>		<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>		<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag>

<tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>		<tag class="endtag">tr</tag>

<tag class="starttag">tr</tag>		<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>

<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>		<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>		<tag class="endtag">table</tag></programlisting>
</example>		</example>

<para xml:lang="en">A cell can span multiple rows and columns by adding the		<para xml:lang="en">A cell can span multiple rows and columns by adding the
<tag class="attribute">rowspan</tag> or		<tag class="attribute">rowspan</tag> or
<tag class="attribute">colspan</tag> attributes with		<tag class="attribute">colspan</tag> attributes with
values for the number of rows or columns to be spanned.</para>		values for the number of rows or columns to be spanned.</para>

<example>		<example>
<title xml:lang="en">Using		<title>使用 <tag class="attribute">rowspan</tag></title>
<tag class="attribute">rowspan</tag></title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to		<programlisting xml:lang="en"><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to
it on the right.<tag class="endtag">p</tag>		it on the right.<tag class="endtag">p</tag>

<tag class="starttag">table</tag>		<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>		<tag class="starttag">tr</tag>
<tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag>		<tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>		<tag class="endtag">tr</tag>

<tag class="starttag">tr</tag>		<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag>

<tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>		<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>		<tag class="endtag">table</tag></programlisting>
</example>		</example>

<example>		<example>
<title xml:lang="en">Using		<title>使用 <tag class="attribute">colspan</tag></title>
<tag class="attribute">colspan</tag></title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag>		<programlisting xml:lang="en"><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag>

<tag class="starttag">table</tag>		<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>		<tag class="starttag">tr</tag>
<tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag>		<tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>		<tag class="endtag">tr</tag>

<tag class="starttag">tr</tag>		<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>

<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>		<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>		<tag class="endtag">table</tag></programlisting>
</example>		</example>

<example>		<example>
<title xml:lang="en">Using <tag class="attribute">rowspan</tag> and		<title><tag class="attribute">rowspan</tag> 與 <tag class="attribute">colspan</tag> 一起使用</title>
<tag class="attribute">colspan</tag>
Together</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of		<programlisting xml:lang="en"><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of
cells merged into one. The other cells are normal.<tag class="endtag">p</tag>		cells merged into one. The other cells are normal.<tag class="endtag">p</tag>

<tag class="starttag">table</tag>		<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>		<tag class="starttag">tr</tag>
<tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag>		<tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag>

Show All 16 Lines	<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>		<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>		<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>		<tag class="endtag">table</tag></programlisting>
</example>		</example>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="xhtml-markup-inline-elements">		<sect1 xml:id="xhtml-markup-inline-elements">
<title xml:lang="en">In-line Elements</title>		<title>行內元素</title>

<sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">		<sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">
<title xml:lang="en">Emphasizing Information</title>		<title>強調資訊</title>

<para xml:lang="en">Two levels of emphasis are available in		<para xml:lang="en">Two levels of emphasis are available in
<acronym>XHTML</acronym>, <tag>em</tag> and		<acronym>XHTML</acronym>, <tag>em</tag> and
<tag>strong</tag>. <tag>em</tag> is for a		<tag>strong</tag>. <tag>em</tag> is for a
normal level of emphasis and <tag>strong</tag>		normal level of emphasis and <tag>strong</tag>
indicates stronger emphasis.</para>		indicates stronger emphasis.</para>

<para xml:lang="en"><tag>em</tag> is typically rendered in italic		<para xml:lang="en"><tag>em</tag> is typically rendered in italic
and <tag>strong</tag> is rendered in bold. This is		and <tag>strong</tag> is rendered in bold. This is
not always the case, and should not be relied upon. According		not always the case, and should not be relied upon. According
to best practices, web pages only hold structural and		to best practices, web pages only hold structural and
semantical information, and stylesheets are later applied to		semantical information, and stylesheets are later applied to
them. Think of semantics, not formatting, when using these		them. Think of semantics, not formatting, when using these
tags.</para>		tags.</para>

<example>		<example>
<title xml:lang="en"><tag>em</tag> and		<title><tag>em</tag> 與 <tag>strong</tag> 範例</title>
<tag>strong</tag> Example</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while		<programlisting xml:lang="en"><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while
<tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting>		<tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text">		<sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text">
<title xml:lang="en">Indicating Fixed-Pitch Text</title>		<title>標示等寬文字</title>

<para xml:lang="en">Content that should be rendered in a fixed pitch		<para xml:lang="en">Content that should be rendered in a fixed pitch
(typewriter) typeface is tagged with <tag>tt</tag>		(typewriter) typeface is tagged with <tag>tt</tag>
(for <quote>teletype</quote>).</para>		(for <quote>teletype</quote>).</para>

<example>		<example>
<title xml:lang="en"><tag>tt</tag> Example</title>		<title><tag>tt</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>Many system settings are stored in		<programlisting xml:lang="en"><tag class="starttag">p</tag>Many system settings are stored in
<tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>		<tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="xhtml-markup-inline-elements-links">		<sect2 xml:id="xhtml-markup-inline-elements-links">
<title xml:lang="en">Links</title>		<title>連結</title>

<note>		<note>
<para xml:lang="en">Links are also inline elements.</para>		<para xml:lang="en">Links are also inline elements.</para>
</note>		</note>

<sect3 xml:id="xhtml-markup-inline-elements-linking">		<sect3 xml:id="xhtml-markup-inline-elements-linking">
<title xml:lang="en">Linking to Other Documents on the Web</title>		<title>連結在網站上的其他文件</title>

<para xml:lang="en">A link points to the <acronym>URL</acronym> of a		<para xml:lang="en">A link points to the <acronym>URL</acronym> of a
document on the web. The link is indicated with		document on the web. The link is indicated with
<tag>a</tag>, and the		<tag>a</tag>, and the
<tag class="attribute">href</tag> attribute contains		<tag class="attribute">href</tag> attribute contains
the <acronym>URL</acronym> of the target document. The		the <acronym>URL</acronym> of the target document. The
content of the element becomes the link, indicated to the		content of the element becomes the link, indicated to the
user by showing it in a different color or with an		user by showing it in a different color or with an
underline.</para>		underline.</para>

<example>		<example>
<title xml:lang="en">Using		<title>使用 <tag class="starttag">a href="..."</tag></title>
<tag class="starttag">a href="..."</tag></title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>More information is available at the		<programlisting xml:lang="en"><tag class="starttag">p</tag>More information is available at the
<tag class="starttag">a href="http://www.&os;.org/"</tag>&os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting>		<tag class="starttag">a href="http://www.&os;.org/"</tag>&os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">This link always takes the user to the top of the linked		<para xml:lang="en">This link always takes the user to the top of the linked
document.</para>		document.</para>
</sect3>		</sect3>

<sect3 xml:id="xhtml-markup-inline-elements-specific-parts">		<sect3 xml:id="xhtml-markup-inline-elements-specific-parts">
<title xml:lang="en">Linking to Specific Parts of Documents</title>		<title>連結說明文件的特定章節</title>

<para xml:lang="en">To link to a specific point within a document, that		<para xml:lang="en">To link to a specific point within a document, that
document must include an <emphasis>anchor</emphasis> at the		document must include an <emphasis>anchor</emphasis> at the
desired point. Anchors are included by setting the		desired point. Anchors are included by setting the
<tag class="attribute">id</tag> attribute of an		<tag class="attribute">id</tag> attribute of an
element to a name. This example creates an anchor by		element to a name. This example creates an anchor by
setting the <tag class="attribute">id</tag>		setting the <tag class="attribute">id</tag>
attribute of a <tag class="element">p</tag>		attribute of a <tag class="element">p</tag>
element.</para>		element.</para>

<example>		<example>
<title xml:lang="en">Creating an Anchor</title>		<title>建立錨點</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced		<programlisting xml:lang="en"><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced
in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>		in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">Links to anchors are similar to plain links, but include		<para xml:lang="en">Links to anchors are similar to plain links, but include
a <literal>#</literal> symbol and the anchor's		a <literal>#</literal> symbol and the anchor's
<acronym>ID</acronym> at the end of the		<acronym>ID</acronym> at the end of the
<acronym>URL</acronym>.</para>		<acronym>URL</acronym>.</para>

<example>		<example>
<title xml:lang="en">Linking to a Named Part of a Different		<title>連結到另一份文件中已命名的段落</title>
Document</title>

<para xml:lang="en">The <literal>samplepara</literal> example is part of a		<para xml:lang="en">The <literal>samplepara</literal> example is part of a
document called <filename>foo.html</filename>. A link to		document called <filename>foo.html</filename>. A link to
that specific paragraph in the document is constructed in		that specific paragraph in the document is constructed in
this example.</para>		this example.</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>More information can be found in the		<programlisting xml:lang="en"><tag class="starttag">p</tag>More information can be found in the
<tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of		<tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of
<tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>		<tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>		</example>

<para xml:lang="en">To link to a named anchor within the same document, omit		<para xml:lang="en">To link to a named anchor within the same document, omit
the document's <acronym>URL</acronym>, and just use the		the document's <acronym>URL</acronym>, and just use the
<literal>#</literal> symbol followed by the name of the		<literal>#</literal> symbol followed by the name of the
anchor.</para>		anchor.</para>

<example>		<example>
<title xml:lang="en">Linking to a Named Part of the Same Document</title>		<title>連結到同一份文件已命名的段茖</title>

<para xml:lang="en">The <literal>samplepara</literal> example		<para xml:lang="en">The <literal>samplepara</literal> example
resides in this document. To link to it:</para>		resides in this document. To link to it:</para>

<programlisting xml:lang="en"><tag class="starttag">p</tag>More information can be found in the		<programlisting xml:lang="en"><tag class="starttag">p</tag>More information can be found in the
<tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this		<tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this
document.<tag class="endtag">p</tag></programlisting>		document.<tag class="endtag">p</tag></programlisting>
</example>		</example>
Show All 32 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->

<chapter version="5.0" xml:id="docbook-markup">		<chapter version="5.0" xml:id="docbook-markup">

<title xml:lang="en">DocBook Markup</title>		<title>DocBook 標籤</title>

<sect1 xml:id="docbook-markup-introduction">		<sect1 xml:id="docbook-markup-introduction">
<title xml:lang="en">Introduction</title>		<title>簡介</title>

<para xml:lang="en">This chapter is an introduction to DocBook as it is used for		<para xml:lang="en">This chapter is an introduction to DocBook as it is used for
FreeBSD documentation. DocBook is a large and complex markup		FreeBSD documentation. DocBook is a large and complex markup
system, but the subset described here covers the parts that are		system, but the subset described here covers the parts that are
most widely used for FreeBSD documentation. While a moderate		most widely used for FreeBSD documentation. While a moderate
subset is covered, it is impossible to anticipate every		subset is covered, it is impossible to anticipate every
situation. Please post questions that this document does		situation. Please post questions that this document does
not answer to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>		not answer to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
Show All 34 Lines	<chapter version="5.0" xml:id="docbook-markup">
can occur within a block element, and does not cause a line		can occur within a block element, and does not cause a line
break. A <emphasis>block</emphasis> element, by comparison,		break. A <emphasis>block</emphasis> element, by comparison,
will cause a line break (and other processing) when it is		will cause a line break (and other processing) when it is
encountered.</para>		encountered.</para>
</note>		</note>
</sect1>		</sect1>

<sect1 xml:id="docbook-markup-freebsd-extensions">		<sect1 xml:id="docbook-markup-freebsd-extensions">
<title xml:lang="en">FreeBSD Extensions</title>		<title>FreeBSD 擴充項目</title>

<para xml:lang="en">The FreeBSD Documentation Project has extended the DocBook		<para xml:lang="en">The FreeBSD Documentation Project has extended the DocBook
<acronym>DTD</acronym> with additional elements and entities.		<acronym>DTD</acronym> with additional elements and entities.
These additions serve to make some of the markup easier or more		These additions serve to make some of the markup easier or more
precise.</para>		precise.</para>

<para xml:lang="en">Throughout the rest of this document, the term		<para xml:lang="en">Throughout the rest of this document, the term
<quote>DocBook</quote> is used to mean the FreeBSD-extended		<quote>DocBook</quote> is used to mean the FreeBSD-extended
DocBook <acronym>DTD</acronym>.</para>		DocBook <acronym>DTD</acronym>.</para>

<note>		<note>
<para xml:lang="en">Most of these extensions are not unique to FreeBSD, it was		<para xml:lang="en">Most of these extensions are not unique to FreeBSD, it was
just felt that they were useful enhancements for this		just felt that they were useful enhancements for this
particular project. Should anyone from any of the other *nix		particular project. Should anyone from any of the other *nix
camps (NetBSD, OpenBSD, Linux, …) be interested in		camps (NetBSD, OpenBSD, Linux, …) be interested in
collaborating on a standard DocBook extension set, please		collaborating on a standard DocBook extension set, please
contact Documentation Engineering Team <email>doceng@FreeBSD.org</email>.</para>		contact Documentation Engineering Team <email>doceng@FreeBSD.org</email>.</para>
</note>		</note>

<sect2 xml:id="docbook-markup-freebsd-extensions-elements">		<sect2 xml:id="docbook-markup-freebsd-extensions-elements">
<title xml:lang="en">FreeBSD Elements</title>		<title>FreeBSD 元素</title>

<para xml:lang="en">The additional FreeBSD elements are not (currently) in the		<para xml:lang="en">The additional FreeBSD elements are not (currently) in the
Ports Collection. They are stored in the FreeBSD Subversion		Ports Collection. They are stored in the FreeBSD Subversion
tree, as <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para>		tree, as <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para>

<para xml:lang="en">FreeBSD-specific elements used in the examples below are		<para xml:lang="en">FreeBSD-specific elements used in the examples below are
clearly marked.</para>		clearly marked.</para>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-freebsd-extensions-entities">		<sect2 xml:id="docbook-markup-freebsd-extensions-entities">
<title xml:lang="en">FreeBSD Entities</title>		<title>FreeBSD Entities</title>

<para xml:lang="en">This table shows some of the most useful entities		<para xml:lang="en">This table shows some of the most useful entities
available in the <acronym>FDP</acronym>. For a complete list,		available in the <acronym>FDP</acronym>. For a complete list,
see the <filename>*.ent</filename> files in		see the <filename>*.ent</filename> files in
<filename>doc/share/xml</filename>.</para>		<filename>doc/share/xml</filename>.</para>

<informaltable frame="none" pgwide="1">		<informaltable frame="none" pgwide="1">
<tgroup cols="3">		<tgroup cols="3">
▲ Show 20 Lines • Show All 223 Lines • ▼ Show 20 Lines	Window System.</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="docbook-markup-fpi">		<sect1 xml:id="docbook-markup-fpi">
<title xml:lang="en">Formal Public Identifier (FPI)</title>		<title>正式公用識別碼 (FPI)</title>

<para xml:lang="en">In compliance with the DocBook guidelines for writing		<para xml:lang="en">In compliance with the DocBook guidelines for writing
<acronym>FPI</acronym>s for DocBook customizations, the		<acronym>FPI</acronym>s for DocBook customizations, the
<acronym>FPI</acronym> for the FreeBSD extended DocBook		<acronym>FPI</acronym> for the FreeBSD extended DocBook
<acronym>DTD</acronym> is:</para>		<acronym>DTD</acronym> is:</para>

<programlisting xml:lang="en">PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>		<programlisting xml:lang="en">PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
</sect1>		</sect1>

<sect1 xml:id="docbook-markup-document-structure">		<sect1 xml:id="docbook-markup-document-structure">
<title xml:lang="en">Document Structure</title>		<title>文件結構</title>

<para xml:lang="en">DocBook allows structuring documentation in several ways.		<para xml:lang="en">DocBook allows structuring documentation in several ways.
The FreeBSD Documentation Project uses two primary types of DocBook		The FreeBSD Documentation Project uses two primary types of DocBook
document: the book and the article.</para>		document: the book and the article.</para>

<para xml:lang="en">Books are organized into <tag>chapter</tag>s.		<para xml:lang="en">Books are organized into <tag>chapter</tag>s.
This is a mandatory requirement. There may be		This is a mandatory requirement. There may be
<tag>part</tag>s between the book and the chapter to		<tag>part</tag>s between the book and the chapter to
Show All 26 Lines	<sect1 xml:id="docbook-markup-document-structure">

<para xml:lang="en">The <link xlink:href="@@URL_RELPREFIX@@/docs.html">FreeBSD		<para xml:lang="en">The <link xlink:href="@@URL_RELPREFIX@@/docs.html">FreeBSD
tutorials</link> are all marked up as articles, while this		tutorials</link> are all marked up as articles, while this
document, the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/index.html">FAQ</link>,		document, the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/index.html">FAQ</link>,
and the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">Handbook</link> are all marked up as books, for		and the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">Handbook</link> are all marked up as books, for
example.</para>		example.</para>

<sect2 xml:id="docbook-markup-starting-a-book">		<sect2 xml:id="docbook-markup-starting-a-book">
<title xml:lang="en">Starting a Book</title>		<title>開始撰寫書籍</title>

<para xml:lang="en">The content of a book is contained within the		<para xml:lang="en">The content of a book is contained within the
<tag>book</tag> element. As well as containing		<tag>book</tag> element. As well as containing
structural markup, this element can contain elements that		structural markup, this element can contain elements that
include additional information about the book. This is either		include additional information about the book. This is either
meta-information, used for reference purposes, or additional		meta-information, used for reference purposes, or additional
content used to produce a title page.</para>		content used to produce a title page.</para>

<para xml:lang="en">This additional information is contained within		<para xml:lang="en">This additional information is contained within
<tag>info</tag>.</para>		<tag>info</tag>.</para>

<example>		<example>
<title xml:lang="en">Boilerplate <tag>book</tag> with		<title>使用 <tag>info</tag> 的 <tag>book</tag> 樣板</title>
<tag>info</tag></title>

<!-- Cannot put this in a marked section because of the		<!-- Cannot put this in a marked section because of the
replaceable elements -->		replaceable elements -->

<programlisting><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"		<programlisting xml:lang="en"><tag class="starttag">book</tag>
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

<tag class="starttag">article xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:lang="en"</tag>

<tag class="starttag">info</tag>		<tag class="starttag">info</tag>
<tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag>		<tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag>

<tag class="starttag">author</tag>		<tag class="starttag">author</tag>
<tag class="starttag">personname</tag>		<tag class="starttag">personname</tag>
<tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>		<tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
<tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>		<tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
<tag class="endtag">personname</tag>		<tag class="endtag">personname</tag>

<tag class="starttag">affiliation</tag>		<tag class="starttag">affiliation</tag>
<tag class="starttag">address</tag>		<tag class="starttag">address</tag>
<tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>		<tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag>
<tag class="endtag">address</tag>		<tag class="endtag">address</tag>
<tag class="endtag">affiliation</tag>		<tag class="endtag">affiliation</tag>
<tag class="endtag">author</tag>		<tag class="endtag">author</tag>

<tag class="starttag">copyright</tag>		<tag class="starttag">copyright</tag>
<tag class="starttag">year</tag>2000<tag class="endtag">year</tag>		<tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag>
<tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>		<tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag>
<tag class="endtag">copyright</tag>		<tag class="endtag">copyright</tag>

		<tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag>

<tag class="starttag">abstract</tag>		<tag class="starttag">abstract</tag>
<tag class="starttag">para</tag>If your article has an abstract then it should go here。<tag class="endtag">para</tag>		<tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag>
<tag class="endtag">abstract</tag>		<tag class="endtag">abstract</tag>
<tag class="endtag">info</tag>		<tag class="endtag">info</tag>

<tag class="starttag">sect1</tag>		…
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>

<tag class="starttag">para</tag>This is the first section in my article。<tag class="endtag">para</tag>		<tag class="endtag">book</tag></programlisting>

<tag class="starttag">sect2</tag>
<tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag>

<tag class="starttag">para</tag>This is the first sub-section in my article。<tag class="endtag">para</tag>
<tag class="endtag">sect2</tag>
<tag class="endtag">sect1</tag>
<tag class="endtag">article</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-starting-an-article">		<sect2 xml:id="docbook-markup-starting-an-article">
<title xml:lang="en">Starting an Article</title>		<title>開始撰寫文章</title>

<para xml:lang="en">The content of the article is contained within the		<para xml:lang="en">The content of the article is contained within the
<tag>article</tag> element. As well as containing		<tag>article</tag> element. As well as containing
structural markup, this element can contain elements that		structural markup, this element can contain elements that
include additional information about the article. This is		include additional information about the article. This is
either meta-information, used for reference purposes, or		either meta-information, used for reference purposes, or
additional content used to produce a title page.</para>		additional content used to produce a title page.</para>

<para xml:lang="en">This additional information is contained within		<para xml:lang="en">This additional information is contained within
<tag>info</tag>.</para>		<tag>info</tag>.</para>

<example>		<example>
<title xml:lang="en">Boilerplate <tag>article</tag> with		<title>使用 <tag>info</tag> 的 <tag>article</tag> 樣板</title>
<tag>info</tag></title>

<!-- Cannot put this in a marked section because of the		<!-- Cannot put this in a marked section because of the
replaceable elements -->		replaceable elements -->

<programlisting><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"		<programlisting xml:lang="en"><tag class="starttag">article</tag>
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

<tag class="starttag">article xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:lang="en"</tag>

<tag class="starttag">info</tag>		<tag class="starttag">info</tag>
<tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag>		<tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag>

<tag class="starttag">author</tag>		<tag class="starttag">author</tag>
<tag class="starttag">personname</tag>		<tag class="starttag">personname</tag>
<tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>		<tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
<tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>		<tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
<tag class="endtag">personname</tag>		<tag class="endtag">personname</tag>

<tag class="starttag">affiliation</tag>		<tag class="starttag">affiliation</tag>
<tag class="starttag">address</tag>		<tag class="starttag">address</tag>
<tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>		<tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag>
<tag class="endtag">address</tag>		<tag class="endtag">address</tag>
<tag class="endtag">affiliation</tag>		<tag class="endtag">affiliation</tag>
<tag class="endtag">author</tag>		<tag class="endtag">author</tag>

<tag class="starttag">copyright</tag>		<tag class="starttag">copyright</tag>
<tag class="starttag">year</tag>2000<tag class="endtag">year</tag>		<tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag>
<tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>		<tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag>
<tag class="endtag">copyright</tag>		<tag class="endtag">copyright</tag>

		<tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag>

<tag class="starttag">abstract</tag>		<tag class="starttag">abstract</tag>
<tag class="starttag">para</tag>If your article has an abstract then it should go here。<tag class="endtag">para</tag>		<tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag>
<tag class="endtag">abstract</tag>		<tag class="endtag">abstract</tag>
<tag class="endtag">info</tag>		<tag class="endtag">info</tag>

<tag class="starttag">sect1</tag>		…
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>

<tag class="starttag">para</tag>This is the first section in my article。<tag class="endtag">para</tag>

<tag class="starttag">sect2</tag>
<tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag>

<tag class="starttag">para</tag>This is the first sub-section in my article。<tag class="endtag">para</tag>
<tag class="endtag">sect2</tag>
<tag class="endtag">sect1</tag>
<tag class="endtag">article</tag></programlisting>		<tag class="endtag">article</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-indicating-chapters">		<sect2 xml:id="docbook-markup-indicating-chapters">
<title xml:lang="en">Indicating Chapters</title>		<title>標示章節</title>

<para xml:lang="en">Use <tag>chapter</tag> to mark up your chapters.		<para xml:lang="en">Use <tag>chapter</tag> to mark up your chapters.
Each chapter has a mandatory <tag>title</tag>.		Each chapter has a mandatory <tag>title</tag>.
Articles do not contain chapters, they are reserved for		Articles do not contain chapters, they are reserved for
books.</para>		books.</para>

<example>		<example>
<title xml:lang="en">A Simple Chapter</title>		<title>簡單的章節</title>

<programlisting xml:lang="en"><tag class="starttag">chapter</tag>		<programlisting xml:lang="en"><tag class="starttag">chapter</tag>
<tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag>		<tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag>

...		...
<tag class="endtag">chapter</tag></programlisting>		<tag class="endtag">chapter</tag></programlisting>
</example>		</example>

<para xml:lang="en">A chapter cannot be empty; it must contain elements in		<para xml:lang="en">A chapter cannot be empty; it must contain elements in
addition to <tag>title</tag>. If you need to		addition to <tag>title</tag>. If you need to
include an empty chapter then just use an empty		include an empty chapter then just use an empty
paragraph.</para>		paragraph.</para>

<example>		<example>
<title xml:lang="en">Empty Chapters</title>		<title>空白章節</title>

<programlisting xml:lang="en"><tag class="starttag">chapter</tag>		<programlisting xml:lang="en"><tag class="starttag">chapter</tag>
<tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag>		<tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag>

<tag class="starttag">para</tag><tag class="endtag">para</tag>		<tag class="starttag">para</tag><tag class="endtag">para</tag>
<tag class="endtag">chapter</tag></programlisting>		<tag class="endtag">chapter</tag></programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-sections-below-chapters">		<sect2 xml:id="docbook-markup-sections-below-chapters">
<title xml:lang="en">Sections Below Chapters</title>		<title>章底下的小節</title>

<para xml:lang="en">In books, chapters may (but do not need to) be broken up		<para xml:lang="en">In books, chapters may (but do not need to) be broken up
into sections, subsections, and so on. In articles, sections		into sections, subsections, and so on. In articles, sections
are the main structural element, and each article must contain		are the main structural element, and each article must contain
at least one section. Use the		at least one section. Use the
<tag>sect<replaceable>n</replaceable></tag> element.		<tag>sect<replaceable>n</replaceable></tag> element.
The <replaceable>n</replaceable> indicates the section number,		The <replaceable>n</replaceable> indicates the section number,
which identifies the section level.</para>		which identifies the section level.</para>

<para xml:lang="en">The first		<para xml:lang="en">The first
<tag>sect<replaceable>n</replaceable></tag> is		<tag>sect<replaceable>n</replaceable></tag> is
<tag>sect1</tag>. You can have one or more of these		<tag>sect1</tag>. You can have one or more of these
in a chapter. They can contain one or more		in a chapter. They can contain one or more
<tag>sect2</tag> elements, and so on, down to		<tag>sect2</tag> elements, and so on, down to
<tag>sect5</tag>.</para>		<tag>sect5</tag>.</para>

<example>		<example>
<title xml:lang="en">Sections in Chapters</title>		<title>章中的小節</title>

<programlisting xml:lang="en"><tag class="starttag">chapter</tag>		<programlisting xml:lang="en"><tag class="starttag">chapter</tag>
<tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag>		<tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag>

<tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag>

<tag class="starttag">sect1</tag>		<tag class="starttag">sect1</tag>
<tag class="starttag">title</tag>First Section<tag class="endtag">title</tag>		<tag class="starttag">title</tag>First Section<tag class="endtag">title</tag>
▲ Show 20 Lines • Show All 49 Lines • ▼ Show 20 Lines	<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en">1.2.2. Second Sub-Section</para>		<para xml:lang="en">1.2.2. Second Sub-Section</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-subdividing-part">		<sect2 xml:id="docbook-markup-subdividing-part">
<title xml:lang="en">Subdividing Using <tag>part</tag>		<title>使用 <tag>part</tag> 元素來分部</title>
Elements</title>

<para xml:lang="en"><tag>part</tag>s introduce another level of		<para xml:lang="en"><tag>part</tag>s introduce another level of
organization between <tag>book</tag> and		organization between <tag>book</tag> and
<tag>chapter</tag> with one or more		<tag>chapter</tag> with one or more
<tag>part</tag>s. This cannot be done in an		<tag>part</tag>s. This cannot be done in an
<tag>article</tag>.</para>		<tag>article</tag>.</para>

<programlisting xml:lang="en"><tag class="starttag">part</tag>		<programlisting xml:lang="en"><tag class="starttag">part</tag>
Show All 16 Lines	<tag class="starttag">chapter</tag>

...		...
<tag class="endtag">chapter</tag>		<tag class="endtag">chapter</tag>
<tag class="endtag">part</tag></programlisting>		<tag class="endtag">part</tag></programlisting>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="docbook-markup-block-elements">		<sect1 xml:id="docbook-markup-block-elements">
<title xml:lang="en">Block Elements</title>		<title>區塊元素</title>

<sect2 xml:id="docbook-markup-paragraphs">		<sect2 xml:id="docbook-markup-paragraphs">
<title xml:lang="en">Paragraphs</title>		<title>段落</title>

<para xml:lang="en">DocBook supports three types of paragraphs:		<para xml:lang="en">DocBook supports three types of paragraphs:
<tag>formalpara</tag>, <tag>para</tag>, and		<tag>formalpara</tag>, <tag>para</tag>, and
<tag>simpara</tag>.</para>		<tag>simpara</tag>.</para>

<para xml:lang="en">Almost all paragraphs in FreeBSD documentation use		<para xml:lang="en">Almost all paragraphs in FreeBSD documentation use
<tag>para</tag>. <tag>formalpara</tag>		<tag>para</tag>. <tag>formalpara</tag>
includes a <tag>title</tag> element, and		includes a <tag>title</tag> element, and
<tag>simpara</tag> disallows some elements from		<tag>simpara</tag> disallows some elements from
within <tag>para</tag>. Stick with		within <tag>para</tag>. Stick with
<tag>para</tag>.</para>		<tag>para</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>para</tag> Example</title>		<title><tag>para</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>This is a paragraph. It can contain just about any		<programlisting xml:lang="en"><tag class="starttag">para</tag>This is a paragraph. It can contain just about any
other element.<tag class="endtag">para</tag></programlisting>		other element.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">This is a paragraph. It can contain just about any		<para xml:lang="en">This is a paragraph. It can contain just about any
other element.</para>		other element.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-block-quotations">		<sect2 xml:id="docbook-markup-block-quotations">
<title xml:lang="en">Block Quotations</title>		<title>區塊引言</title>

<para xml:lang="en">A block quotation is an extended quotation from another		<para xml:lang="en">A block quotation is an extended quotation from another
document that should not appear within the current paragraph.		document that should not appear within the current paragraph.
These are rarely needed.</para>		These are rarely needed.</para>

<para xml:lang="en">Blockquotes can optionally contain a title and an		<para xml:lang="en">Blockquotes can optionally contain a title and an
attribution (or they can be left untitled and		attribution (or they can be left untitled and
unattributed).</para>		unattributed).</para>

<example>		<example>
<title xml:lang="en"><tag>blockquote</tag> Example</title>		<title><tag>blockquote</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag>		<programlisting xml:lang="en"><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag>

<tag class="starttag">blockquote</tag>		<tag class="starttag">blockquote</tag>
<tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag>		<tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag>

<tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag>		<tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag>

<tag class="starttag">para</tag>We the People of the United States, in Order to form a more		<tag class="starttag">para</tag>We the People of the United States, in Order to form a more
perfect Union, establish Justice, insure domestic Tranquility,		perfect Union, establish Justice, insure domestic Tranquility,
provide for the common defence, promote the general Welfare, and		provide for the common defence, promote the general Welfare, and
secure the Blessings of Liberty to ourselves and our Posterity, do		secure the Blessings of Liberty to ourselves and our Posterity, do
ordain and establish this Constitution for the United States of		ordain and establish this Constitution for the United States of
America.<tag class="endtag">para</tag>		America.<tag class="endtag">para</tag>
<tag class="endtag">blockquote</tag></programlisting>		<tag class="endtag">blockquote</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">A small excerpt from the US Constitution:</para>		<para xml:lang="en">A small excerpt from the US Constitution:</para>

<blockquote>		<blockquote>
<title xml:lang="en">Preamble to the Constitution of the United		<title xml:lang="en">Preamble to the Constitution of the United
States</title>		States</title>

<attribution xml:lang="en">Copied from a web site		<attribution xml:lang="en">Copied from a web site
somewhere</attribution>		somewhere</attribution>

<para xml:lang="en">We the People of the United States, in Order to form		<para xml:lang="en">We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic		a more perfect Union, establish Justice, insure domestic
Tranquility, provide for the common defence, promote the		Tranquility, provide for the common defence, promote the
general Welfare, and secure the Blessings of Liberty to		general Welfare, and secure the Blessings of Liberty to
ourselves and our Posterity, do ordain and establish		ourselves and our Posterity, do ordain and establish
this Constitution for the United States of		this Constitution for the United States of
America.</para>		America.</para>
</blockquote>		</blockquote>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-tips-notes">		<sect2 xml:id="docbook-markup-tips-notes">
<title xml:lang="en">Tips, Notes, Warnings, Cautions, and Important		<title>提示、注意、警告、注意事項及重要資訊</title>
Information</title>

<para xml:lang="en">Extra information may need to be separated from		<para xml:lang="en">Extra information may need to be separated from
the main body of the text. Typically this is		the main body of the text. Typically this is
<quote>meta</quote> information of which the user should be		<quote>meta</quote> information of which the user should be
aware.</para>		aware.</para>

<para xml:lang="en">Several types of admonitions are available:		<para xml:lang="en">Several types of admonitions are available:
<tag>tip</tag>, <tag>note</tag>,		<tag>tip</tag>, <tag>note</tag>,
Show All 21 Lines	<tag class="endtag">blockquote</tag></programlisting>

<listitem>		<listitem>
<para xml:lang="en">Warning is for information regarding possible		<para xml:lang="en">Warning is for information regarding possible
hardware damage or injury to life or limb.</para>		hardware damage or injury to life or limb.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

<example>		<example>
<title xml:lang="en"><tag>tip</tag> and <tag>important</tag> Example</title>		<title><tag>tip</tag> 與 <tag>important</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">tip</tag>		<programlisting xml:lang="en"><tag class="starttag">tip</tag>
<tag class="starttag">para</tag>&os; may reduce stress.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>&os; may reduce stress.<tag class="endtag">para</tag>
<tag class="endtag">tip</tag>		<tag class="endtag">tip</tag>

<tag class="starttag">important</tag>		<tag class="starttag">important</tag>
<tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions		<tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions
are visually jarring and can have the opposite of the		are visually jarring and can have the opposite of the
intended effect.<tag class="endtag">para</tag>		intended effect.<tag class="endtag">para</tag>
<tag class="endtag">important</tag></programlisting>		<tag class="endtag">important</tag></programlisting>
</example>		</example>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>
<!-- Need to do this outside of the example -->		<!-- Need to do this outside of the example -->
<tip>		<tip>
<para xml:lang="en">FreeBSD may reduce stress.</para>		<para xml:lang="en">FreeBSD may reduce stress.</para>
</tip>		</tip>

<important>		<important>
<para xml:lang="en">Please use admonitions sparingly. Too many admonitions		<para xml:lang="en">Please use admonitions sparingly. Too many admonitions
are visually jarring and can have the opposite of the		are visually jarring and can have the opposite of the
intended effect.</para>		intended effect.</para>
</important>		</important>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-example">		<sect2 xml:id="docbook-markup-example">
<title>舉例</title>		<title>範例</title>

<para xml:lang="en">Examples can be shown with <tag>example</tag>.</para>		<para xml:lang="en">Examples can be shown with <tag>example</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>example</tag> Source</title>		<title><tag>example</tag> 原始碼</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">example</tag>		<programlisting xml:lang="en"><tag class="starttag">example</tag>
<tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag>		<tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag>

<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag>		<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag>
<tag class="endtag">example</tag></programlisting>		<tag class="endtag">example</tag></programlisting>
</example>		</example>

<!-- Need to do this outside of the example -->		<!-- Need to do this outside of the example -->
<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<example>		<example>
<title xml:lang="en">Rendered <tag>example</tag></title>		<title><tag>example</tag> 的結果</title>

<para xml:lang="en">Empty files can be created easily:</para>		<para xml:lang="en">Empty files can be created easily:</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>touch file1 file2 file3</userinput></screen>		<screen xml:lang="en"><prompt>%</prompt> <userinput>touch file1 file2 file3</userinput></screen>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-lists-and-procedures">		<sect2 xml:id="docbook-markup-lists-and-procedures">
<title xml:lang="en">Lists and Procedures</title>		<title>清單與步驟</title>

<para xml:lang="en">Information often needs to be presented as lists, or as a		<para xml:lang="en">Information often needs to be presented as lists, or as a
number of steps that must be carried out in order to		number of steps that must be carried out in order to
accomplish a particular goal.</para>		accomplish a particular goal.</para>

<para xml:lang="en">To do this, use <tag>itemizedlist</tag>,		<para xml:lang="en">To do this, use <tag>itemizedlist</tag>,
<tag>orderedlist</tag>, <tag>variablelist</tag>, or		<tag>orderedlist</tag>, <tag>variablelist</tag>, or
<tag>procedure</tag>. There are other types of list		<tag>procedure</tag>. There are other types of list
elements in DocBook, but we will not cover them here.</para>		elements in DocBook, but we will not cover them here.</para>

<para xml:lang="en"><tag>itemizedlist</tag> and		<para xml:lang="en"><tag>itemizedlist</tag> and
<tag>orderedlist</tag> are similar to their		<tag>orderedlist</tag> are similar to their
counterparts in <acronym>HTML</acronym>, <tag>ul</tag>		counterparts in <acronym>HTML</acronym>, <tag>ul</tag>
and <tag>ol</tag>. Each one consists of one or more		and <tag>ol</tag>. Each one consists of one or more
<tag>listitem</tag> elements, and each		<tag>listitem</tag> elements, and each
<tag>listitem</tag> contains one or more block		<tag>listitem</tag> contains one or more block
elements. The <tag>listitem</tag> elements are		elements. The <tag>listitem</tag> elements are
analogous to <acronym>HTML</acronym>'s <tag>li</tag>		analogous to <acronym>HTML</acronym>'s <tag>li</tag>
tags. However, unlike HTML, they are required.</para>		tags. However, unlike HTML, they are required.</para>

<example>		<example>
<title xml:lang="en"><tag>itemizedlist</tag> and		<title><tag>itemizedlist</tag> 與 <tag>orderedlist</tag> 範例</title>
<tag>orderedlist</tag> Example</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">itemizedlist</tag>		<programlisting xml:lang="en"><tag class="starttag">itemizedlist</tag>
<tag class="starttag">listitem</tag>		<tag class="starttag">listitem</tag>
<tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag>
<tag class="endtag">listitem</tag>		<tag class="endtag">listitem</tag>

<tag class="starttag">listitem</tag>		<tag class="starttag">listitem</tag>
<tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag>
<tag class="endtag">listitem</tag>		<tag class="endtag">listitem</tag>
<tag class="endtag">itemizedlist</tag>		<tag class="endtag">itemizedlist</tag>

<tag class="starttag">orderedlist</tag>		<tag class="starttag">orderedlist</tag>
<tag class="starttag">listitem</tag>		<tag class="starttag">listitem</tag>
<tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag>
<tag class="endtag">listitem</tag>		<tag class="endtag">listitem</tag>

<tag class="starttag">listitem</tag>		<tag class="starttag">listitem</tag>
<tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag>
<tag class="endtag">listitem</tag>		<tag class="endtag">listitem</tag>
<tag class="endtag">orderedlist</tag></programlisting>		<tag class="endtag">orderedlist</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en">This is the first itemized item.</para>		<para xml:lang="en">This is the first itemized item.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en">This is the second itemized item.</para>		<para xml:lang="en">This is the second itemized item.</para>
Show All 19 Lines	<tag class="endtag">orderedlist</tag></programlisting>
often easier for the reader than sections and		often easier for the reader than sections and
subsections.</para>		subsections.</para>

<para xml:lang="en">A <tag>variablelist</tag> has a <tag>title</tag>, and then		<para xml:lang="en">A <tag>variablelist</tag> has a <tag>title</tag>, and then
pairs of <tag>term</tag> and <tag>listitem</tag>		pairs of <tag>term</tag> and <tag>listitem</tag>
entries.</para>		entries.</para>

<example xml:id="docbook-markup-variablelist-example">		<example xml:id="docbook-markup-variablelist-example">
<title xml:lang="en"><tag>variablelist</tag> Example</title>		<title><tag>variablelist</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">variablelist</tag>		<programlisting xml:lang="en"><tag class="starttag">variablelist</tag>
<tag class="starttag">varlistentry</tag>		<tag class="starttag">varlistentry</tag>
<tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag>		<tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag>

<tag class="starttag">listitem</tag>		<tag class="starttag">listitem</tag>
<tag class="starttag">para</tag>In parallel communications, groups of bits arrive		<tag class="starttag">para</tag>In parallel communications, groups of bits arrive
at the same time over multiple communications		at the same time over multiple communications
channels.<tag class="endtag">para</tag>		channels.<tag class="endtag">para</tag>
<tag class="endtag">listitem</tag>		<tag class="endtag">listitem</tag>
<tag class="endtag">varlistentry</tag>		<tag class="endtag">varlistentry</tag>

<tag class="starttag">varlistentry</tag>		<tag class="starttag">varlistentry</tag>
<tag class="starttag">term</tag>Serial<tag class="endtag">term</tag>		<tag class="starttag">term</tag>Serial<tag class="endtag">term</tag>

<tag class="starttag">listitem</tag>		<tag class="starttag">listitem</tag>
<tag class="starttag">para</tag>In serial communications, bits arrive one at a		<tag class="starttag">para</tag>In serial communications, bits arrive one at a
time over a single communications		time over a single communications
channel.<tag class="endtag">para</tag>		channel.<tag class="endtag">para</tag>
<tag class="endtag">listitem</tag>		<tag class="endtag">listitem</tag>
<tag class="endtag">varlistentry</tag>		<tag class="endtag">varlistentry</tag>
<tag class="endtag">variablelist</tag></programlisting>		<tag class="endtag">variablelist</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<variablelist>		<variablelist>
<varlistentry>		<varlistentry>
<term xml:lang="en">Parallel</term>		<term xml:lang="en">Parallel</term>

<listitem>		<listitem>
<para xml:lang="en">In parallel communications, groups of bits arrive		<para xml:lang="en">In parallel communications, groups of bits arrive
at the same time over multiple communications		at the same time over multiple communications
Show All 19 Lines	<tag class="endtag">variablelist</tag></programlisting>
contains block elements and may include an optional title.</para>		contains block elements and may include an optional title.</para>

<para xml:lang="en">Sometimes, steps are not sequential, but present a choice:		<para xml:lang="en">Sometimes, steps are not sequential, but present a choice:
do <emphasis>this</emphasis> or do <emphasis>that</emphasis>,		do <emphasis>this</emphasis> or do <emphasis>that</emphasis>,
but not both. For these alternative choices, use		but not both. For these alternative choices, use
<tag>stepalternatives</tag>.</para>		<tag>stepalternatives</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>procedure</tag> Example</title>		<title><tag>procedure</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">procedure</tag>		<programlisting xml:lang="en"><tag class="starttag">procedure</tag>
<tag class="starttag">step</tag>		<tag class="starttag">step</tag>
<tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag>
<tag class="endtag">step</tag>		<tag class="endtag">step</tag>

<tag class="starttag">step</tag>		<tag class="starttag">step</tag>
<tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag>
Show All 13 Lines	<tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag>

<tag class="starttag">step</tag>		<tag class="starttag">step</tag>
<tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag>		<tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag>
<tag class="endtag">step</tag>		<tag class="endtag">step</tag>
<tag class="endtag">stepalternatives</tag>		<tag class="endtag">stepalternatives</tag>
<tag class="endtag">step</tag>		<tag class="endtag">step</tag>
<tag class="endtag">procedure</tag></programlisting>		<tag class="endtag">procedure</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<procedure>		<procedure>
<step>		<step>
<para xml:lang="en">Do this.</para>		<para xml:lang="en">Do this.</para>
</step>		</step>

<step>		<step>
<para xml:lang="en">Then do this.</para>		<para xml:lang="en">Then do this.</para>
Show All 16 Lines	<para xml:lang="en">Go right.</para>
</step>		</step>
</stepalternatives>		</stepalternatives>
</step>		</step>
</procedure>		</procedure>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-showing-file-samples">		<sect2 xml:id="docbook-markup-showing-file-samples">
<title xml:lang="en">Showing File Samples</title>		<title>顯示檔案範本</title>

<para xml:lang="en">Fragments of a file (or perhaps a complete file) are shown		<para xml:lang="en">Fragments of a file (or perhaps a complete file) are shown
by wrapping them in the <tag>programlisting</tag>		by wrapping them in the <tag>programlisting</tag>
element.</para>		element.</para>

<para xml:lang="en">White space and line breaks within		<para xml:lang="en">White space and line breaks within
<tag>programlisting</tag> <emphasis>are</emphasis>		<tag>programlisting</tag> <emphasis>are</emphasis>
significant. In particular, this means that the opening tag		significant. In particular, this means that the opening tag
should appear on the same line as the first line of the		should appear on the same line as the first line of the
output, and the closing tag should appear on the same line		output, and the closing tag should appear on the same line
as the last line of the output, otherwise spurious blank		as the last line of the output, otherwise spurious blank
lines may be included.</para>		lines may be included.</para>

<example>		<example>
<title xml:lang="en"><tag>programlisting</tag> Example</title>		<title><tag>programlisting</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like		<programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like
this:<tag class="endtag">para</tag>		this:<tag class="endtag">para</tag>

<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt;		<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt;

int		int
main(void)		main(void)
{		{
printf("hello, world\n");		printf("hello, world\n");
}<tag class="endtag">programlisting</tag></programlisting>		}<tag class="endtag">programlisting</tag></programlisting>

<para xml:lang="en">Notice how the angle brackets in the		<para xml:lang="en">Notice how the angle brackets in the
<literal>#include</literal> line need to be referenced by		<literal>#include</literal> line need to be referenced by
their entities instead of being included literally.</para>		their entities instead of being included literally.</para>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">When finished, the program will look like this:</para>		<para xml:lang="en">When finished, the program will look like this:</para>

<programlisting xml:lang="en">#include <stdio.h>		<programlisting xml:lang="en">#include <stdio.h>

int		int
main(void)		main(void)
{		{
printf("hello, world\n");		printf("hello, world\n");
}</programlisting>		}</programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-callouts">		<sect2 xml:id="docbook-markup-callouts">
<title xml:lang="en">Callouts</title>		<title>標註</title>

<para xml:lang="en">A callout is a visual marker for referring to a		<para xml:lang="en">A callout is a visual marker for referring to a
piece of text or specific position within an		piece of text or specific position within an
example.</para>		example.</para>

<para xml:lang="en">Callouts are marked with the <tag>co</tag>		<para xml:lang="en">Callouts are marked with the <tag>co</tag>
element. Each element must have a unique		element. Each element must have a unique
<literal>id</literal> assigned to it. After the example,		<literal>id</literal> assigned to it. After the example,
include a <tag>calloutlist</tag> that describes each		include a <tag>calloutlist</tag> that describes each
callout.</para>		callout.</para>

<example>		<example>
<title xml:lang="en"><tag>co</tag> and		<title><tag>co</tag> 與 <tag>calloutlist</tag> 範例</title>
<tag>calloutlist</tag> Example</title>

<programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like		<programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like
this:<tag class="endtag">para</tag>		this:<tag class="endtag">para</tag>

<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co xml:id="co-ex-include"</tag>		<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co xml:id="co-ex-include"</tag>

int <tag class="emptytag">co xml:id="co-ex-return"</tag>		int <tag class="emptytag">co xml:id="co-ex-return"</tag>
main(void)		main(void)
Show All 12 Lines	<tag class="starttag">calloutlist</tag>
<tag class="endtag">callout</tag>		<tag class="endtag">callout</tag>

<tag class="starttag">callout arearefs="co-ex-printf"</tag>		<tag class="starttag">callout arearefs="co-ex-printf"</tag>
<tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes		<tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes
<tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag>		<tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag>
<tag class="endtag">callout</tag>		<tag class="endtag">callout</tag>
<tag class="endtag">calloutlist</tag></programlisting>		<tag class="endtag">calloutlist</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">When finished, the program will look like this:</para>		<para xml:lang="en">When finished, the program will look like this:</para>

<programlisting xml:lang="en">#include <stdio.h> <co xml:id="co-ex-include"/>		<programlisting xml:lang="en">#include <stdio.h> <co xml:id="co-ex-include"/>

int <co xml:id="co-ex-return"/>		int <co xml:id="co-ex-return"/>
main(void)		main(void)
{		{
Show All 15 Lines	<callout arearefs="co-ex-printf">
<literal>hello, world</literal> to standard		<literal>hello, world</literal> to standard
output.</para>		output.</para>
</callout>		</callout>
</calloutlist>		</calloutlist>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-tables">		<sect2 xml:id="docbook-markup-tables">
<title xml:lang="en">Tables</title>		<title>表格</title>

<para xml:lang="en">Unlike <acronym>HTML</acronym>, DocBook does not need		<para xml:lang="en">Unlike <acronym>HTML</acronym>, DocBook does not need
tables for layout purposes, as the stylesheet handles those		tables for layout purposes, as the stylesheet handles those
issues. Instead, just use tables for marking up tabular		issues. Instead, just use tables for marking up tabular
data.</para>		data.</para>

<para xml:lang="en">In general terms (and see the DocBook documentation for		<para xml:lang="en">In general terms (and see the DocBook documentation for
more detail) a table (which can be either formal or informal)		more detail) a table (which can be either formal or informal)
consists of a <tag>table</tag> element. This contains		consists of a <tag>table</tag> element. This contains
at least one <tag>tgroup</tag> element, which		at least one <tag>tgroup</tag> element, which
specifies (as an attribute) the number of columns in this		specifies (as an attribute) the number of columns in this
table group. Within the tablegroup there is one		table group. Within the tablegroup there is one
<tag>thead</tag> element, which contains elements for		<tag>thead</tag> element, which contains elements for
the table headings (column headings), and one		the table headings (column headings), and one
<tag>tbody</tag> which contains the body of the		<tag>tbody</tag> which contains the body of the
table.</para>		table.</para>

<para xml:lang="en">Both <tag>tgroup</tag> and		<para xml:lang="en">Both <tag>tgroup</tag> and
<tag>thead</tag> contain <tag>row</tag>		<tag>thead</tag> contain <tag>row</tag>
elements, which in turn contain <tag>entry</tag>		elements, which in turn contain <tag>entry</tag>
elements. Each <tag>entry</tag> element specifies		elements. Each <tag>entry</tag> element specifies
one cell in the table.</para>		one cell in the table.</para>

<example>		<example>
<title xml:lang="en"><tag>informaltable</tag> Example</title>		<title><tag>informaltable</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">informaltable pgwide="1"</tag>		<programlisting xml:lang="en"><tag class="starttag">informaltable pgwide="1"</tag>
<tag class="starttag">tgroup cols="2"</tag>		<tag class="starttag">tgroup cols="2"</tag>
<tag class="starttag">thead</tag>		<tag class="starttag">thead</tag>
<tag class="starttag">row</tag>		<tag class="starttag">row</tag>
<tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag>		<tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag>
<tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag>		<tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag>
<tag class="endtag">row</tag>		<tag class="endtag">row</tag>
<tag class="endtag">thead</tag>		<tag class="endtag">thead</tag>

<tag class="starttag">tbody</tag>		<tag class="starttag">tbody</tag>
<tag class="starttag">row</tag>		<tag class="starttag">row</tag>
<tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag>		<tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag>
<tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag>		<tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag>
<tag class="endtag">row</tag>		<tag class="endtag">row</tag>

<tag class="starttag">row</tag>		<tag class="starttag">row</tag>
<tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag>		<tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag>
<tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag>		<tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag>
<tag class="endtag">row</tag>		<tag class="endtag">row</tag>
<tag class="endtag">tbody</tag>		<tag class="endtag">tbody</tag>
<tag class="endtag">tgroup</tag>		<tag class="endtag">tgroup</tag>
<tag class="endtag">informaltable</tag></programlisting>		<tag class="endtag">informaltable</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<informaltable pgwide="1">		<informaltable pgwide="1">
<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry xml:lang="en">This is Column Head 1</entry>		<entry xml:lang="en">This is Column Head 1</entry>
<entry xml:lang="en">This is Column Head 2</entry>		<entry xml:lang="en">This is Column Head 2</entry>
</row>		</row>
Show All 21 Lines	<tag class="endtag">informaltable</tag></programlisting>
is omitted.</para>		is omitted.</para>

<para xml:lang="en">Table borders can be suppressed by setting the		<para xml:lang="en">Table borders can be suppressed by setting the
<literal>frame</literal> attribute to <literal>none</literal>		<literal>frame</literal> attribute to <literal>none</literal>
in the <tag>informaltable</tag> element. For example,		in the <tag>informaltable</tag> element. For example,
<literal>informaltable frame="none"</literal>.</para>		<literal>informaltable frame="none"</literal>.</para>

<example>		<example>
<title xml:lang="en">Table with <literal>frame="none"</literal> Example</title>		<title>表格使用 <literal>frame="none"</literal> 範例</title>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<informaltable frame="none" pgwide="1">		<informaltable frame="none" pgwide="1">
<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry xml:lang="en">This is Column Head 1</entry>		<entry xml:lang="en">This is Column Head 1</entry>
<entry xml:lang="en">This is Column Head 2</entry>		<entry xml:lang="en">This is Column Head 2</entry>
</row>		</row>
Show All 11 Lines	<entry xml:lang="en">Row 2, column 2</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-examples">		<sect2 xml:id="docbook-markup-examples">
<title xml:lang="en">Examples for the User to Follow</title>		<title>給使用者遵循的範例</title>

<para xml:lang="en">Examples for the user to follow are often necessary.		<para xml:lang="en">Examples for the user to follow are often necessary.
Typically, these will consist of dialogs with the computer;		Typically, these will consist of dialogs with the computer;
the user types in a command, the user gets a response back,		the user types in a command, the user gets a response back,
the user types another command, and so on.</para>		the user types another command, and so on.</para>

<para xml:lang="en">A number of distinct elements and entities come into		<para xml:lang="en">A number of distinct elements and entities come into
play here.</para>		play here.</para>
▲ Show 20 Lines • Show All 48 Lines • ▼ Show 20 Lines	<listitem>
<para xml:lang="en">When displaying text that the user should type in,		<para xml:lang="en">When displaying text that the user should type in,
wrap it in <tag>userinput</tag> tags. It will		wrap it in <tag>userinput</tag> tags. It will
be displayed differently than system output text.</para>		be displayed differently than system output text.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>
</variablelist>		</variablelist>

<example>		<example>
<title xml:lang="en"><tag>screen</tag>, <tag>prompt</tag>,		<title><tag>screen</tag>, <tag>prompt</tag> 與 <tag>userinput</tag> 範例</title>
and <tag>userinput</tag> Example</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag>		<programlisting xml:lang="en"><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag>
foo1		foo1
foo2		foo2
foo3		foo3
&prompt.user; <tag class="starttag">userinput</tag>ls -1 \| grep foo2<tag class="endtag">userinput</tag>		&prompt.user; <tag class="starttag">userinput</tag>ls -1 \| grep foo2<tag class="endtag">userinput</tag>
foo2		foo2
&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag>		&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag>
<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag>		<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag>
&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag>		&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag>
This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting>		This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>ls -1</userinput>		<screen xml:lang="en"><prompt>%</prompt> <userinput>ls -1</userinput>
foo1		foo1
foo2		foo2
foo3		foo3
<prompt>%</prompt> <userinput>ls -1 \| grep foo2</userinput>		<prompt>%</prompt> <userinput>ls -1 \| grep foo2</userinput>
foo2		foo2
<prompt>%</prompt> <userinput>su</userinput>		<prompt>%</prompt> <userinput>su</userinput>
<prompt>Password: </prompt>		<prompt>Password: </prompt>
<prompt>#</prompt> <userinput>cat foo2</userinput>		<prompt>#</prompt> <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>		This is the file called 'foo2'</screen>
</example>		</example>

<note>		<note>
<para xml:lang="en">Even though we are displaying the contents of the file		<para xml:lang="en">Even though we are displaying the contents of the file
<filename>foo2</filename>, it is <emphasis>not</emphasis>		<filename>foo2</filename>, it is <emphasis>not</emphasis>
marked up as <tag>programlisting</tag>. Reserve		marked up as <tag>programlisting</tag>. Reserve
<tag>programlisting</tag> for showing fragments of		<tag>programlisting</tag> for showing fragments of
files outside the context of user actions.</para>		files outside the context of user actions.</para>
</note>		</note>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="docbook-markup-inline-elements">		<sect1 xml:id="docbook-markup-inline-elements">
<title xml:lang="en">In-line Elements</title>		<title>行內元素</title>

<sect2 xml:id="docbook-markup-inline-emphasizing">		<sect2 xml:id="docbook-markup-inline-emphasizing">
<title xml:lang="en">Emphasizing Information</title>		<title>強調資訊</title>

<para xml:lang="en">To emphasize a particular word or phrase, use		<para xml:lang="en">To emphasize a particular word or phrase, use
<tag>emphasis</tag>. This may be presented as		<tag>emphasis</tag>. This may be presented as
italic, or bold, or might be spoken differently with a		italic, or bold, or might be spoken differently with a
text-to-speech system.</para>		text-to-speech system.</para>

<para xml:lang="en">There is no way to change the presentation of the		<para xml:lang="en">There is no way to change the presentation of the
emphasis within the document, no equivalent of		emphasis within the document, no equivalent of
<acronym>HTML</acronym>'s <tag>b</tag> and		<acronym>HTML</acronym>'s <tag>b</tag> and
<tag>i</tag>. If the information being presented is		<tag>i</tag>. If the information being presented is
important, then consider presenting it in		important, then consider presenting it in
<tag>important</tag> rather than		<tag>important</tag> rather than
<tag>emphasis</tag>.</para>		<tag>emphasis</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>emphasis</tag> Example</title>		<title><tag>emphasis</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>&os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag>		<programlisting xml:lang="en"><tag class="starttag">para</tag>&os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag>
premiere &unix;-like operating system for the Intel		premiere &unix;-like operating system for the Intel
architecture.<tag class="endtag">para</tag></programlisting>		architecture.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">FreeBSD is without doubt <emphasis>the</emphasis>		<para xml:lang="en">FreeBSD is without doubt <emphasis>the</emphasis>
premiere <trademark class="registered">UNIX</trademark>-like operating system for the Intel		premiere <trademark class="registered">UNIX</trademark>-like operating system for the Intel
architecture.</para>		architecture.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-acronyms">		<sect2 xml:id="docbook-markup-acronyms">
<title xml:lang="en">Acronyms</title>		<title>縮寫</title>

<para xml:lang="en">Many computer terms are <emphasis>acronyms</emphasis>,		<para xml:lang="en">Many computer terms are <emphasis>acronyms</emphasis>,
words formed from the first letter of each word in a		words formed from the first letter of each word in a
phrase. Acronyms are marked up into		phrase. Acronyms are marked up into
<tag>acronym</tag> elements. It is helpful to the		<tag>acronym</tag> elements. It is helpful to the
reader when an acronym is defined on the first use, as shown		reader when an acronym is defined on the first use, as shown
in the example below.</para>		in the example below.</para>

<example>		<example>
<title xml:lang="en"><tag>acronym</tag> Example</title>		<title><tag>acronym</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149		<programlisting xml:lang="en"><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149
defined the use of avian carriers for transmission of		defined the use of avian carriers for transmission of
Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The		Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The
quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently		quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently
transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting>		transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Request For Comments (<acronym>RFC</acronym>) 1149		<para xml:lang="en">Request For Comments (<acronym>RFC</acronym>) 1149
defined the use of avian carriers for transmission of		defined the use of avian carriers for transmission of
Internet Protocol (<acronym>IP</acronym>) data. The		Internet Protocol (<acronym>IP</acronym>) data. The
quantity of <acronym>IP</acronym> data currently		quantity of <acronym>IP</acronym> data currently
transmitted in that manner is unknown.</para>		transmitted in that manner is unknown.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-quotations">		<sect2 xml:id="docbook-markup-quotations">
<title xml:lang="en">Quotations</title>		<title>引言</title>

<para xml:lang="en">To quote text from another document or source, or to		<para xml:lang="en">To quote text from another document or source, or to
denote a phrase that is used figuratively, use		denote a phrase that is used figuratively, use
<tag>quote</tag>. Most of the markup tags available		<tag>quote</tag>. Most of the markup tags available
for normal text are also available from within a		for normal text are also available from within a
<tag>quote</tag>.</para>		<tag>quote</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>quote</tag> Example</title>		<title><tag>quote</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>However, make sure that the search does not go beyond the		<programlisting xml:lang="en"><tag class="starttag">para</tag>However, make sure that the search does not go beyond the
<tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>,		<tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>,
as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting>		as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">However, make sure that the search does not go beyond		<para xml:lang="en">However, make sure that the search does not go beyond
the <quote>boundary between local and public		the <quote>boundary between local and public
administration</quote>, as <acronym>RFC</acronym> 1535		administration</quote>, as <acronym>RFC</acronym> 1535
calls it.</para>		calls it.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-keys">		<sect2 xml:id="docbook-markup-keys">
<title xml:lang="en">Keys, Mouse Buttons, and Combinations</title>		<title>鍵盤按鍵、滑鼠按鍵及組合鍵</title>

<para xml:lang="en">To refer to a specific key on the keyboard, use		<para xml:lang="en">To refer to a specific key on the keyboard, use
<tag>keycap</tag>. To refer to a mouse button, use		<tag>keycap</tag>. To refer to a mouse button, use
<tag>mousebutton</tag>. And to refer to		<tag>mousebutton</tag>. And to refer to
combinations of key presses or mouse clicks, wrap them all		combinations of key presses or mouse clicks, wrap them all
in <tag>keycombo</tag>.</para>		in <tag>keycombo</tag>.</para>

<para xml:lang="en"><tag>keycombo</tag> has an attribute called		<para xml:lang="en"><tag>keycombo</tag> has an attribute called
<literal>action</literal>, which may be one of		<literal>action</literal>, which may be one of
<literal>click</literal>, <literal>double-click</literal>,		<literal>click</literal>, <literal>double-click</literal>,
<literal>other</literal>, <literal>press</literal>,		<literal>other</literal>, <literal>press</literal>,
<literal>seq</literal>, or <literal>simul</literal>. The		<literal>seq</literal>, or <literal>simul</literal>. The
last two values denote whether the keys or buttons should be		last two values denote whether the keys or buttons should be
pressed in sequence, or simultaneously.</para>		pressed in sequence, or simultaneously.</para>

<para xml:lang="en">The stylesheets automatically add any connecting		<para xml:lang="en">The stylesheets automatically add any connecting
symbols, such as <literal>+</literal>, between the key		symbols, such as <literal>+</literal>, between the key
names, when wrapped in <tag>keycombo</tag>.</para>		names, when wrapped in <tag>keycombo</tag>.</para>

<example>		<example>
<title xml:lang="en">Keys, Mouse Buttons, and Combinations Example</title>		<title>鍵盤按鍵、滑鼠案件及組合鍵範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>To switch to the second virtual terminal, press		<programlisting xml:lang="en"><tag class="starttag">para</tag>To switch to the second virtual terminal, press
<tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>		<tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>
<tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>		<tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>

<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type		<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type
<tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag>		<tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag>
<tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>		<tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>

<tag class="starttag">para</tag>My window manager is configured so that		<tag class="starttag">para</tag>My window manager is configured so that
<tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>		<tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>
<tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag>		<tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag>
<tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting>		<tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">To switch to the second virtual terminal, press		<para xml:lang="en">To switch to the second virtual terminal, press
<keycombo action="simul"><keycap>Alt</keycap>		<keycombo action="simul"><keycap>Alt</keycap>
<keycap>F1</keycap></keycombo>.</para>		<keycap>F1</keycap></keycombo>.</para>

<para xml:lang="en">To exit <command>vi</command> without saving changes,		<para xml:lang="en">To exit <command>vi</command> without saving changes,
type <keycombo action="seq">		type <keycombo action="seq">
<keycap>Esc</keycap>		<keycap>Esc</keycap>
<keycap>:</keycap>		<keycap>:</keycap>
<keycap>q</keycap>		<keycap>q</keycap>
<keycap>!</keycap></keycombo>.</para>		<keycap>!</keycap></keycombo>.</para>

<para xml:lang="en">My window manager is configured so that		<para xml:lang="en">My window manager is configured so that
<keycombo action="simul">		<keycombo action="simul">
<keycap>Alt</keycap>		<keycap>Alt</keycap>
<mousebutton>right</mousebutton></keycombo> mouse button		<mousebutton>right</mousebutton></keycombo> mouse button
is used to move windows.</para>		is used to move windows.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-applications">		<sect2 xml:id="docbook-markup-applications">
<title xml:lang="en">Applications, Commands, Options, and Cites</title>		<title>應用程式、指令、選項與引用</title>

<para xml:lang="en">Both applications and commands are frequently referred to		<para xml:lang="en">Both applications and commands are frequently referred to
when writing documentation. The distinction between them is		when writing documentation. The distinction between them is
that an application is the name of a program or suite of		that an application is the name of a program or suite of
programs that fulfill a particular task. A command is the		programs that fulfill a particular task. A command is the
filename of a program that the user can type and run at a		filename of a program that the user can type and run at a
command line.</para>		command line.</para>

▲ Show 20 Lines • Show All 52 Lines • ▼ Show 20 Lines	]></programlisting>
close proximity, it is preferred to use the		close proximity, it is preferred to use the
<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>		<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
notation to markup the first reference and use		notation to markup the first reference and use
<tag>command</tag> to markup subsequent references.		<tag>command</tag> to markup subsequent references.
This makes the generated output, especially		This makes the generated output, especially
<acronym>HTML</acronym>, appear visually better.</para>		<acronym>HTML</acronym>, appear visually better.</para>

<example>		<example>
<title xml:lang="en">Applications, Commands, and Options Example</title>		<title>應用程式、指令、選項範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most		<programlisting xml:lang="en"><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most
widely used Unix mail application.<tag class="starttag">para</tag>		widely used Unix mail application.<tag class="starttag">para</tag>

<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the		<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the
<tag class="starttag">citerefentry</tag>		<tag class="starttag">citerefentry</tag>
<tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>		<tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>
<tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>		<tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>
<tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1;		<tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1;
programs.<tag class="endtag">para</tag>		programs.<tag class="endtag">para</tag>

<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag>		<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag>
<tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>		<tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>
<tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>		<tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>
<tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current		<tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current
status of messages in the mail queue. Check this on the command		status of messages in the mail queue. Check this on the command
line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting>		line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en"><application>Sendmail</application> is the most widely		<para xml:lang="en"><application>Sendmail</application> is the most widely
used Unix mail application.</para>		used Unix mail application.</para>

<para xml:lang="en"><application>Sendmail</application> includes the		<para xml:lang="en"><application>Sendmail</application> includes the
<citerefentry>		<citerefentry>
<refentrytitle>sendmail</refentrytitle>		<refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>		<manvolnum>8</manvolnum>
Show All 13 Lines	<command>sendmail -bp</command>.</para>
<note>		<note>
<para xml:lang="en">Notice how the		<para xml:lang="en">Notice how the
<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>		<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
notation is easier to follow.</para>		notation is easier to follow.</para>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-files">		<sect2 xml:id="docbook-markup-files">
<title xml:lang="en">Files, Directories, Extensions, Device Names</title>		<title>檔案、目錄、副檔名、裝置名稱</title>

<para xml:lang="en">To refer to the name of a file, a directory, a file		<para xml:lang="en">To refer to the name of a file, a directory, a file
extension, or a device name, use <tag>filename</tag>.</para>		extension, or a device name, use <tag>filename</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>filename</tag> Example</title>		<title><tag>filename</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>The source for the Handbook in English is found in		<programlisting xml:lang="en"><tag class="starttag">para</tag>The source for the Handbook in English is found in
<tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>.		<tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>.
The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>.		The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>.
There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a		There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a
number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag>		number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag>

<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected		<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected
by the system, and appears in		by the system, and appears in
<tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting>		<tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">The source for the Handbook in English is found in		<para xml:lang="en">The source for the Handbook in English is found in
<filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.		<filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
The main file is called <filename>book.xml</filename>.		The main file is called <filename>book.xml</filename>.
There is also a <filename>Makefile</filename> and a number		There is also a <filename>Makefile</filename> and a number
of files with a <filename>.ent</filename> extension.</para>		of files with a <filename>.ent</filename> extension.</para>

<para xml:lang="en"><filename>kbd0</filename> is the first keyboard detected		<para xml:lang="en"><filename>kbd0</filename> is the first keyboard detected
by the system, and appears in		by the system, and appears in
<filename>/dev</filename>.</para>		<filename>/dev</filename>.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-name-of-ports">		<sect2 xml:id="docbook-markup-name-of-ports">
<title xml:lang="en">The Name of Ports</title>		<title>Port 名稱</title>

<note>		<note>
<title xml:lang="en">FreeBSD Extension</title>		<title xml:lang="en">FreeBSD Extension</title>

<para xml:lang="en">These elements are part of the FreeBSD extension to		<para xml:lang="en">These elements are part of the FreeBSD extension to
DocBook, and do not exist in the original DocBook		DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>		<acronym>DTD</acronym>.</para>
</note>		</note>

<para xml:lang="en">To include the name of a program from the FreeBSD		<para xml:lang="en">To include the name of a program from the FreeBSD
Ports Collection in the document, use the <tag>package</tag>		Ports Collection in the document, use the <tag>package</tag>
tag. Since the Ports Collection can be installed in any		tag. Since the Ports Collection can be installed in any
number of locations, only include the category and the port		number of locations, only include the category and the port
name; do not include <filename>/usr/ports</filename>.</para>		name; do not include <filename>/usr/ports</filename>.</para>

<para xml:lang="en">By default, <tag>package</tag> refers to a binary package.		<para xml:lang="en">By default, <tag>package</tag> refers to a binary package.
To refer to a port that will be built from source, set the		To refer to a port that will be built from source, set the
<literal>role</literal> attribute to		<literal>role</literal> attribute to
<literal>port</literal>.</para>		<literal>port</literal>.</para>

<example>		<example>
<title xml:lang="en"><tag>package</tag> Example</title>		<title><tag>package</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary		<programlisting xml:lang="en"><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary
package to view network traffic.<tag class="endtag">para</tag>		package to view network traffic.<tag class="endtag">para</tag>

<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be		<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be
built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting>		built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Install the <package>net/wireshark</package> binary		<para xml:lang="en">Install the <package>net/wireshark</package> binary
package to view network traffic.</para>		package to view network traffic.</para>

<para xml:lang="en"><package role="port">net/wireshark</package> can also be		<para xml:lang="en"><package role="port">net/wireshark</package> can also be
built and installed from the Ports Collection.</para>		built and installed from the Ports Collection.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-hosts">		<sect2 xml:id="docbook-markup-hosts">
<title xml:lang="en">Hosts, Domains, IP Addresses, User Names, Group Names,		<title>主機、網域、IP 位址、使用名稱、群組名稱及其他系統項目</title>
and Other System Items</title>

<note>		<note>
<title xml:lang="en">FreeBSD Extension</title>		<title xml:lang="en">FreeBSD Extension</title>

<para xml:lang="en">These elements are part of the FreeBSD extension to		<para xml:lang="en">These elements are part of the FreeBSD extension to
DocBook, and do not exist in the original DocBook		DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>		<acronym>DTD</acronym>.</para>
</note>		</note>
▲ Show 20 Lines • Show All 80 Lines • ▼ Show 20 Lines	<varlistentry>
<listitem>		<listitem>
<para xml:lang="en">The text is a groupname, like		<para xml:lang="en">The text is a groupname, like
<literal>wheel</literal>.</para>		<literal>wheel</literal>.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>
</variablelist>		</variablelist>

<example>		<example>
<title xml:lang="en"><tag>systemitem</tag> and Classes Example</title>		<title><tag>systemitem</tag> 與類別 (Class) 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>The local machine can always be referred to by the		<programlisting xml:lang="en"><tag class="starttag">para</tag>The local machine can always be referred to by the
name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP		name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP
address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>		address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>

<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag>		<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag>
domain contains a number of different hosts, including		domain contains a number of different hosts, including
<tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and		<tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and
Show All 9 Lines
<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies		<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies
every network card in existence. A typical		every network card in existence. A typical
<tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like		<tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like
<tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>		<tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>

<tag class="starttag">para</tag>To carry out most system administration functions		<tag class="starttag">para</tag>To carry out most system administration functions
requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting>		requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">The local machine can always be referred to by the name		<para xml:lang="en">The local machine can always be referred to by the name
<systemitem>localhost</systemitem>, which will have the IP		<systemitem>localhost</systemitem>, which will have the IP
address		address
<systemitem class="ipaddress">127.0.0.1</systemitem>.</para>		<systemitem class="ipaddress">127.0.0.1</systemitem>.</para>

<para xml:lang="en">The		<para xml:lang="en">The
<systemitem class="fqdomainname">FreeBSD.org</systemitem>		<systemitem class="fqdomainname">FreeBSD.org</systemitem>
Show All 14 Lines	<tag class="starttag">para</tag>To carry out most system administration functions

<para xml:lang="en">To carry out most system administration functions		<para xml:lang="en">To carry out most system administration functions
requires logging in as		requires logging in as
<systemitem class="username">root</systemitem>.</para>		<systemitem class="username">root</systemitem>.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-uri">		<sect2 xml:id="docbook-markup-uri">
<title xml:lang="en">Uniform Resource Identifiers		<title>統一資源識別碼 (<acronym>URI</acronym>)</title>
(<acronym>URI</acronym>s)</title>

<para xml:lang="en">Occasionally it is useful to show a		<para xml:lang="en">Occasionally it is useful to show a
Uniform Resource Identifier (<acronym>URI</acronym>) without		Uniform Resource Identifier (<acronym>URI</acronym>) without
making it an active hyperlink. The <tag>uri</tag> element		making it an active hyperlink. The <tag>uri</tag> element
makes this possible:</para>		makes this possible:</para>

<example>		<example>
<title xml:lang="en"><tag>uri</tag> Example</title>		<title><tag>uri</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text:		<programlisting xml:lang="en"><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text:
<tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not		<tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not
create a link.<tag class="endtag">para</tag></programlisting>		create a link.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">This <acronym>URL</acronym> shows only as text:		<para xml:lang="en">This <acronym>URL</acronym> shows only as text:
<uri>https://www.FreeBSD.org</uri>. It does not		<uri>https://www.FreeBSD.org</uri>. It does not
create a link.</para>		create a link.</para>
</example>		</example>

<para xml:lang="en">To create links, see		<para xml:lang="en">To create links, see
<xref linkend="docbook-markup-links"/>.</para>		<xref linkend="docbook-markup-links"/>.</para>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-email-addresses">		<sect2 xml:id="docbook-markup-email-addresses">
<title xml:lang="en">Email Addresses</title>		<title>郵件地址</title>

<para xml:lang="en">Email addresses are marked up as <tag>email</tag>		<para xml:lang="en">Email addresses are marked up as <tag>email</tag>
elements. In the <acronym>HTML</acronym> output format, the		elements. In the <acronym>HTML</acronym> output format, the
wrapped text becomes a hyperlink to the email address. Other		wrapped text becomes a hyperlink to the email address. Other
output formats that support hyperlinks may also make the email		output formats that support hyperlinks may also make the email
address into a link.</para>		address into a link.</para>

<example>		<example>
<title xml:lang="en"><tag>email</tag> with a Hyperlink Example</title>		<title>有超連結的 <tag>email</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>An email address that does not actually exist, like		<programlisting xml:lang="en"><tag class="starttag">para</tag>An email address that does not actually exist, like
<tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an		<tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an
example.<tag class="endtag">para</tag></programlisting>		example.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">An email address that does not actually exist, like		<para xml:lang="en">An email address that does not actually exist, like
<email>notreal@example.com</email>, can be used as an		<email>notreal@example.com</email>, can be used as an
example.</para>		example.</para>
</example>		</example>

<para xml:lang="en">A FreeBSD-specific extension allows setting the		<para xml:lang="en">A FreeBSD-specific extension allows setting the
<literal>role</literal> attribute to <literal>nolink</literal>		<literal>role</literal> attribute to <literal>nolink</literal>
to prevent the creation of the hyperlink to the email		to prevent the creation of the hyperlink to the email
address.</para>		address.</para>

<example>		<example>
<title xml:lang="en"><tag>email</tag> Without a Hyperlink Example</title>		<title>沒有超連結的 <tag>email</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Sometimes a link to an email address like		<programlisting xml:lang="en"><tag class="starttag">para</tag>Sometimes a link to an email address like
<tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not		<tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not
desired.<tag class="endtag">para</tag></programlisting>		desired.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Sometimes a link to an email address like		<para xml:lang="en">Sometimes a link to an email address like
<email role="nolink">notreal@example.com</email> is not		<email role="nolink">notreal@example.com</email> is not
desired.</para>		desired.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-describing-makefiles">		<sect2 xml:id="docbook-markup-describing-makefiles">
<title xml:lang="en">Describing <filename>Makefile</filename>s</title>		<title>說明 <filename>Makefile</filename></title>

<note>		<note>
<title xml:lang="en">FreeBSD Extension</title>		<title xml:lang="en">FreeBSD Extension</title>

<para xml:lang="en">These elements are part of the FreeBSD extension to		<para xml:lang="en">These elements are part of the FreeBSD extension to
DocBook, and do not exist in the original DocBook		DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>		<acronym>DTD</acronym>.</para>
</note>		</note>

<para xml:lang="en">Two elements exist to describe parts of		<para xml:lang="en">Two elements exist to describe parts of
<filename>Makefile</filename>s, <tag>buildtarget</tag>		<filename>Makefile</filename>s, <tag>buildtarget</tag>
and <tag>varname</tag>.</para>		and <tag>varname</tag>.</para>

<para xml:lang="en"><tag>buildtarget</tag> identifies a build target		<para xml:lang="en"><tag>buildtarget</tag> identifies a build target
exported by a <filename>Makefile</filename> that can be		exported by a <filename>Makefile</filename> that can be
given as a parameter to <command>make</command>.		given as a parameter to <command>make</command>.
<tag>varname</tag> identifies a variable that can be		<tag>varname</tag> identifies a variable that can be
set (in the environment, on the command line with		set (in the environment, on the command line with
<command>make</command>, or within the		<command>make</command>, or within the
<filename>Makefile</filename>) to influence the		<filename>Makefile</filename>) to influence the
process.</para>		process.</para>

<example>		<example>
<title xml:lang="en"><tag>buildtarget</tag> and		<title><tag>buildtarget</tag> 與 <tag>varname</tag> 範例</title>
<tag>varname</tag> Example</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag>		<programlisting xml:lang="en"><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag>
are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and		are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and
<tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag>		<tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag>

<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will		<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will
rebuild the application, and invoking		rebuild the application, and invoking
<tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary		<tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary
files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the		files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the
build process.<tag class="endtag">para</tag>		build process.<tag class="endtag">para</tag>

<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a		<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a
number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag>		number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag>
and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting>		and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Two common targets in a <filename>Makefile</filename>		<para xml:lang="en">Two common targets in a <filename>Makefile</filename>
are <buildtarget xml:lang="en">all</buildtarget> and		are <buildtarget xml:lang="en">all</buildtarget> and
<buildtarget xml:lang="en">clean</buildtarget>.</para>		<buildtarget xml:lang="en">clean</buildtarget>.</para>

<para xml:lang="en">Typically, invoking <buildtarget xml:lang="en">all</buildtarget> will		<para xml:lang="en">Typically, invoking <buildtarget xml:lang="en">all</buildtarget> will
rebuild the application, and invoking		rebuild the application, and invoking
<buildtarget xml:lang="en">clean</buildtarget> will remove the temporary		<buildtarget xml:lang="en">clean</buildtarget> will remove the temporary
files (<filename>.o</filename> for example) created by the		files (<filename>.o</filename> for example) created by the
build process.</para>		build process.</para>

<para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> may be controlled by a		<para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> may be controlled by a
number of variables, including <varname>CLOBBER</varname>		number of variables, including <varname>CLOBBER</varname>
and <varname>RECURSE</varname>.</para>		and <varname>RECURSE</varname>.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-literal-text">		<sect2 xml:id="docbook-markup-literal-text">
<title xml:lang="en">Literal Text</title>		<title>實際文字 (Literal)</title>

<para xml:lang="en">Literal text, or text which should be entered verbatim, is		<para xml:lang="en">Literal text, or text which should be entered verbatim, is
often needed in documentation. This is text that is excerpted		often needed in documentation. This is text that is excerpted
from another file, or which should be copied exactly as shown		from another file, or which should be copied exactly as shown
from the documentation into another file.</para>		from the documentation into another file.</para>

<para xml:lang="en">Some of the time, <tag>programlisting</tag> will		<para xml:lang="en">Some of the time, <tag>programlisting</tag> will
be sufficient to denote this text. But		be sufficient to denote this text. But
<tag>programlisting</tag> is not always appropriate,		<tag>programlisting</tag> is not always appropriate,
particularly when you want to include a portion of a file		particularly when you want to include a portion of a file
<quote>in-line</quote> with the rest of the		<quote>in-line</quote> with the rest of the
paragraph.</para>		paragraph.</para>

<para xml:lang="en">On these occasions, use		<para xml:lang="en">On these occasions, use
<tag>literal</tag>.</para>		<tag>literal</tag>.</para>

<example>		<example>
<title xml:lang="en"><tag>literal</tag> Example</title>		<title><tag>literal</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel		<programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel
configuration file determines the size of many system tables, and is		configuration file determines the size of many system tables, and is
a rough guide to how many simultaneous logins the system will		a rough guide to how many simultaneous logins the system will
support.<tag class="endtag">para</tag></programlisting>		support.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">The <literal>maxusers 10</literal> line in the kernel		<para xml:lang="en">The <literal>maxusers 10</literal> line in the kernel
configuration file determines the size of many system		configuration file determines the size of many system
tables, and is a rough guide to how many simultaneous		tables, and is a rough guide to how many simultaneous
logins the system will support.</para>		logins the system will support.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-replaceable">		<sect2 xml:id="docbook-markup-replaceable">
<title xml:lang="en">Showing Items That the User <emphasis>Must</emphasis>		<title>顯示使用者<emphasis>必填</emphasis>的項目</title>
Fill In</title>

<para xml:lang="en">There will often be times when the user is shown		<para xml:lang="en">There will often be times when the user is shown
what to do, or referred to a file or command line, but		what to do, or referred to a file or command line, but
cannot simply copy the example provided. Instead, they		cannot simply copy the example provided. Instead, they
must supply some information themselves.</para>		must supply some information themselves.</para>

<para xml:lang="en"><tag>replaceable</tag> is designed for this		<para xml:lang="en"><tag>replaceable</tag> is designed for this
eventuality. Use it <emphasis>inside</emphasis> other		eventuality. Use it <emphasis>inside</emphasis> other
elements to indicate parts of that element's content that		elements to indicate parts of that element's content that
the user must replace.</para>		the user must replace.</para>

<example>		<example>
<title xml:lang="en"><tag>replaceable</tag> Example</title>		<title><tag>replaceable</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>		<programlisting xml:lang="en"><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<informalexample>		<informalexample>
<screen xml:lang="en"><prompt>%</prompt> <userinput>man <replaceable>command</replaceable></userinput></screen>		<screen xml:lang="en"><prompt>%</prompt> <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>		</informalexample>

<para xml:lang="en"><tag>replaceable</tag> can be used in many		<para xml:lang="en"><tag>replaceable</tag> can be used in many
different elements, including <tag>literal</tag>.		different elements, including <tag>literal</tag>.
This example also shows that <tag>replaceable</tag>		This example also shows that <tag>replaceable</tag>
should only be wrapped around the content that the user		should only be wrapped around the content that the user
<emphasis>is</emphasis> meant to provide. The other content		<emphasis>is</emphasis> meant to provide. The other content
should be left alone.</para>		should be left alone.</para>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag>		<programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag>
line in the kernel configuration file determines the size of many system		line in the kernel configuration file determines the size of many system
tables, and is a rough guide to how many simultaneous logins the system will		tables, and is a rough guide to how many simultaneous logins the system will
support.<tag class="endtag">para</tag>		support.<tag class="endtag">para</tag>

<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value		<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value
for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting>		for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">The		<para xml:lang="en">The
<literal>maxusers <replaceable>n</replaceable></literal>		<literal>maxusers <replaceable>n</replaceable></literal>
line in the kernel configuration file determines the size		line in the kernel configuration file determines the size
of many system tables, and is a rough guide to how many		of many system tables, and is a rough guide to how many
simultaneous logins the system will support.</para>		simultaneous logins the system will support.</para>

<para xml:lang="en">For a desktop workstation, <literal>32</literal> is a		<para xml:lang="en">For a desktop workstation, <literal>32</literal> is a
good value for <replaceable>n</replaceable>.</para>		good value for <replaceable>n</replaceable>.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-gui-buttons">		<sect2 xml:id="docbook-markup-gui-buttons">
<title xml:lang="en">Showing <acronym>GUI</acronym> Buttons</title>		<title>顯示 <acronym>GUI</acronym> 按鈕</title>

<para xml:lang="en">Buttons presented by a graphical user interface are marked		<para xml:lang="en">Buttons presented by a graphical user interface are marked
with <tag>guibutton</tag>. To make the text look more		with <tag>guibutton</tag>. To make the text look more
like a graphical button, brackets and non-breaking spaces are		like a graphical button, brackets and non-breaking spaces are
added surrounding the text.</para>		added surrounding the text.</para>

<example>		<example>
<title xml:lang="en"><tag>guibutton</tag> Example</title>		<title><tag>guibutton</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Edit the file, then click		<programlisting xml:lang="en"><tag class="starttag">para</tag>Edit the file, then click
<tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the		<tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the
changes.<tag class="endtag">para</tag></programlisting>		changes.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Edit the file, then click		<para xml:lang="en">Edit the file, then click
<guibutton>[!Save!]</guibutton> to save the		<guibutton>[!Save!]</guibutton> to save the
changes.</para>		changes.</para>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-system-errors">		<sect2 xml:id="docbook-markup-system-errors">
<title xml:lang="en">Quoting System Errors</title>		<title>引用系統錯誤</title>

<para xml:lang="en">System errors generated by FreeBSD are marked with		<para xml:lang="en">System errors generated by FreeBSD are marked with
<tag>errorname</tag>. This indicates the exact error		<tag>errorname</tag>. This indicates the exact error
that appears.</para>		that appears.</para>

<example>		<example>
<title xml:lang="en"><tag>errorname</tag> Example</title>		<title><tag>errorname</tag> 範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting>		<programlisting xml:lang="en"><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<informalexample>		<informalexample>
<screen xml:lang="en"><errorname>Panic: cannot mount root</errorname></screen>		<screen xml:lang="en"><errorname>Panic: cannot mount root</errorname></screen>
</informalexample>		</informalexample>
</example>		</example>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="docbook-markup-images">		<sect1 xml:id="docbook-markup-images">
<title xml:lang="en">Images</title>		<title>圖片</title>

<important>		<important>
<para xml:lang="en">Image support in the documentation is somewhat		<para xml:lang="en">Image support in the documentation is somewhat
experimental. The mechanisms described here are unlikely to		experimental. The mechanisms described here are unlikely to
change, but that is not guaranteed.</para>		change, but that is not guaranteed.</para>

<para xml:lang="en">To provide conversion between different image formats, the		<para xml:lang="en">To provide conversion between different image formats, the
<package>graphics/ImageMagick</package>		<package>graphics/ImageMagick</package>
port must be installed. This port is not included in the		port must be installed. This port is not included in the
<package>textproc/docproj</package> meta		<package>textproc/docproj</package> meta
port, and must be installed separately.</para>		port, and must be installed separately.</para>

<para xml:lang="en">A good example of the use of images is the		<para xml:lang="en">A good example of the use of images is the
<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>		<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
document. Examine the files in that directory to see how		document. Examine the files in that directory to see how
these elements are used together. Build different output		these elements are used together. Build different output
formats to see how the format determines what images are shown		formats to see how the format determines what images are shown
in the rendered document.</para>		in the rendered document.</para>
</important>		</important>

<sect2 xml:id="docbook-markup-image-formats">		<sect2 xml:id="docbook-markup-image-formats">
<title xml:lang="en">Image Formats</title>		<title>圖片格式</title>

<para xml:lang="en">The following image formats are currently supported. An		<para xml:lang="en">The following image formats are currently supported. An
image file will automatically be converted to bitmap or vector		image file will automatically be converted to bitmap or vector
image depending on the output document format.</para>		image depending on the output document format.</para>

<para xml:lang="en">These are the <emphasis>only</emphasis> formats in which		<para xml:lang="en">These are the <emphasis>only</emphasis> formats in which
images should be committed to the documentation		images should be committed to the documentation
repository.</para>		repository.</para>
▲ Show 20 Lines • Show All 67 Lines • ▼ Show 20 Lines	<para xml:lang="en">The Documentation Project may eventually switch to using
the <acronym>SVG</acronym> (Scalable Vector Graphic) format		the <acronym>SVG</acronym> (Scalable Vector Graphic) format
for vector images. However, the current state of		for vector images. However, the current state of
<acronym>SVG</acronym> capable editing tools makes this		<acronym>SVG</acronym> capable editing tools makes this
impractical.</para>		impractical.</para>
</important>		</important>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-image-file-locations">		<sect2 xml:id="docbook-markup-image-file-locations">
<title xml:lang="en">Image File Locations</title>		<title>圖片檔案位置</title>

<para xml:lang="en">Image files can be stored in one of several locations,		<para xml:lang="en">Image files can be stored in one of several locations,
depending on the document and image:</para>		depending on the document and image:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para xml:lang="en">In the same directory as the document itself, usually		<para xml:lang="en">In the same directory as the document itself, usually
done for articles and small books that keep all their		done for articles and small books that keep all their
Show All 21 Lines	<para xml:lang="en">In a subdirectory of
this upper level of the documentation file tree.		this upper level of the documentation file tree.
Generally, these are images that can be used unchanged in		Generally, these are images that can be used unchanged in
non-English translations of the document.</para>		non-English translations of the document.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-image-markup">		<sect2 xml:id="docbook-markup-image-markup">
<title xml:lang="en">Image Markup</title>		<title>圖片標籤</title>

<para xml:lang="en">Images are included as part of a <tag>mediaobject</tag>.		<para xml:lang="en">Images are included as part of a <tag>mediaobject</tag>.
The <tag>mediaobject</tag> can contain other, more specific		The <tag>mediaobject</tag> can contain other, more specific
objects. We are concerned with two, the		objects. We are concerned with two, the
<tag>imageobject</tag> and the <tag>textobject</tag>.</para>		<tag>imageobject</tag> and the <tag>textobject</tag>.</para>

<para xml:lang="en">Include one <tag>imageobject</tag>, and two		<para xml:lang="en">Include one <tag>imageobject</tag>, and two
<tag>textobject</tag> elements. The <tag>imageobject</tag>		<tag>textobject</tag> elements. The <tag>imageobject</tag>
▲ Show 20 Lines • Show All 62 Lines • ▼ Show 20 Lines	<para xml:lang="en">The second <tag>textobject</tag> contains a
this phrase will become the <literal>alt</literal>		this phrase will become the <literal>alt</literal>
attribute for the image when this document is converted to		attribute for the image when this document is converted to
<acronym>HTML</acronym>.</para>		<acronym>HTML</acronym>.</para>
</callout>		</callout>
</calloutlist>		</calloutlist>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-image-makefile-entries">		<sect2 xml:id="docbook-markup-image-makefile-entries">
<title xml:lang="en">Image <filename>Makefile</filename> Entries</title>		<title>圖片 <filename>Makefile</filename> 項目</title>

<para xml:lang="en">Images must be listed in the <filename>Makefile</filename>		<para xml:lang="en">Images must be listed in the <filename>Makefile</filename>
in the <varname>IMAGES</varname> variable. This variable must		in the <varname>IMAGES</varname> variable. This variable must
contain the names of all the <emphasis>source</emphasis>		contain the names of all the <emphasis>source</emphasis>
images. For example, if there are three figures,		images. For example, if there are three figures,
<filename>fig1.eps</filename>, <filename>fig2.png</filename>,		<filename>fig1.eps</filename>, <filename>fig2.png</filename>,
<filename>fig3.png</filename>, then the		<filename>fig3.png</filename>, then the
<filename>Makefile</filename> should have lines like this in		<filename>Makefile</filename> should have lines like this in
Show All 13 Lines	…</programlisting>

<para xml:lang="en">Again, the <filename>Makefile</filename> will work out the		<para xml:lang="en">Again, the <filename>Makefile</filename> will work out the
complete list of images it needs to build the source document,		complete list of images it needs to build the source document,
you only need to list the image files <emphasis>you</emphasis>		you only need to list the image files <emphasis>you</emphasis>
provided.</para>		provided.</para>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-images-in-subdirectories">		<sect2 xml:id="docbook-markup-images-in-subdirectories">
<title xml:lang="en">Images and Chapters in Subdirectories</title>		<title>在子目錄中的圖片與章節</title>

<para xml:lang="en">Be careful when separating documentation into smaller		<para xml:lang="en">Be careful when separating documentation into smaller
files in different directories (see <xref linkend="xml-primer-include-using-gen-entities"/>).</para>		files in different directories (see <xref linkend="xml-primer-include-using-gen-entities"/>).</para>

<para xml:lang="en">Suppose there is a book with three chapters, and the		<para xml:lang="en">Suppose there is a book with three chapters, and the
chapters are stored in their own directories, called		chapters are stored in their own directories, called
<filename>chapter1/chapter.xml</filename>,		<filename>chapter1/chapter.xml</filename>,
<filename>chapter2/chapter.xml</filename>, and		<filename>chapter2/chapter.xml</filename>, and
Show All 34 Lines	</callout>

<programlisting xml:lang="en">…		<programlisting xml:lang="en">…
IMAGES= chapter1/fig1.png		IMAGES= chapter1/fig1.png
…</programlisting>		…</programlisting>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="docbook-markup-links">		<sect1 xml:id="docbook-markup-links">
<title xml:lang="en">Links</title>		<title>連結</title>

<note>		<note>
<para xml:lang="en">Links are also in-line elements. To show a		<para xml:lang="en">Links are also in-line elements. To show a
<acronym>URI</acronym> without creating a link, see		<acronym>URI</acronym> without creating a link, see
<xref linkend="docbook-markup-uri"/>.</para>		<xref linkend="docbook-markup-uri"/>.</para>
</note>		</note>

<sect2 xml:id="docbook-markup-links-ids">		<sect2 xml:id="docbook-markup-links-ids">
<title xml:lang="en"><literal>xml:id</literal> Attributes</title>		<title><literal>xml:id</literal> 屬性</title>

<para xml:lang="en">Most DocBook elements accept an <literal>xml:id</literal>		<para xml:lang="en">Most DocBook elements accept an <literal>xml:id</literal>
attribute to give that part of the document a unique name.		attribute to give that part of the document a unique name.
The <literal>xml:id</literal> can be used as a target for a		The <literal>xml:id</literal> can be used as a target for a
crossreference or link.</para>		crossreference or link.</para>

<para xml:lang="en">Any portion of the document that will be a link target		<para xml:lang="en">Any portion of the document that will be a link target
must have an <literal>xml:id</literal> attribute. Assigning		must have an <literal>xml:id</literal> attribute. Assigning
an <literal>xml:id</literal> to all chapters and sections,		an <literal>xml:id</literal> to all chapters and sections,
even if there are no current plans to link to them, is a good		even if there are no current plans to link to them, is a good
idea. These <literal>xml:id</literal>s can be used as unique		idea. These <literal>xml:id</literal>s can be used as unique
reference points by anyone referring to the		reference points by anyone referring to the
<acronym>HTML</acronym> version of the document.</para>		<acronym>HTML</acronym> version of the document.</para>

<example>		<example>
<title xml:lang="en"><literal>xml:id</literal> on Chapters and		<title>在章與節上加 <literal>xml:id</literal> 的範例</title>
Sections Example</title>

<programlisting xml:lang="en"><tag class="starttag">chapter xml:id="introduction"</tag>		<programlisting xml:lang="en"><tag class="starttag">chapter xml:id="introduction"</tag>
<tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag>		<tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag>

<tag class="starttag">para</tag>This is the introduction. It contains a subsection,		<tag class="starttag">para</tag>This is the introduction. It contains a subsection,
which is identified as well.<tag class="endtag">para</tag>		which is identified as well.<tag class="endtag">para</tag>

<tag class="starttag">sect1 xml:id="introduction-moredetails"</tag>		<tag class="starttag">sect1 xml:id="introduction-moredetails"</tag>
Show All 11 Lines	<tag class="endtag">chapter</tag></programlisting>
the chapter <literal>xml:id</literal>. This ensures that the		the chapter <literal>xml:id</literal>. This ensures that the
<literal>xml:id</literal>s are unique. It also helps both		<literal>xml:id</literal>s are unique. It also helps both
reader and anyone editing the document to see where the link		reader and anyone editing the document to see where the link
is located within the document, similar to a directory path to		is located within the document, similar to a directory path to
a file.</para>		a file.</para>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-links-crossreferences">		<sect2 xml:id="docbook-markup-links-crossreferences">
<title xml:lang="en">Crossreferences with <literal>xref</literal></title>		<title>使用 <literal>xref</literal> 交叉參照</title>

<para xml:lang="en"><tag>xref</tag> provides the reader with a link to jump to		<para xml:lang="en"><tag>xref</tag> provides the reader with a link to jump to
another section of the document. The target		another section of the document. The target
<literal>xml:id</literal> is specified in the		<literal>xml:id</literal> is specified in the
<literal>linkend</literal> attribute, and <tag>xref</tag>		<literal>linkend</literal> attribute, and <tag>xref</tag>
generates the link text automatically.</para>		generates the link text automatically.</para>

<example>		<example>
<title xml:lang="en"><tag>xref</tag> Example</title>		<title><tag>xref</tag> 範例</title>

<para xml:lang="en">Assume that this fragment appears somewhere in a		<para xml:lang="en">Assume that this fragment appears somewhere in a
document that includes the <literal>xml:id</literal>		document that includes the <literal>xml:id</literal>
example shown above:</para>		example shown above:</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>More information can be found		<programlisting xml:lang="en"><tag class="starttag">para</tag>More information can be found
in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag>		in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag>

Show All 15 Lines	</blockquote>
</example>		</example>

<para xml:lang="en">The link text is generated automatically from the chapter		<para xml:lang="en">The link text is generated automatically from the chapter
and section number and <literal>title</literal>		and section number and <literal>title</literal>
elements.</para>		elements.</para>
</sect2>		</sect2>

<sect2 xml:id="docbook-markup-links-to-web-documents">		<sect2 xml:id="docbook-markup-links-to-web-documents">
<title xml:lang="en">Linking to Other Documents on the		<title>連結在網站上的其他文件</title>
Web</title>

<para xml:lang="en">The link element described here allows the writer to		<para xml:lang="en">The link element described here allows the writer to
define the link text. When link text is used, it is very important to be descriptive		define the link text. When link text is used, it is very important to be descriptive
to give the reader an idea of where the link goes.		to give the reader an idea of where the link goes.
Remember that DocBook can be rendered to multiple		Remember that DocBook can be rendered to multiple
types of media. The reader might be looking at a printed book		types of media. The reader might be looking at a printed book
or other form of media where there are no links. If the link		or other form of media where there are no links. If the link
text is not descriptive enough, the reader might not be able to		text is not descriptive enough, the reader might not be able to
locate the linked section.</para>		locate the linked section.</para>

<para xml:lang="en">The <literal>xlink:href</literal> attribute		<para xml:lang="en">The <literal>xlink:href</literal> attribute
is the <acronym>URL</acronym> of the page,		is the <acronym>URL</acronym> of the page,
and the content of the element is the text that		and the content of the element is the text that
will be displayed for the user to activate.</para>		will be displayed for the user to activate.</para>

<para xml:lang="en">In many situations, it is preferable to show the actual		<para xml:lang="en">In many situations, it is preferable to show the actual
<acronym>URL</acronym> rather than text. This can be done by		<acronym>URL</acronym> rather than text. This can be done by
leaving out the element text entirely.</para>		leaving out the element text entirely.</para>

<example>		<example>
<title xml:lang="en"><tag>link</tag> to a FreeBSD Documentation Web		<title><tag>link</tag> 到 FreeBSD 說明文件網頁範例</title>
Page Example</title>

<para xml:lang="en">Link to the book or article <acronym>URL</acronym>		<para xml:lang="en">Link to the book or article <acronym>URL</acronym>
entity. To link to a specific chapter in a book, add a		entity. To link to a specific chapter in a book, add a
slash and the chapter file name, followed by an optional		slash and the chapter file name, followed by an optional
anchor within the chapter. For articles, link to the		anchor within the chapter. For articles, link to the
article <acronym>URL</acronym> entity, followed by an		article <acronym>URL</acronym> entity, followed by an
optional anchor within the article.		optional anchor within the article.
<acronym>URL</acronym> entities can be found in		<acronym>URL</acronym> entities can be found in
<filename>doc/share/xml/urls.ent</filename>.</para>		<filename>doc/share/xml/urls.ent</filename>.</para>

<para xml:lang="en">Usage for FreeBSD book links:</para>		<para xml:lang="en">Usage for FreeBSD book links:</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Read the <tag class="starttag">link		<programlisting xml:lang="en"><tag class="starttag">para</tag>Read the <tag class="starttag">link
xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN		xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN
introduction<tag class="endtag">link</tag>, then pick the nearest mirror from		introduction<tag class="endtag">link</tag>, then pick the nearest mirror from
the list of <tag class="starttag">link		the list of <tag class="starttag">link
xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion		xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion
mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>		mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Read the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-intro">SVN		<para xml:lang="en">Read the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-intro">SVN
introduction</link>, then pick the nearest mirror from		introduction</link>, then pick the nearest mirror from
the list of <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion		the list of <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion
mirror sites</link>.</para>		mirror sites</link>.</para>

<para xml:lang="en">Usage for FreeBSD article links:</para>		<para xml:lang="en">Usage for FreeBSD article links:</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Read this		<programlisting xml:lang="en"><tag class="starttag">para</tag>Read this
<tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article		<tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article
about the BSD license<tag class="endtag">link</tag>, or just the		about the BSD license<tag class="endtag">link</tag>, or just the
<tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>		<tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Read this		<para xml:lang="en">Read this
<link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl">article		<link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl">article
about the BSD license</link>, or just the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl#intro">introduction</link>.</para>		about the BSD license</link>, or just the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl#intro">introduction</link>.</para>
</example>		</example>

<example>		<example>
<title xml:lang="en"><tag>link</tag> to a FreeBSD Web Page Example</title>		<title><tag>link</tag> 到 FreeBSD 網頁範例</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the		<programlisting xml:lang="en"><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the
<tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting>		<tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Of course, you could stop reading this document and go		<para xml:lang="en">Of course, you could stop reading this document and go
to the <link xlink:href="@@URL_RELPREFIX@@/index.html">FreeBSD		to the <link xlink:href="@@URL_RELPREFIX@@/index.html">FreeBSD
home page</link> instead.</para>		home page</link> instead.</para>
</example>		</example>

<example>		<example>
<title xml:lang="en"><tag>link</tag> to an External Web		<title><tag>link</tag> 到外部網頁範例</title>
Page Example</title>

<para xml:lang="en">Usage:</para>		<para>用法：</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on		<programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
<tag class="starttag">link		<tag class="starttag">link
xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID		xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID
Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>		Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>

<para xml:lang="en">Appearance:</para>		<para>輸出結果：</para>

<para xml:lang="en">Wikipedia has an excellent reference on <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID		<para xml:lang="en">Wikipedia has an excellent reference on <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
Partition Tables</link>.</para>		Partition Tables</link>.</para>

<para xml:lang="en">The link text can be omitted to show the actual		<para xml:lang="en">The link text can be omitted to show the actual
URL:</para>		URL:</para>

<programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on		<programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,		HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN		STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="stylesheets">		<chapter version="5.0" xml:id="stylesheets">
<title xml:lang="en">Style Sheets</title>		<title>樣式表</title>

<para xml:lang="en"><acronym>XML</acronym> is concerned with content, and says		<para xml:lang="en"><acronym>XML</acronym> is concerned with content, and says
nothing about how that content should be presented to the reader		nothing about how that content should be presented to the reader
or rendered on paper. Multiple <emphasis>style sheet</emphasis>		or rendered on paper. Multiple <emphasis>style sheet</emphasis>
languages have been developed to describe visual layout, including		languages have been developed to describe visual layout, including
Extensible Stylesheet Language Transformation		Extensible Stylesheet Language Transformation
(<acronym>XSLT</acronym>), Document Style Semantics and		(<acronym>XSLT</acronym>), Document Style Semantics and
Specification Language (<acronym>DSSSL</acronym>), and Cascading		Specification Language (<acronym>DSSSL</acronym>), and Cascading
Show All 12 Lines	<sect1 xml:id="stylesheets-css">

<para xml:lang="en">Cascading Style Sheets (<acronym>CSS</acronym>) are a		<para xml:lang="en">Cascading Style Sheets (<acronym>CSS</acronym>) are a
mechanism for attaching style information (font, weight, size,		mechanism for attaching style information (font, weight, size,
color, and so forth) to elements in an <acronym>XHTML</acronym>		color, and so forth) to elements in an <acronym>XHTML</acronym>
document without abusing <acronym>XHTML</acronym> to do		document without abusing <acronym>XHTML</acronym> to do
so.</para>		so.</para>

<sect2>		<sect2>
<title xml:lang="en">The DocBook Documents</title>		<title>DocBook 文件</title>

<para xml:lang="en">The FreeBSD <acronym>XSLT</acronym> and		<para xml:lang="en">The FreeBSD <acronym>XSLT</acronym> and
<acronym>DSSSL</acronym> stylesheets refer to		<acronym>DSSSL</acronym> stylesheets refer to
<filename>docbook.css</filename>, which is expected to be		<filename>docbook.css</filename>, which is expected to be
present in the same directory as the <acronym>XHTML</acronym>		present in the same directory as the <acronym>XHTML</acronym>
files. The project-wide <acronym>CSS</acronym> file is copied		files. The project-wide <acronym>CSS</acronym> file is copied
from <filename>doc/share/misc/docbook.css</filename> when		from <filename>doc/share/misc/docbook.css</filename> when
documents are converted to <acronym>XHTML</acronym>, and is		documents are converted to <acronym>XHTML</acronym>, and is
Show All 32 Lines	<!-- Copyright (c) 1999 Nik Clayton, All rights reserved.
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="translations">		<chapter version="5.0" xml:id="translations">
<title>翻譯</title>		<title>翻譯</title>

<para>本章是翻譯 FreeBSD 文件(包含：FAQ, Handbook, tutorials, manual pages等)的常見問題(FAQ)。</para>		<para>本章節是供要翻譯 FreeBSD 說明文件 (常見問答集 (FAQ)、使用手冊 (Handbook)、教學 (Tutorial)、操作手冊 (Manual page) 等) 到各種語言的常見問答集 (FAQ)。</para>

<para>本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文翻譯計劃的翻譯 FAQ 為母本而來的，原始撰稿者為 Frank Gründer <email>elwood@mc5sys.in-berlin.de</email>，並由 Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。</para>		<para>本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文說明文件計劃的翻譯常見問答集為母本而來的，原始撰稿者為 Frank Gründer <email>elwood@mc5sys.in-berlin.de</email>，並由 Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。</para>

<para>本 FAQ 是由文件工程團隊 <email>doceng@FreeBSD.org</email> 所維護。</para>		<para>本常見問答集是由文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 所維護。</para>

<qandaset>		<qandaset>
<qandaentry>		<qandaentry>
<question>		<question>
<para><phrase>i18n</phrase> 跟 <phrase>l10n</phrase> 是什麼呢？</para>		<para><phrase>i18n</phrase> 與 <phrase>l10n</phrase> 代表的是什麼意思？</para>
</question>		</question>

<answer>		<answer>
<para><phrase>i18n</phrase> 是 <phrase>internationalization</phrase> 而 <phrase>l10n</phrase> 是 <phrase>localization</phrase>。這些都是為了書寫方便而用的簡寫。</para>		<para><phrase>i18n</phrase> 指的是國際化 (<phrase>Internationalization</phrase>) 而 <phrase>l10n</phrase> 指的是在地化 (<phrase>Localization</phrase>)。這些都是為了書寫方便而用的簡寫。</para>

<para><phrase>i18n</phrase> 就是開頭為 <quote>i</quote> 後面有 18 個字母，最後接 <quote>n</quote>。同樣地， <phrase>l10n</phrase> 是開頭為 <quote>l</quote> 後面有 10 個字母，最後接 <quote>n</quote>。</para>		<para><phrase>i18n</phrase> 就是開頭為 <quote>i</quote> 後面有 18 個字母，最後接 <quote>n</quote>。同樣地， <phrase>l10n</phrase> 是開頭為 <quote>l</quote> 後面有 10 個字母，最後接 <quote>n</quote>。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>有專門給譯者參與討論的 mailing list 嗎？</para>		<para>有給翻譯人員參與討論的郵遞論壇 (Mailing list) 嗎？</para>
</question>		</question>

<answer>		<answer>
<para>有的，不同的語系翻譯者都各自有自屬的 mailing lists。這份 <link xlink:href="http://www.freebsd.org/docproj/translations.html"> 翻譯計劃清單</link> 有列出各翻譯計劃的詳細 mailing lists 及相關網站。此外，有一般翻譯討論的<email>freebsd-translators@freebsd.org</email>郵件論壇。</para>		<para>有的，不同的語系翻譯人員都各自有自屬的郵遞論壇。這份 <link xlink:href="http://www.freebsd.org/docproj/translations.html"> 翻譯計劃清單</link> 有列出各翻譯計劃的詳細 mailing lists 及相關網站。此外，有一般翻譯討論的<email>freebsd-translators@freebsd.org</email>郵件論壇。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>需要更多人一起參與翻譯嗎？</para>		<para>需要更多人一起參與翻譯嗎？</para>
</question>		</question>

<answer>		<answer>
<para>當然囉，越多人參與翻譯，那麼就能夠越快翻完，而且英文版文件若有增減、更新的話，各翻譯版也可以儘快同步囉。</para>		<para>當然囉，越多人參與翻譯，那麼就能夠越快翻完，而且英文版說明文件若有增減、更新的話，各翻譯版也可以儘快同步囉。</para>

<para>不一定得是專業譯者，才能參與翻譯的。</para>		<para>不一定得是專業譯者，才能參與翻譯的。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>有要求哪些語言能力呢</para>		<para>有要求哪些語言能力呢</para>
</question>		</question>

<answer>		<answer>
<para>理論上，必須要對英文非常熟稔，而且很明顯地，對想翻譯的語言必須要能運用自如。</para>		<para>理論上，必須要對英文非常熟稔，而且很明顯地，對想翻譯的語言必須要能運用自如。</para>

<para>英文也並非一定要會的。比如說，可以把西班牙文(Spanish)的 FAQ 翻譯為匈牙利文(Hungarian)。</para>		<para>英文也並非一定要會的。比如說，可以把西班牙文 (Spanish) 的 FAQ 翻譯為匈牙利文 (Hungarian)。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>該學會哪些程式的使用呢？</para>		<para>該學會哪些程式的使用呢？</para>
</question>		</question>

<answer>		<answer>
<para>強烈建議在自己機器上也建立 FreeBSD Subversion repository 的備份(至少文件部分)，這可以執行：</para>		<para>強烈建議在自己機器上也建立 FreeBSD Subversion 檔案庫的備份 (至少要有說明文件的部分)，這可以執行：</para>

<screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen>		<screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen>

<para><link xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link>是公共的 <literal>SVN</literal> 伺服器。可以從<link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion 鏡相站</link>清單檢查認證的伺服器。</para>		<para><link xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link> 是公共的 <literal>SVN</literal> 伺服器。可以從 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion 鏡像站</link> 清單檢查認證的伺服器。</para>

<note>		<note>
<para>這需要安裝<package>devel/subversion</package> 套件。</para>		<para>這需要安裝 <package>devel/subversion</package> 套件。</para>
</note>		</note>

<para>你可以很自在地使用<application>svn</application>。他可以讓你察看文件檔案不同版本之間的修改差異。</para>		<para>你可以很自在地使用 <application>svn</application>。他可以讓你察看說明文件檔案不同版本之間的修改差異。</para>

<para>例如你要看<filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename> 版本<literal>r33733</literal> 和 <literal>r33734</literal> 的差異，請執行：</para>		<para>例如你要看 <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename> 版本<literal>r33733</literal> 和 <literal>r33734</literal> 的差異，請執行：</para>

<screen><prompt>%</prompt> <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>		<screen><prompt>%</prompt> <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>要怎麼找出來還有誰要跟我一起翻譯的呢？</para>		<para>要怎麼找出來還有誰要跟我一起翻譯的呢？</para>
</question>		</question>

<answer>		<answer>
<para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">文件計劃的翻譯 </link> 列了目前已知的各翻譯者成果，如果已經有其他人也在做跟你一樣的翻譯工作，那麼請不要重複浪費人力，請與他們聯繫看看還有哪些地方可以幫上忙的。</para>		<para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">說明文件計劃翻譯頁 </link> 列了目前已知的各翻譯者成果，如果已經有其他人也在做跟你一樣的翻譯工作，那麼請不要重複浪費人力，請與他們聯繫看看還有哪些地方可以幫上忙的。</para>

<para>若上面並未列出你母語的翻譯，或是也有人要翻譯但還未公開宣布的話，那麼就寄信到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project 郵遞論壇 </link>。</para>		<para>若上面並未列出你母語的翻譯，或是也有人要翻譯但還未公開宣布的話，那麼就寄信到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 說明文件計劃郵遞論壇 </link>。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>都沒人翻譯為我所使用的語言，該怎麼辦？</para>		<para>都沒人翻譯為我所使用的語言，該怎麼辦？</para>
</question>		</question>

<answer>		<answer>
<para>恭喜啊，你剛好踏上 <quote>FreeBSD <replaceable>你的母語</replaceable> 文件翻譯計劃</quote>的啟程之路，歡迎上船。</para>		<para>恭喜啊，你剛好踏上 <quote>FreeBSD <replaceable>您的語言</replaceable> 說明文件翻譯計劃</quote>的啟程之路，歡迎登船。</para>

<para>首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已，因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para>		<para>首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已，因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para>

<para>寫信到 FreeBSD documentation project 郵遞論壇向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料</para>		<para>寫信到文件計劃郵遞論壇 (Documentation Project mailing list) 向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料。</para>

<para>若你的國家已經有人提供 FreeBSD 的 mirror(映設) 服務的話，那麼就先跟他們聯繫，並詢問你是否在上面可以有網頁空間來放相關計劃資料，以及是否可以有提供 email 帳號或 mailing list 服務。</para>		<para>若你的國家已經有人提供 FreeBSD 的鏡像站 (Mirror) 服務的話，那麼就先跟他們聯繫，並詢問你是否在上面可以有網頁空間來放相關計劃資料，以及是否可以有提供電子郵件帳號或郵遞論壇服務。</para>

<para>然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦，或是如何上手之類的說明文章。</para>		<para>然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦，或是如何上手之類的說明文章。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>已經翻好一些文件了，該寄到哪呢？</para>		<para>已經翻好一些說明文件了，該寄到哪呢？</para>
</question>		</question>

<answer>		<answer>
<para>這要看情況而定。若你是在翻譯團隊內做的話(像是日本、德國)，他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。</para>		<para>這要看情況而定。若你是在翻譯團隊內做的話 (像是日本團隊、德國團隊)，他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。</para>

<para>若你是某語系的唯一翻譯者(或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃) ，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para>		<para>若你是某語系的唯一翻譯者 (或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃) ，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？</para>		<para>我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？</para>

<para xml:lang="en">or</para>		<para xml:lang="en">or</para>

<para>我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？</para>		<para>我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？</para>
</question>		</question>

<answer>		<answer>
<para>首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說：把它擺到現有文件架構內是可以正確編譯成功的。</para>		<para>首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說：把它擺到現有說明文件樹內是可以正確編譯成功的。</para>

<para>目前，FreeBSD 文件都是放在最上層的 <filename>head/</filename> 目錄內。而該目錄下的則依其語系來做分類命名的，依照 ISO639 定義(在比比 1999/01/20 還新的 FreeBSD 版本的/usr/share/misc/iso639 )。</para>		<para>目前，FreeBSD 說明文件都是放在最上層的 <filename>head/</filename> 目錄內。而該目錄下的則根據其 ISO639 所定義的語系代碼來做分類命名的 (在 1999/1/20 之後的 FreeBSD 版本中的 <filename>/usr/share/misc/iso639</filename>)。</para>

<para>若你這個語系可能會有不同編碼方式(像是：中文) 那麼就應該會像下面這樣，來依你所使用的編碼方式細分</para>		<para>若你這個語系可能會有不同編碼方式 (像是：中文) 那麼就應該會像下面這樣，來依你所使用的編碼方式細分。</para>

<para>最後，你應該建立好各文件的目錄了。</para>		<para>最後，你應該建立好各文件的目錄了。</para>

<para>舉例來說，假設有瑞典文(Swedish)版的翻譯，那麼應該會長像：</para>		<para>舉例來說，假設有瑞典文 (Swedish) 版的翻譯，那麼應該會長像：</para>

<programlisting>head/		<programlisting>head/
sv_SE.ISO8859-1/		sv_SE.ISO8859-1/
Makefile		Makefile
htdocs/		htdocs/
docproj/		docproj/
books/		books/
faq/		faq/
Makefile		Makefile
book.xml</programlisting>		book.xml</programlisting>

<para><literal>sv_SE.ISO8859-1</literal>是依照 <filename><replaceable>語系(lang)</replaceable>.<replaceable>編碼(encoding)</replaceable></filename> 的規則來建立的譯名。請注意：其中有兩個 Makefiles 檔，它們是用來建構文件的。</para>		<para><literal>sv_SE.ISO8859-1</literal>是依照 <filename><replaceable>語系 (Lang)</replaceable>.<replaceable>編碼 (Encoding)</replaceable></filename> 的規則來建立的譯名。請注意：其中有兩個 Makefile 檔，它們是用來建置說明文件的。</para>

<para>然後請用 <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 與 <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來把你的翻譯文件壓縮起來，並寄到本計劃來。</para>		<para>然後請用 <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 與 <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來把你的說明文件壓縮起來，並寄到本計劃來。</para>

<screen><prompt>%</prompt> <userinput>cd doc</userinput>		<screen><prompt>%</prompt> <userinput>cd doc</userinput>
<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>		<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput></screen>		<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput></screen>

<para>接著，把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上，若你沒有自己網頁空間的話(ISP不提供) ，那麼可以該檔寄到 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 來。</para>		<para>接著，把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上，若你沒有自己網頁空間的話(ISP不提供) ，那麼可以該檔寄到文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 來。</para>

<para>還有，記得用 Bugzilla 提交一個報告以通知大家；你已經寄出翻譯文件了，還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好，因為這也有助於提升翻譯品質的流暢度。</para>		<para>還有，記得用 Bugzilla 提交一個回報來通知大家你已經提交說明文件了，還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好，因為這也有助於提升翻譯品質的流暢度。</para>

<para>最後，會有人(可能是文件計劃總管，或是 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 成員) 會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點：</para>		<para>最後，會有人 (可能是文件計劃管理者，或是文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 成員) 會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點：</para>

<orderedlist>		<orderedlist>
<listitem>		<listitem>
<para>你的檔案是否都有用 RCS tag (像是 "ID" 之類的)？</para>		<para>你的檔案是否都有用 RCS tag (像是 "ID" 之類的)？</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><filename>sv_SE.ISO8859-1</filename> 是否可以順利<command>make all</command> 編譯呢？</para>		<para><filename>sv_SE.ISO8859-1</filename> 是否可以順利<command>make all</command> 編譯呢？</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><command>make install</command> 是否結果有正確</para>		<para><command>make install</command> 是否結果有正確</para>
</listitem>		</listitem>
</orderedlist>		</orderedlist>

<para>若有問題的話，那麼檢閱者會叮嚀你，來讓這些翻譯成果可以正確使用。</para>		<para>若有問題的話，那麼檢閱者會叮嚀你，來讓這些翻譯成果可以正確使用。</para>

<para>若沒問題的話，那麼就會很快把你的翻譯成果 commit 進去了。</para>		<para>若沒問題的話，那麼就會很快把你的翻譯成果提交。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>可以加入某語系或某國家才有的東西到翻譯內容內嗎？</para>		<para>可以加入某語系或某國家才有的東西到翻譯內容內嗎？</para>
</question>		</question>

<answer>		<answer>
<para>我們希望不要這麼做。</para>		<para>我們希望不要這麼做。</para>

<para>舉例來說，假設你正準備把 Handbook 翻譯為韓文版，並希望把韓國零售商也加到你翻譯的 Handbook 韓文版內。</para>		<para>舉例來說，假設你正準備把使用手冊 (Handbook) 翻譯為韓文版，並希望把韓國零售商也加到你翻譯的韓文版使用手冊內。</para>

<para>我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 …) 因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。</para>		<para>我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 …) 因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。</para>

<para>若你有某國才有的資料，請(用 Bugzilla )提供給英文版 Handbook 以作為修訂，然後再把英文版的修訂部分，翻為你要翻譯的 Handbook 吧。</para>		<para>若你有某國才有的資料，請提供給英文版使用手冊以作為修訂 (用 Bugzilla)，然後再把英文版的修訂部分翻為你要翻譯的使用手冊吧。</para>

<para>謝謝。</para>		<para>謝謝。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>要怎麼把該語系特有的字元寫進去翻譯內容呢？</para>		<para>要怎麼把該語系特有的字元寫進去翻譯內容呢？</para>
</question>		</question>

<answer>		<answer>
<para>文件內所有的非 ASCII(Non-ASCII) 字元，都要使用 SGML entities 才能寫進去。</para>		<para>說明文件內所有的非 ASCII (Non-ASCII) 的字元，都要使用 SGML entities 才能寫進去。</para>

<para>簡單來說，長相一開頭會是 and 符號(&)，然後是該 entity 名稱，最後接上分號(;)。</para>		<para>簡單來說，長相一開頭會是 and 符號 (&)，然後是該 Entity 名稱，最後接上分號 (;)。</para>

<para>這些 entity 名稱都是 ISO8879 所制訂的，而 port tree 內則 <package>textproc/iso8879</package>。</para>		<para>這些 Entity 名稱都是 ISO8879 所制訂的，其在 Port 樹內的 <package>textproc/iso8879</package>。</para>

<para>以下舉一些例子：</para>		<para>以下舉一些例子：</para>

<segmentedlist>		<segmentedlist>
<segtitle>Entity名稱</segtitle>		<segtitle>Entity 名稱</segtitle>

<segtitle>實際樣子</segtitle>		<segtitle>外觀</segtitle>

<segtitle xml:lang="en">Description</segtitle>		<segtitle>說明</segtitle>

<seglistitem>		<seglistitem>
<seg>&eacute;</seg>		<seg>&eacute;</seg>
<seg>é</seg>		<seg>é</seg>
<seg>小 <quote>e</quote>，並帶尖、重音(acute accent)</seg>		<seg>小 <quote>e</quote>，並帶尖、重音 (Acute accent)</seg>
</seglistitem>		</seglistitem>

<seglistitem>		<seglistitem>
<seg>&Eacute;</seg>		<seg>&Eacute;</seg>
<seg>É</seg>		<seg>É</seg>
<seg>大 <quote>E</quote>，並帶尖、重音(acute accent)</seg>		<seg>大 <quote>E</quote>，並帶尖、重音 (Acute accent)</seg>
</seglistitem>		</seglistitem>

<seglistitem>		<seglistitem>
<seg>&uuml;</seg>		<seg>&uuml;</seg>
<seg>ü</seg>		<seg>ü</seg>
<seg>小 <quote>u</quote>，並帶日耳曼語系中的母音變化(umlaut)</seg>		<seg>小 <quote>u</quote>，並帶日耳曼語系中的母音變化 (Umlaut)</seg>
</seglistitem>		</seglistitem>
</segmentedlist>		</segmentedlist>

<para>在裝了 iso8879 這個 port 之後，就可以在 <filename>/usr/local/share/xml/iso8879</filename> 找到這些的詳細列表。</para>		<para>在裝了 iso8879 這個 Port 之後，就可以在 <filename>/usr/local/share/xml/iso8879</filename> 找到這些的詳細列表。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>如何稱呼讀者呢？</para>		<para>如何稱呼讀者呢？</para>
</question>		</question>

<answer>		<answer>
<para>在英文文件內，讀者都是以 <quote>you</quote> 來稱呼，而有些語言並沒有正式/非正式的區隔。</para>		<para>在英文文件內，讀者都是以 <quote>you</quote> 來稱呼，而有些語言並沒有正式/非正式的區隔。</para>

<para>若你所要翻的語言可以區別這些差異，那麼請用該語系在一般技術文件上所使用的稱呼吧。如果容易造成困惑的話，那麼請改用較中性的稱呼來取代。</para>		<para>若你所要翻的語言可以區別這些差異，那麼請用該語系在一般技術說明文件上所使用的稱呼吧。如果容易造成困惑的話，那麼請改用較中性的稱呼來取代。</para>
</answer>		</answer>
</qandaentry>		</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>翻譯成果內要不要附上一些其他訊息呢？</para>		<para>翻譯成果內要不要附上一些其他訊息呢？</para>
</question>		</question>

<answer>		<answer>
<para>要。</para>		<para>要。</para>

<para>每份英文版原稿的開頭，通常會有像下面的內容：</para>		<para>每份英文版原稿的開頭，通常會有像下面的內容：</para>

<programlisting><!--		<programlisting xml:lang="en"><!--
The FreeBSD Documentation Project		The FreeBSD Documentation Project

$FreeBSD$		$FreeBSD$
--></programlisting>		--></programlisting>

<para xml:lang="en">The exact boilerplate may change, but it will always		<para>實際上的內容可能稍有不同，但每份原稿都會附上 $FreeBSD$ 這一行以及 <literal>The FreeBSD Documentation Project</literal> 宣告。請注意：$FreeBSD$ 開頭的這行是會由 Subversion 隨著每次異動而自動更改的，所以新檔案的話請保持原狀 (也就是只要寫 $FreeBSD$ 就好了)。</para>
include a $FreeBSD$ line and the phrase
<literal>The FreeBSD Documentation Project</literal>.
Note that the $FreeBSD part is expanded automatically
by Subversion, so it should be empty (just
<literal>$FreeBSD$</literal>) for new
files.</para>

<para>翻譯文件中，必須都要有 $FreeBSD$ 這行，並且把 <literal>FreeBSD Documentation Project</literal> 這行改為 <literal>The FreeBSD <replaceable>language</replaceable> Documentation Project</literal>。</para>		<para>翻譯文件中，必須都要有 $FreeBSD$ 這行，並且把 <literal>FreeBSD Documentation Project</literal> 這行改為 <literal>The FreeBSD <replaceable>language</replaceable> Documentation Project</literal>。</para>

<para>此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。</para>		<para>此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。</para>

<para>因此呢，西班牙文版(Spanish)的檔案開頭應該是長像這樣：</para>		<para>因此呢，西班牙文版 (Spanish) 的檔案開頭應該是長像這樣：</para>

<programlisting><!--		<programlisting xml:lang="en"><!--
The FreeBSD Spanish Documentation Project		The FreeBSD Spanish Documentation Project

$FreeBSD$		$FreeBSD$
Original revision: r38674		Original revision: r38674
--></programlisting>		--></programlisting>
</answer>		</answer>
</qandaentry>		</qandaentry>
</qandaset>		</qandaset>
</chapter>		</chapter>


<!--		<!--
The FreeBSD Documentation Project		The FreeBSD Documentation Project
$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="po-translations">		<chapter version="5.0" xml:id="po-translations">

<title><acronym>PO</acronym> 翻譯</title>		<title><acronym>PO</acronym> 翻譯</title>

<sect1 xml:id="po-translations-introduction">		<sect1 xml:id="po-translations-introduction">
<title xml:lang="en">Introduction</title>		<title>簡介</title>

<para><link xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym> <application>gettext</application></link> 系統提供翻譯者一個簡單的方法來建立和維護文件的翻譯。翻譯的字串從原始文件題取出來到<acronym>PO</acronym> (Portable Object) 檔。字串的翻譯用另外的編輯器輸入。翻譯的字串可以直接使用，或是編譯成原始文件的完整翻譯版本。</para>		<para><link xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym> <application>gettext</application></link> 系統提供翻譯者一個簡單的方法來建立和維護文件的翻譯。翻譯的字串從原始文件題取出來到 <acronym>PO</acronym> (Portable Object) 檔。字串的翻譯用另外的編輯器輸入。翻譯的字串可以直接使用，或是編譯成原始文件的完整翻譯版本。</para>
</sect1>		</sect1>

<sect1 xml:id="po-translations-quick-start">		<sect1 xml:id="po-translations-quick-start">
<title>快速上手</title>		<title>快速上手</title>

<para>在 <xref linkend="overview-quick-start"/> 的步驟還必須打開 <package role="port">textproc/docproj</package> port <literal>TRANSLATOR</literal> 選項。如果沒有打開這個選項，請打開選項後，重新安裝 port。</para>		<para>我們會假設您已做過在 <xref linkend="overview-quick-start"/> 中的步驟，除此之外還必須打開 <package role="port">textproc/docproj</package> Port 中的 <literal>TRANSLATOR</literal> 選項。如果沒有打開這個選項，請打開選項後重新安裝 Port。</para>

<screen><prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput>		<screen><prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput>
<prompt>#</prompt> <userinput>make config</userinput>		<prompt>#</prompt> <userinput>make config</userinput>
<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput></screen>		<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput></screen>

<para>這個範例示範如何建立<link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds">Leap Seconds</link> 短文的西班牙文翻譯</para>		<para>這個範例示範如何建立 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds">Leap Seconds</link> 短文的西班牙文翻譯。</para>

<procedure xml:id="po-translations-quick-start-install-po-editor">		<procedure xml:id="po-translations-quick-start-install-po-editor">
<title>安裝 <acronym>PO</acronym> 編輯器</title>		<title>安裝 <acronym>PO</acronym> 編輯器</title>

<step>		<step>
<para>編輯翻譯檔案需要<acronym>PO</acronym>編輯器。這個範例使用<package role="ports">editors/poedit</package>。</para>		<para>編輯翻譯檔案需要 <acronym>PO</acronym> 編輯器。這個範例使用 <package role="ports">editors/poedit</package>。</para>

<screen><prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput>		<screen><prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput>
<prompt>#</prompt> <userinput>make install clean</userinput></screen>		<prompt>#</prompt> <userinput>make install clean</userinput></screen>
</step>		</step>
</procedure>		</procedure>

<procedure xml:id="po-translations-quick-start-initial-setup">		<procedure xml:id="po-translations-quick-start-initial-setup">
<title>初始設定</title>		<title>初始設定</title>
▲ Show 20 Lines • Show All 54 Lines • ▼ Show 20 Lines
<prompt>%</prompt> <userinput>firefox article.html</userinput></screen>		<prompt>%</prompt> <userinput>firefox article.html</userinput></screen>
</step>		</step>
</procedure>		</procedure>
</sect1>		</sect1>

<sect1 xml:id="po-translations-creating">		<sect1 xml:id="po-translations-creating">
<title>建立新翻譯</title>		<title>建立新翻譯</title>

<para>建立新翻譯文件的第一步是找到或建立一個目錄來放它。FreeBSD 將翻譯文件放在子目錄，用語系和區域以<filename><replaceable>語系</replaceable>_<replaceable>區域</replaceable></filename>來命名。<replaceable>語系</replaceable> 是小寫的兩個字元碼。接著是底線和兩個字元的大寫 <replaceable>REGION</replaceable> 碼。</para>		<para>建立新翻譯文件的第一步是找到或建立一個目錄來放它。FreeBSD 將翻譯文件放在子目錄，用語系和區域以 <filename><replaceable>語系 (lang)</replaceable>_<replaceable>區域 (REGION)</replaceable></filename> 來命名。<replaceable>語系 (lang)</replaceable> 是小寫的兩個字元碼，接著是底線和兩個字元的大寫 <replaceable>REGION</replaceable> 碼。</para>

<table xml:id="po-translations-language-names" frame="none">		<table xml:id="po-translations-language-names" frame="none">
<title>語系名稱</title>		<title>語系名稱</title>

<tgroup cols="5">		<tgroup cols="5">
<thead>		<thead>
<row>		<row>
<entry>語言</entry>		<entry>語言</entry>
▲ Show 20 Lines • Show All 171 Lines • ▼ Show 20 Lines	<row>
<entry><filename>zh_TW.UTF-8</filename></entry>		<entry><filename>zh_TW.UTF-8</filename></entry>
<entry><filename>zh_TW.po</filename></entry>		<entry><filename>zh_TW.po</filename></entry>
<entry><acronym>UTF</acronym>-8</entry>		<entry><acronym>UTF</acronym>-8</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</table>		</table>

<para>翻譯位於主要文件目錄的子目錄，這裡假設如 <xref linkend="overview-quick-start"/> 所示，是 <filename>~/doc/</filename>。例如德文位於 <filename>~/doc/de_DE.ISO8859-1/</filename>，法文位於 <filename>~/doc/fr_FR.ISO8859-1/</filename>。</para>		<para>翻譯位於主要說明文件目錄的子目錄，這裡假設如 <xref linkend="overview-quick-start"/> 所示，是 <filename>~/doc/</filename>。例如德文位於 <filename>~/doc/de_DE.ISO8859-1/</filename>，法文位於 <filename>~/doc/fr_FR.ISO8859-1/</filename>。</para>

<para>每個語系目錄包含不同文件類型的子目錄，通常是 <filename>articles/</filename> 和 <filename>books/</filename>。</para>		<para>每個語系目錄包含不同文件類型的子目錄，通常是 <filename>articles/</filename> 和 <filename>books/</filename>。</para>

<para>將目錄名稱組合起來就是文章或書的完整路徑。例如，NanoBSD 文章的法語翻譯在 <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename> 。而使用手冊的蒙古文翻譯在<filename>~/doc/mn_MN.UTF-8/books/handbook/</filename> 。</para>		<para>將目錄名稱組合起來就是文章或書的完整路徑。例如，NanoBSD 文章的法語翻譯在 <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename> 。而使用手冊的蒙古文翻譯在<filename>~/doc/mn_MN.UTF-8/books/handbook/</filename> 。</para>

<para>當翻譯到一個新語系時必須建立一個新的語系目錄。如果語系目錄已經存在，那只需要有 <filename>articles/</filename> 或 <filename>books/</filename> 的子目錄。</para>		<para>當翻譯到一個新語系時必須建立一個新的語系目錄。如果語系目錄已經存在，那只需要有 <filename>articles/</filename> 或 <filename>books/</filename> 的子目錄。</para>

<para>FreeBSD 文件的編譯是由同一個目錄的 <filename>Makefile</filename> 控制。簡單的文章可以從原始的英語目錄直接複製 <filename>Makefile</filename> 過來。書籍的翻譯流程結合多個獨立的 <filename>book.xml</filename> 和 <filename>chapter.xml</filename> 成為一個檔案，所以書籍翻譯的 <filename>Makefile</filename> 必須複製並修改。</para>		<para>FreeBSD 說明文件的編譯是由同一個目錄的 <filename>Makefile</filename> 控制。簡單的文章可以從原始的英語目錄直接複製 <filename>Makefile</filename> 過來。書籍的翻譯流程結合多個獨立的 <filename>book.xml</filename> 和 <filename>chapter.xml</filename> 成為一個檔案，所以書籍翻譯的 <filename>Makefile</filename> 必須複製並修改。</para>

<example xml:id="po-translations-creating-example">		<example xml:id="po-translations-creating-example">
<title>建立 Porter 手冊的西班牙語翻譯</title>		<title>建立 Porter 手冊的西班牙語翻譯</title>

<para>建立<link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook">Porter 手冊</link>的西班牙文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename> 的書籍。</para>		<para>建立 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook">Porter 手冊</link> 的西班牙文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename> 的書籍。</para>

<procedure>		<procedure>
<step>		<step>
<para>西班牙文 books 目錄 <filename>~/doc/es_ES.ISO8859-1/books/</filename> 已經存在，所以只要建立 Porter 手冊的子目錄：</para>		<para>西班牙文 books 目錄 <filename>~/doc/es_ES.ISO8859-1/books/</filename> 已經存在，所以只要建立 Porter 手冊的子目錄：</para>
<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>		<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>
<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput>		<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput>
A porters-handbook</screen>		A porters-handbook</screen>
</step>		</step>

<step>		<step>
<para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para>		<para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para>

<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>		<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>		<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>
A Makefile</screen>		A Makefile</screen>

<para>修改 <filename>Makefile</filename> 內容以產生單一的 <filename>book.xml</filename>：</para>		<para>修改 <filename>Makefile</filename> 內容以產生單一的 <filename>book.xml</filename>：</para>

<programlisting>#		<programlisting xml:lang="en">#
# $FreeBSD$		# $FreeBSD$
#		#
# Build the FreeBSD Porter's Handbook。		# Build the FreeBSD Porter's Handbook.
#		#

MAINTAINER=doc@FreeBSD.org		MAINTAINER=doc@FreeBSD.org

DOC?= book		DOC?= book

FORMATS?= html-split		FORMATS?= html-split

Show All 34 Lines	.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
<para>現在文件結構已經準備好讓翻譯者執行 <command>make po</command> 開始翻譯。</para>		<para>現在文件結構已經準備好讓翻譯者執行 <command>make po</command> 開始翻譯。</para>
</step>		</step>
</procedure>		</procedure>
</example>		</example>

<example xml:id="po-translations-creating-example-french">		<example xml:id="po-translations-creating-example-french">
<title>建立 <acronym>PGP</acronym> 金鑰文章的法語翻譯。</title>		<title>建立 <acronym>PGP</acronym> 金鑰文章的法語翻譯。</title>

<para>建立 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/pgpkeys"><acronym>PGP</acronym> 金鑰文章</link>的法文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename> 的文章。</para>		<para>建立 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/pgpkeys"><acronym>PGP</acronym> 金鑰文章</link> 的法文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename> 的文章。</para>

<procedure>		<procedure>
<step>		<step>
<para>法文 article 目錄 <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> 已經存在，所以只要建立 <acronym>PGP</acronym> 金鑰文章的子目錄：</para>		<para>法文文章目錄 <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> 已經存在，所以只要建立 <acronym>PGP</acronym> 金鑰文章的子目錄：</para>
<screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>		<screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>
<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput>		<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput>
A pgpkeys</screen>		A pgpkeys</screen>
</step>		</step>

<step>		<step>
<para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para>		<para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para>

<screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>		<screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>
<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>		<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>
A Makefile</screen>		A Makefile</screen>

<para>檢查 <filename>Makefile</filename> 的內容。因為這是簡單的文章，此例的 <filename>Makefile</filename> 不用修改。第二行的 <literal>$FreeBSD...$</literal> 版本字串將會在檔案提交時被版本控制系統替換掉。</para>		<para>檢查 <filename>Makefile</filename> 的內容。因為這是簡單的文章，此例的 <filename>Makefile</filename> 不用修改。第二行的 <literal>$FreeBSD...$</literal> 版本字串將會在檔案提交時被版本控制系統替換掉。</para>

<programlisting>#		<programlisting xml:lang="en">#
# $FreeBSD$		# $FreeBSD$
#		#
# Article：PGP Keys		# Article: PGP Keys

DOC?= article		DOC?= article

FORMATS?= html		FORMATS?= html
WITH_ARTICLE_TOC?= YES		WITH_ARTICLE_TOC?= YES

INSTALL_COMPRESSED?= gz		INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=		INSTALL_ONLY_COMPRESSED?=

SRCS= article.xml		SRCS= article.xml

# To build with just key fingerprints, set FINGERPRINTS_ONLY。		# To build with just key fingerprints, set FINGERPRINTS_ONLY.

URL_RELPREFIX?= ../../../..		URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..		DOC_PREFIX?= ${.CURDIR}/../../..

.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>		.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>

<para>文章結構處理好後，可以執行建立 <command>make po</command> 建立 <acronym>PO</acronym> 檔。</para>		<para>文章結構處理好後，可以執行建立 <command>make po</command> 建立 <acronym>PO</acronym> 檔。</para>
</step>		</step>
</procedure>		</procedure>
</example>		</example>
</sect1>		</sect1>

<sect1 xml:id="po-translations-translating">		<sect1 xml:id="po-translations-translating">
<title>翻譯</title>		<title>翻譯</title>

<para><application>gettext</application>系統大幅減少翻譯者要追蹤的事情。字串從原始文件提取到<acronym>PO</acronym> 檔。再用 <acronym>PO</acronym> 檔編輯器輸入字串的翻譯。</para>		<para><application>gettext</application> 系統大幅減少翻譯者要追蹤的事情。字串從原始文件提取到 <acronym>PO</acronym> 檔。再用 <acronym>PO</acronym> 檔編輯器輸入字串的翻譯。</para>

<para>FreeBSD <acronym>PO</acronym> 翻譯系統不會覆蓋掉 <acronym>PO</acronym> 檔。所以提取步驟可以在任何時候重複執行來更新 <acronym>PO</acronym> 檔。</para>		<para>FreeBSD <acronym>PO</acronym> 翻譯系統不會覆蓋掉 <acronym>PO</acronym> 檔。所以提取步驟可以在任何時候重複執行來更新 <acronym>PO</acronym> 檔。</para>

<para>用 <acronym>PO</acronym> 檔編輯器來編輯檔案。此例是用 <package role="port">editors/poedit</package>，因為它很簡單而且系統需求低。其他的 <acronym>PO</acronym> 檔編輯器提供一些特點，能使翻譯工作更輕鬆。Ports 裡有數個編輯器，包括 <package role="port">devel/gtranslator</package> 。</para>		<para>用 <acronym>PO</acronym> 檔編輯器來編輯檔案。此例是用 <package role="port">editors/poedit</package>，因為它很簡單而且系統需求低。其他的 <acronym>PO</acronym> 檔編輯器提供一些特點，能使翻譯工作更輕鬆。Port 套件集裡有數個編輯器，包括 <package role="port">devel/gtranslator</package> 。</para>

<para>保留 <acronym>PO</acronym> 檔是很重要的。它包含所有的翻譯成果。</para>		<para>保留 <acronym>PO</acronym> 檔是很重要的。它包含所有的翻譯成果。</para>

<example xml:id="po-translations-translating-example">		<example xml:id="po-translations-translating-example">
<title>翻譯 Porter 手冊到西班牙文</title>		<title>翻譯 Porter 手冊到西班牙文</title>

<para>輸入 Porter 手冊的西班牙文內容</para>		<para>輸入 Porter 手冊的西班牙文內容</para>

Show All 15 Lines	<prompt>%</prompt> <userinput>make po</userinput></screen>
</sect1>		</sect1>

<sect1 xml:id="po-translations-tips">		<sect1 xml:id="po-translations-tips">
<title>給翻譯者的提示</title>		<title>給翻譯者的提示</title>

<sect2 xml:id="po-translations-tips-xmltags">		<sect2 xml:id="po-translations-tips-xmltags">
<title>保留 <acronym>XML</acronym> 標籤</title>		<title>保留 <acronym>XML</acronym> 標籤</title>

<para xml:lang="en">Preserve <acronym>XML</acronym> tags that are shown in		<para>保留在英文原文的 <acronym>XML</acronym> 標籤。</para>
the English original.</para>

<example>		<example>
<title>保留 <acronym>XML</acronym> 標籤</title>		<title>保留 <acronym>XML</acronym> 標籤</title>

<para>英文原文：</para>		<para>英文原文：</para>

<programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting>		<programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting>

<para>西班牙文翻譯：</para>		<para>西班牙文翻譯：</para>

<programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting>		<programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting>
</example>		</example>
</sect2>		</sect2>

<sect2 xml:id="po-translations-tips-spaces">		<sect2 xml:id="po-translations-tips-spaces">
<title>保留空白</title>		<title>保留空白</title>

<para>保留要翻譯字串前後的空白。翻譯的版本也要有這些空白。</para>		<para>保留要翻譯字串前後的空白，翻譯過的版本也需要有這些空白。</para>
</sect2>		</sect2>

<sect2 xml:id="po-translations-tips-verbatim">		<sect2 xml:id="po-translations-tips-verbatim">
<title>不要翻譯的標籤</title>		<title>不要翻譯的標籤</title>

<para>有些標籤的內容要一字不差地保留，不要翻譯。</para>		<para>有些標籤的內容要一字不差地保留，不要翻譯。</para>

<itemizedlist xml:id="po-translations-tips-verbatim-list">		<itemizedlist xml:id="po-translations-tips-verbatim-list">
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines	<prompt>%</prompt> <userinput>make po</userinput></screen>

<listitem>		<listitem>
<para><tag class="starttag">varname</tag></para>		<para><tag class="starttag">varname</tag></para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect2>		</sect2>

<sect2 xml:id="po-translations-literal-dollar">		<sect2 xml:id="po-translations-literal-dollar">
<title xml:lang="en"><literal>$FreeBSD$</literal>		<title><literal>$FreeBSD$</literal> 字串</title>
Strings</title>

<para xml:lang="en">The $FreeBSD$ version strings used in		<para>在檔案中使用到的 $FreeBSD$ 版本字串都需要特別處理，例如在 <xref linkend="po-translations-creating-example"/>，使用這些字串的用意並非要展開成版本。英文的說明文件會使用 <literal>&dollar;</literal> Entity 來避免在檔案中用到錢字符號：</para>
files require special handling. In examples like
<xref linkend="po-translations-creating-example"/>, these
strings are not meant to be expanded. The English documents
use <literal>&dollar;</literal> entities to avoid
including actual literal dollar signs in the file:</para>

<programlisting>&dollar;FreeBSD&dollar;</programlisting>		<programlisting>&dollar;FreeBSD&dollar;</programlisting>

<para>版本控制符號不會把 <literal>&dollar;</literal> entities 看成金錢符號，所以不會把字串展開成版本字串。</para>		<para>版本控制符號不會把 <literal>&dollar;</literal> entities 看成金錢符號，所以不會把字串展開成版本字串。</para>

<para>當 <acronym>PO</acronym> 檔建立後，範例中的 <literal>&dollar;</literal> entities 被實際的金錢符號取代。當檔案提交時，產生的 <literal>$FreeBSD$</literal> 將會被版本控制系統展開。</para>		<para>當 <acronym>PO</acronym> 檔建立之後，在範例中使用到的 <literal>&dollar;</literal> Entity 會被取代成實際的錢字符號，這會使的 <literal>$FreeBSD$</literal> 字串在提交時錯誤的被版本控制系統展開成版本字串。</para>

<para>英文文件用的相同技術可以被用在翻譯上。翻譯時用 <literal>&dollar;</literal> 來取代金錢符號，輸入到 <acronym>PO</acronym> 檔編輯器：</para>		<para>在英文文件上使用的方法也可以用在翻譯上，翻譯時在 <acronym>PO</acronym> 編輯器用 <literal>&dollar;</literal> 來取代金錢符號：</para>

<programlisting>&dollar;FreeBSD&dollar;</programlisting>		<programlisting>&dollar;FreeBSD&dollar;</programlisting>
</sect2>		</sect2>

<!--		<!--
<sect2 xml:id="po-translations-tips-makefile">		<sect2 xml:id="po-translations-tips-makefile">
<title>Modifying the <filename>Makefile</filename></title>		<title>Modifying the <filename>Makefile</filename></title>

Show All 39 Lines	<sect1 xml:id="po-translations-building">

<example xml:id="po-translations-building-example">		<example xml:id="po-translations-building-example">
<title>編譯西班牙文 Porter 手冊</title>		<title>編譯西班牙文 Porter 手冊</title>

<para>編譯和預覽之前範例翻譯的西班牙文版 Porter 手冊</para>		<para>編譯和預覽之前範例翻譯的西班牙文版 Porter 手冊</para>

<procedure>		<procedure>
<step>		<step>
<para>編譯翻譯好的文件。因為原文是書籍，所以產生的文件是<filename>book.xml</filename>。</para>		<para>編譯翻譯好的文件。因為原文是書籍，所以產生的文件是 <filename>book.xml</filename>。</para>

<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>		<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
<prompt>%</prompt> <userinput>make tran</userinput></screen>		<prompt>%</prompt> <userinput>make tran</userinput></screen>
</step>		</step>

<step>		<step>
<para>轉換翻譯好的<filename>book.xml</filename>成<acronym>HTML</acronym>並用<application>Firefox</application>來瀏覽。這和英文版是相同的步驟，其他 <varname>FORMATS</varname> 也可以這樣做。請見<xref linkend="doc-build-rendering-common-formats"/> 。</para>		<para>轉換翻譯好的 <filename>book.xml</filename> 成 <acronym>HTML</acronym> 並用 <application>Firefox</application> 來瀏覽。這和英文版是相同的步驟，其他 <varname>FORMATS</varname> 也可以這樣做。請見 <xref linkend="doc-build-rendering-common-formats"/> 。</para>

<screen><prompt>%</prompt> <userinput>make FORMATS=html</userinput>		<screen><prompt>%</prompt> <userinput>make FORMATS=html</userinput>
<prompt>%</prompt> <userinput>firefox book.html</userinput></screen>		<prompt>%</prompt> <userinput>firefox book.html</userinput></screen>
</step>		</step>
</procedure>		</procedure>
</example>		</example>
</sect1>		</sect1>

<sect1 xml:id="po-translations-submitting">		<sect1 xml:id="po-translations-submitting">
<title>提交新翻譯</title>		<title>提交新翻譯</title>

<para>準備要提交的新翻譯。這包含新增檔案到版本控制系統，對檔案設定額外的屬性，並建立 diff 來提交。</para>		<para>準備要提交的新翻譯。這包含新增檔案到版本控制系統，對檔案設定額外的屬性，並建立 diff 來提交。</para>

<para>範例中產生的 diff 檔可以被附加到 <link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">documentation bug report</link> 或 <link xlink:href="https://reviews.freebsd.org/">code review</link> 。</para>		<para>範例中產生的 diff 檔可以被附加到 <link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">文件問題回報 (Documentation bug report)</link> 或 <link xlink:href="https://reviews.freebsd.org/">程式碼審查 (Code review)</link> 。</para>

<example xml:id="po-translations-submitting-spanish">		<example xml:id="po-translations-submitting-spanish">
<title>NanoBSD 文章的西班牙文翻譯</title>		<title>NanoBSD 文章的西班牙文翻譯</title>

<procedure>		<procedure>
<step>		<step>
<para>增加 FreeBSD 版本字串註解到 <acronym>PO</acronym> 檔的第一行：</para>		<para>增加 FreeBSD 版本字串註解到 <acronym>PO</acronym> 檔的第一行：</para>

<programlisting xml:lang="en">#$FreeBSD$</programlisting>		<programlisting xml:lang="en">#$FreeBSD$</programlisting>
</step>		</step>

<step>		<step>
<para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統：</para>		<para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統：</para>

<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>		<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>
<prompt>%</prompt> <userinput>ls</userinput>		<prompt>%</prompt> <userinput>ls</userinput>
Makefile article.xml es_ES.po		Makefile article.xml es_ES.po
<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput>		<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput>
A Makefile		A Makefile
A article.xml		A article.xml
A es_ES.po</screen>		A es_ES.po</screen>
</step>		</step>

<step>		<step>
<para>設定這些檔案的 <application>Subversion</application> <literal>svn:keywords</literal> 屬性到 <literal>FreeBSD=%H</literal>，讓提交時 <literal>$FreeBSD$</literal> 字串可以被展開成路徑、版本、日期和作者。</para>		<para>在這些檔案設定 <application>Subversion</application> <literal>svn:keywords</literal> 屬性為 <literal>FreeBSD=%H</literal> 讓 <literal>$FreeBSD$</literal> 字串可以在提交時被展開成為路徑、修訂、日期以及作者：</para>

<screen><prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput>		<screen><prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput>
property 'svn:keywords' set on 'Makefile'		property 'svn:keywords' set on 'Makefile'
property 'svn:keywords' set on 'article.xml'		property 'svn:keywords' set on 'article.xml'
property 'svn:keywords' set on 'es_ES.po'</screen>		property 'svn:keywords' set on 'es_ES.po'</screen>
</step>		</step>

<step>		<step>
<para>設定檔案的<acronym>MIME</acronym> 類型。書籍和文章是 <literal>text/xml</literal> ，<acronym>PO</acronym> 檔是 <literal>text/x-gettext-translation</literal> 。</para>		<para>設定檔案的 <acronym>MIME</acronym> 類型。書籍和文章是 <literal>text/xml</literal> ，<acronym>PO</acronym> 檔是 <literal>text/x-gettext-translation</literal> 。</para>

<screen><prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput>		<screen><prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput>
property 'svn:mime-type' set on 'es_ES.po'		property 'svn:mime-type' set on 'es_ES.po'
<prompt>%</prompt> <userinput>svn propset svn:mime-type text/xml article.xml</userinput>		<prompt>%</prompt> <userinput>svn propset svn:mime-type text/xml article.xml</userinput>
property 'svn:mime-type' set on 'article.xml'</screen>		property 'svn:mime-type' set on 'article.xml'</screen>
</step>		</step>

<step>		<step>
Show All 23 Lines
Makefile article.xml ko_KR.po		Makefile article.xml ko_KR.po
<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput>		<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput>
A Makefile		A Makefile
A article.xml		A article.xml
A ko_KR.po</screen>		A ko_KR.po</screen>
</step>		</step>

<step>		<step>
<para>設定這些檔案的 <application>Subversion</application> <literal>svn:keywords</literal> 屬性到 <literal>FreeBSD=%H</literal>，讓提交時 <literal>$FreeBSD$</literal> 字串可以被展開成路徑、版本、日期和作者。</para>		<para>在這些檔案設定 <application>Subversion</application> <literal>svn:keywords</literal> 屬性為 <literal>FreeBSD=%H</literal> 讓 <literal>$FreeBSD$</literal> 字串可以在提交時被展開成為路徑、修訂、日期以及作者：</para>

<screen><prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput>		<screen><prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput>
property 'svn:keywords' set on 'Makefile'		property 'svn:keywords' set on 'Makefile'
property 'svn:keywords' set on 'article.xml'		property 'svn:keywords' set on 'article.xml'
property 'svn:keywords' set on 'ko_KR.po'</screen>		property 'svn:keywords' set on 'ko_KR.po'</screen>
</step>		</step>

<step>		<step>
▲ Show 20 Lines • Show All 62 Lines • ▼ Show 20 Lines	<para xml:lang="en">Technical documentation can be improved by consistent use of
several principles. Most of these can be classified into three		several principles. Most of these can be classified into three
goals: <emphasis>be clear</emphasis>,		goals: <emphasis>be clear</emphasis>,
<emphasis>be complete</emphasis>, and		<emphasis>be complete</emphasis>, and
<emphasis>be concise</emphasis>. These goals can conflict with		<emphasis>be concise</emphasis>. These goals can conflict with
each other. Good writing consists of a balance between		each other. Good writing consists of a balance between
them.</para>		them.</para>

<sect2 xml:id="writing-style-be-clear">		<sect2 xml:id="writing-style-be-clear">
<title xml:lang="en">Be Clear</title>		<title>要明瞭</title>

<para xml:lang="en">Clarity is extremely important. The reader may be a		<para xml:lang="en">Clarity is extremely important. The reader may be a
novice, or reading the document in a second language. Strive		novice, or reading the document in a second language. Strive
for simple, uncomplicated text that clearly explains the		for simple, uncomplicated text that clearly explains the
concepts.</para>		concepts.</para>

<para xml:lang="en">Avoid flowery or embellished speech, jokes, or colloquial		<para xml:lang="en">Avoid flowery or embellished speech, jokes, or colloquial
expressions. Write as simply and clearly as possible. Simple		expressions. Write as simply and clearly as possible. Simple
Show All 29 Lines	<chapter version="5.0" xml:id="writing-style">
create doubt in the reader.</para>		create doubt in the reader.</para>

<para xml:lang="en">Similarly, give instructions as imperative commands: not		<para xml:lang="en">Similarly, give instructions as imperative commands: not
<quote>you should do this</quote>, but merely		<quote>you should do this</quote>, but merely
<quote>do this</quote>.</para>		<quote>do this</quote>.</para>
</sect2>		</sect2>

<sect2 xml:id="writing-style-be-complete">		<sect2 xml:id="writing-style-be-complete">
<title xml:lang="en">Be Complete</title>		<title>要完整</title>

<para xml:lang="en">Do not make assumptions about the reader's abilities or		<para xml:lang="en">Do not make assumptions about the reader's abilities or
skill level. Tell them what they need to know. Give links to		skill level. Tell them what they need to know. Give links to
other documents to provide background information without		other documents to provide background information without
having to recreate it. Put yourself in the reader's place,		having to recreate it. Put yourself in the reader's place,
anticipate the questions they will ask, and answer		anticipate the questions they will ask, and answer
them.</para>		them.</para>
</sect2>		</sect2>

<sect2 xml:id="writing-style-be-concise">		<sect2 xml:id="writing-style-be-concise">
<title xml:lang="en">Be Concise</title>		<title>要簡潔</title>

<para xml:lang="en">While features should be documented completely, sometimes		<para xml:lang="en">While features should be documented completely, sometimes
there is so much information that the reader cannot easily		there is so much information that the reader cannot easily
find the specific detail needed. The balance between being		find the specific detail needed. The balance between being
complete and being concise is a challenge. One approach is to		complete and being concise is a challenge. One approach is to
have an introduction, then a <quote>quick start</quote>		have an introduction, then a <quote>quick start</quote>
section that describes the most common situation, followed by		section that describes the most common situation, followed by
an in-depth reference section.</para>		an in-depth reference section.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="writing-style-guidelines">		<sect1 xml:id="writing-style-guidelines">
<title xml:lang="en">Guidelines</title>		<title>準則</title>

<para xml:lang="en">To promote consistency between the myriad authors of the		<para xml:lang="en">To promote consistency between the myriad authors of the
FreeBSD documentation, some guidelines have been drawn up for		FreeBSD documentation, some guidelines have been drawn up for
authors to follow.</para>		authors to follow.</para>

<variablelist>		<variablelist>
<varlistentry>		<varlistentry>
<term xml:lang="en">Use American English Spelling</term>		<term>使用美式英語拼寫</term>

<listitem>		<listitem>
<para xml:lang="en">There are several variants of English, with different		<para xml:lang="en">There are several variants of English, with different
spellings for the same word. Where spellings differ, use		spellings for the same word. Where spellings differ, use
the American English variant. <quote>color</quote>, not		the American English variant. <quote>color</quote>, not
<quote>colour</quote>, <quote>rationalize</quote>, not		<quote>colour</quote>, <quote>rationalize</quote>, not
<quote>rationalise</quote>, and so on.</para>		<quote>rationalise</quote>, and so on.</para>

<note>		<note>
<para xml:lang="en">The use of British English may be accepted in the		<para xml:lang="en">The use of British English may be accepted in the
case of a contributed article, however the spelling must		case of a contributed article, however the spelling must
be consistent within the whole document. The other		be consistent within the whole document. The other
documents such as books, web site, manual pages, etc.		documents such as books, web site, manual pages, etc.
will have to use American English.</para>		will have to use American English.</para>
</note>		</note>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry>		<varlistentry>
<term xml:lang="en">Do not use contractions</term>		<term>不要使用縮寫式</term>

<listitem>		<listitem>
<para xml:lang="en">Do not use contractions. Always spell the phrase out		<para xml:lang="en">Do not use contractions. Always spell the phrase out
in full. <quote>Don't use contractions</quote> is		in full. <quote>Don't use contractions</quote> is
wrong.</para>		wrong.</para>

<para xml:lang="en">Avoiding contractions makes for a more formal tone, is		<para xml:lang="en">Avoiding contractions makes for a more formal tone, is
more precise, and is slightly easier for		more precise, and is slightly easier for
translators.</para>		translators.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry>		<varlistentry>
<term xml:lang="en">Use the serial comma</term>		<term>使用逗號串行</term>

<listitem>		<listitem>
<para xml:lang="en">In a list of items within a paragraph, separate each		<para xml:lang="en">In a list of items within a paragraph, separate each
item from the others with a comma. Separate the last item		item from the others with a comma. Separate the last item
from the others with a comma and the word		from the others with a comma and the word
<quote>and</quote>.</para>		<quote>and</quote>.</para>

<para xml:lang="en">For example:</para>		<para xml:lang="en">For example:</para>
Show All 12 Lines	<listitem>

<blockquote>		<blockquote>
<para xml:lang="en">This is a list of one, two, and three items.</para>		<para xml:lang="en">This is a list of one, two, and three items.</para>
</blockquote>		</blockquote>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry>		<varlistentry>
<term xml:lang="en">Avoid redundant phrases</term>		<term>避免多餘的語句</term>

<listitem>		<listitem>
<para xml:lang="en">Do not use redundant phrases. In particular,		<para xml:lang="en">Do not use redundant phrases. In particular,
<quote>the command</quote>, <quote>the file</quote>, and		<quote>the command</quote>, <quote>the file</quote>, and
<quote>man command</quote> are often redundant.</para>		<quote>man command</quote> are often redundant.</para>

<para xml:lang="en">For example, commands:</para>		<para xml:lang="en">For example, commands:</para>

Show All 30 Lines	<listitem>

<informalexample>		<informalexample>
<para xml:lang="en">Right: See <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>		<para xml:lang="en">Right: See <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</informalexample>		</informalexample>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry>		<varlistentry>
<term xml:lang="en">Two spaces between sentences</term>		<term>在句子之間空兩個空白</term>

<listitem>		<listitem>
<para xml:lang="en">Always use two spaces between sentences, as it		<para xml:lang="en">Always use two spaces between sentences, as it
improves readability and eases use of tools such as		improves readability and eases use of tools such as
<application>Emacs</application>.</para>		<application>Emacs</application>.</para>

<para xml:lang="en">A period and spaces followed by a capital letter		<para xml:lang="en">A period and spaces followed by a capital letter
does not always mark a new sentence, especially in names.		does not always mark a new sentence, especially in names.
<quote>Jordan K. Hubbard</quote> is a good example. It		<quote>Jordan K. Hubbard</quote> is a good example. It
has a capital <literal>H</literal> following a period and		has a capital <literal>H</literal> following a period and
a space, and is certainly not a new sentence.</para>		a space, and is certainly not a new sentence.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>
</variablelist>		</variablelist>

<para xml:lang="en">For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of		<para xml:lang="en">For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of
Style</link>, by William Strunk.</para>		Style</link>, by William Strunk.</para>
</sect1>		</sect1>

<sect1 xml:id="writing-style-guide">		<sect1 xml:id="writing-style-guide">
<title>風格指南</title>		<title>風格指南</title>

<para>由於文件是由眾多作者所維護，為了保持寫作風格的一貫性，請遵守下列撰寫風格慣例。</para>		<para>由於說明文件是由眾多作者所維護，為了保持寫作風格的一貫性，請遵守下列撰寫風格慣例。</para>

<sect2>		<sect2>
<title>大小寫</title>		<title>大小寫</title>

<para>Tag 的部份都是用小寫字母，譬如是用 <tag>para</tag> ，<emphasis>而非</emphasis><tag>PARA</tag>。</para>		<para>Tag 的部份都是用小寫字母，譬如是用 <tag>para</tag> ，<emphasis>而非</emphasis><tag>PARA</tag>。</para>

<para>而 SGML 內文則是用大寫字母表示，像是： <literal><!ENTITY…></literal> 及 <literal><!DOCTYPE…></literal>， <emphasis>而不是</emphasis> <literal><!entity…></literal> 及 <literal><!doctype…></literal>。</para>		<para>而 SGML 內文則是用大寫字母表示，像是： <literal><!ENTITY…></literal> 及 <literal><!DOCTYPE…></literal>， <emphasis>而不是</emphasis> <literal><!entity…></literal> 及 <literal><!doctype…></literal>。</para>
</sect2>		</sect2>

<sect2 xml:id="writing-style-acronyms">		<sect2 xml:id="writing-style-acronyms">
<title xml:lang="en">Acronyms</title>		<title>縮寫</title>

<para>縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法，比如：<quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>。定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙，除非使用完整詞彙可以更能表達語意)來表達即可。通常每本書只會第一次提到時，才會列出完整詞彙，但若您高興也可以在每章第一次提到時又列出完整詞彙。</para>		<para>縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法，比如：<quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>。定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙，除非使用完整詞彙可以更能表達語意)來表達即可。通常每本書只會第一次提到時，才會列出完整詞彙，但若您高興也可以在每章第一次提到時又列出完整詞彙。</para>

<para>所有縮寫要包在<tag>acronym</tag>標籤內。</para>		<para>所有縮寫要包在<tag>acronym</tag>標籤內。</para>
</sect2>		</sect2>

<sect2 xml:id="writing-style-indentation">		<sect2 xml:id="writing-style-indentation">
<title>縮排</title>		<title>縮排</title>
▲ Show 20 Lines • Show All 50 Lines • ▼ Show 20 Lines	<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &os;
these guidelines can be found in		these guidelines can be found in
<xref linkend="editor-config"/>.</para>		<xref linkend="editor-config"/>.</para>
</sect2>		</sect2>

<sect2 xml:id="writing-style-tag-style">		<sect2 xml:id="writing-style-tag-style">
<title>標籤風格</title>		<title>標籤風格</title>

<sect3 xml:id="writing-style-tag-style-spacing">		<sect3 xml:id="writing-style-tag-style-spacing">
<title>標籤空行</title>		<title>標籤間距</title>

<para>同一縮排等級的標籤要以空一行來做區隔，而不同縮排等級的則不必。比如：</para>		<para>同一縮排階層的標籤要以空一行來做區隔，而不同縮排階層的則不必。比如：</para>

<informalexample>		<informalexample>
<programlisting><tag class="starttag">article lang='en'</tag>		<programlisting><tag class="starttag">article lang='en'</tag>
<tag class="starttag">articleinfo</tag>		<tag class="starttag">articleinfo</tag>
<tag class="starttag">title</tag>NIS<tag class="endtag">title</tag>		<tag class="starttag">title</tag>NIS<tag class="endtag">title</tag>

<tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag>		<tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag>

Show All 15 Lines	<tag class="starttag">sect1</tag>

<tag class="starttag">para</tag>...<tag class="endtag">para</tag>		<tag class="starttag">para</tag>...<tag class="endtag">para</tag>
<tag class="endtag">sect1</tag>		<tag class="endtag">sect1</tag>
<tag class="endtag">article</tag></programlisting>		<tag class="endtag">article</tag></programlisting>
</informalexample>		</informalexample>
</sect3>		</sect3>

<sect3 xml:id="writing-style-tag-style-separating">		<sect3 xml:id="writing-style-tag-style-separating">
<title>標籤的分行</title>		<title>分隔標籤</title>

<para>像是 <tag>itemizedlist</tag> 這類的標籤事實上本身不含任何文字資料，必須得由其他標籤來補充內文。這類的標籤會獨用一整行。</para>		<para>像是 <tag>itemizedlist</tag> 這類的標籤事實上本身不含任何文字資料，必須得由其他標籤來補充內文。這類的標籤會獨用一整行。</para>

<para>另外，像是 <tag>para</tag> 及 <tag>term</tag> 這類的標籤並不需搭配其他標籤，就可附上文字資料，並且在標籤後面的<emphasis>同一行</emphasis>內即可立即寫上這些內文。</para>		<para>另外，像是 <tag>para</tag> 及 <tag>term</tag> 這類的標籤並不需搭配其他標籤，就可附上文字資料，並且在標籤後面的<emphasis>同一行</emphasis>內即可立即寫上這些內文。</para>

<para>當然，這兩類的標籤結尾時也是跟上面道理相同。</para>		<para>當然，這兩類的標籤結尾時也是跟上面道理相同。</para>

<para>不過，當上述這兩種標籤混用時，會有很明顯的困擾。</para>		<para>不過，當上述這兩種標籤混用時，會有很明顯的困擾。</para>

<para>當第一類標籤的後面接上第二類標籤的話，那麼要把這兩類標籤各自分行來寫。後者標籤的段落，也是需要做適當縮排調整。</para>		<para>當第一類標籤的後面接上第二類標籤的話，那麼要把這兩類標籤各自分行來寫。後者標籤的段落，也是需要做適當縮排調整。</para>

<para>而第二類標籤結尾時，可以與第一類標籤的結尾放在同一行。</para>		<para>而第二類標籤結尾時，可以與第一類標籤的結尾放在同一行。</para>
</sect3>		</sect3>
</sect2>		</sect2>

<sect2 xml:id="writing-style-whitespace-changes">		<sect2 xml:id="writing-style-whitespace-changes">
<title>空白的更改</title>		<title>空白變更</title>

<para><emphasis>在提交修改時，請別在修改內容的同時，也一起更改編排格式。</emphasis>。</para>		<para><emphasis>在提交修改時，請別在修改內容的同時也一起更改編排格式</emphasis>。</para>

<para>如此一來，像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容，而不用費心思去判斷該行的改變，是由於格式重排或者內容異動。</para>		<para>如此一來，像是翻譯團隊才能迅速找出你改了哪些內容，而不用費心思去判斷該行的改變，是由於格式重排或者內容異動。</para>

<para>舉例說明，若要在某段加上兩個句子，如此一來該段落的某行勢必會超出 80 縱列，這時請先 commmit 修改。接著，再修飾過長行落的換行，然後再次 commit 之。而第二次的 commit 紀錄，請明確說明這只是 whitespace-only (修改空白而已) 的更改，如此一來，翻譯團隊就可以忽略第二次 commit 了。</para>		<para>舉例說明，若要在某段加上兩個句子，如此一來該段落的某行勢必會超出 80 縱列，這時請先 commmit 修改。接著，再修飾過長行落的換行，然後再次 commit 之。而第二次的 commit 紀錄，請明確說明這只是 whitespace-only (修改空白而已) 的更改，如此一來，翻譯團隊就可以忽略第二次 commit 了。</para>
</sect2>		</sect2>

<sect2 xml:id="writing-style-nonbreaking-space">		<sect2 xml:id="writing-style-nonbreaking-space">
<title>Nonbreaking space</title>		<title>不斷行空白</title>

<para>請避免一些情況下的斷行：造成版面醜醜的、或是須連貫表達的同一句子。斷行的情況會隨所閱讀的工具不同而有所不同。尤其是透過純文字瀏覽器來看 HTML 時會更明顯看到類似下面這樣不好的編排段落：</para>		<para>請避免一些情況下的斷行：造成版面醜醜的、或是須連貫表達的同一句子。斷行的情況會隨所閱讀的工具不同而有所不同。尤其是透過純文字瀏覽器來看 HTML 說明文件時會更明顯看到類似下面這樣不好的編排段落：</para>

<literallayout class="monospaced">Data capacity ranges from 40 MB to 15		<literallayout class="monospaced">Data capacity ranges from 40 MB to 15
GB。 Hardware compression …</literallayout>		GB。 Hardware compression …</literallayout>

<para>請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行，以下示範如何使用 nonbreaking spaces：</para>		<para>請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行，以下示範如何使用不斷行空白：</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para>在數字與單位之間：</para>		<para>在數字與單位之間：</para>
<programlisting>57600&nbsp;bps</programlisting>		<programlisting>57600&nbsp;bps</programlisting>
</listitem>		</listitem>

<listitem>		<listitem>
<para>在程式名稱與版號之間：</para>		<para>在程式名稱與版號之間：</para>
<programlisting>&os;&nbsp;9.2</programlisting>		<programlisting>&os;&nbsp;9.2</programlisting>
</listitem>		</listitem>

<listitem>		<listitem>
<para>multiword 之間 (使用時請小心，像是 <quote>The FreeBSD Brazilian Portuguese Documentation Project</quote> 這類由三到四個字所組成的，則不用加。)：</para>		<para>多個單字的名稱之間 (在套用到如 <quote>The FreeBSD Brazilian Portuguese Documentation Project</quote> 這種由三到四個字所組成的名稱時請小心)：</para>
<programlisting>Sun&nbsp;Microsystems</programlisting>		<programlisting>Sun&nbsp;Microsystems</programlisting>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="writing-style-word-list">		<sect1 xml:id="writing-style-word-list">
<title>詞彙表</title>		<title>詞彙表</title>

<para>以下詞彙表列出使用在 FreeBSD 文件的正確拼法和大小寫。若找不到要找的詞彙，請詢問 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link> 。</para>		<para>以下詞彙表列出使用在 FreeBSD 文件的正確拼法和大小寫。若找不到要找的詞彙，請詢問 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link> 。</para>

<informaltable frame="none" pgwide="0">		<informaltable frame="none" pgwide="0">
<tgroup cols="3">		<tgroup cols="3">
<thead>		<thead>
<row>		<row>
<entry>Word</entry>		<entry>字詞</entry>
<entry>XML Code</entry>		<entry>XML 程式碼</entry>
<entry>Notes</entry>		<entry>備註</entry>
</row>		</row>
</thead>		</thead>

<tbody>		<tbody>
<row>		<row>
<entry>CD-ROM</entry>		<entry>CD-ROM</entry>

<entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry>		<entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry>
▲ Show 20 Lines • Show All 58 Lines • ▼ Show 20 Lines	<row>
<entry>stderr</entry>		<entry>stderr</entry>
<entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry>		<entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry>
</row>		</row>

<row>		<row>
<entry>Subversion</entry>		<entry>Subversion</entry>

<entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry>		<entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry>
<entry>不要用大寫<literal>SVN</literal>來表示 Subversion應用程式。以<tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>來表示指令。</entry>		<entry>不要用大寫 <literal>SVN</literal> 來表示 Subversion 應用程式。若要表示指令，請使用 <tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>。</entry>
</row>		</row>

<row>		<row>
<entry xml:lang="en"><trademark class="registered">UNIX</trademark></entry>		<entry xml:lang="en"><trademark class="registered">UNIX</trademark></entry>
<entry xml:lang="en"><literal>&unix;</literal></entry>		<entry xml:lang="en"><literal>&unix;</literal></entry>
</row>		</row>

<row>		<row>
<entry>userland</entry>		<entry>userland</entry>
<entry/>		<entry/>
<entry>指user space，不是核心。</entry>		<entry>指那些要會用在使用者空間 (User space) 而非核心的東西。</entry>
</row>		</row>

<row>		<row>
<entry>web server</entry>		<entry>web server</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>
Show All 26 Lines	<!-- Copyright (c) 2013 Warren Block
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR		CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,		OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.		EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<chapter version="5.0" xml:id="editor-config">		<chapter version="5.0" xml:id="editor-config">

<title xml:lang="en">Editor Configuration</title>		<title>編輯器設定</title>

<para xml:lang="en">Adjusting text editor configuration can make working on		<para xml:lang="en">Adjusting text editor configuration can make working on
document files quicker and easier, and help documents conform to		document files quicker and easier, and help documents conform to
<acronym>FDP</acronym> guidelines.</para>		<acronym>FDP</acronym> guidelines.</para>

<sect1 xml:id="editor-config-vim">		<sect1 xml:id="editor-config-vim">
<title xml:lang="en"><application>Vim</application></title>		<title xml:lang="en"><application>Vim</application></title>

<para xml:lang="en">Install from <package>editors/vim</package> or		<para xml:lang="en">Install from <package>editors/vim</package> or
<package>editors/vim-lite</package>, then follow the		<package>editors/vim-lite</package>, then follow the
configuration instructions in		configuration instructions in
<xref linkend="editor-config-vim-config"/>.</para>		<xref linkend="editor-config-vim-config"/>.</para>

<sect2 xml:id="editor-config-vim-use">		<sect2 xml:id="editor-config-vim-use">
<title xml:lang="en">Use</title>		<title>使用</title>

<para xml:lang="en">Press <keycap>P</keycap> to reformat paragraphs or text		<para xml:lang="en">Press <keycap>P</keycap> to reformat paragraphs or text
that has been selected in Visual mode. Press		that has been selected in Visual mode. Press
<keycap>T</keycap> to replace groups of eight spaces with a		<keycap>T</keycap> to replace groups of eight spaces with a
tab.</para>		tab.</para>
</sect2>		</sect2>

<sect2 xml:id="editor-config-vim-config">		<sect2 xml:id="editor-config-vim-config">
<title xml:lang="en">Configuration</title>		<title>設置</title>

<para xml:lang="en">Edit <filename>~/.vimrc</filename>, adding these		<para xml:lang="en">Edit <filename>~/.vimrc</filename>, adding these
lines to the end of the file:</para>		lines to the end of the file:</para>

<programlisting xml:lang="en">if has("autocmd")		<programlisting xml:lang="en">if has("autocmd")
au BufNewFile,BufRead .sgml,.ent,.xsl,.xml call Set_SGML()		au BufNewFile,BufRead .sgml,.ent,.xsl,.xml call Set_SGML()
au BufNewFile,BufRead *.[1-9] call ShowSpecial()		au BufNewFile,BufRead *.[1-9] call ShowSpecial()
endif " has(autocmd)		endif " has(autocmd)
Show All 36 Lines	endfunction " Set_SGML()</programlisting>

<sect1 xml:id="editor-config-emacs">		<sect1 xml:id="editor-config-emacs">
<title xml:lang="en"><application>Emacs</application></title>		<title xml:lang="en"><application>Emacs</application></title>

<para xml:lang="en">Install from <package>editors/emacs</package> or		<para xml:lang="en">Install from <package>editors/emacs</package> or
<package>editors/emacs-devel</package>.</para>		<package>editors/emacs-devel</package>.</para>

<sect2 xml:id="editor-config-emacs-validation">		<sect2 xml:id="editor-config-emacs-validation">
<title xml:lang="en">Validation</title>		<title>檢驗</title>

<para xml:lang="en">Emacs's nxml-mode uses compact relax NG schemas for		<para xml:lang="en">Emacs's nxml-mode uses compact relax NG schemas for
validating XML. A compact relax NG schema for FreeBSD's		validating XML. A compact relax NG schema for FreeBSD's
extension to DocBook 5.0 is included in the documentation		extension to DocBook 5.0 is included in the documentation
repository. To configure nxml-mode to validate using this		repository. To configure nxml-mode to validate using this
schema, create		schema, create
<filename>~/.emacs.d/schema/schemas.xml</filename> and add		<filename>~/.emacs.d/schema/schemas.xml</filename> and add
these lines to the file:</para>		these lines to the file:</para>

<programlisting xml:lang="en"><tag class="starttag">locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"</tag>		<programlisting xml:lang="en"><tag class="starttag">locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"</tag>
<tag class="starttag">documentElement localName="section" typeId="DocBook"</tag>		<tag class="starttag">documentElement localName="section" typeId="DocBook"</tag>
<tag class="starttag">documentElement localName="chapter" typeId="DocBook"</tag>		<tag class="starttag">documentElement localName="chapter" typeId="DocBook"</tag>
<tag class="starttag">documentElement localName="article" typeId="DocBook"</tag>		<tag class="starttag">documentElement localName="article" typeId="DocBook"</tag>
<tag class="starttag">documentElement localName="book" typeId="DocBook"</tag>		<tag class="starttag">documentElement localName="book" typeId="DocBook"</tag>
<tag class="starttag">typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc"</tag>		<tag class="starttag">typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc"</tag>
<tag class="endtag">locatingRules</tag></programlisting>		<tag class="endtag">locatingRules</tag></programlisting>

</sect2>		</sect2>

<sect2 xml:id="editor-config-emacs-igor">		<sect2 xml:id="editor-config-emacs-igor">
<title xml:lang="en">Automated Proofreading with Flycheck and Igor</title>		<title>使用 Flycheck 和 Igor 自動化校對</title>

<para xml:lang="en">The Flycheck package is available from Milkypostman's		<para xml:lang="en">The Flycheck package is available from Milkypostman's
Emacs Lisp Package Archive (<acronym>MELPA</acronym>). If		Emacs Lisp Package Archive (<acronym>MELPA</acronym>). If
<acronym>MELPA</acronym> is not already in Emacs's		<acronym>MELPA</acronym> is not already in Emacs's
packages-archives, it can be added by evaluating</para>		packages-archives, it can be added by evaluating</para>

<programlisting xml:lang="en">(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)</programlisting>		<programlisting xml:lang="en">(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)</programlisting>

Show All 22 Lines	http://www.freshports.org/textproc/igor/."

(add-to-list 'flycheck-checkers 'igor 'append)</programlisting>		(add-to-list 'flycheck-checkers 'igor 'append)</programlisting>

<para xml:lang="en">Again, add these lines to Emacs's initialization file to		<para xml:lang="en">Again, add these lines to Emacs's initialization file to
make the changes permanent.</para>		make the changes permanent.</para>
</sect2>		</sect2>

<sect2 xml:id="editor-config-emacs-specifc">		<sect2 xml:id="editor-config-emacs-specifc">
<title xml:lang="en">FreeBSD Documentation Specific Settings</title>		<title>FreeBSD 說明文件特定的設定</title>

<para xml:lang="en">To apply settings specific to the FreeBSD documentation		<para xml:lang="en">To apply settings specific to the FreeBSD documentation
project, create <filename>.dir-locals.el</filename> in the		project, create <filename>.dir-locals.el</filename> in the
root directory of the documentation repository and add these		root directory of the documentation repository and add these
lines to the file:</para>		lines to the file:</para>

<programlisting xml:lang="en">;;; Directory Local Variables		<programlisting xml:lang="en">;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")		;;; For more information see (info "(emacs) Directory Variables")
Show All 11 Lines	((nxml-mode
<sect1 xml:id="editor-config-nano">		<sect1 xml:id="editor-config-nano">
<title xml:lang="en"><application>nano</application></title>		<title xml:lang="en"><application>nano</application></title>

<para xml:lang="en">Install from		<para xml:lang="en">Install from
<package>editors/nano</package> or		<package>editors/nano</package> or
<package>editors/nano-devel</package>.</para>		<package>editors/nano-devel</package>.</para>

<sect2 xml:id="editor-config-nano-config">		<sect2 xml:id="editor-config-nano-config">
<title xml:lang="en">Configuration</title>		<title>設置</title>

<para xml:lang="en">Copy the sample <acronym>XML</acronym> syntax highlight		<para xml:lang="en">Copy the sample <acronym>XML</acronym> syntax highlight
file to the user's home directory:</para>		file to the user's home directory:</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen>		<screen xml:lang="en"><prompt>%</prompt> <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen>

<para xml:lang="en">Add these lines to the new		<para xml:lang="en">Add these lines to the new
<filename>~/.nanorc</filename>.</para>		<filename>~/.nanorc</filename>.</para>
Show All 12 Lines
color ,yellow "^(.{71})\|(TAB.{63})\|(TAB{2}.{55})\|(TAB{3}.{47}).+$"</programlisting>		color ,yellow "^(.{71})\|(TAB.{63})\|(TAB{2}.{55})\|(TAB{3}.{47}).+$"</programlisting>

<para xml:lang="en">Process the file to create embedded tabs:</para>		<para xml:lang="en">Process the file to create embedded tabs:</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen>		<screen xml:lang="en"><prompt>%</prompt> <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen>
</sect2>		</sect2>

<sect2 xml:id="editor-config-nano-use">		<sect2 xml:id="editor-config-nano-use">
<title xml:lang="en">Use</title>		<title>使用</title>

<para xml:lang="en">Specify additional helpful options when running the		<para xml:lang="en">Specify additional helpful options when running the
editor:</para>		editor:</para>

<screen xml:lang="en"><prompt>%</prompt> <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen>		<screen xml:lang="en"><prompt>%</prompt> <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen>

<para xml:lang="en">Users of <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> can define an alias in		<para xml:lang="en">Users of <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> can define an alias in
<filename>~/.cshrc</filename> to automate these		<filename>~/.cshrc</filename> to automate these
▲ Show 20 Lines • Show All 45 Lines • ▼ Show 20 Lines	<chapter version="5.0" xml:id="see-also">
<title>他山之石</title>		<title>他山之石</title>

<para xml:lang="en">This document is deliberately not an exhaustive discussion of		<para xml:lang="en">This document is deliberately not an exhaustive discussion of
XML, the DTDs listed, and the FreeBSD Documentation Project. For		XML, the DTDs listed, and the FreeBSD Documentation Project. For
more information about these, you are encouraged to see the		more information about these, you are encouraged to see the
following web sites.</para>		following web sites.</para>

<sect1 xml:id="see-also-fdp">		<sect1 xml:id="see-also-fdp">
<title>FreeBSD 文件計劃</title>		<title>FreeBSD 說明文件計劃</title>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><link xlink:href="@@URL_RELPREFIX@@/docproj/index.html">FreeBSD 文件計劃網頁</link></para>		<para><link xlink:href="@@URL_RELPREFIX@@/docproj/index.html">FreeBSD 說明文件計劃網頁</link></para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">FreeBSD 使用手冊</link></para>		<para><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">FreeBSD 使用手冊</link></para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect1>		</sect1>

Show All 25 Lines	<sect1 xml:id="see-also-docbook">
<title>DocBook</title>		<title>DocBook</title>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><link xlink:href="http://www.oasis-open.org/docbook/">The DocBook 技術委員會</link>， DocBook DTD的維護者</para>		<para><link xlink:href="http://www.oasis-open.org/docbook/">The DocBook 技術委員會</link>， DocBook DTD的維護者</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><link xlink:href="http://www.docbook.org/">DocBook：The Definitive Guide</link>， DocBook DTD的線上文件。</para>		<para><link xlink:href="http://www.docbook.org/">DocBook：The Definitive Guide</link>， DocBook DTD 的線上說明文件。</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para xml:lang="en"><link xlink:href="http://docbook.sourceforge.net/">The DocBook		<para xml:lang="en"><link xlink:href="http://docbook.sourceforge.net/">The DocBook
Open Repository</link> contains DSSSL stylesheets and		Open Repository</link> contains DSSSL stylesheets and
other resources for people using DocBook</para>		other resources for people using DocBook</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
Show All 31 Lines	<!-- Copyright (c) 2000 Nik Clayton, All rights reserved.
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN		STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE		ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.		POSSIBILITY OF SUCH DAMAGE.

$FreeBSD$		$FreeBSD$
-->		-->
<appendix version="5.0" xml:id="examples">		<appendix version="5.0" xml:id="examples">

<title>舉例</title>		<title>範例</title>

<para xml:lang="en">These examples are not exhaustive—they do not contain		<para xml:lang="en">These examples are not exhaustive—they do not contain
all the elements that might be desirable to use, particularly in a		all the elements that might be desirable to use, particularly in a
document's front matter. For more examples of DocBook markup,		document's front matter. For more examples of DocBook markup,
examine the <acronym>XML</acronym> source for this and other		examine the <acronym>XML</acronym> source for this and other
documents available in the <application>Subversion</application>		documents available in the <application>Subversion</application>
<literal>doc</literal> repository, or available online starting at		<literal>doc</literal> repository, or available online starting at
<uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para>		<uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para>
▲ Show 20 Lines • Show All 120 Lines • Show Last 20 Lines