D6869.id.diff
No OneTemporary
Actions

Size

796 KB

Referenced Files

None

Subscribers

None

D6869.id.diff
View Options

This file is larger than 256 KB, so syntax highlighting was skipped.

	Index: head/zh_TW.UTF-8/books/fdp-primer/Makefile
	===================================================================
	--- head/zh_TW.UTF-8/books/fdp-primer/Makefile
	+++ head/zh_TW.UTF-8/books/fdp-primer/Makefile
	@@ -20,20 +20,6 @@

	# XML content
	SRCS= book.xml
	-SRCS+= overview/chapter.xml
	-SRCS+= psgml-mode/chapter.xml
	-SRCS+= see-also/chapter.xml
	-SRCS+= sgml-markup/chapter.xml
	-SRCS+= sgml-primer/chapter.xml
	-SRCS+= stylesheets/chapter.xml
	-SRCS+= structure/chapter.xml
	-SRCS+= doc-build/chapter.xml
	-SRCS+= the-website/chapter.xml
	-SRCS+= tools/chapter.xml
	-SRCS+= translations/chapter.xml
	-SRCS+= writing-style/chapter.xml
	-
	-SRCS+= examples/appendix.xml

	# Images from the cross-document image library
	IMAGES_LIB= callouts/1.png
	Index: head/zh_TW.UTF-8/books/fdp-primer/book.xml
	===================================================================
	--- head/zh_TW.UTF-8/books/fdp-primer/book.xml
	+++ head/zh_TW.UTF-8/books/fdp-primer/book.xml
	@@ -1,8 +1,32 @@
	<?xml version="1.0" encoding="utf-8"?>
	-<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
	-<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
	-]>
	+<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
	+<!ENTITY % chapters SYSTEM "chapters.ent">
	+<!--
	+ Creates entities for each chapter in the Documentation Project Primer.
	+ Each entity is named chap.foo, where foo is the value of the id
	+ attribute on that chapter, and corresponds to the name of the
	+ directory in which that chapter's .xml file is stored.
	+
	+ Chapters should be listed in the order in which they are referenced.
	+
	+ $FreeBSD$
	+--><!ENTITY chap.overview SYSTEM "overview/chapter.xml">
	+<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
	+<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml">
	+<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
	+<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml">
	+<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
	+<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml">
	+<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml">
	+<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml">
	+<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
	+<!ENTITY chap.translations SYSTEM "translations/chapter.xml">
	+<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml">
	+<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml">
	+<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml">
	+<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml">
	+<!ENTITY app.examples SYSTEM "examples/appendix.xml">
	+<!-- ENTITY index SYSTEM "index.xml" -->]>
	<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

	Redistribution and use in source (SGML DocBook) and 'compiled' forms
	@@ -33,71 +57,96 @@
	POSSIBILITY OF SUCH DAMAGE.

	$FreeBSD$
	- Original revision: 1.27
	-->
	-<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>


	<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>
	- <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">$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	- &legalnotice;
	+
	+<legalnotice xml:id="legalnotice">
	+ <title>版權</title>
	+
	+ <para xml:lang="en">Redistribution and use in source (XML DocBook) and 'compiled'
	+ forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions are
	+ met:</para>
	+
	+ <orderedlist>
	+ <listitem>
	+ <para xml:lang="en">Redistributions of source code (XML DocBook) must retain the
	+ above copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must
	+ reproduce the above copyright notice, this list of conditions and
	+ the following disclaimer in the documentation and/or other
	+ materials provided with the distribution.</para>
	+ </listitem>
	+ </orderedlist>
	+
	+ <important>
	+ <para xml:lang="en">THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION
	+ PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
	+ BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
	+ FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
	+ THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT,
	+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
	+ BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
	+ OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
	+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
	+ TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
	+ USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
	+ DAMAGE.</para>
	+ </important>
	+</legalnotice>
	+

	<abstract>
	- <para>感謝您參與 FreeBSD 文件計劃(簡稱：FDP, FreeBSD Documentation Project)，您的點滴貢獻，都相當寶貴。</para>
	+ <para>感謝您參與 FreeBSD 文件計劃，您的點滴貢獻，都相當寶貴。</para>

	- <para>本入手書內容包括：如何開始著手翻譯的各項細節，以及會用到的一些好用工具(包括：必備工具、輔助工具)
	- ，以及文件計畫的宗旨。</para>
	+ <para>本入手書內容包括：如何開始著手貢獻FreeBSD 文件計劃 (簡稱： <acronym>FDP</acronym> )的各項細節，以及會用到的一些工具、軟體，以及文件計畫的宗旨。</para>

	- <para>本文件還在草稿，尚未完稿。未完成的章節，我們會在章節名稱旁邊加註『<literal>*</literal> 』以作識別。</para>
	+ <para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para>
	</abstract>
	</info>

	<preface xml:id="preface">
	- <title>序言</title>
	+ <title>序</title>

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

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

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>帳號</entry>
	- <entry>提示符號(Prompt)</entry>
	+ <entry>提示符號</entry>
	</row>
	</thead>

	<tbody>
	<row>
	- <entry>普通帳號</entry>
	- <entry>&prompt.user;</entry>
	+ <entry>一般使用者</entry>
	+ <entry><prompt>%</prompt></entry>
	</row>

	<row>
	<entry><systemitem class="username">root</systemitem></entry>
	- <entry>&prompt.root;</entry>
	+ <entry><prompt>#</prompt></entry>
	</row>
	</tbody>
	</tgroup>
	@@ -107,7 +156,7 @@
	<sect1 xml:id="preface-conventions">
	<title>書中所用的編排風格</title>

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

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	@@ -121,12 +170,12 @@
	<tbody>
	<row>
	<entry>指令</entry>
	- <entry>使用 <command>ls -a</command> 來列出所有的檔案。</entry>
	+ <entry>使用 <command>ls -l</command> 來列出所有的檔案。</entry>
	</row>

	<row>
	<entry>檔名</entry>
	- <entry>修改 <filename>.login</filename> 檔。</entry>
	+ <entry>編輯 <filename>.login</filename> 。</entry>
	</row>

	<row>
	@@ -137,40 +186,33 @@
	<row>
	<entry>輸入指令後，螢幕上會出現的對應內容。</entry>

	- <entry><screen>&prompt.user; <userinput>su</userinput>
	-Password:</screen></entry>
	+ <entry><screen><prompt>%</prompt> <userinput>date +"The time is %H:%M"</userinput>
	+The time is 09:18</screen></entry>
	</row>

	<row>
	- <entry>要參考的線上手冊(manual)</entry>
	-
	- <entry>以 <citerefentry>
	- <refentrytitle>su</refentrytitle>
	- <manvolnum>1</manvolnum>
	- </citerefentry> 來切換帳號。</entry>
	+ <entry>要參考的線上手冊</entry>
	+ <entry>使用 <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來切換帳號。</entry>
	</row>

	<row>
	- <entry>在講到帳號(user)、群組(group)的名稱的時候...</entry>
	-
	- <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry>
	+ <entry>使用者名稱和群組名稱</entry>
	+ <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry>
	</row>

	<row>
	- <entry>語氣的強調</entry>
	-
	- <entry>你『必須』這麼做才行。</entry>
	+ <entry>語氣的強調。</entry>
	+ <entry>使用者<emphasis>必須</emphasis>這樣做</entry>
	</row>

	<row>
	<entry>打指令時，可替換的部份</entry>

	- <entry>要刪除檔案的話，請打 <command>rm 要刪除的檔名</command></entry>
	+ <entry>要搜尋線上手冊的關鍵字，請輸入 <command>man -k <replaceable>關鍵字</replaceable></command></entry>
	</row>

	<row>
	- <entry>環境變數設定</entry>
	-
	+ <entry>環境變數。</entry>
	<entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry>
	</row>
	</tbody>
	@@ -179,29 +221,28 @@
	</sect1>

	<sect1 xml:id="preface-notes">
	- <title>『Note、Tip、Important、Warning、Example』的運用</title>
	+ <title>注意、技巧、重要訊息、警告、與範例的運用。</title>

	- <para>以下文字是『注意』、『技巧』、『重要訊息』、『警告』、『範例』的運用。</para>
	+ <para>出現在本文中的注意、警告、與範例。</para>

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

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

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

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

	<example>
	- <title>這是舉例說明</title>
	+ <title>一個範例</title>

	<para>這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。</para>
	</example>
	@@ -210,25 +251,8472 @@
	<sect1 xml:id="preface-acknowledgements">
	<title>感謝</title>

	- <para>在此要感謝 Sue Blake, Patrick Durusau, Jon Hamilton, Peter
	- Flynn, Christopher Maden 這些人的協助與閱讀初期草稿，並提供許多寶貴的潤稿意見與評論。</para>
	+ <para>在此要感謝 Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, Christopher Maden 這些人的協助與閱讀初期草稿，並提供許多寶貴的潤稿意見與評論。</para>
	</sect1>
	</preface>

	- &chap.overview;
	- &chap.tools;
	- &chap.xml-primer;
	- &chap.xml-markup;
	- &chap.stylesheets;
	- &chap.structure;
	- &chap.doc-build;
	- &chap.the-website;
	- &chap.translations;
	- &chap.writing-style;
	- &chap.psgml-mode;
	- &chap.see-also;
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="overview">
	+ <title>概論</title>
	+
	+ <para>歡迎參與 FreeBSD 文件計劃( 簡稱 <acronym>FDP</acronym> ) 。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，您的點滴貢獻都是十分寶貴的。</para>
	+
	+ <para>本文件描述：『 <acronym>FDP</acronym> 的架構有哪些』、『如何撰寫並提交文件』、『如何有效運用工具來協助撰稿』。</para>
	+
	+ <para>歡迎大家對 <acronym>FDP</acronym> 做出貢獻。唯一的成員要求就有貢獻的意願。</para>
	+
	+ <para>本入門書指出如何：</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para>瞭解有哪些文件是由 <acronym>FDP</acronym> 所維護的。</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>安裝所需的文件工具和檔案</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>修改文件</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>提交修改以供審核並納入 FreeBSD 文件</para>
	+ </listitem>
	+ </itemizedlist>
	+
	+ <sect1 xml:id="overview-doc">
	+ <title>FreeBSD 文件組</title>
	+
	+ <para><acronym>FDP</acronym> 負責四類 FreeBSD 文件</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para><emphasis>使用手冊</emphasis>：使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><emphasis>FAQ</emphasis> 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><emphasis>線上手冊 ( manual pages )</emphasis>:英文版的系統 manual 並不是由 <acronym>FDP</acronym> 所撰寫的，因為它們是屬於 base system 的部份。然而，<acronym>FDP</acronym> 可以修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><emphasis>網站</emphasis>: 這是 FreeBSD 在網路上的主要部份，位於 <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link> 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方</para>
	+ </listitem>
	+ </itemizedlist>
	+
	+ <para>翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯</para>
	+
	+ <para>FreeBSD 網站、使用手冊、和 <acronym>FAQ</acronym> 的文件原始碼可以在 <literal>https://svn.FreeBSD.org/doc/</literal> 的文件庫取得。</para>
	+
	+ <para>線上手冊的原始碼則是在 <literal>https://svn.FreeBSD.org/base/</literal> 的原始碼庫可以取得。</para>
	+
	+ <para>文件提交訊息可以用 <command>svn log</command> 察看。提交訊息也會保存在<uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>。</para>
	+
	+ <para>這些儲存庫的網頁版位於<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>
	+ </sect1>
	+
	+ <sect1 xml:id="overview-quick-start">
	+ <title>快速上手</title>
	+
	+ <para>在編輯 FreeBSD 文件之前，有一些準備工作要做。首先，請訂閱 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 文件計劃郵件論壇</link>。有些團隊成員也會出現在<link xlink:href="http://www.efnet.org/">EFnet</link>的<literal>#bsddocs</literal> <acronym>IRC</acronym> 頻道。這些人可以幫忙解決文件相關的問題。</para>
	+
	+ <procedure>
	+ <step>
	+ <para>安裝 <package>textproc/docproj</package> 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。</para>
	+ </step>
	+
	+ <step>
	+ <para>在<filename>~/doc</filename>安裝 FreeBSD 文件庫的本地端工作副本 ( 請見 <xref linkend="working-copy"/> )。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
	+ </step>
	+
	+ <step>
	+ <para>設定文字編輯器：</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para>Word wrap 設為70個字元。</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>Tab stops 設成。</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>將句首每八個空白以一個 tab 替換。</para>
	+ </listitem>
	+ </itemizedlist>
	+
	+ <para>特定編輯器的設定方式列於 <xref linkend="editor-config"/>。</para>
	+ </step>
	+
	+ <step>
	+ <para>更新本地端工作副本</para>
	+
	+ <screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
	+ </step>
	+
	+ <step>
	+ <para>編輯需要修改的文件檔案。如果檔案需要大幅度的編修，請先諮詢郵件論壇。</para>
	+
	+ <para>標籤 ( tag ) 和 entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>. 。</para>
	+ </step>
	+
	+ <step>
	+ <para>編輯完後，執行以下指令來檢查是否有問題：</para>
	+
	+ <screen><prompt>%</prompt> <userinput>igor -R filename.xml \| less -RS</userinput></screen>
	+
	+ <para>檢查輸出並重新編輯檔案來修正顯示的錯誤，然後重新執行指令來找出剩下的問題。重複執行直到所有錯誤都解決完。</para>
	+ </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>
	+ </step>
	+
	+ <step>
	+ <para>修改並測試完後，產生<quote>diff 檔</quote>：</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput>
	+<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
	+
	+ <para>設一個可辨識的檔名。如上例中，是使用手冊的<filename>bsdinstall</filename> 部份的修改。</para>
	+ </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>
	+ </step>
	+ </procedure>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="tools">
	+ <title>工具</title>
	+
	+ <para>有些工具軟體用來管理 FreeBSD 文件，並將他轉換成不同的輸出格式。有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。</para>
	+
	+ <sect1 xml:id="tools-required">
	+ <title>必備工具</title>
	+
	+ <para>從 Ports Collection 安裝 <package>textproc/docproj</package>。這個 <emphasis>組合型 port (meta-port)</emphasis> 會安裝處理 FreeBSD 文件需要的所有應用程式。以下列出特定元件的進一步說明。</para>
	+
	+ <sect2>
	+ <title><acronym>DTD</acronym>s 與 <acronym>Entities</acronym></title>
	+
	+ <para>FreeBSD 文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 組。這些都會經由 <package>textproc/docproj</package> port 來安裝。</para>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)</term>
	+
	+ <listitem>
	+ <para><acronym>XHTML</acronym> 是全球資訊網的一種標記語言，也是整個 FreeBSD 網站所使用的格式。</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term>
	+
	+ <listitem>
	+ <para>DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term>ISO 8879 entities (<package>textproc/iso8879</package>)</term>
	+
	+ <listitem>
	+ <para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用，包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="tools-optional">
	+ <title>輔助工具</title>
	+
	+ <para>不一定得裝下列的應用程式才行，但是，出的格式也更具彈性。</para>
	+
	+ <sect2>
	+ <title>軟體</title>
	+
	+ <variablelist>
	+
	+ <varlistentry>
	+ <term><application>Vim</application> (<package>editors/vim</package>)</term>
	+
	+ <listitem>
	+ <para>一個很受歡迎的編輯器，可以處理 <acronym>XML</acronym> 和他的衍生相關文件，例如 DocBook <acronym>XML</acronym>。</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term><application>Emacs</application> 或 <application>XEmacs</application> (<package>editors/emacs</package> 或 <package>editors/xemacs</package>)</term>
	+
	+ <listitem>
	+ <para>這兩個編輯器都包含特別模式來編輯用 <acronym>XML</acronym> <acronym>DTD</acronym> 標記的文件。這個模式包含指令來減少打字量，並可以幫忙減少錯誤的發生。</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+ </sect2>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 2013 Warren Block
	+ All rights reserved.
	+
	+ Redistribution and use in source and binary forms, with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+ 1. Redistributions of source code must retain the above copyright
	+ notice, this list of conditions and the following disclaimer.
	+ 2. Redistributions in binary form must reproduce the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer in the documentation and/or other materials provided
	+ with the distribution.
	+
	+ THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS
	+ IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
	+ FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
	+ AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
	+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	+ OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
	+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="working-copy">
	+ <title>工作副本</title>
	+
	+ <para xml:lang="en">The <emphasis>working copy</emphasis> is a copy of the FreeBSD
	+ repository documentation tree downloaded onto the local computer.
	+ Changes are made to the local working copy, tested, and then
	+ submitted as patches to be committed to the main
	+ repository.</para>
	+
	+ <para xml:lang="en">A full copy of the documentation tree can occupy 700 megabytes
	+ of disk space. Allow for a full gigabyte of space to have room
	+ for temporary files and test versions of various output
	+ formats.</para>
	+
	+ <para xml:lang="en"><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link>
	+ is used to manage the FreeBSD documentation files. It is installed
	+ by <package>textproc/docproj</package> as one of
	+ the required applications.</para>
	+
	+ <sect1 xml:id="working-copy-doc-and-src">
	+ <title xml:lang="en">Documentation and Manual Pages</title>
	+
	+ <para xml:lang="en">FreeBSD documentation is not just books and articles. Manual
	+ pages for all the commands and configuration files are also part
	+ of the documentation, and part of the <acronym>FDP</acronym>'s
	+ territory. Two repositories are involved:
	+ <literal>doc</literal> for the books and articles, and
	+ <literal>base</literal> for the operating system and manual
	+ pages. To edit manual pages, the <literal>base</literal>
	+ repository must be checked out separately.</para>
	+
	+ <para xml:lang="en">Repositories may contain multiple versions of documentation
	+ and source code. New modifications are almost always made only
	+ to the latest version, called <literal>head</literal>.</para>
	+ </sect1>
	+
	+ <sect1 xml:id="working-copy-choosing-directory">
	+ <title xml:lang="en">Choosing a Directory</title>
	+
	+ <para xml:lang="en">FreeBSD documentation is traditionally stored in
	+ <filename>/usr/doc/</filename>, and system
	+ source code with manual pages in
	+ <filename>/usr/src/</filename>. These
	+ directory trees are relocatable, and users may want to put the
	+ working copies in other locations to avoid interfering with
	+ existing information in the main directories. The examples
	+ that follow use <filename>~/doc</filename>
	+ and <filename>~/src</filename>, both
	+ subdirectories of the user's home directory.</para>
	+ </sect1>
	+
	+ <sect1 xml:id="working-copy-checking-out">
	+ <title xml:lang="en">Checking Out a Copy</title>
	+
	+ <para xml:lang="en">A download of a working copy from the repository is called
	+ a <emphasis>checkout</emphasis>, and done with
	+ <command>svn checkout</command>. This example checks out a
	+ copy of the latest version (<literal>head</literal>) of
	+ the main documentation tree:</para>
	+
	+ <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
	+
	+ <para xml:lang="en">A checkout of the source code to work on manual pages is
	+ very similar:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
	+ </sect1>
	+
	+ <sect1 xml:id="working-copy-updating">
	+ <title xml:lang="en">Updating a Working Copy</title>
	+
	+ <para xml:lang="en">The documents and files in the FreeBSD repository change daily.
	+ People modify files and commit changes frequently. Even a short
	+ time after an initial checkout, there will already be
	+ differences between the local working copy and the main FreeBSD
	+ repository. To update the local version with the changes that
	+ have been made to the main repository, use
	+ <command>svn update</command> on the directory containing the
	+ local working copy:</para>
	+
	+ <screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>
	+
	+ <para xml:lang="en">Get in the protective habit of using
	+ <command>svn update</command> before editing document files.
	+ Someone else may have edited that file very recently, and the
	+ local working copy will not include the latest changes until it
	+ has been updated. Editing the newest version of a file is much
	+ easier than trying to combine an older, edited local file with
	+ the newer version from the repository.</para>
	+ </sect1>
	+
	+ <sect1 xml:id="working-copy-revert">
	+ <title xml:lang="en">Reverting Changes</title>
	+
	+ <para xml:lang="en">Sometimes it turns out that changes were
	+ not necessary after all, or the writer just wants to start over.
	+ Files can be <quote>reset</quote> to their unchanged form with
	+ <command>svn revert</command>. For example, to erase the edits
	+ made to <filename>chapter.xml</filename> and reset it to
	+ unmodified form:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen>
	+ </sect1>
	+
	+ <sect1 xml:id="working-copy-making-diff">
	+ <title xml:lang="en">Making a Diff</title>
	+
	+ <para xml:lang="en">After edits to a file or group of files are completed, the
	+ differences between the local working copy and the version on
	+ the FreeBSD repository must be collected into a single file for
	+ submission. These <emphasis>diff</emphasis> files are produced
	+ by redirecting the output of <command>svn diff</command> into a
	+ file:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>
	+<prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen>
	+
	+ <para xml:lang="en">Give the file a meaningful name that identifies the
	+ contents. The example above is for spelling fixes to the whole
	+ documentation tree.</para>
	+
	+ <para xml:lang="en">If the diff file is to be submitted with the web
	+ <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a FreeBSD
	+ problem report</link></quote> interface, add a
	+ <filename>.txt</filename> extension to give the earnest and
	+ simple-minded web form a clue that the contents are plain
	+ text.</para>
	+
	+ <para xml:lang="en">Be careful: <command>svn diff</command> includes all changes
	+ made in the current directory and any subdirectories. If there
	+ are files in the working copy with edits that are not ready to
	+ be submitted yet, provide a list of only the files that are to
	+ be included:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>
	+<prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen>
	+ </sect1>
	+
	+ <sect1 xml:id="working-copy-subversion-references">
	+ <title xml:lang="en"><application>Subversion</application> References</title>
	+
	+ <para xml:lang="en">These examples show very basic usage of
	+ <application>Subversion</application>. More detail is available
	+ in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link>
	+ and the <link xlink:href="http://subversion.apache.org/docs/">Subversion
	+ documentation</link>.</para>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="structure">
	+ <title xml:lang="en">Documentation Directory Structure</title>
	+
	+ <para xml:lang="en">Files and directories in the
	+ <filename>doc/</filename> tree follow a
	+ structure meant to:</para>
	+
	+ <orderedlist>
	+ <listitem>
	+ <para xml:lang="en">Make it easy to automate converting the document to other
	+ formats.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">Promote consistency between the different documentation
	+ organizations, to make it easier to switch between working on
	+ different documents.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">Make it easy to decide where in the tree new documentation
	+ should be placed.</para>
	+ </listitem>
	+ </orderedlist>
	+
	+ <para xml:lang="en">In addition, the documentation tree must accommodate
	+ documents in many different languages and encodings. It is
	+ important that the documentation tree structure does not enforce
	+ any particular defaults or cultural preferences.</para>
	+
	+ <sect1 xml:id="structure-top">
	+ <title xml:lang="en">The Top Level,
	+ <filename>doc/</filename></title>
	+
	+ <para xml:lang="en">There are two types of directory under
	+ <filename>doc/</filename>, each with very
	+ specific directory names and meanings.</para>
	+
	+ <informaltable pgwide="1" frame="none">
	+ <tgroup cols="2">
	+ <thead>
	+ <row>
	+ <entry xml:lang="en">Directory</entry>
	+ <entry xml:lang="en">Usage</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry valign="top" xml:lang="en">
	+ <filename>share</filename></entry>
	+
	+ <entry xml:lang="en">Contains files that are not specific to the various
	+ translations and encodings of the documentation.
	+ Contains subdirectories to further categorize the
	+ information. For example, the files that comprise the
	+ <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> infrastructure are in
	+ <filename>share/mk</filename>, while
	+ the additional <acronym>XML</acronym> support files
	+ (such as the FreeBSD extended DocBook
	+ <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry>
	+ </row>
	+
	+ <row>
	+ <entry valign="top" xml:lang="en">
	+ <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
	+
	+ <entry xml:lang="en">One directory exists for each available translation
	+ and encoding of the documentation, for example
	+ <filename>en_US.ISO8859-1/</filename>
	+ and <filename>zh_TW.UTF-8/</filename>.
	+ The names are long, but by fully specifying the language
	+ and encoding we prevent any future headaches when a
	+ translation team wants to provide documentation in the
	+ same language but in more than one encoding. This also
	+ avoids problems that might be caused by a future switch
	+ to Unicode.</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </informaltable>
	+ </sect1>
	+
	+ <sect1 xml:id="structure-locale">
	+ <title xml:lang="en">The
	+ <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename>
	+ Directories</title>
	+
	+ <para xml:lang="en">These directories contain the documents themselves. The
	+ documentation is split into up to three more categories at
	+ this level, indicated by the different directory names.</para>
	+
	+ <informaltable pgwide="1" frame="none">
	+ <tgroup cols="2">
	+ <thead>
	+ <row>
	+ <entry xml:lang="en">Directory</entry>
	+ <entry xml:lang="en">Usage</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry valign="top" xml:lang="en">
	+ <filename>articles</filename></entry>
	+
	+ <entry xml:lang="en">Documentation marked up as a DocBook
	+ <tag>article</tag> (or equivalent). Reasonably
	+ short, and broken up into sections. Normally only
	+ available as one <acronym>XHTML</acronym> file.</entry>
	+ </row>
	+
	+ <row>
	+ <entry valign="top" xml:lang="en"><filename>books</filename></entry>
	+
	+ <entry xml:lang="en">Documentation marked up as a DocBook
	+ <tag>book</tag> (or equivalent). Book length,
	+ and broken up into chapters. Normally available as both
	+ one large <acronym>XHTML</acronym> file (for people with
	+ fast connections, or who want to print it easily from a
	+ browser) and as a collection of linked, smaller
	+ files.</entry>
	+ </row>
	+
	+ <row>
	+ <entry valign="top" xml:lang="en">
	+ <filename>man</filename></entry>
	+
	+ <entry xml:lang="en">For translations of the system manual pages. This
	+ directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename>
	+ directories, corresponding to the sections that have
	+ been translated.</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </informaltable>
	+
	+ <para xml:lang="en">Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
	+ directory will have all of these subdirectories. It depends
	+ on how much translation has been accomplished by that
	+ translation team.</para>
	+ </sect1>
	+
	+ <sect1 xml:id="structure-document">
	+ <title xml:lang="en">Document-Specific Information</title>
	+
	+ <para xml:lang="en">This section contains specific notes about particular
	+ documents managed by the FDP.</para>
	+
	+ <sect2>
	+ <title xml:lang="en">The Handbook</title>
	+
	+ <subtitle xml:lang="en"><filename>books/handbook/</filename></subtitle>
	+
	+ <para xml:lang="en">The Handbook is written in DocBook <acronym>XML</acronym>
	+ using the FreeBSD DocBook extended <acronym>DTD</acronym>.</para>
	+
	+ <para xml:lang="en">The Handbook is organized as a DocBook
	+ <tag>book</tag>. The book is divided into
	+ <tag>part</tag>s, each of which contains several
	+ <tag>chapter</tag>s. <tag>chapter</tag>s are
	+ further subdivided into sections (<tag>sect1</tag>)
	+ and subsections (<tag>sect2</tag>,
	+ <tag>sect3</tag>) and so on.</para>
	+
	+ <sect3>
	+ <title xml:lang="en">Physical Organization</title>
	+
	+ <para xml:lang="en">There are a number of files and directories within the
	+ <filename>handbook</filename> directory.</para>
	+
	+ <note>
	+ <para xml:lang="en">The Handbook's organization may change over time, and
	+ this document may lag in detailing the organizational
	+ changes. Post questions about Handbook organization to the
	+ <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
	+ </note>
	+
	+ <sect4>
	+ <title xml:lang="en"><filename>Makefile</filename></title>
	+
	+ <para xml:lang="en">The <filename>Makefile</filename> defines some
	+ variables that affect how the <acronym>XML</acronym>
	+ source is converted to other formats, and lists the
	+ various source files that make up the Handbook. It then
	+ includes the standard <filename>doc.project.mk</filename>,
	+ to bring in the rest of the code that handles converting
	+ documents from one format to another.</para>
	+ </sect4>
	+
	+ <sect4>
	+ <title xml:lang="en"><filename>book.xml</filename></title>
	+
	+ <para xml:lang="en">This is the top level document in the Handbook. It
	+ contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE
	+ declaration</link>, as well as the elements that
	+ describe the Handbook's structure.</para>
	+
	+ <para xml:lang="en"><filename>book.xml</filename> uses <link linkend="xml-primer-parameter-entities">parameter
	+ entities</link> to load in the files with the
	+ <filename>.ent</filename> extension. These files
	+ (described later) then define <link linkend="xml-primer-general-entities">general
	+ entities</link> that are used throughout the rest of the
	+ Handbook.</para>
	+ </sect4>
	+
	+ <sect4>
	+ <title xml:lang="en"><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
	+
	+ <para xml:lang="en">Each chapter in the Handbook is stored in a file
	+ called <filename>chapter.xml</filename> in a separate
	+ directory from the other chapters. Each directory is
	+ named after the value of the <literal>id</literal>
	+ attribute on the <tag>chapter</tag>
	+ element.</para>
	+
	+ <para xml:lang="en">For example, if one of the chapter files
	+ contains:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">chapter id="kernelconfig"</tag>
	+...
	+<tag class="endtag">chapter</tag></programlisting>
	+
	+ <para xml:lang="en">Then it will be called
	+ <filename>chapter.xml</filename> in the
	+ <filename>kernelconfig</filename> directory. In general,
	+ the entire contents of the chapter are in this one
	+ file.</para>
	+
	+ <para xml:lang="en">When the <acronym>XHTML</acronym> version of the
	+ Handbook is produced, this will yield
	+ <filename>kernelconfig.html</filename>. This is because
	+ of the <literal>id</literal> value, and is not related to
	+ the name of the directory.</para>
	+
	+ <para xml:lang="en">In earlier versions of the Handbook, the files were
	+ stored in the same directory as
	+ <filename>book.xml</filename>, and named after the value
	+ of the <literal>id</literal> attribute on the file's
	+ <tag>chapter</tag> element. Now, it is possible
	+ to include images in each chapter. Images for each
	+ Handbook chapter are stored within <filename>share/images/books/handbook</filename>.
	+ The localized version of these images should be
	+ placed in the same directory as the <acronym>XML</acronym>
	+ sources for each chapter. Namespace collisions are
	+ inevitable, and it is easier to work with several
	+ directories with a few files in them than it is to work
	+ with one directory that has many files in it.</para>
	+
	+ <para xml:lang="en">A brief look will show that there are many directories
	+ with individual <filename>chapter.xml</filename> files,
	+ including <filename>basics/chapter.xml</filename>,
	+ <filename>introduction/chapter.xml</filename>, and
	+ <filename>printing/chapter.xml</filename>.</para>
	+
	+ <important>
	+ <para xml:lang="en">Do not name chapters or directories after
	+ their ordering within the Handbook. This ordering can
	+ change as the content within the Handbook is
	+ reorganized. Reorganization should be possible without
	+ renaming files, unless entire chapters are being
	+ promoted or demoted within the hierarchy.</para>
	+ </important>
	+
	+ <para xml:lang="en">The <filename>chapter.xml</filename> files are not
	+ complete <acronym>XML</acronym> documents that can be
	+ built individually. They can only be built
	+ as parts of the whole Handbook.</para>
	+ </sect4>
	+ </sect3>
	+ </sect2>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="doc-build">
	+ <title xml:lang="en">The Documentation Build Process</title>
	+
	+ <para xml:lang="en">This chapter covers organization of the documentation build
	+ process and how <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to control it.</para>
	+
	+ <sect1 xml:id="doc-build-rendering">
	+ <title xml:lang="en">Rendering DocBook into Output</title>
	+
	+ <para xml:lang="en">Different types of output can be produced from a single
	+ DocBook source file. The type of output desired is set with the
	+ <varname>FORMATS</varname> variable. A list of known formats is
	+ stored in <varname>KNOWN_FORMATS</varname>:</para>
	+
	+ <screen xml:id="doc-build-rendering-known-formats" xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
	+<prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput></screen>
	+
	+ <table xml:id="doc-build-rendering-common-formats" frame="none">
	+ <title xml:lang="en">Common Output Formats</title>
	+
	+ <tgroup cols="3">
	+ <thead>
	+ <row>
	+ <entry xml:lang="en"><varname>FORMATS</varname> Value</entry>
	+ <entry xml:lang="en">File Type</entry>
	+ <entry xml:lang="en">Description</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry xml:lang="en"><literal>html</literal></entry>
	+ <entry xml:lang="en"><acronym>HTML</acronym>, one file</entry>
	+ <entry xml:lang="en">A single <filename>book.html</filename> or
	+ <filename>article.html</filename>.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>html-split</literal></entry>
	+ <entry xml:lang="en"><acronym>HTML</acronym>, multiple files</entry>
	+ <entry xml:lang="en">Multiple <acronym>HTML</acronym> files, one for
	+ each chapter or section, for use on a typical web
	+ site.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>pdf</literal></entry>
	+ <entry xml:lang="en"><acronym>PDF</acronym></entry>
	+ <entry xml:lang="en">Portable Document Format</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </table>
	+
	+ <para xml:lang="en">The default output format can vary by document, but is
	+ usually <literal>html-split</literal>. Other formats are chosen
	+ by setting <varname>FORMATS</varname> to a specific value.
	+ Multiple output formats can be created at a single time by
	+ setting <varname>FORMATS</varname> to a list of formats.</para>
	+
	+ <example xml:id="doc-build-formats-example-html">
	+ <title xml:lang="en">Build a Single HTML Output File</title>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
	+<prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen>
	+ </example>
	+
	+ <example xml:id="doc-build-formats-example-html-split-pdf">
	+ <title xml:lang="en">Build HTML-Split and <acronym>PDF</acronym> Output
	+ Files</title>
	+
	+ <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>
	+ </example>
	+ </sect1>
	+
	+ <sect1 xml:id="doc-build-toolset">
	+ <title xml:lang="en">The FreeBSD Documentation Build Toolset</title>
	+
	+ <para xml:lang="en">These are the tools used to build and install the
	+ <acronym>FDP</acronym> documentation.</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en">The primary build tool is <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, specifically
	+ <application>Berkeley Make</application>.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">Package building is handled by FreeBSD's
	+ <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to create compressed versions of
	+ the document. <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> archives are also supported.
	+ <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used for package building.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to install the
	+ documentation.</para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect1>
	+
	+ <sect1 xml:id="doc-build-makefiles">
	+
	+ <title xml:lang="en">Understanding <filename>Makefile</filename>s in the
	+ Documentation Tree</title>
	+
	+ <para xml:lang="en">There are three main types of <filename>Makefile</filename>s
	+ in the FreeBSD Documentation Project tree.</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en"><link linkend="sub-make">Subdirectory
	+ <filename>Makefile</filename>s</link> simply pass
	+ commands to those directories below them.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><link linkend="doc-make">Documentation
	+ <filename>Makefile</filename>s</link> describe the
	+ documents that are produced from this
	+ directory.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><link linkend="make-includes"><application>Make</application>
	+ includes</link> are the glue that perform the document
	+ production, and are usually of the form
	+ <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
	+ </listitem>
	+ </itemizedlist>
	+
	+ <sect2 xml:id="sub-make">
	+ <title xml:lang="en">Subdirectory <filename>Makefile</filename>s</title>
	+
	+ <para xml:lang="en">These <filename>Makefile</filename>s usually take the form
	+ of:</para>
	+
	+ <programlisting xml:lang="en">SUBDIR =articles
	+SUBDIR+=books
	+
	+COMPAT_SYMLINK = en
	+
	+DOC_PREFIX?= ${.CURDIR}/..
	+.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
	+
	+ <para xml:lang="en">The first four non-empty lines define the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	+ variables <varname>SUBDIR</varname>,
	+ <varname>COMPAT_SYMLINK</varname>, and
	+ <varname>DOC_PREFIX</varname>.</para>
	+
	+ <para xml:lang="en">The <varname>SUBDIR</varname> statement and
	+ <varname>COMPAT_SYMLINK</varname> statement show how to
	+ assign a value to a variable, overriding any previous
	+ value.</para>
	+
	+ <para xml:lang="en">The second <varname>SUBDIR</varname> statement shows how a
	+ value is appended to the current value of a variable. The
	+ <varname>SUBDIR</varname> variable is now <literal>articles
	+ books</literal>.</para>
	+
	+ <para xml:lang="en">The <varname>DOC_PREFIX</varname> assignment shows how a
	+ value is assigned to the variable, but only if it is not
	+ already defined. This is useful if
	+ <varname>DOC_PREFIX</varname> is not where this
	+ <filename>Makefile</filename> thinks it is - the user can
	+ override this and provide the correct value.</para>
	+
	+ <para xml:lang="en">What does it all mean? <varname>SUBDIR</varname>
	+ mentions which subdirectories below this one the build process
	+ should pass any work on to.</para>
	+
	+ <para xml:lang="en"><varname>COMPAT_SYMLINK</varname> is specific to
	+ compatibility symlinks (amazingly enough) for languages to
	+ their official encoding (<filename>doc/en</filename> would
	+ point to <filename>en_US.ISO-8859-1</filename>).</para>
	+
	+ <para xml:lang="en"><varname>DOC_PREFIX</varname> is the path to the root of
	+ the FreeBSD Document Project tree. This is not always that easy
	+ to find, and is also easily overridden, to allow for
	+ flexibility. <varname>.CURDIR</varname> is a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	+ builtin variable with the path to the current
	+ directory.</para>
	+
	+ <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
	+ <filename>doc.project.mk</filename> which is the glue which
	+ converts these variables into build instructions.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="doc-make">
	+ <title xml:lang="en">Documentation <filename>Makefile</filename>s</title>
	+
	+ <para xml:lang="en">These <filename>Makefile</filename>s set <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	+ variables that describe how to build the documentation
	+ contained in that directory.</para>
	+
	+ <para xml:lang="en">Here is an example:</para>
	+
	+ <programlisting xml:lang="en">MAINTAINER=nik@FreeBSD.org
	+
	+DOC?= book
	+
	+FORMATS?= html-split html
	+
	+INSTALL_COMPRESSED?= gz
	+INSTALL_ONLY_COMPRESSED?=
	+
	+# SGML content
	+SRCS= book.xml
	+
	+DOC_PREFIX?= ${.CURDIR}/../../..
	+
	+.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
	+
	+ <para xml:lang="en">The <varname>MAINTAINER</varname> variable allows
	+ committers to claim ownership of a document in the FreeBSD
	+ Documentation Project, and take responsibility for maintaining
	+ it.</para>
	+
	+ <para xml:lang="en"><varname>DOC</varname> is the name (sans the
	+ <filename>.xml</filename> extension) of the main document
	+ created by this directory. <varname>SRCS</varname> lists all
	+ the individual files that make up the document. This should
	+ also include important files in which a change should result
	+ in a rebuild.</para>
	+
	+ <para xml:lang="en"><varname>FORMATS</varname> indicates the default formats
	+ that should be built for this document.
	+ <varname>INSTALL_COMPRESSED</varname> is the default list of
	+ compression techniques that should be used in the document
	+ build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by
	+ default, should be non-empty if only compressed documents are
	+ desired in the build.</para>
	+
	+ <para xml:lang="en">The <varname>DOC_PREFIX</varname> and include statements
	+ should be familiar already.</para>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="make-includes">
	+ <title xml:lang="en">FreeBSD Documentation Project
	+ <application>Make</application> Includes</title>
	+
	+ <para xml:lang="en"><citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes are best explained by inspection of
	+ the code. Here are the system include files:</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en"><filename>doc.project.mk</filename> is the main project
	+ include file, which includes all the following include
	+ files, as necessary.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><filename>doc.subdir.mk</filename> handles traversing of
	+ the document tree during the build and install
	+ processes.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><filename>doc.install.mk</filename> provides variables
	+ that affect ownership and installation of documents.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><filename>doc.docbook.mk</filename> is included if
	+ <varname>DOCFORMAT</varname> is <literal>docbook</literal>
	+ and <varname>DOC</varname> is set.</para>
	+ </listitem>
	+ </itemizedlist>
	+
	+ <sect2>
	+ <title xml:lang="en"><filename>doc.project.mk</filename></title>
	+
	+ <para xml:lang="en">By inspection:</para>
	+
	+ <programlisting xml:lang="en">DOCFORMAT?= docbook
	+MAINTAINER?= doc@FreeBSD.org
	+
	+PREFIX?= /usr/local
	+PRI_LANG?= en_US.ISO8859-1
	+
	+.if defined(DOC)
	+.if ${DOCFORMAT} == "docbook"
	+.include "doc.docbook.mk"
	+.endif
	+.endif
	+
	+.include "doc.subdir.mk"
	+.include "doc.install.mk"</programlisting>
	+
	+ <sect3>
	+
	+ <title xml:lang="en">Variables</title>
	+
	+ <para xml:lang="en"><varname>DOCFORMAT</varname> and
	+ <varname>MAINTAINER</varname> are assigned default values,
	+ if these are not set by the document make file.</para>
	+
	+ <para xml:lang="en"><varname>PREFIX</varname> is the prefix under which the
	+ <link linkend="tools">documentation building tools</link>
	+ are installed. For normal package and port installation,
	+ this is <filename>/usr/local</filename>.</para>
	+
	+ <para xml:lang="en"><varname>PRI_LANG</varname> should be set to whatever
	+ language and encoding is natural amongst users these
	+ documents are being built for. US English is the
	+ default.</para>
	+
	+ <note>
	+ <para xml:lang="en"><varname>PRI_LANG</varname> does not affect which
	+ documents can, or even will, be built. Its main use is
	+ creating links to commonly referenced documents into the
	+ FreeBSD documentation install root.</para>
	+ </note>
	+ </sect3>
	+
	+ <sect3>
	+ <title xml:lang="en">Conditionals</title>
	+
	+ <para xml:lang="en">The <literal>.if defined(DOC)</literal> line is an
	+ example of a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> conditional which, like in other
	+ programs, defines behavior if some condition is true or if
	+ it is false. <literal>defined</literal> is a function which
	+ returns whether the variable given is defined or not.</para>
	+
	+ <para xml:lang="en"><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
	+ tests whether the <varname>DOCFORMAT</varname> variable is
	+ <literal>"docbook"</literal>, and in this case, includes
	+ <filename>doc.docbook.mk</filename>.</para>
	+
	+ <para xml:lang="en">The two <literal>.endif</literal>s close the two above
	+ conditionals, marking the end of their application.</para>
	+ </sect3>
	+ </sect2>
	+
	+ <sect2>
	+ <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
	+ describe the most important features.</para>
	+
	+ <sect3>
	+ <title xml:lang="en">Variables</title>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en"><varname>SUBDIR</varname> is a list of
	+ subdirectories that the build process should go further
	+ down into.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><varname>ROOT_SYMLINKS</varname> is the name of
	+ directories that should be linked to the document
	+ install root from their actual locations, if the current
	+ language is the primary language (specified by
	+ <varname>PRI_LANG</varname>).</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><varname>COMPAT_SYMLINK</varname> is described in
	+ the
	+ <link linkend="sub-make">Subdirectory Makefile</link>
	+ section.</para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect3>
	+
	+ <sect3>
	+ <title xml:lang="en">Targets and Macros</title>
	+
	+ <para xml:lang="en">Dependencies are described by
	+ <literal><replaceable>target</replaceable>:
	+ <replaceable>dependency1 dependency2
	+ ...</replaceable></literal> tuples, where to build
	+ <literal>target</literal>, the given
	+ dependencies must be built first.</para>
	+
	+ <para xml:lang="en">After that descriptive tuple, instructions on how to
	+ build the target may be given, if the conversion process
	+ between the target and its dependencies are not previously
	+ defined, or if this particular conversion is not the same as
	+ the default conversion method.</para>
	+
	+ <para xml:lang="en">A special dependency <literal>.USE</literal> defines
	+ the equivalent of a macro.</para>
	+
	+ <programlisting xml:lang="en">_SUBDIRUSE: .USE
	+.for entry in ${SUBDIR}
	+ @${ECHO} "===> ${DIRPRFX}${entry}"
	+ @(cd ${.CURDIR}/${entry} && \
	+ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
	+.endfor</programlisting>
	+
	+ <para xml:lang="en">In the above, <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> is now
	+ a macro which will execute the given commands when it is
	+ listed as a dependency.</para>
	+
	+ <para xml:lang="en">What sets this macro apart from other targets?
	+ Basically, it is executed <emphasis>after</emphasis> the
	+ instructions given in the build procedure it is listed as a
	+ dependency to, and it does not adjust
	+ <varname>.TARGET</varname>, which is the variable which
	+ contains the name of the target currently being
	+ built.</para>
	+
	+ <programlisting xml:lang="en">clean: _SUBDIRUSE
	+ rm -f ${CLEANFILES}</programlisting>
	+
	+ <para xml:lang="en">In the above, <buildtarget xml:lang="en">clean</buildtarget> will use
	+ the <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> macro after it has
	+ executed the instruction
	+ <command>rm -f ${CLEANFILES}</command>. In effect, this
	+ causes <buildtarget xml:lang="en">clean</buildtarget> to go further and
	+ further down the directory tree, deleting built files as it
	+ goes <emphasis>down</emphasis>, not on the way back
	+ up.</para>
	+
	+ <sect4>
	+ <title xml:lang="en">Provided Targets</title>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en"><buildtarget xml:lang="en">install</buildtarget> and
	+ <buildtarget xml:lang="en">package</buildtarget> both go down the
	+ directory tree calling the real versions of themselves
	+ in the subdirectories
	+ (<buildtarget xml:lang="en">realinstall</buildtarget> and
	+ <buildtarget xml:lang="en">realpackage</buildtarget>
	+ respectively).</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> removes files
	+ created by the build process (and goes down the
	+ directory tree too).
	+ <buildtarget xml:lang="en">cleandir</buildtarget> does the same, and
	+ also removes the object directory, if any.</para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect4>
	+ </sect3>
	+
	+ <sect3>
	+ <title xml:lang="en">More on Conditionals</title>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en"><literal>exists</literal> is another condition
	+ function which returns true if the given file
	+ exists.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><literal>empty</literal> returns true if the given
	+ variable is empty.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><literal>target</literal> returns true if the given
	+ target does not already exist.</para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect3>
	+
	+ <sect3>
	+ <title xml:lang="en">Looping Constructs in <command>make
	+ (.for)</command></title>
	+
	+ <para xml:lang="en"><literal>.for</literal> provides a way to repeat a set
	+ of instructions for each space-separated element in a
	+ variable. It does this by assigning a variable to contain
	+ the current element in the list being examined.</para>
	+
	+ <programlisting xml:lang="en">_SUBDIRUSE: .USE
	+.for entry in ${SUBDIR}
	+ @${ECHO} "===> ${DIRPRFX}${entry}"
	+ @(cd ${.CURDIR}/${entry} && \
	+ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
	+.endfor</programlisting>
	+
	+ <para xml:lang="en">In the above, if <varname>SUBDIR</varname> is empty, no
	+ action is taken; if it has one or more elements, the
	+ instructions between <literal>.for</literal> and
	+ <literal>.endfor</literal> would repeat for every element,
	+ with <varname>entry</varname> being replaced with the value
	+ of the current element.</para>
	+ </sect3>
	+ </sect2>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="the-website">
	+ <title>網站</title>
	+
	+ <para>FreeBSD 網站是 FreeBSD 文件的一部份。網站的檔案儲存在文件樹目錄，此例中是 <filename>~/doc</filename>，的 <filename>en_US.ISO8859-1/htdocs</filename> 子目錄。</para>
	+
	+ <sect1 xml:id="the-website-env">
	+ <title>環境變數</title>
	+
	+ <para>有些環境變數控制網站的建構或安裝，和裝到哪個目錄</para>
	+
	+ <tip>
	+ <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
	+ are empty. The examples here show the recommended ways of
	+ defining and using these variables. Setting or defining these
	+ variables with other values or methods might lead to
	+ unexpected surprises.</para>
	+ </tip>
	+
	+ <variablelist>
	+ <varlistentry xml:id="the-website-env-destdir">
	+ <term xml:lang="en"><varname>DESTDIR</varname></term>
	+
	+ <listitem>
	+ <para xml:lang="en">DESTDIR specifies the path where the web site files
	+ are to be installed.</para>
	+
	+ <para xml:lang="en">This variable is best set with <citerefentry><refentrytitle>env</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the user
	+ shell's method of setting environment variables,
	+ <command>setenv</command> for <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
	+ <command>export</command> for <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <variablelist>
	+ <varlistentry xml:id="the-website-env-englishonly">
	+ <term xml:lang="en"><varname>ENGLISH_ONLY</varname></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Default: undefined. Build and include all
	+ translations.</para>
	+
	+ <para xml:lang="en"><userinput>ENGLISH_ONLY=yes</userinput>: use only
	+ the English documents and ignore all translations.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry xml:id="the-website-env-webonly">
	+ <term xml:lang="en"><varname>WEB_ONLY</varname></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Default: undefined. Build both the web site
	+ and all the books and articles.</para>
	+
	+ <para xml:lang="en"><userinput>WEB_ONLY=yes</userinput>: build or install
	+ only <acronym>HTML</acronym> pages from the
	+ <filename>en_US.ISO8859-1/htdocs</filename> directory.
	+ Other directories and documents, including books and
	+ articles, will be ignored.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry xml:id="the-website-env-weblang">
	+ <term xml:lang="en"><varname>WEB_LANG</varname></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Default: undefined. Build and include all the
	+ available languages on the web site.</para>
	+
	+ <para xml:lang="en">Set to a space-separated list of languages to be
	+ included in the build
	+ or install. The formats are the same as the directory
	+ names in the document root directory. For example, to
	+ include the German and French documents:</para>
	+
	+ <screen xml:lang="en"><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <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 can be set in <filename>/etc/make.conf</filename>,
	+ <filename>Makefile.inc</filename>, as environment variables on
	+ the command line, or in dot files.</para>
	+ </sect1>
	+
	+ <sect1 xml:id="the-website-build">
	+ <title xml:lang="en">Building and Installing the Web Pages</title>
	+
	+ <para xml:lang="en">Having obtained the documentation and web site source files,
	+ 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>
	+ user because the permissions on the web server directory will
	+ not allow files to be installed by an unprivileged user.
	+ For testing, it can be useful to install the files as a normal
	+ user to a temporary directory.</para>
	+
	+ <para xml:lang="en">In these examples, the web site files are built by user
	+ <systemitem class="username">jru</systemitem> in their home
	+ directory, <filename>~/doc</filename>, with a full path of
	+ <filename>/usr/home/jru/doc</filename>.</para>
	+
	+ <tip>
	+ <para xml:lang="en">The web site build uses the <filename>INDEX</filename>
	+ from the Ports Collection and might fail if that file or
	+ <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
	+ Collection</link>.</para>
	+ </tip>
	+
	+ <example xml:id="the-website-examples-build">
	+ <title xml:lang="en">Build the Full Web Site and All Documents</title>
	+
	+ <para xml:lang="en">Build the web site and all documents. The resulting files
	+ are left in the document tree:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
	+<prompt>%</prompt> <userinput>make all</userinput></screen>
	+ </example>
	+
	+ <example xml:id="the-website-examples-buildinstall-englishonly">
	+ <title xml:lang="en">Build Only the Web Site in English</title>
	+
	+ <para xml:lang="en">Build the web site only, in English, as user
	+ <systemitem class="username">jru</systemitem>, and install
	+ the resulting files into <filename>/tmp/www</filename> for
	+ testing:</para>
	+
	+ <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>
	+
	+ <para xml:lang="en">Changes to static files can usually be tested by viewing
	+ the modified files directly with a web browser. If the site
	+ has been built as shown above, a modified main page can be
	+ viewed with:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>firefox /tmp/www/data/index.html</userinput></screen>
	+
	+ <para xml:lang="en">Modifications to dynamic files can be tested with a web
	+ server running on the local system. After building the site
	+ as shown above, this
	+ <filename>/usr/local/etc/apache24/httpd.conf</filename> can be
	+ used with <package>www/apache24</package>:</para>
	+
	+ <programlisting xml:lang="en"># httpd.conf for testing the FreeBSD website
	+Define TestRoot "/tmp/www/data"
	+
	+# directory for configuration files
	+ServerRoot "/usr/local"
	+
	+Listen 80
	+
	+# minimum required modules
	+LoadModule authz_core_module libexec/apache24/mod_authz_core.so
	+LoadModule mime_module libexec/apache24/mod_mime.so
	+LoadModule unixd_module libexec/apache24/mod_unixd.so
	+LoadModule cgi_module libexec/apache24/mod_cgi.so
	+LoadModule dir_module libexec/apache24/mod_dir.so
	+
	+# run the webserver as user and group
	+User www
	+Group www
	+
	+ServerAdmin you@example.com
	+ServerName fbsdtest
	+
	+# deny access to all files
	+<Directory />
	+ AllowOverride none
	+ Require all denied
	+</Directory>
	+
	+# allow access to the website directory
	+DocumentRoot "${TestRoot}"
	+<Directory "${TestRoot}">
	+ Options Indexes FollowSymLinks
	+ AllowOverride None
	+ Require all granted
	+</Directory>
	+
	+# prevent access to .htaccess and .htpasswd files
	+<Files ".ht*">
	+ Require all denied
	+</Files>
	+
	+ErrorLog "/var/log/httpd-error.log"
	+LogLevel warn
	+
	+# set up the CGI script directory
	+<Directory "${TestRoot}/cgi">
	+ AllowOverride None
	+ Options None
	+ Require all granted
	+ Options +ExecCGI
	+ AddHandler cgi-script .cgi
	+</Directory>
	+
	+Include etc/apache24/Includes/*.conf</programlisting>
	+
	+ <para xml:lang="en">Start the web server with</para>
	+
	+ <screen xml:lang="en"><prompt>#</prompt> <userinput>service apache24 onestart</userinput></screen>
	+
	+ <para xml:lang="en">The web site can be viewed at
	+ <link xlink:href="http://localhost"/>. Be aware that many
	+ links refer to the real FreeBSD site by name, and those links
	+ will still go to the external site instead of the local test
	+ version. Fully testing the local site will require
	+ temporarily setting <acronym>DNS</acronym> so
	+ <literal>www.FreeBSD.org</literal> resolves to
	+ <literal>localhost</literal> or the local
	+ <acronym>IP</acronym> address.</para>
	+ </example>
	+
	+ <example xml:id="the-website-examples-buildinstall">
	+ <title xml:lang="en">Build and Install the Web Site</title>
	+
	+ <para xml:lang="en">Build the web site and all documents as user
	+ <systemitem class="username">jru</systemitem>. Install the
	+ resulting files as
	+ <systemitem class="username">root</systemitem> into the
	+ default directory,
	+ <filename>/root/public_html</filename>:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
	+<prompt>%</prompt> <userinput>make all</userinput>
	+<prompt>%</prompt> <userinput>su -</userinput>
	+Password:
	+<prompt>#</prompt> <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
	+<prompt>#</prompt> <userinput>make install</userinput></screen>
	+ </example>
	+
	+ <para xml:lang="en">The install process does not delete any old or outdated
	+ files that existed previously in the same directory. If a new
	+ copy of the site is built and installed every day, this command
	+ will find and delete all files that have not been updated in
	+ three days:</para>
	+
	+ <screen xml:lang="en"><prompt>#</prompt> <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="xml-primer">
	+ <title xml:lang="en">XML Primer</title>
	+
	+ <para xml:lang="en">Most <acronym>FDP</acronym> documentation is written with
	+ markup languages based on <acronym>XML</acronym>. This chapter
	+ explains what that means, how to read and understand the
	+ documentation source, and the <acronym>XML</acronym> techniques
	+ used.</para>
	+
	+ <para xml:lang="en">Portions of this section were inspired by Mark Galassi's
	+ <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
	+ Going With DocBook</link>.</para>
	+
	+ <sect1 xml:id="xml-primer-overview">
	+ <title>概論</title>
	+
	+ <para xml:lang="en">In the original days of computers, electronic text was
	+ simple. There were a few character sets like
	+ <acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, but that
	+ was about it. Text was text, and what you saw really was what
	+ you got. No frills, no formatting, no intelligence.</para>
	+
	+ <para xml:lang="en">Inevitably, this was not enough. When text is in a
	+ machine-usable format, machines are expected to be able to use
	+ and manipulate it intelligently. Authors want to indicate that
	+ certain phrases should be emphasized, or added to a glossary, or
	+ made into hyperlinks. Filenames could be shown in a
	+ <quote>typewriter</quote> style font for viewing on screen, but
	+ as <quote>italics</quote> when printed, or any of a myriad of
	+ other options for presentation.</para>
	+
	+ <para xml:lang="en">It was once hoped that Artificial Intelligence (AI) would
	+ make this easy. The computer would read the document and
	+ automatically identify key phrases, filenames, text that the
	+ reader should type in, examples, and more. Unfortunately, real
	+ life has not happened quite like that, and computers still
	+ require assistance before they can meaningfully process
	+ text.</para>
	+
	+ <para xml:lang="en">More precisely, they need help identifying what is what.
	+ Consider this text:</para>
	+
	+ <blockquote>
	+ <para xml:lang="en">To remove <filename>/tmp/foo</filename>, use
	+ <citerefentry><refentrytitle>rm</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>rm /tmp/foo</userinput></screen>
	+ </blockquote>
	+
	+ <para xml:lang="en">It is easy to see which parts are filenames, which are
	+ commands to be typed in, which parts are references to manual
	+ pages, and so on. But the computer processing the document
	+ cannot. For this we need markup.</para>
	+
	+ <para xml:lang="en"><quote>Markup</quote> is commonly used to describe
	+ <quote>adding value</quote> or <quote>increasing cost</quote>.
	+ The term takes on both these meanings when applied to text.
	+ Markup is additional text included in the document,
	+ distinguished from the document's content in some way, so that
	+ programs that process the document can read the markup and use
	+ it when making decisions about the document. Editors can hide
	+ the markup from the user, so the user is not distracted by
	+ it.</para>
	+
	+ <para xml:lang="en">The extra information stored in the markup
	+ <emphasis>adds value</emphasis> to the document. Adding the
	+ markup to the document must typically be done by a
	+ person—after all, if computers could recognize the text
	+ sufficiently well to add the markup then there would be no need
	+ to add it in the first place. This
	+ <emphasis>increases the cost</emphasis> (the effort required) to
	+ create the document.</para>
	+
	+ <para xml:lang="en">The previous example is actually represented in this
	+ document like this:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &man.rm.1;.<tag class="endtag">para</tag>
	+
	+<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>
	+
	+ <para xml:lang="en">The markup is clearly separate from the content.</para>
	+
	+ <para xml:lang="en">Markup languages define what the markup means and how it
	+ should be interpreted.</para>
	+
	+ <para xml:lang="en">Of course, one markup language might not be enough. A
	+ markup language for technical documentation has very different
	+ requirements than a markup language that is intended for cookery
	+ recipes. This, in turn, would be very different from a markup
	+ language used to describe poetry. What is really needed is a
	+ first language used to write these other markup languages. A
	+ <emphasis>meta markup language</emphasis>.</para>
	+
	+ <para xml:lang="en">This is exactly what the eXtensible Markup
	+ Language (<acronym>XML</acronym>) is. Many markup languages
	+ have been written in <acronym>XML</acronym>, including the two
	+ most used by the <acronym>FDP</acronym>,
	+ <acronym>XHTML</acronym> and DocBook.</para>
	+
	+ <para xml:lang="en">Each language definition is more properly called a grammar,
	+ vocabulary, schema or Document Type Definition
	+ (<acronym>DTD</acronym>). There are various languages to
	+ specify an <acronym>XML</acronym> grammar, or
	+ <emphasis>schema</emphasis>.</para>
	+
	+ <para xml:id="xml-primer-validating" xml:lang="en">A schema is a
	+ <emphasis>complete</emphasis> specification of all the elements
	+ that are allowed to appear, the order in which they should
	+ appear, which elements are mandatory, which are optional, and so
	+ forth. This makes it possible to write an
	+ <acronym>XML</acronym> <emphasis>parser</emphasis> which reads
	+ in both the schema and a document which claims to conform to the
	+ schema. The parser can then confirm whether or not all the
	+ elements required by the vocabulary are in the document in the
	+ right order, and whether there are any errors in the markup.
	+ This is normally referred to as
	+ <quote>validating the document</quote>.</para>
	+
	+ <note>
	+ <para xml:lang="en">Validation confirms that the choice of
	+ elements, their ordering, and so on, conforms to that listed
	+ in the grammar. It does <emphasis>not</emphasis> check
	+ whether <emphasis>appropriate</emphasis> markup has been used
	+ for the content. If all the filenames in a document were
	+ marked up as function names, the parser would not flag this as
	+ an error (assuming, of course, that the schema defines
	+ elements for filenames and functions, and that they are
	+ allowed to appear in the same place).</para>
	+ </note>
	+
	+ <para xml:lang="en">Most contributions to the Documentation
	+ Project will be content marked up in either
	+ <acronym>XHTML</acronym> or DocBook, rather than alterations to
	+ the schemas. For this reason, this book will not touch on how
	+ to write a vocabulary.</para>
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-elements">
	+ <title xml:lang="en">Elements, Tags, and Attributes</title>
	+
	+ <para xml:lang="en">All the vocabularies written in <acronym>XML</acronym> share
	+ certain characteristics. This is hardly surprising, as the
	+ philosophy behind <acronym>XML</acronym> will inevitably show
	+ through. One of the most obvious manifestations of this
	+ philosophy is that of <emphasis>content</emphasis> and
	+ <emphasis>elements</emphasis>.</para>
	+
	+ <para xml:lang="en">Documentation, whether it is a single web page, or a lengthy
	+ book, is considered to consist of content. This content is then
	+ divided and further subdivided into elements. The purpose of
	+ adding markup is to name and identify the boundaries of these
	+ elements for further processing.</para>
	+
	+ <para xml:lang="en">For example, consider a typical book. At the very top
	+ level, the book is itself an element. This <quote>book</quote>
	+ element obviously contains chapters, which can be considered to
	+ be elements in their own right. Each chapter will contain more
	+ elements, such as paragraphs, quotations, and footnotes. Each
	+ paragraph might contain further elements, identifying content
	+ that was direct speech, or the name of a character in the
	+ story.</para>
	+
	+ <para xml:lang="en">It may be helpful to think of this as
	+ <quote>chunking</quote> content. At the very top level is one
	+ chunk, the book. Look a little deeper, and there are more
	+ chunks, the individual chapters. These are chunked further into
	+ paragraphs, footnotes, character names, and so on.</para>
	+
	+ <para xml:lang="en">Notice how this differentiation between different elements
	+ of the content can be made without resorting to any
	+ <acronym>XML</acronym> terms. It really is surprisingly
	+ straightforward. This could be done with a highlighter pen and
	+ a printout of the book, using different colors to indicate
	+ different chunks of content.</para>
	+
	+ <para xml:lang="en">Of course, we do not have an electronic highlighter pen, so
	+ we need some other way of indicating which element each piece of
	+ content belongs to. In languages written in
	+ <acronym>XML</acronym> (<acronym>XHTML</acronym>, DocBook, et
	+ al) this is done by means of <emphasis>tags</emphasis>.</para>
	+
	+ <para xml:lang="en">A tag is used to identify where a particular element starts,
	+ and where the element ends. <emphasis>The tag is not part of
	+ the element itself</emphasis>. Because each grammar was
	+ normally written to mark up specific types of information, each
	+ one will recognize different elements, and will therefore have
	+ different names for the tags.</para>
	+
	+ <para xml:lang="en">For an element called
	+ <replaceable>element-name</replaceable> the start tag will
	+ 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>
	+
	+ <example>
	+ <title xml:lang="en">Using an Element (Start and End Tags)</title>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating
	+ that the content enclosed by the element is a paragraph,
	+ 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
	+ the 'p' element, and it will end with the end tag for the 'p'
	+ 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>
	+ </example>
	+
	+ <para xml:lang="en">Some elements have no content. For example, in
	+ <acronym>XHTML</acronym>, a horizontal line can be included in
	+ the document. For these <quote>empty</quote> elements,
	+ <acronym>XML</acronym> introduced a shorthand form that is
	+ completely equivalent to the two-tag version:</para>
	+
	+ <example>
	+ <title xml:lang="en">Using an Element Without Content</title>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating a
	+ horizontal rule, called <tag>hr</tag>. This element
	+ 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>
	+<tag class="starttag">hr</tag><tag class="endtag">hr</tag>
	+
	+<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
	+ from the previous paragraph.<tag class="endtag">p</tag></programlisting>
	+
	+ <para xml:lang="en">The shorthand version consists of a single tag:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
	+<tag class="emptytag">hr</tag>
	+
	+<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
	+ from the previous paragraph.<tag class="endtag">p</tag></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">As shown above, elements can contain other elements. In the
	+ book example earlier, the book element contained all the chapter
	+ elements, which in turn contained all the paragraph elements,
	+ and so on.</para>
	+
	+ <example>
	+ <title xml:lang="en">Elements Within Elements; <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
	+ 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>
	+
	+ <para xml:lang="en">The grammar consists of rules that describe which elements
	+ can contain other elements, and exactly what they can
	+ contain.</para>
	+
	+ <important>
	+ <para xml:lang="en">People often confuse the terms tags and elements, and use
	+ the terms as if they were interchangeable. They are
	+ not.</para>
	+
	+ <para xml:lang="en">An element is a conceptual part of your document. An
	+ element has a defined start and end. The tags mark where the
	+ element starts and ends.</para>
	+
	+ <para xml:lang="en">When this document (or anyone else knowledgeable about
	+ <acronym>XML</acronym>) refers to
	+ <quote>the <tag class="starttag">p</tag> tag</quote>
	+ they mean the literal text consisting of the three characters
	+ <literal><</literal>, <literal>p</literal>, and
	+ <literal>></literal>. But the phrase
	+ <quote>the <tag>p</tag> element</quote> refers to the
	+ whole element.</para>
	+
	+ <para xml:lang="en">This distinction <emphasis>is</emphasis> very subtle. But
	+ keep it in mind.</para>
	+ </important>
	+
	+ <para xml:lang="en">Elements can have attributes. An attribute has a name and a
	+ value, and is used for adding extra information to the element.
	+ This might be information that indicates how the content should
	+ be rendered, or might be something that uniquely identifies that
	+ occurrence of the element, or it might be something else.</para>
	+
	+ <para xml:lang="en">An element's attributes are written
	+ <emphasis>inside</emphasis> the start tag for that element, and
	+ take the form
	+ <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
	+
	+ <para xml:lang="en">In <acronym>XHTML</acronym>, the <tag>p</tag>
	+ element has an attribute called
	+ <tag class="attribute">align</tag>, which suggests an
	+ alignment (justification) for the paragraph to the program
	+ displaying the <acronym>XHTML</acronym>.</para>
	+
	+ <para xml:lang="en">The <tag class="attribute">align</tag> attribute can
	+ take one of four defined values, <literal>left</literal>,
	+ <literal>center</literal>, <literal>right</literal> and
	+ <literal>justify</literal>. If the attribute is not specified
	+ then the default is <literal>left</literal>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Using an Element with an Attribute</title>
	+
	+ <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>
	+
	+<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">Some attributes only take specific values, such as
	+ <literal>left</literal> or <literal>justify</literal>. Others
	+ allow any value.</para>
	+
	+ <example>
	+ <title xml:lang="en">Single Quotes Around Attributes</title>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">Attribute values in <acronym>XML</acronym> must be enclosed
	+ in either single or double quotes. Double quotes are
	+ traditional. Single quotes are useful when the attribute value
	+ contains double quotes.</para>
	+
	+ <para xml:lang="en">Information about attributes, elements, and tags is stored
	+ in catalog files. The Documentation Project uses standard
	+ DocBook catalogs and includes additional catalogs for
	+ FreeBSD-specific features. Paths to the catalog files are defined
	+ in an environment variable so they can be found by the document
	+ build tools.</para>
	+
	+ <sect2>
	+ <title xml:lang="en">To Do…</title>
	+
	+ <para xml:lang="en">Before running the examples in this document, install
	+ <package>textproc/docproj</package> from
	+ the FreeBSD Ports Collection. This is a
	+ <emphasis>meta-port</emphasis> that downloads and installs
	+ the standard programs and supporting files needed by the
	+ Documentation Project. <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> users must use
	+ <command>rehash</command> for the shell to recognize new
	+ programs after they have been installed, or log out
	+ and then log back in again.</para>
	+
	+ <procedure>
	+ <step>
	+ <para xml:lang="en">Create <filename>example.xml</filename>, and enter
	+ this text:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag>
	+
	+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
	+ <tag class="starttag">head</tag>
	+ <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
	+ <tag class="endtag">head</tag>
	+
	+ <tag class="starttag">body</tag>
	+ <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
	+
	+ <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
	+
	+ <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
	+ <tag class="endtag">body</tag>
	+<tag class="endtag">html</tag></programlisting>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Try to validate this file using an
	+ <acronym>XML</acronym> parser.</para>
	+
	+ <para xml:lang="en"><package>textproc/docproj</package>
	+ includes the <command>xmllint</command>
	+ <link linkend="xml-primer-validating">validating
	+ parser</link>.</para>
	+
	+ <para xml:lang="en">Use <command>xmllint</command> to validate the
	+ document:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput></screen>
	+
	+ <para xml:lang="en"><command>xmllint</command> returns without displaying
	+ any output, showing that the document validated
	+ successfully.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">See what happens when required elements are omitted.
	+ Delete the line with the
	+ <tag class="starttag">title</tag> and
	+ <tag class="endtag">title</tag> tags, and re-run
	+ the validation.</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput>
	+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>
	+
	+ <para xml:lang="en">This shows that the validation error comes from the
	+ <replaceable>fifth</replaceable> line of the
	+ <replaceable>example.xml</replaceable> file and that the
	+ content of the <tag class="starttag">head</tag> is
	+ the part which does not follow the rules of the
	+ <acronym>XHTML</acronym> grammar.</para>
	+
	+ <para xml:lang="en">Then <command>xmllint</command> shows the line where
	+ the error was found and marks the exact character position
	+ with a <literal>^</literal> sign.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Replace the <tag>title</tag> element.</para>
	+ </step>
	+ </procedure>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-doctype-declaration">
	+ <title xml:lang="en">The DOCTYPE Declaration</title>
	+
	+ <para xml:lang="en">The beginning of each document can specify the name of the
	+ <acronym>DTD</acronym> to which the document conforms. This
	+ DOCTYPE declaration is used by <acronym>XML</acronym> parsers to
	+ identify the <acronym>DTD</acronym> and ensure that the document
	+ does conform to it.</para>
	+
	+ <para xml:lang="en">A typical declaration for a document written to conform with
	+ version 1.0 of the <acronym>XHTML</acronym>
	+ <acronym>DTD</acronym> looks like this:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting>
	+
	+ <para xml:lang="en">That line contains a number of different components.</para>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term xml:lang="en"><literal><!</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The <emphasis>indicator</emphasis> shows
	+ this is an <acronym>XML</acronym> declaration.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>DOCTYPE</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Shows that this is an <acronym>XML</acronym>
	+ declaration of the document type.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>html</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Names the first
	+ <link linkend="xml-primer-elements">element</link> that
	+ will appear in the document.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Lists the Formal Public Identifier
	+ (<acronym>FPI</acronym>)
	+ <indexterm xml:lang="en">
	+ <primary>Formal Public Identifier</primary>
	+ </indexterm>
	+ for the <acronym>DTD</acronym> to which this document
	+ conforms. The <acronym>XML</acronym> parser uses this to
	+ find the correct <acronym>DTD</acronym> when processing
	+ this document.</para>
	+
	+ <para xml:lang="en"><literal>PUBLIC</literal> is not a part of the
	+ <acronym>FPI</acronym>, but indicates to the
	+ <acronym>XML</acronym> processor how to find the
	+ <acronym>DTD</acronym> referenced in the
	+ <acronym>FPI</acronym>. Other ways of telling the
	+ <acronym>XML</acronym> parser how to find the
	+ <acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">A local filename or a <acronym>URL</acronym> to find
	+ the <acronym>DTD</acronym>.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>></literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Ends the declaration and returns to the
	+ document.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <sect2>
	+ <title xml:lang="en">Formal Public Identifiers
	+ (<acronym>FPI</acronym>s)</title>
	+
	+ <indexterm significance="preferred" xml:lang="en">
	+ <primary>Formal Public Identifier</primary>
	+ </indexterm>
	+
	+ <note>
	+ <para xml:lang="en">It is not necessary to know this, but it is useful
	+ background, and might help debug problems when the
	+ <acronym>XML</acronym> processor can not locate the
	+ <acronym>DTD</acronym>.</para>
	+ </note>
	+
	+ <para xml:lang="en"><acronym>FPI</acronym>s must follow a specific
	+ syntax:</para>
	+
	+ <programlisting xml:lang="en">"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term xml:lang="en"><replaceable>Owner</replaceable></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The owner of the <acronym>FPI</acronym>.</para>
	+
	+ <para xml:lang="en">The beginning of the string identifies the owner of
	+ the <acronym>FPI</acronym>. For example, the
	+ <acronym>FPI</acronym>
	+ <literal>"ISO 8879:1986//ENTITIES Greek
	+ Symbols//EN"</literal> lists
	+ <literal>ISO 8879:1986</literal> as being the owner for
	+ the set of entities for Greek symbols.
	+ <acronym>ISO</acronym> 8879:1986 is the International
	+ Organization for Standardization
	+ (<acronym>ISO</acronym>) number for the
	+ <acronym>SGML</acronym> standard, the predecessor (and a
	+ superset) of <acronym>XML</acronym>.</para>
	+
	+ <para xml:lang="en">Otherwise, this string will either look like
	+ <literal>-//<replaceable>Owner</replaceable></literal>
	+ or
	+ <literal>+//<replaceable>Owner</replaceable></literal>
	+ (notice the only difference is the leading
	+ <literal>+</literal> or <literal>-</literal>).</para>
	+
	+ <para xml:lang="en">If the string starts with <literal>-</literal> then
	+ the owner information is unregistered, with a
	+ <literal>+</literal> identifying it as
	+ registered.</para>
	+
	+ <para xml:lang="en"><acronym>ISO</acronym> 9070:1991 defines how
	+ registered names are generated. It might be derived
	+ from the number of an <acronym>ISO</acronym>
	+ publication, an <acronym>ISBN</acronym> code, or an
	+ organization code assigned according to
	+ <acronym>ISO</acronym> 6523. Additionally, a
	+ registration authority could be created in order to
	+ assign registered names. The <acronym>ISO</acronym>
	+ council delegated this to the American National
	+ Standards Institute (<acronym>ANSI</acronym>).</para>
	+
	+ <para xml:lang="en">Because the FreeBSD Project has not been registered,
	+ the owner string is <literal>-//FreeBSD</literal>. As seen
	+ in the example, the <acronym>W3C</acronym> are not a
	+ registered owner either.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><replaceable>Keyword</replaceable></term>
	+
	+ <listitem>
	+ <para xml:lang="en">There are several keywords that indicate the type of
	+ information in the file. Some of the most common
	+ keywords are <literal>DTD</literal>,
	+ <literal>ELEMENT</literal>, <literal>ENTITIES</literal>,
	+ and <literal>TEXT</literal>. <literal>DTD</literal> is
	+ used only for <acronym>DTD</acronym> files,
	+ <literal>ELEMENT</literal> is usually used for
	+ <acronym>DTD</acronym> fragments that contain only
	+ entity or element declarations. <literal>TEXT</literal>
	+ is used for <acronym>XML</acronym> content (text and
	+ tags).</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><replaceable>Description</replaceable></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Any description can be given for the contents
	+ of this file. This may include version numbers or any
	+ short text that is meaningful and unique for the
	+ <acronym>XML</acronym> system.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><replaceable>Language</replaceable></term>
	+
	+ <listitem>
	+ <para xml:lang="en">An <acronym>ISO</acronym> two-character code that
	+ identifies the native language for the file.
	+ <literal>EN</literal> is used for English.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <sect3>
	+ <title xml:lang="en"><filename>catalog</filename> Files</title>
	+
	+ <para xml:lang="en">With the syntax above, an <acronym>XML</acronym>
	+ processor needs to have some way of turning the
	+ <acronym>FPI</acronym> into the name of the file containing
	+ the <acronym>DTD</acronym>. A catalog file (typically
	+ called <filename>catalog</filename>) contains lines that map
	+ <acronym>FPI</acronym>s to filenames. For example, if the
	+ catalog file contained the line:</para>
	+
	+<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog -->
	+
	+ <programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting>
	+
	+ <para xml:lang="en">The <acronym>XML</acronym> processor knows that the
	+ <acronym>DTD</acronym> is called
	+ <filename>transitional.dtd</filename> in the
	+ <filename>1.0</filename> subdirectory of the directory that
	+ held <filename>catalog</filename>.</para>
	+
	+ <para xml:lang="en">Examine the contents of
	+ <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
	+ This is the catalog file for the <acronym>XHTML</acronym>
	+ <acronym>DTD</acronym>s that were installed as part of the
	+ <package>textproc/docproj</package> port.</para>
	+ </sect3>
	+ </sect2>
	+
	+ <sect2 xml:id="xml-primer-fpi-alternatives">
	+ <title xml:lang="en">Alternatives to <acronym>FPI</acronym>s</title>
	+
	+ <para xml:lang="en">Instead of using an <acronym>FPI</acronym> to indicate the
	+ <acronym>DTD</acronym> to which the document conforms (and
	+ therefore, which file on the system contains the
	+ <acronym>DTD</acronym>), the filename can be explicitly
	+ specified.</para>
	+
	+ <para xml:lang="en">The syntax is slightly different:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting>
	+
	+ <para xml:lang="en">The <literal>SYSTEM</literal> keyword indicates that the
	+ <acronym>XML</acronym> processor should locate the
	+ <acronym>DTD</acronym> in a system specific fashion. This
	+ typically (but not always) means the <acronym>DTD</acronym>
	+ will be provided as a filename.</para>
	+
	+ <para xml:lang="en">Using <acronym>FPI</acronym>s is preferred for reasons of
	+ portability. If the <literal>SYSTEM</literal> identifier is
	+ used, then the <acronym>DTD</acronym> must be provided and
	+ kept in the same location for everyone.</para>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-xml-escape">
	+ <title xml:lang="en">Escaping Back to <acronym>XML</acronym></title>
	+
	+ <para xml:lang="en">Some of the underlying <acronym>XML</acronym> syntax can be
	+ useful within documents. For example, comments can be included
	+ in the document, and will be ignored by the parser. Comments
	+ are entered using <acronym>XML</acronym> syntax. Other uses for
	+ <acronym>XML</acronym> syntax will be shown later.</para>
	+
	+ <para xml:lang="en"><acronym>XML</acronym> sections begin with a
	+ <literal><!</literal> tag and end with a
	+ <literal>></literal>. These sections contain instructions
	+ for the parser rather than elements of the document. Everything
	+ between these tags is <acronym>XML</acronym> syntax. The
	+ <link linkend="xml-primer-doctype-declaration">DOCTYPE
	+ declaration</link> shown earlier is an example of
	+ <acronym>XML</acronym> syntax included in the document.</para>
	+
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-comments">
	+ <title xml:lang="en">Comments</title>
	+
	+ <para xml:lang="en">Comments are an <acronym>XML</acronym> construct, and are
	+ normally only valid inside a <acronym>DTD</acronym>. However,
	+ as <xref linkend="xml-primer-xml-escape"/> shows, it is possible
	+ to use <acronym>XML</acronym> syntax within the document.</para>
	+
	+ <para xml:lang="en">The delimiter for XML comments is the string
	+ <quote><literal>--</literal></quote>. The first occurrence of
	+ this string opens a comment, and the second closes it.</para>
	+
	+ <example>
	+ <title xml:lang="en"><acronym>XML</acronym> Generic Comment</title>
	+
	+ <programlisting xml:lang="en"><!-- This is inside the comment -->
	+
	+<!-- This is another comment -->
	+
	+<!-- This is one way
	+ of doing multiline comments -->
	+
	+<!-- This is another way of --
	+ -- doing multiline comments --></programlisting>
	+ </example>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> users may be familiar with different
	+ rules for comments. In particular, it is often believed that
	+ the string <literal><!--</literal> opens a comment, and it is
	+ only closed by <literal>--></literal>.</para>
	+
	+ <para xml:lang="en">This is <emphasis>not</emphasis> correct. Many web browsers
	+ have broken <acronym>XHTML</acronym> parsers, and will accept
	+ incorrect input as valid. However, the <acronym>XML</acronym>
	+ parsers used by the Documentation Project are more strict, and
	+ will reject documents with that error.</para>
	+
	+ <example>
	+ <title xml:lang="en">Erroneous <acronym>XML</acronym> Comments</title>
	+
	+ <programlisting xml:lang="en"><!-- This is in the comment --
	+
	+ THIS IS OUTSIDE THE COMMENT!
	+
	+ -- back inside the comment --></programlisting>
	+
	+ <para xml:lang="en">The <acronym>XML</acronym> parser will treat this as
	+ though it were actually:</para>
	+
	+ <programlisting xml:lang="en"><!THIS IS OUTSIDE THE COMMENT></programlisting>
	+
	+ <para xml:lang="en">That is not valid <acronym>XML</acronym>, and may give
	+ confusing error messages.</para>
	+ </example>
	+
	+ <sect2>
	+ <title xml:lang="en">To Do…</title>
	+
	+ <procedure>
	+ <step>
	+ <para xml:lang="en">Add some comments to
	+ <filename>example.xml</filename>, and check that the file
	+ still validates using <command>xmllint</command>.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Add some invalid comments to
	+ <filename>example.xml</filename>, and see the error
	+ messages that <command>xmllint</command> gives when it
	+ encounters an invalid comment.</para>
	+ </step>
	+ </procedure>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-entities">
	+ <title xml:lang="en">Entities</title>
	+
	+ <para xml:lang="en">Entities are a mechanism for assigning names to chunks of
	+ content. As an <acronym>XML</acronym> parser processes a
	+ document, any entities it finds are replaced by the content of
	+ the entity.</para>
	+
	+ <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
	+ also the only way to include one marked up file inside another
	+ using <acronym>XML</acronym>.</para>
	+
	+ <para xml:lang="en">There are two types of entities for two different
	+ situations: <emphasis>general entities</emphasis> and
	+ <emphasis>parameter entities</emphasis>.</para>
	+
	+ <sect2 xml:id="xml-primer-general-entities">
	+ <title xml:lang="en">General Entities</title>
	+
	+ <para xml:lang="en">General entities are used to assign names to reusable
	+ chunks of text. These entities can only be used in the
	+ document. They cannot be used in an
	+ <acronym>XML</acronym> context.</para>
	+
	+ <para xml:lang="en">To include the text of a general entity in the document,
	+ include
	+ <literal>&<replaceable>entity-name</replaceable>;</literal>
	+ in the text. For example, consider a general entity called
	+ <literal>current.version</literal> which expands to the
	+ current version number of a product. To use it in the
	+ document, write:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>The current version of our product is
	+ &current.version;.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">When the version number changes, edit the definition of
	+ the general entity, replacing the value. Then reprocess the
	+ document.</para>
	+
	+ <para xml:lang="en">General entities can also be used to enter characters that
	+ could not otherwise be included in an <acronym>XML</acronym>
	+ document. For example, <literal><</literal> and
	+ <literal>&</literal> cannot normally appear in an
	+ <acronym>XML</acronym> document. The <acronym>XML</acronym>
	+ parser sees the <literal><</literal> symbol as the start of
	+ a tag. Likewise, when the <literal>&</literal> symbol is
	+ seen, the next text is expected to be an entity name.</para>
	+
	+ <para xml:lang="en">These symbols can be included by using two predefined
	+ general entities: <literal>&lt;</literal> and
	+ <literal>&amp;</literal>.</para>
	+
	+ <para xml:lang="en">General entities can only be defined within an
	+ <acronym>XML</acronym> context. Such definitions are usually
	+ done immediately after the DOCTYPE declaration.</para>
	+
	+ <example>
	+ <title xml:lang="en">Defining General Entities</title>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
	+<!ENTITY current.version "3.0-RELEASE">
	+<!ENTITY last.version "2.2.7-RELEASE">
	+]></programlisting>
	+
	+ <para xml:lang="en">The DOCTYPE declaration has been extended by adding a
	+ square bracket at the end of the first line. The two
	+ entities are then defined over the next two lines, the
	+ square bracket is closed, and then the DOCTYPE declaration
	+ is closed.</para>
	+
	+ <para xml:lang="en">The square brackets are necessary to indicate that the
	+ DTD indicated by the DOCTYPE declaration is being
	+ extended.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="xml-primer-parameter-entities">
	+ <title xml:lang="en">Parameter Entities</title>
	+
	+ <para xml:lang="en">Parameter entities, like
	+ <link linkend="xml-primer-general-entities">general
	+ entities</link>, are used to assign names to reusable chunks
	+ of text. But parameter entities can only be used within an
	+ <link linkend="xml-primer-xml-escape">XML
	+ context</link>.</para>
	+
	+ <para xml:lang="en">Parameter entity definitions are similar to those for
	+ general entities. However, parameter entries are included
	+ with
	+ <literal>%<replaceable>entity-name</replaceable>;</literal>.
	+ The definition also includes the <literal>%</literal> between
	+ the <literal>ENTITY</literal> keyword and the name of the
	+ entity.</para>
	+
	+ <para xml:lang="en">For a mnemonic, think
	+ <quote><emphasis>P</emphasis>arameter entities use the
	+ <emphasis>P</emphasis>ercent symbol</quote>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Defining Parameter Entities</title>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
	+<!ENTITY % param.some "some">
	+<!ENTITY % param.text "text">
	+<!ENTITY % param.new "%param.some more %param.text">
	+
	+<!-- %param.new now contains "some more text" -->
	+]></programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2>
	+ <title xml:lang="en">To Do…</title>
	+
	+ <procedure>
	+ <step>
	+ <para xml:lang="en">Add a general entity to
	+ <filename>example.xml</filename>.</para>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
	+<!ENTITY version "1.1">
	+]>
	+
	+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
	+ <tag class="starttag">head</tag>
	+ <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
	+ <tag class="endtag">head</tag>
	+
	+ <!-- There may be some comments in here as well -->
	+
	+ <tag class="starttag">body</tag>
	+ <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
	+
	+ <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
	+
	+ <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
	+
	+ <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag>
	+ <tag class="endtag">body</tag>
	+<tag class="endtag">html</tag></programlisting>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Validate the document using
	+ <command>xmllint</command>.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Load <filename>example.xml</filename> into a web
	+ browser. It may have to be copied to
	+ <filename>example.html</filename> before the browser
	+ recognizes it as an <acronym>XHTML</acronym>
	+ document.</para>
	+
	+ <para xml:lang="en">Older browsers with simple parsers may not render this
	+ file as expected. The entity reference
	+ <literal>&version;</literal> may not be replaced by
	+ the version number, or the <acronym>XML</acronym> context
	+ closing <literal>]></literal> may not be recognized and
	+ instead shown in the output.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">The solution is to <emphasis>normalize</emphasis> the
	+ document with an <acronym>XML</acronym> normalizer. The
	+ normalizer reads valid <acronym>XML</acronym> and writes
	+ equally valid <acronym>XML</acronym> which has been
	+ transformed in some way. One way the normalizer
	+ transforms the input is by expanding all the entity
	+ references in the document, replacing the entities with
	+ the text that they represent.</para>
	+
	+ <para xml:lang="en"><command>xmllint</command> can be used for this. It
	+ also has an option to drop the initial
	+ <acronym>DTD</acronym> section so that the closing
	+ <literal>]></literal> does not confuse browsers:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput></screen>
	+
	+ <para xml:lang="en">A normalized copy of the document with entities
	+ expanded is produced in <filename>example.html</filename>,
	+ ready to load into a web browser.</para>
	+ </step>
	+ </procedure>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-include">
	+ <title xml:lang="en">Using Entities to Include Files</title>
	+
	+ <para xml:lang="en">Both
	+ <link linkend="xml-primer-general-entities">general</link> and
	+ <link linkend="xml-primer-parameter-entities">parameter</link>
	+ entities are particularly useful for including one file inside
	+ another.</para>
	+
	+ <sect2 xml:id="xml-primer-include-using-gen-entities">
	+ <title xml:lang="en">Using General Entities to Include Files</title>
	+
	+ <para xml:lang="en">Consider some content for an <acronym>XML</acronym> book
	+ organized into files, one file per chapter, called
	+ <filename>chapter1.xml</filename>,
	+ <filename>chapter2.xml</filename>, and so forth, with a
	+ <filename>book.xml</filename> that will contain these
	+ chapters.</para>
	+
	+ <para xml:lang="en">In order to use the contents of these files as the values
	+ for entities, they are declared with the
	+ <literal>SYSTEM</literal> keyword. This directs the
	+ <acronym>XML</acronym> parser to include the contents of the
	+ named file as the value of the entity.</para>
	+
	+ <example>
	+ <title xml:lang="en">Using General Entities to Include Files</title>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
	+<!ENTITY chapter.1 SYSTEM "chapter1.xml">
	+<!ENTITY chapter.2 SYSTEM "chapter2.xml">
	+<!ENTITY chapter.3 SYSTEM "chapter3.xml">
	+<!-- And so forth -->
	+]>
	+
	+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
	+ <!-- Use the entities to load in the chapters -->
	+
	+ &chapter.1;
	+ &chapter.2;
	+ &chapter.3;
	+<tag class="endtag">html</tag></programlisting>
	+ </example>
	+
	+ <warning>
	+ <para xml:lang="en">When using general entities to include other files
	+ within a document, the files being included
	+ (<filename>chapter1.xml</filename>,
	+ <filename>chapter2.xml</filename>, and so on)
	+ <emphasis>must not</emphasis> start with a DOCTYPE
	+ declaration. This is a syntax error because entities are
	+ low-level constructs and they are resolved before any
	+ parsing happens.</para>
	+ </warning>
	+ </sect2>
	+
	+ <sect2>
	+ <title xml:lang="en">Using Parameter Entities to Include Files</title>
	+
	+ <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 can be used
	+ to ensure that general entities are reusable.</para>
	+
	+ <para xml:lang="en">Suppose that there are many chapters in the document, and
	+ these chapters were reused in two different books, each book
	+ organizing the chapters in a different fashion.</para>
	+
	+ <para xml:lang="en">The entities could be listed at the top of each book, but
	+ that quickly becomes cumbersome to manage.</para>
	+
	+ <para xml:lang="en">Instead, place the general entity definitions inside one
	+ file, and use a parameter entity to include that file within
	+ the document.</para>
	+
	+ <example>
	+ <title xml:lang="en">Using Parameter Entities to Include Files</title>
	+
	+ <para xml:lang="en">Place the entity definitions in a separate file
	+ called <filename>chapters.ent</filename> and
	+ containing this text:</para>
	+
	+ <programlisting xml:lang="en"><!ENTITY chapter.1 SYSTEM "chapter1.xml">
	+<!ENTITY chapter.2 SYSTEM "chapter2.xml">
	+<!ENTITY chapter.3 SYSTEM "chapter3.xml"></programlisting>
	+
	+ <para xml:lang="en">Create a parameter entity to refer to the contents
	+ of the file. Then use the parameter entity to load the file
	+ into the document, which will then make all the general
	+ entities available for use. Then use the general entities
	+ as before:</para>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
	+<!-- Define a parameter entity to load in the chapter general entities -->
	+<!ENTITY % chapters SYSTEM "chapters.ent">
	+
	+<!-- Now use the parameter entity to load in this file -->
	+%chapters;
	+]>
	+
	+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
	+ &chapter.1;
	+ &chapter.2;
	+ &chapter.3;
	+<tag class="endtag">html</tag></programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2>
	+ <title xml:lang="en">To Do…</title>
	+
	+ <sect3>
	+ <title xml:lang="en">Use General Entities to Include Files</title>
	+
	+ <procedure>
	+ <step>
	+ <para xml:lang="en">Create three files, <filename>para1.xml</filename>,
	+ <filename>para2.xml</filename>, and
	+ <filename>para3.xml</filename>.</para>
	+
	+ <para xml:lang="en">Put content like this in each file:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Edit <filename>example.xml</filename> so that it
	+ looks like this:</para>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
	+<!ENTITY version "1.1">
	+<!ENTITY para1 SYSTEM "para1.xml">
	+<!ENTITY para2 SYSTEM "para2.xml">
	+<!ENTITY para3 SYSTEM "para3.xml">
	+]>
	+
	+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
	+ <tag class="starttag">head</tag>
	+ <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
	+ <tag class="endtag">head</tag>
	+
	+ <tag class="starttag">body</tag>
	+ <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag>
	+
	+ &para1;
	+ &para2;
	+ &para3;
	+ <tag class="endtag">body</tag>
	+<tag class="endtag">html</tag></programlisting>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Produce <filename>example.html</filename> by
	+ normalizing <filename>example.xml</filename>.</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Load <filename>example.html</filename> into the web
	+ browser and confirm that the
	+ <filename>para<replaceable>n</replaceable>.xml</filename>
	+ files have been included in
	+ <filename>example.html</filename>.</para>
	+ </step>
	+ </procedure>
	+ </sect3>
	+
	+ <sect3>
	+ <title xml:lang="en">Use Parameter Entities to Include Files</title>
	+
	+ <note>
	+ <para xml:lang="en">The previous steps must have completed before this
	+ step.</para>
	+ </note>
	+
	+ <procedure>
	+ <step>
	+ <para xml:lang="en">Edit <filename>example.xml</filename> so that it
	+ looks like this:</para>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
	+<!ENTITY % entities SYSTEM "entities.ent"> %entities;
	+]>
	+
	+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
	+ <tag class="starttag">head</tag>
	+ <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
	+ <tag class="endtag">head</tag>
	+
	+ <tag class="starttag">body</tag>
	+ <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag>
	+
	+ &para1;
	+ &para2;
	+ &para3;
	+ <tag class="endtag">body</tag>
	+<tag class="endtag">html</tag></programlisting>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Create a new file called
	+ <filename>entities.ent</filename> with this
	+ content:</para>
	+
	+ <programlisting xml:lang="en"><!ENTITY version "1.1">
	+<!ENTITY para1 SYSTEM "para1.xml">
	+<!ENTITY para2 SYSTEM "para2.xml">
	+<!ENTITY para3 SYSTEM "para3.xml"></programlisting>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Produce <filename>example.html</filename> by
	+ normalizing <filename>example.xml</filename>.</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Load <filename>example.html</filename> into the web
	+ browser and confirm that the
	+ <filename>para<replaceable>n</replaceable>.xml</filename>
	+ files have been included in
	+ <filename>example.html</filename>.</para>
	+ </step>
	+ </procedure>
	+ </sect3>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-marked-sections">
	+ <title xml:lang="en">Marked Sections</title>
	+
	+ <para xml:lang="en"><acronym>XML</acronym> provides a mechanism to indicate that
	+ particular pieces of the document should be processed in a
	+ special way. These are called
	+ <quote>marked sections</quote>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Structure of a Marked Section</title>
	+
	+ <programlisting xml:lang="en"><![<replaceable>KEYWORD</replaceable>[
	+ Contents of marked section
	+]]></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">As expected of an <acronym>XML</acronym> construct, a marked
	+ section starts with <literal><!</literal>.</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
	+ section is to be processed by the parser.</para>
	+
	+ <para xml:lang="en">The second square bracket indicates the start of the
	+ marked section's content.</para>
	+
	+ <para xml:lang="en">The marked section is finished by closing the two square
	+ brackets, and then returning to the document context from the
	+ <acronym>XML</acronym> context with
	+ <literal>></literal>.</para>
	+
	+ <sect2 xml:id="xml-primer-marked-section-keywords">
	+ <title xml:lang="en">Marked Section Keywords</title>
	+
	+ <sect3 xml:id="xml-primer-cdata">
	+ <title xml:lang="en"><literal>CDATA</literal></title>
	+
	+ <para xml:lang="en">These keywords denote the marked sections
	+ <emphasis>content model</emphasis>, and allow you to change
	+ it from the default.</para>
	+
	+ <para xml:lang="en">When an <acronym>XML</acronym> parser is processing a
	+ document, it keeps track of the
	+ <quote>content model</quote>.</para>
	+
	+ <para xml:lang="en">The content model describes the
	+ content the parser is expecting to see and what it will do
	+ with that content.</para>
	+
	+ <para xml:lang="en">The <literal>CDATA</literal> content model is one of the
	+ most useful.</para>
	+
	+ <para xml:lang="en"><literal>CDATA</literal> is for
	+ <quote>Character Data</quote>. When the parser is in this
	+ content model, it expects to see only characters. In this
	+ model the <literal><</literal> and
	+ <literal>&</literal> symbols lose their special status,
	+ and will be treated as ordinary characters.</para>
	+
	+ <note>
	+ <para xml:lang="en">When using <literal>CDATA</literal> in examples of
	+ text marked up in <acronym>XML</acronym>, remember that
	+ the content of <literal>CDATA</literal> is not validated.
	+ The included text must be check with other means. For
	+ example, the content could be written in another document,
	+ validated, and then pasted into the
	+ <literal>CDATA</literal> section.</para>
	+ </note>
	+
	+ <example>
	+ <title xml:lang="en">Using a <literal>CDATA</literal> Marked
	+ Section</title>
	+
	+ <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>
	+ 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">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
	+ 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
	+ 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>
	+
	+ <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 second 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="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting>
	+ </example>
	+ </sect3>
	+
	+ <sect3 xml:id="xml-primer-include-ignore">
	+ <title xml:lang="en"><literal>INCLUDE</literal> and
	+ <literal>IGNORE</literal></title>
	+
	+ <para xml:lang="en">When the keyword is <literal>INCLUDE</literal>, then the
	+ contents of the marked section will be processed. When the
	+ keyword is <literal>IGNORE</literal>, the marked section
	+ is ignored and will not be processed. It will not appear in
	+ the output.</para>
	+
	+ <example>
	+ <title xml:lang="en">Using <literal>INCLUDE</literal> and
	+ <literal>IGNORE</literal> in Marked Sections</title>
	+
	+ <programlisting xml:lang="en"><![INCLUDE[
	+ This text will be processed and included.
	+]]>
	+
	+<![IGNORE[
	+ This text will not be processed or included.
	+]]></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">By itself, this is not too useful. Text to be
	+ removed from the document could be cut out, or wrapped
	+ in comments.</para>
	+
	+ <para xml:lang="en">It becomes more useful when controlled by
	+ <link linkend="xml-primer-parameter-entities">parameter
	+ entities</link>, yet this usage is limited
	+ to entity files.</para>
	+
	+ <para xml:lang="en">For example, suppose that documentation was produced in
	+ a hard-copy version and an electronic version. Some extra
	+ text is desired in the electronic version content that was
	+ not to appear in the hard-copy.</para>
	+
	+ <para xml:lang="en">Create an entity file that defines general entities to
	+ include each chapter and guard these definitions with a
	+ parameter entity that can be set to either
	+ <literal>INCLUDE</literal> or <literal>IGNORE</literal> to
	+ control whether the entity is defined. After these
	+ conditional general entity definitions, place one more
	+ definition for each general entity to set them to an empty
	+ value. This technique makes use of the fact that entity
	+ definitions cannot be overridden but the first definition
	+ always takes effect. So the inclusion of the chapter is
	+ controlled with the corresponding parameter entity. Set to
	+ <literal>INCLUDE</literal>, the first general entity
	+ definition will be read and the second one will be ignored.
	+ Set to <literal>IGNORE</literal>, the first definition will
	+ be ignored and the second one will take effect.</para>
	+
	+ <example>
	+ <title xml:lang="en">Using a Parameter Entity to Control a Marked
	+ Section</title>
	+
	+ <programlisting xml:lang="en"><!ENTITY % electronic.copy "INCLUDE">
	+
	+<![%electronic.copy;[
	+<!ENTITY chap.preface SYSTEM "preface.xml">
	+]]>
	+
	+<!ENTITY chap.preface ""></programlisting>
	+
	+ <para xml:lang="en">When producing the hard-copy version, change the
	+ parameter entity's definition to:</para>
	+
	+ <programlisting xml:lang="en"><!ENTITY % electronic.copy "IGNORE"></programlisting>
	+ </example>
	+ </sect3>
	+ </sect2>
	+
	+ <sect2>
	+ <title xml:lang="en">To Do…</title>
	+
	+ <procedure>
	+ <step>
	+ <para xml:lang="en">Modify <filename>entities.ent</filename> to
	+ contain the following:</para>
	+
	+ <programlisting xml:lang="en"><!ENTITY version "1.1">
	+<!ENTITY % conditional.text "IGNORE">
	+
	+<![%conditional.text;[
	+<!ENTITY para1 SYSTEM "para1.xml">
	+]]>
	+
	+<!ENTITY para1 "">
	+
	+<!ENTITY para2 SYSTEM "para2.xml">
	+<!ENTITY para3 SYSTEM "para3.xml"></programlisting>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Normalize <filename>example.xml</filename>
	+ and notice that the conditional text is not present in the
	+ output document. Set the parameter entity
	+ guard to <literal>INCLUDE</literal> and regenerate the
	+ normalized document and the text will appear again.
	+ This method makes sense if there are more
	+ conditional chunks depending on the same condition. For
	+ example, to control generating printed or online
	+ text.</para>
	+ </step>
	+ </procedure>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="xml-primer-conclusion">
	+ <title xml:lang="en">Conclusion</title>
	+
	+ <para xml:lang="en">That is the conclusion of this <acronym>XML</acronym>
	+ primer. For reasons of space and complexity, several things
	+ have not been covered in depth (or at all). However, the
	+ previous sections cover enough <acronym>XML</acronym> to
	+ introduce the organization of the <acronym>FDP</acronym>
	+ documentation.</para>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="xhtml-markup">
	+ <title xml:lang="en"><acronym>XHTML</acronym> Markup</title>
	+
	+ <sect1 xml:id="xhtml-markup-introduction">
	+ <title xml:lang="en">Introduction</title>
	+
	+ <para xml:lang="en">This chapter describes usage of the <acronym>XHTML</acronym>
	+ markup language used for the FreeBSD web site.</para>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> is the <acronym>XML</acronym>
	+ version of the HyperText Markup Language, the markup language of
	+ 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>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> is used to mark up pages on the
	+ FreeBSD web site. It is usually not used to mark up other
	+ documentation, since DocBook offers a far richer set of elements
	+ from which to choose. Consequently, <acronym>XHTML</acronym>
	+ pages will normally only be encountered when writing for the web
	+ site.</para>
	+
	+ <para xml:lang="en"><acronym>HTML</acronym> has gone through a number of
	+ versions. The <acronym>XML</acronym>-compliant version
	+ described here is called <acronym>XHTML</acronym>. The latest
	+ widespread version is <acronym>XHTML</acronym> 1.0, available in
	+ both <emphasis>strict</emphasis> and
	+ <emphasis>transitional</emphasis> variants.</para>
	+
	+ <para xml:lang="en">The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
	+ available from the Ports Collection in
	+ <package>textproc/xhtml</package>. They are
	+ automatically installed by the <package>textproc/docproj</package> port.</para>
	+
	+ <note>
	+ <para xml:lang="en">This is <emphasis>not</emphasis> an exhaustive list of
	+ elements, since that would just repeat the documentation for
	+ <acronym>XHTML</acronym>. The aim is to list those elements
	+ most commonly used. Please post questions about elements or
	+ uses not covered here to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
	+ </note>
	+
	+ <note>
	+ <title xml:lang="en">Inline Versus Block</title>
	+
	+ <para xml:lang="en">In the remainder of this document, when describing
	+ elements, <emphasis>inline</emphasis> means that the element
	+ can occur within a block element, and does not cause a line
	+ break. A <emphasis>block</emphasis> element, by comparison,
	+ will cause a line break (and other processing) when it is
	+ encountered.</para>
	+ </note>
	+ </sect1>
	+
	+ <sect1 xml:id="xhtml-markup-fpi">
	+ <title xml:lang="en">Formal Public Identifier (<acronym>FPI</acronym>)</title>
	+
	+ <para xml:lang="en">There are a number of <acronym>XHTML</acronym>
	+ <acronym>FPI</acronym>s, depending upon the version, or
	+ <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
	+ a document conforms. Most <acronym>XHTML</acronym> documents on
	+ the FreeBSD web site comply with the transitional version of
	+ <acronym>XHTML</acronym> 1.0.</para>
	+
	+ <programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
	+ </sect1>
	+
	+ <sect1 xml:id="xhtml-markup-sectional-elements">
	+ <title xml:lang="en">Sectional Elements</title>
	+
	+ <para xml:lang="en">An <acronym>XHTML</acronym> document is normally split into
	+ two sections. The first section, called the
	+ <emphasis>head</emphasis>, contains meta-information about the
	+ document, such as its title, the name of the author, the parent
	+ document, and so on. The second section, the
	+ <emphasis>body</emphasis>, contains content that will be
	+ displayed to the user.</para>
	+
	+ <para xml:lang="en">These sections are indicated with <tag>head</tag>
	+ and <tag>body</tag> elements respectively. These
	+ elements are contained within the top-level
	+ <tag>html</tag> element.</para>
	+
	+ <example>
	+ <title xml:lang="en">Normal <acronym>XHTML</acronym> Document
	+ Structure</title>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
	+ <tag class="starttag">head</tag>
	+ <tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag>
	+ <tag class="endtag">head</tag>
	+
	+ <tag class="starttag">body</tag>
	+
	+ …
	+
	+ <tag class="endtag">body</tag>
	+<tag class="endtag">html</tag></programlisting>
	+ </example>
	+ </sect1>
	+
	+ <sect1 xml:id="xhtml-markup-block-elements">
	+ <title xml:lang="en">Block Elements</title>
	+
	+ <sect2 xml:id="xhtml-markup-block-elements-headings">
	+ <title xml:lang="en">Headings</title>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> has tags to denote headings in
	+ the document at up to six different levels.</para>
	+
	+ <para xml:lang="en">The largest and most prominent heading is
	+ <tag>h1</tag>, then <tag>h2</tag>,
	+ continuing down to <tag>h6</tag>.</para>
	+
	+ <para xml:lang="en">The element's content is the text of the heading.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>h1</tag>, <tag>h2</tag>,
	+ and Other Header Tags</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag>
	+
	+<!-- Document introduction goes here -->
	+
	+<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 -->
	+
	+<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag>
	+
	+<!-- Content for the first sub-section goes here -->
	+
	+<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag>
	+
	+<!-- Content for the second section goes here --></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">Generally, an <acronym>XHTML</acronym> page should have
	+ one first level heading (<tag>h1</tag>). This can
	+ contain many second level headings (<tag>h2</tag>),
	+ which can in turn contain many third level headings. Do not
	+ leave gaps in the numbering.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="xhtml-markup-block-elements-paragraphs">
	+ <title xml:lang="en">Paragraphs</title>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> supports a single paragraph
	+ element, <tag>p</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>p</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="xhtml-markup-block-elements-block-quotations">
	+ <title xml:lang="en">Block Quotations</title>
	+
	+ <para xml:lang="en">A block quotation is an extended quotation from another
	+ document that will appear in a separate paragraph.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>blockquote</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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
	+ a more perfect Union, establish Justice, insure domestic
	+ Tranquility, provide for the common defence, promote the general
	+ Welfare, and secure the Blessings of Liberty to ourselves and our
	+ Posterity, do ordain and establish this Constitution for the
	+ United States of America.<tag class="endtag">blockquote</tag></programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="xhtml-markup-block-elements-lists">
	+ <title xml:lang="en">Lists</title>
	+
	+ <para xml:lang="en"><acronym>XHTML</acronym> can present the user with three
	+ types of lists: ordered, unordered, and definition.</para>
	+
	+ <para xml:lang="en">Entries in an ordered list will be numbered, while entries
	+ in an unordered list will be preceded by bullet points.
	+ Definition lists have two sections for each entry. The first
	+ section is the term being defined, and the second section is
	+ the definition.</para>
	+
	+ <para xml:lang="en">Ordered lists are indicated by the <tag>ol</tag>
	+ element, unordered lists by the <tag>ul</tag>
	+ element, and definition lists by the <tag>dl</tag>
	+ element.</para>
	+
	+ <para xml:lang="en">Ordered and unordered lists contain listitems, indicated
	+ by the <tag>li</tag> element. A listitem can
	+ contain textual content, or it may be further wrapped in one
	+ or more <tag>p</tag> elements.</para>
	+
	+ <para xml:lang="en">Definition lists contain definition terms
	+ (<tag>dt</tag>) and definition descriptions
	+ (<tag>dd</tag>). A definition term can only contain
	+ inline elements. A definition description can contain other
	+ block elements.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>ul</tag> and
	+ <tag>ol</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">p</tag>An unordered list. Listitems will probably be
	+ preceded by bullets.<tag class="endtag">p</tag>
	+
	+<tag class="starttag">ul</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>Third item<tag class="endtag">li</tag>
	+<tag class="endtag">ul</tag>
	+
	+<tag class="starttag">p</tag>An ordered list, with list items consisting of multiple
	+ paragraphs. Each item (note: not each paragraph) will be
	+ numbered.<tag class="endtag">p</tag>
	+
	+<tag class="starttag">ol</tag>
	+ <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item. It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag>
	+
	+ <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">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>
	+<tag class="endtag">ol</tag></programlisting>
	+ </example>
	+
	+ <example>
	+ <title xml:lang="en">Definition Lists with <tag>dl</tag></title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">dl</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">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">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">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>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="xhtml-markup-block-elements-preformatted-text">
	+ <title xml:lang="en">Pre-formatted Text</title>
	+
	+ <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
	+ and line breaks are shown exactly as they are in the
	+ file.</para>
	+
	+ <para xml:lang="en">Wrap pre-formatted text in the <tag>pre</tag>
	+ element.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>pre</tag> Example</title>
	+
	+ <para xml:lang="en">For example, the <tag>pre</tag> tags could be
	+ used to mark up an email message:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">pre</tag> From: nik@FreeBSD.org
	+ To: freebsd-doc@FreeBSD.org
	+ Subject: New documentation available
	+
	+ There is a new copy of my primer for contributors to the FreeBSD
	+ Documentation Project available at
	+
	+ &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;
	+
	+ Comments appreciated.
	+
	+ N<tag class="endtag">pre</tag></programlisting>
	+
	+ <para xml:lang="en">Keep in mind that <literal><</literal> and
	+ <literal>&</literal> still are recognized as special
	+ characters in pre-formatted text. This is why the example
	+ shown had to use <literal>&lt;</literal> instead of
	+ <literal><</literal>. For consistency,
	+ <literal>&gt;</literal> was used in place of
	+ <literal>></literal>, too. Watch out for the special
	+ characters that may appear in text copied from a plain-text
	+ source, like an email message or program code.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="xhtml-markup-block-elements-tables">
	+ <title xml:lang="en">Tables</title>
	+
	+ <para xml:lang="en">Mark up tabular information using the
	+ <tag>table</tag> element. A table consists of one or
	+ more table rows (<tag>tr</tag>), each containing one
	+ or more cells of table data (<tag>td</tag>). Each
	+ cell can contain other block elements, such as paragraphs or
	+ lists. It can also contain another table (this nesting can
	+ repeat indefinitely). If the cell only contains one paragraph
	+ then the <tag>p</tag>element is not needed.</para>
	+
	+ <example>
	+ <title xml:lang="en">Simple Use of <tag>table</tag></title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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">tr</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="endtag">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 right cell<tag class="endtag">td</tag>
	+ <tag class="endtag">tr</tag>
	+<tag class="endtag">table</tag></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">A cell can span multiple rows and columns by adding the
	+ <tag class="attribute">rowspan</tag> or
	+ <tag class="attribute">colspan</tag> attributes with
	+ values for the number of rows or columns to be spanned.</para>
	+
	+ <example>
	+ <title xml:lang="en">Using
	+ <tag class="attribute">rowspan</tag></title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+
	+<tag class="starttag">table</tag>
	+ <tag class="starttag">tr</tag>
	+ <tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag>
	+ <tag class="endtag">tr</tag>
	+
	+ <tag class="starttag">tr</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="endtag">tr</tag>
	+<tag class="endtag">table</tag></programlisting>
	+ </example>
	+
	+ <example>
	+ <title xml:lang="en">Using
	+ <tag class="attribute">colspan</tag></title>
	+
	+ <para xml:lang="en">Usage:</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>
	+
	+<tag class="starttag">table</tag>
	+ <tag class="starttag">tr</tag>
	+ <tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag>
	+ <tag class="endtag">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 right cell<tag class="endtag">td</tag>
	+ <tag class="endtag">tr</tag>
	+<tag class="endtag">table</tag></programlisting>
	+ </example>
	+
	+ <example>
	+ <title xml:lang="en">Using <tag class="attribute">rowspan</tag> and
	+ <tag class="attribute">colspan</tag>
	+ Together</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+
	+<tag class="starttag">table</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</tag>Top right cell<tag class="endtag">td</tag>
	+ <tag class="endtag">tr</tag>
	+
	+ <tag class="starttag">tr</tag>
	+ <!-- Because the large cell on the left merges into
	+ this row, the first <td> will occur on its
	+ right -->
	+
	+ <tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag>
	+ <tag class="endtag">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 middle 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">table</tag></programlisting>
	+ </example>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="xhtml-markup-inline-elements">
	+ <title xml:lang="en">In-line Elements</title>
	+
	+ <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">
	+ <title xml:lang="en">Emphasizing Information</title>
	+
	+ <para xml:lang="en">Two levels of emphasis are available in
	+ <acronym>XHTML</acronym>, <tag>em</tag> and
	+ <tag>strong</tag>. <tag>em</tag> is for a
	+ normal level of emphasis and <tag>strong</tag>
	+ indicates stronger emphasis.</para>
	+
	+ <para xml:lang="en"><tag>em</tag> is typically rendered in italic
	+ and <tag>strong</tag> is rendered in bold. This is
	+ not always the case, and should not be relied upon. According
	+ to best practices, web pages only hold structural and
	+ semantical information, and stylesheets are later applied to
	+ them. Think of semantics, not formatting, when using these
	+ tags.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>em</tag> and
	+ <tag>strong</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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
	+ <tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text">
	+ <title xml:lang="en">Indicating Fixed-Pitch Text</title>
	+
	+ <para xml:lang="en">Content that should be rendered in a fixed pitch
	+ (typewriter) typeface is tagged with <tag>tt</tag>
	+ (for <quote>teletype</quote>).</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>tt</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="xhtml-markup-inline-elements-links">
	+ <title xml:lang="en">Links</title>
	+
	+ <note>
	+ <para xml:lang="en">Links are also inline elements.</para>
	+ </note>
	+
	+ <sect3 xml:id="xhtml-markup-inline-elements-linking">
	+ <title xml:lang="en">Linking to Other Documents on the Web</title>
	+
	+ <para xml:lang="en">A link points to the <acronym>URL</acronym> of a
	+ document on the web. The link is indicated with
	+ <tag>a</tag>, and the
	+ <tag class="attribute">href</tag> attribute contains
	+ the <acronym>URL</acronym> of the target document. The
	+ content of the element becomes the link, indicated to the
	+ user by showing it in a different color or with an
	+ underline.</para>
	+
	+ <example>
	+ <title xml:lang="en">Using
	+ <tag class="starttag">a href="..."</tag></title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+ </example>
	+
	+ <para xml:lang="en">This link always takes the user to the top of the linked
	+ document.</para>
	+ </sect3>
	+
	+ <sect3 xml:id="xhtml-markup-inline-elements-specific-parts">
	+ <title xml:lang="en">Linking to Specific Parts of Documents</title>
	+
	+ <para xml:lang="en">To link to a specific point within a document, that
	+ document must include an <emphasis>anchor</emphasis> at the
	+ desired point. Anchors are included by setting the
	+ <tag class="attribute">id</tag> attribute of an
	+ element to a name. This example creates an anchor by
	+ setting the <tag class="attribute">id</tag>
	+ attribute of a <tag class="element">p</tag>
	+ element.</para>
	+
	+ <example>
	+ <title xml:lang="en">Creating an Anchor</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+ </example>
	+
	+ <para xml:lang="en">Links to anchors are similar to plain links, but include
	+ a <literal>#</literal> symbol and the anchor's
	+ <acronym>ID</acronym> at the end of the
	+ <acronym>URL</acronym>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Linking to a Named Part of a Different
	+ Document</title>
	+
	+ <para xml:lang="en">The <literal>samplepara</literal> example is part of a
	+ document called <filename>foo.html</filename>. A link to
	+ that specific paragraph in the document is constructed in
	+ this example.</para>
	+
	+ <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">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
	+ </example>
	+
	+ <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
	+ <literal>#</literal> symbol followed by the name of the
	+ anchor.</para>
	+
	+ <example>
	+ <title xml:lang="en">Linking to a Named Part of the Same Document</title>
	+
	+ <para xml:lang="en">The <literal>samplepara</literal> example
	+ 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
	+ <tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this
	+ document.<tag class="endtag">p</tag></programlisting>
	+ </example>
	+ </sect3>
	+ </sect2>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+
	+<chapter version="5.0" xml:id="docbook-markup">
	+
	+ <title xml:lang="en">DocBook Markup</title>
	+
	+ <sect1 xml:id="docbook-markup-introduction">
	+ <title xml:lang="en">Introduction</title>
	+
	+ <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
	+ system, but the subset described here covers the parts that are
	+ most widely used for FreeBSD documentation. While a moderate
	+ subset is covered, it is impossible to anticipate every
	+ 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>
	+
	+ <para xml:lang="en">DocBook was originally developed by HaL Computer Systems and
	+ O'Reilly & Associates to be a Document Type Definition
	+ (<acronym>DTD</acronym>) for writing technical documentation
	+ <footnote><para xml:lang="en">A short history can be found under <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>.
	+ Since 1998 it is maintained by the <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
	+ DocBook Technical Committee</link>. As such, and unlike
	+ LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily
	+ oriented towards markup that describes <emphasis>what</emphasis>
	+ something is, rather than describing <emphasis>how</emphasis> it
	+ should be presented.</para>
	+
	+ <para xml:lang="en">The DocBook <acronym>DTD</acronym> is available from the
	+ Ports Collection in the
	+ <package>textproc/docbook-xml</package>
	+ port. It is automatically installed as part of the
	+ <package>textproc/docproj</package>
	+ port.</para>
	+
	+ <note>
	+ <title xml:lang="en">Formal Versus Informal</title>
	+
	+ <para xml:lang="en">Some elements may exist in two forms,
	+ <emphasis>formal</emphasis> and <emphasis>informal</emphasis>.
	+ Typically, the formal version of the element will consist of a
	+ title followed by the informal version of the element. The
	+ informal version will not have a title.</para>
	+ </note>
	+
	+ <note>
	+ <title xml:lang="en">Inline Versus Block</title>
	+
	+ <para xml:lang="en">In the remainder of this document, when describing
	+ elements, <emphasis>inline</emphasis> means that the element
	+ can occur within a block element, and does not cause a line
	+ break. A <emphasis>block</emphasis> element, by comparison,
	+ will cause a line break (and other processing) when it is
	+ encountered.</para>
	+ </note>
	+ </sect1>
	+
	+ <sect1 xml:id="docbook-markup-freebsd-extensions">
	+ <title xml:lang="en">FreeBSD Extensions</title>
	+
	+ <para xml:lang="en">The FreeBSD Documentation Project has extended the DocBook
	+ <acronym>DTD</acronym> with additional elements and entities.
	+ These additions serve to make some of the markup easier or more
	+ precise.</para>
	+
	+ <para xml:lang="en">Throughout the rest of this document, the term
	+ <quote>DocBook</quote> is used to mean the FreeBSD-extended
	+ DocBook <acronym>DTD</acronym>.</para>
	+
	+ <note>
	+ <para xml:lang="en">Most of these extensions are not unique to FreeBSD, it was
	+ just felt that they were useful enhancements for this
	+ particular project. Should anyone from any of the other *nix
	+ camps (NetBSD, OpenBSD, Linux, …) be interested in
	+ collaborating on a standard DocBook extension set, please
	+ contact Documentation Engineering Team <email>doceng@FreeBSD.org</email>.</para>
	+ </note>
	+
	+ <sect2 xml:id="docbook-markup-freebsd-extensions-elements">
	+ <title xml:lang="en">FreeBSD Elements</title>
	+
	+ <para xml:lang="en">The additional FreeBSD elements are not (currently) in the
	+ 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>
	+
	+ <para xml:lang="en">FreeBSD-specific elements used in the examples below are
	+ clearly marked.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-freebsd-extensions-entities">
	+ <title xml:lang="en">FreeBSD Entities</title>
	+
	+ <para xml:lang="en">This table shows some of the most useful entities
	+ available in the <acronym>FDP</acronym>. For a complete list,
	+ see the <filename>*.ent</filename> files in
	+ <filename>doc/share/xml</filename>.</para>
	+
	+ <informaltable frame="none" pgwide="1">
	+ <tgroup cols="3">
	+ <colspec colname="entity"/>
	+ <colspec colname="expandsto"/>
	+ <colspec colname="notes"/>
	+ <thead>
	+ <row>
	+ <entry/>
	+ <entry/>
	+ <entry/>
	+ </row>
	+ </thead>
	+
	+ <tbody valign="top">
	+ <row>
	+ <entry namest="entity" nameend="notes" xml:lang="en"><emphasis>FreeBSD
	+ Name Entities</emphasis></entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&os;</literal></entry>
	+ <entry xml:lang="en"><literal>FreeBSD</literal></entry>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&os.stable;</literal></entry>
	+ <entry xml:lang="en"><literal>FreeBSD-STABLE</literal></entry>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&os.current;</literal></entry>
	+ <entry xml:lang="en"><literal>FreeBSD-CURRENT</literal></entry>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry/>
	+ <entry/>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry namest="entity" nameend="notes" xml:lang="en">Manual Page
	+ Entities</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&man.ls.1;</literal></entry>
	+ <entry xml:lang="en"><citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry>
	+ <entry xml:lang="en">Usage: <literal>&man.ls.1; is the manual page
	+ for
	+ <command>ls</command>.</literal></entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&man.cp.1;</literal></entry>
	+ <entry xml:lang="en"><citerefentry><refentrytitle>cp</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry>
	+ <entry xml:lang="en">Usage: <literal>The manual page for
	+ <command>cp</command> is
	+ &man.cp.1;.</literal></entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry>
	+ <entry xml:lang="en"><emphasis>link to
	+ <replaceable>command</replaceable> manual page in
	+ section
	+ <replaceable>sectionnumber</replaceable></emphasis></entry>
	+ <entry xml:lang="en">Entities are defined for all the
	+ <link xlink:href="@@URL_RELPREFIX@@/cgi/man.cgi">FreeBSD manual
	+ pages</link>.</entry>
	+ </row>
	+
	+ <row>
	+ <entry/>
	+ <entry/>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry namest="entity" nameend="notes" xml:lang="en">FreeBSD Mailing List
	+ Entities</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&a.doc;</literal></entry>
	+ <entry xml:lang="en"><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link></literal></entry>
	+ <entry xml:lang="en">Usage: <literal>A link to the
	+ &a.doc;.</literal></entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&a.questions;</literal></entry>
	+ <entry xml:lang="en"><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions">FreeBSD general questions mailing list</link></literal></entry>
	+ <entry xml:lang="en">Usage: <literal>A link to the
	+ &a.questions;.</literal></entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&a.<replaceable>listname</replaceable>;</literal></entry>
	+ <entry xml:lang="en"><emphasis>link to
	+ <replaceable>listname</replaceable></emphasis></entry>
	+ <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/eresources.html#eresources-mail">FreeBSD
	+ mailing lists</link>.</entry>
	+ </row>
	+
	+ <row>
	+ <entry/>
	+ <entry/>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry namest="entity" nameend="notes" xml:lang="en">FreeBSD Document
	+ Link Entities</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&url.books.handbook;</literal></entry>
	+ <entry xml:lang="en"><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook</literal></entry>
	+ <entry xml:lang="en">Usage: <literal>A link to the <link
	+ xlink:href="&url.books.handbook;/advanced-networking.html">Advanced
	+ Networking</link> chapter of the
	+ Handbook.</literal></entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&url.books.<replaceable>bookname</replaceable>;</literal></entry>
	+ <entry xml:lang="en"><emphasis>relative path to
	+ <replaceable>bookname</replaceable></emphasis></entry>
	+ <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/">FreeBSD
	+ books</link>.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&url.articles.committers-guide;</literal></entry>
	+ <entry xml:lang="en"><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide</literal></entry>
	+ <entry xml:lang="en">Usage: <literal>A link to the <link
	+ xlink:href="&url.articles.committers-guide;">Committer's
	+ Guide</link>
	+ article.</literal></entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&url.articles.<replaceable>articlename</replaceable>;</literal></entry>
	+ <entry xml:lang="en"><emphasis>relative path to
	+ <replaceable>articlename</replaceable></emphasis></entry>
	+ <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/">FreeBSD
	+ articles</link>.</entry>
	+ </row>
	+
	+ <row>
	+ <entry/>
	+ <entry/>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry namest="entity" nameend="notes" xml:lang="en">Other Operating
	+ System Name Entities</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&linux;</literal></entry>
	+ <entry xml:lang="en"><trademark class="registered">Linux</trademark></entry>
	+ <entry xml:lang="en">The <trademark class="registered">Linux</trademark> operating system.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&unix;</literal></entry>
	+ <entry xml:lang="en"><trademark class="registered">UNIX</trademark></entry>
	+ <entry xml:lang="en">The <trademark class="registered">UNIX</trademark> operating system.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&windows;</literal></entry>
	+ <entry xml:lang="en"><trademark class="registered">Windows</trademark></entry>
	+ <entry xml:lang="en">The <trademark class="registered">Windows</trademark> operating system.</entry>
	+ </row>
	+
	+ <row>
	+ <entry/>
	+ <entry/>
	+ <entry/>
	+ </row>
	+
	+ <row>
	+ <entry namest="entity" nameend="notes" xml:lang="en">Miscellaneous
	+ Entities</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&prompt.root;</literal></entry>
	+ <entry><prompt>#</prompt></entry>
	+ <entry xml:lang="en">The <systemitem class="username">root</systemitem> user
	+ prompt.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&prompt.user;</literal></entry>
	+ <entry><prompt>%</prompt></entry>
	+ <entry xml:lang="en">A prompt for an unprivileged user.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&postscript;</literal></entry>
	+ <entry xml:lang="en"><trademark class="registered">PostScript</trademark></entry>
	+ <entry xml:lang="en">The
	+ <trademark class="registered">PostScript</trademark> programming language.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&tex;</literal></entry>
	+ <entry xml:lang="en"><application>TeX</application></entry>
	+ <entry xml:lang="en">The
	+ <application>TeX</application> typesetting language.</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><literal>&xorg;</literal></entry>
	+ <entry xml:lang="en">Xorg</entry>
	+ <entry xml:lang="en">The Xorg open source X
	+ Window System.</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </informaltable>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="docbook-markup-fpi">
	+ <title xml:lang="en">Formal Public Identifier (FPI)</title>
	+
	+ <para xml:lang="en">In compliance with the DocBook guidelines for writing
	+ <acronym>FPI</acronym>s for DocBook customizations, the
	+ <acronym>FPI</acronym> for the FreeBSD extended DocBook
	+ <acronym>DTD</acronym> is:</para>
	+
	+ <programlisting xml:lang="en">PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
	+ </sect1>
	+
	+ <sect1 xml:id="docbook-markup-document-structure">
	+ <title xml:lang="en">Document Structure</title>
	+
	+ <para xml:lang="en">DocBook allows structuring documentation in several ways.
	+ The FreeBSD Documentation Project uses two primary types of DocBook
	+ document: the book and the article.</para>
	+
	+ <para xml:lang="en">Books are organized into <tag>chapter</tag>s.
	+ This is a mandatory requirement. There may be
	+ <tag>part</tag>s between the book and the chapter to
	+ provide another layer of organization. For example, the
	+ Handbook is arranged in this way.</para>
	+
	+ <para xml:lang="en">A chapter may (or may not) contain one or more sections.
	+ These are indicated with the <tag>sect1</tag> element.
	+ If a section contains another section then use the
	+ <tag>sect2</tag> element, and so on, up to
	+ <tag>sect5</tag>.</para>
	+
	+ <para xml:lang="en">Chapters and sections contain the remainder of the
	+ content.</para>
	+
	+ <para xml:lang="en">An article is simpler than a book, and does not use
	+ chapters. Instead, the content of an article is organized into
	+ one or more sections, using the same <tag>sect1</tag>
	+ (and <tag>sect2</tag> and so on) elements that are used
	+ in books.</para>
	+
	+ <para xml:lang="en">The nature of the document being written should be used to
	+ determine whether it is best marked up as a book or an article.
	+ Articles are well suited to information that does not need to be
	+ broken down into several chapters, and that is, relatively
	+ speaking, quite short, at up to 20-25 pages of content. Books
	+ are best suited to information that can be broken up into
	+ several chapters, possibly with appendices and similar content
	+ as well.</para>
	+
	+ <para xml:lang="en">The <link xlink:href="@@URL_RELPREFIX@@/docs.html">FreeBSD
	+ 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>,
	+ 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>
	+
	+ <sect2 xml:id="docbook-markup-starting-a-book">
	+ <title xml:lang="en">Starting a Book</title>
	+
	+ <para xml:lang="en">The content of a book is contained within the
	+ <tag>book</tag> element. As well as containing
	+ structural markup, this element can contain elements that
	+ include additional information about the book. This is either
	+ meta-information, used for reference purposes, or additional
	+ content used to produce a title page.</para>
	+
	+ <para xml:lang="en">This additional information is contained within
	+ <tag>info</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Boilerplate <tag>book</tag> with
	+ <tag>info</tag></title>
	+
	+ <!-- Cannot put this in a marked section because of the
	+ replaceable elements -->
	+
	+ <programlisting xml:lang="en"><tag class="starttag">book</tag>
	+ <tag class="starttag">info</tag>
	+ <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag>
	+
	+ <tag class="starttag">author</tag>
	+ <tag class="starttag">personname</tag>
	+ <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
	+ <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
	+ <tag class="endtag">personname</tag>
	+
	+ <tag class="starttag">affiliation</tag>
	+ <tag class="starttag">address</tag>
	+ <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag>
	+ <tag class="endtag">address</tag>
	+ <tag class="endtag">affiliation</tag>
	+ <tag class="endtag">author</tag>
	+
	+ <tag class="starttag">copyright</tag>
	+ <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</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="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag>
	+
	+ <tag class="starttag">abstract</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">info</tag>
	+
	+ …
	+
	+<tag class="endtag">book</tag></programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-starting-an-article">
	+ <title xml:lang="en">Starting an Article</title>
	+
	+ <para xml:lang="en">The content of the article is contained within the
	+ <tag>article</tag> element. As well as containing
	+ structural markup, this element can contain elements that
	+ include additional information about the article. This is
	+ either meta-information, used for reference purposes, or
	+ additional content used to produce a title page.</para>
	+
	+ <para xml:lang="en">This additional information is contained within
	+ <tag>info</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Boilerplate <tag>article</tag> with
	+ <tag>info</tag></title>
	+
	+ <!-- Cannot put this in a marked section because of the
	+ replaceable elements -->
	+
	+ <programlisting xml:lang="en"><tag class="starttag">article</tag>
	+ <tag class="starttag">info</tag>
	+ <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag>
	+
	+ <tag class="starttag">author</tag>
	+ <tag class="starttag">personname</tag>
	+ <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
	+ <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
	+ <tag class="endtag">personname</tag>
	+
	+ <tag class="starttag">affiliation</tag>
	+ <tag class="starttag">address</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">author</tag>
	+
	+ <tag class="starttag">copyright</tag>
	+ <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</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="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag>
	+
	+ <tag class="starttag">abstract</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">info</tag>
	+
	+ …
	+
	+<tag class="endtag">article</tag></programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-indicating-chapters">
	+ <title xml:lang="en">Indicating Chapters</title>
	+
	+ <para xml:lang="en">Use <tag>chapter</tag> to mark up your chapters.
	+ Each chapter has a mandatory <tag>title</tag>.
	+ Articles do not contain chapters, they are reserved for
	+ books.</para>
	+
	+ <example>
	+ <title xml:lang="en">A Simple Chapter</title>
	+
	+ <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="endtag">chapter</tag></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">A chapter cannot be empty; it must contain elements in
	+ addition to <tag>title</tag>. If you need to
	+ include an empty chapter then just use an empty
	+ paragraph.</para>
	+
	+ <example>
	+ <title xml:lang="en">Empty Chapters</title>
	+
	+ <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">para</tag><tag class="endtag">para</tag>
	+<tag class="endtag">chapter</tag></programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-sections-below-chapters">
	+ <title xml:lang="en">Sections Below Chapters</title>
	+
	+ <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
	+ are the main structural element, and each article must contain
	+ at least one section. Use the
	+ <tag>sect<replaceable>n</replaceable></tag> element.
	+ The <replaceable>n</replaceable> indicates the section number,
	+ which identifies the section level.</para>
	+
	+ <para xml:lang="en">The first
	+ <tag>sect<replaceable>n</replaceable></tag> is
	+ <tag>sect1</tag>. You can have one or more of these
	+ in a chapter. They can contain one or more
	+ <tag>sect2</tag> elements, and so on, down to
	+ <tag>sect5</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Sections in Chapters</title>
	+
	+ <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">para</tag>Some text in the chapter.<tag class="endtag">para</tag>
	+
	+ <tag class="starttag">sect1</tag>
	+ <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag>
	+
	+ …
	+ <tag class="endtag">sect1</tag>
	+
	+ <tag class="starttag">sect1</tag>
	+ <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">sect2</tag>
	+ <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">sect3</tag>
	+ <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag>
	+
	+ …
	+ <tag class="endtag">sect3</tag>
	+ <tag class="endtag">sect2</tag>
	+
	+ <tag class="starttag">sect2</tag>
	+ <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag>
	+
	+ …
	+ <tag class="endtag">sect2</tag>
	+ <tag class="endtag">sect1</tag>
	+<tag class="endtag">chapter</tag></programlisting>
	+ </example>
	+
	+ <note>
	+ <para xml:lang="en">Section numbers are automatically generated and
	+ prepended to titles when the document is rendered to an
	+ output format. The generated section numbers and titles
	+ from the example above will be:</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en">1.1. First Section</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">1.2. Second Section</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">1.2.1. First Sub-Section</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">1.2.1.1. First Sub-Sub-Section</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">1.2.2. Second Sub-Section</para>
	+ </listitem>
	+ </itemizedlist>
	+ </note>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-subdividing-part">
	+ <title xml:lang="en">Subdividing Using <tag>part</tag>
	+ Elements</title>
	+
	+ <para xml:lang="en"><tag>part</tag>s introduce another level of
	+ organization between <tag>book</tag> and
	+ <tag>chapter</tag> with one or more
	+ <tag>part</tag>s. This cannot be done in an
	+ <tag>article</tag>.</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">part</tag>
	+ <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">chapter</tag>
	+ <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag>
	+
	+ ...
	+ <tag class="endtag">chapter</tag>
	+
	+ <tag class="starttag">chapter</tag>
	+ <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag>
	+
	+ ...
	+ <tag class="endtag">chapter</tag>
	+
	+ <tag class="starttag">chapter</tag>
	+ <tag class="starttag">title</tag>History<tag class="endtag">title</tag>
	+
	+ ...
	+ <tag class="endtag">chapter</tag>
	+<tag class="endtag">part</tag></programlisting>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="docbook-markup-block-elements">
	+ <title xml:lang="en">Block Elements</title>
	+
	+ <sect2 xml:id="docbook-markup-paragraphs">
	+ <title xml:lang="en">Paragraphs</title>
	+
	+ <para xml:lang="en">DocBook supports three types of paragraphs:
	+ <tag>formalpara</tag>, <tag>para</tag>, and
	+ <tag>simpara</tag>.</para>
	+
	+ <para xml:lang="en">Almost all paragraphs in FreeBSD documentation use
	+ <tag>para</tag>. <tag>formalpara</tag>
	+ includes a <tag>title</tag> element, and
	+ <tag>simpara</tag> disallows some elements from
	+ within <tag>para</tag>. Stick with
	+ <tag>para</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>para</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">This is a paragraph. It can contain just about any
	+ other element.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-block-quotations">
	+ <title xml:lang="en">Block Quotations</title>
	+
	+ <para xml:lang="en">A block quotation is an extended quotation from another
	+ document that should not appear within the current paragraph.
	+ These are rarely needed.</para>
	+
	+ <para xml:lang="en">Blockquotes can optionally contain a title and an
	+ attribution (or they can be left untitled and
	+ unattributed).</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>blockquote</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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">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">para</tag>We the People of the United States, in Order to form a more
	+ perfect Union, establish Justice, insure domestic Tranquility,
	+ provide for the common defence, promote the general Welfare, and
	+ secure the Blessings of Liberty to ourselves and our Posterity, do
	+ ordain and establish this Constitution for the United States of
	+ America.<tag class="endtag">para</tag>
	+<tag class="endtag">blockquote</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">A small excerpt from the US Constitution:</para>
	+
	+ <blockquote>
	+ <title xml:lang="en">Preamble to the Constitution of the United
	+ States</title>
	+
	+ <attribution xml:lang="en">Copied from a web site
	+ somewhere</attribution>
	+
	+ <para xml:lang="en">We the People of the United States, in Order to form
	+ a more perfect Union, establish Justice, insure domestic
	+ Tranquility, provide for the common defence, promote the
	+ general Welfare, and secure the Blessings of Liberty to
	+ ourselves and our Posterity, do ordain and establish
	+ this Constitution for the United States of
	+ America.</para>
	+ </blockquote>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-tips-notes">
	+ <title xml:lang="en">Tips, Notes, Warnings, Cautions, and Important
	+ Information</title>
	+
	+ <para xml:lang="en">Extra information may need to be separated from
	+ the main body of the text. Typically this is
	+ <quote>meta</quote> information of which the user should be
	+ aware.</para>
	+
	+ <para xml:lang="en">Several types of admonitions are available:
	+ <tag>tip</tag>, <tag>note</tag>,
	+ <tag>warning</tag>, <tag>caution</tag>, and
	+ <tag>important</tag>.</para>
	+
	+ <para xml:lang="en">Which admonition to choose depends on the situation.
	+ The DocBook
	+ documentation suggests:</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en">Note is for information that should be heeded by
	+ all readers.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">Important is a variation on Note.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">Caution is for information regarding possible data
	+ loss or software damage.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">Warning is for information regarding possible
	+ hardware damage or injury to life or limb.</para>
	+ </listitem>
	+ </itemizedlist>
	+
	+ <example>
	+ <title xml:lang="en"><tag>tip</tag> and <tag>important</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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="endtag">tip</tag>
	+
	+<tag class="starttag">important</tag>
	+ <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions
	+ are visually jarring and can have the opposite of the
	+ intended effect.<tag class="endtag">para</tag>
	+<tag class="endtag">important</tag></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">Appearance:</para>
	+ <!-- Need to do this outside of the example -->
	+ <tip>
	+ <para xml:lang="en">FreeBSD may reduce stress.</para>
	+ </tip>
	+
	+ <important>
	+ <para xml:lang="en">Please use admonitions sparingly. Too many admonitions
	+ are visually jarring and can have the opposite of the
	+ intended effect.</para>
	+ </important>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-example">
	+ <title>舉例</title>
	+
	+ <para xml:lang="en">Examples can be shown with <tag>example</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>example</tag> Source</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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">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>
	+ </example>
	+
	+ <!-- Need to do this outside of the example -->
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <example>
	+ <title xml:lang="en">Rendered <tag>example</tag></title>
	+
	+ <para xml:lang="en">Empty files can be created easily:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>touch file1 file2 file3</userinput></screen>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-lists-and-procedures">
	+ <title xml:lang="en">Lists and Procedures</title>
	+
	+ <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
	+ accomplish a particular goal.</para>
	+
	+ <para xml:lang="en">To do this, use <tag>itemizedlist</tag>,
	+ <tag>orderedlist</tag>, <tag>variablelist</tag>, or
	+ <tag>procedure</tag>. There are other types of list
	+ elements in DocBook, but we will not cover them here.</para>
	+
	+ <para xml:lang="en"><tag>itemizedlist</tag> and
	+ <tag>orderedlist</tag> are similar to their
	+ counterparts in <acronym>HTML</acronym>, <tag>ul</tag>
	+ and <tag>ol</tag>. Each one consists of one or more
	+ <tag>listitem</tag> elements, and each
	+ <tag>listitem</tag> contains one or more block
	+ elements. The <tag>listitem</tag> elements are
	+ analogous to <acronym>HTML</acronym>'s <tag>li</tag>
	+ tags. However, unlike HTML, they are required.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>itemizedlist</tag> and
	+ <tag>orderedlist</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">itemizedlist</tag>
	+ <tag class="starttag">listitem</tag>
	+ <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag>
	+ <tag class="endtag">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="endtag">listitem</tag>
	+<tag class="endtag">itemizedlist</tag>
	+
	+<tag class="starttag">orderedlist</tag>
	+ <tag class="starttag">listitem</tag>
	+ <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag>
	+ <tag class="endtag">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="endtag">listitem</tag>
	+<tag class="endtag">orderedlist</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en">This is the first itemized item.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">This is the second itemized item.</para>
	+ </listitem>
	+ </itemizedlist>
	+
	+ <orderedlist>
	+ <listitem>
	+ <para xml:lang="en">This is the first ordered item.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">This is the second ordered item.</para>
	+ </listitem>
	+ </orderedlist>
	+ </example>
	+
	+ <para xml:id="docbook-markup-varlist" xml:lang="en">An alternate and often
	+ useful way of presenting information is the
	+ <tag>variablelist</tag>. These are lists where each entry has
	+ a term and a description. They are well suited for many types
	+ of descriptions, and present information in a form that is
	+ often easier for the reader than sections and
	+ subsections.</para>
	+
	+ <para xml:lang="en">A <tag>variablelist</tag> has a <tag>title</tag>, and then
	+ pairs of <tag>term</tag> and <tag>listitem</tag>
	+ entries.</para>
	+
	+ <example xml:id="docbook-markup-variablelist-example">
	+ <title xml:lang="en"><tag>variablelist</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">variablelist</tag>
	+ <tag class="starttag">varlistentry</tag>
	+ <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag>
	+
	+ <tag class="starttag">listitem</tag>
	+ <tag class="starttag">para</tag>In parallel communications, groups of bits arrive
	+ at the same time over multiple communications
	+ channels.<tag class="endtag">para</tag>
	+ <tag class="endtag">listitem</tag>
	+ <tag class="endtag">varlistentry</tag>
	+
	+ <tag class="starttag">varlistentry</tag>
	+ <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag>
	+
	+ <tag class="starttag">listitem</tag>
	+ <tag class="starttag">para</tag>In serial communications, bits arrive one at a
	+ time over a single communications
	+ channel.<tag class="endtag">para</tag>
	+ <tag class="endtag">listitem</tag>
	+ <tag class="endtag">varlistentry</tag>
	+<tag class="endtag">variablelist</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term xml:lang="en">Parallel</term>
	+
	+ <listitem>
	+ <para xml:lang="en">In parallel communications, groups of bits arrive
	+ at the same time over multiple communications
	+ channels.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en">Serial</term>
	+
	+ <listitem>
	+ <para xml:lang="en">In serial communications, bits arrive one at a
	+ time over a single communications channel.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+ </example>
	+
	+ <para xml:lang="en">A <tag>procedure</tag> shows a series of
	+ <tag>step</tag>s, which may in turn
	+ consist of more <tag>step</tag>s or
	+ <tag>substep</tag>s. Each <tag>step</tag>
	+ contains block elements and may include an optional title.</para>
	+
	+ <para xml:lang="en">Sometimes, steps are not sequential, but present a choice:
	+ do <emphasis>this</emphasis> or do <emphasis>that</emphasis>,
	+ but not both. For these alternative choices, use
	+ <tag>stepalternatives</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>procedure</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">procedure</tag>
	+ <tag class="starttag">step</tag>
	+ <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag>
	+ <tag class="endtag">step</tag>
	+
	+ <tag class="starttag">step</tag>
	+ <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag>
	+ <tag class="endtag">step</tag>
	+
	+ <tag class="starttag">step</tag>
	+ <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag>
	+ <tag class="endtag">step</tag>
	+
	+ <tag class="starttag">step</tag>
	+ <tag class="starttag">para</tag>Finally, do one of these.<tag class="endtag">para</tag>
	+
	+ <tag class="starttag">stepalternatives</tag>
	+ <tag class="starttag">step</tag>
	+ <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag>
	+ <tag class="endtag">step</tag>
	+
	+ <tag class="starttag">step</tag>
	+ <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag>
	+ <tag class="endtag">step</tag>
	+ <tag class="endtag">stepalternatives</tag>
	+ <tag class="endtag">step</tag>
	+<tag class="endtag">procedure</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <procedure>
	+ <step>
	+ <para xml:lang="en">Do this.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Then do this.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">And now do this.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Finally, do one of these:</para>
	+
	+ <stepalternatives>
	+ <step>
	+ <para xml:lang="en">Go left.</para>
	+ </step>
	+
	+ <step>
	+ <para xml:lang="en">Go right.</para>
	+ </step>
	+ </stepalternatives>
	+ </step>
	+ </procedure>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-showing-file-samples">
	+ <title xml:lang="en">Showing File Samples</title>
	+
	+ <para xml:lang="en">Fragments of a file (or perhaps a complete file) are shown
	+ by wrapping them in the <tag>programlisting</tag>
	+ element.</para>
	+
	+ <para xml:lang="en">White space and line breaks within
	+ <tag>programlisting</tag> <emphasis>are</emphasis>
	+ significant. In particular, this means that the opening tag
	+ should appear on the same line as the first line of the
	+ output, and the closing tag should appear on the same line
	+ as the last line of the output, otherwise spurious blank
	+ lines may be included.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>programlisting</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like
	+ this:<tag class="endtag">para</tag>
	+
	+<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt;
	+
	+int
	+main(void)
	+{
	+ printf("hello, world\n");
	+}<tag class="endtag">programlisting</tag></programlisting>
	+
	+ <para xml:lang="en">Notice how the angle brackets in the
	+ <literal>#include</literal> line need to be referenced by
	+ their entities instead of being included literally.</para>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">When finished, the program will look like this:</para>
	+
	+ <programlisting xml:lang="en">#include <stdio.h>
	+
	+int
	+main(void)
	+{
	+ printf("hello, world\n");
	+}</programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-callouts">
	+ <title xml:lang="en">Callouts</title>
	+
	+ <para xml:lang="en">A callout is a visual marker for referring to a
	+ piece of text or specific position within an
	+ example.</para>
	+
	+ <para xml:lang="en">Callouts are marked with the <tag>co</tag>
	+ element. Each element must have a unique
	+ <literal>id</literal> assigned to it. After the example,
	+ include a <tag>calloutlist</tag> that describes each
	+ callout.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>co</tag> and
	+ <tag>calloutlist</tag> Example</title>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like
	+ 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>
	+
	+int <tag class="emptytag">co xml:id="co-ex-return"</tag>
	+main(void)
	+{
	+ printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag>
	+}<tag class="endtag">programlisting</tag>
	+
	+<tag class="starttag">calloutlist</tag>
	+ <tag class="starttag">callout arearefs="co-ex-include"</tag>
	+ <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag>
	+ <tag class="endtag">callout</tag>
	+
	+ <tag class="starttag">callout arearefs="co-ex-return"</tag>
	+ <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an
	+ int.<tag class="endtag">para</tag>
	+ <tag class="endtag">callout</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">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">calloutlist</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</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"/>
	+
	+int <co xml:id="co-ex-return"/>
	+main(void)
	+{
	+ printf("hello, world\n"); <co xml:id="co-ex-printf"/>
	+}</programlisting>
	+
	+ <calloutlist>
	+ <callout arearefs="co-ex-include">
	+ <para xml:lang="en">Includes the standard IO header file.</para>
	+ </callout>
	+
	+ <callout arearefs="co-ex-return">
	+ <para xml:lang="en">Specifies that <function>main()</function> returns
	+ an int.</para>
	+ </callout>
	+
	+ <callout arearefs="co-ex-printf">
	+ <para xml:lang="en">The <function>printf()</function> call that writes
	+ <literal>hello, world</literal> to standard
	+ output.</para>
	+ </callout>
	+ </calloutlist>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-tables">
	+ <title xml:lang="en">Tables</title>
	+
	+ <para xml:lang="en">Unlike <acronym>HTML</acronym>, DocBook does not need
	+ tables for layout purposes, as the stylesheet handles those
	+ issues. Instead, just use tables for marking up tabular
	+ data.</para>
	+
	+ <para xml:lang="en">In general terms (and see the DocBook documentation for
	+ more detail) a table (which can be either formal or informal)
	+ consists of a <tag>table</tag> element. This contains
	+ at least one <tag>tgroup</tag> element, which
	+ specifies (as an attribute) the number of columns in this
	+ table group. Within the tablegroup there is one
	+ <tag>thead</tag> element, which contains elements for
	+ the table headings (column headings), and one
	+ <tag>tbody</tag> which contains the body of the
	+ table.</para>
	+
	+ <para xml:lang="en">Both <tag>tgroup</tag> and
	+ <tag>thead</tag> contain <tag>row</tag>
	+ elements, which in turn contain <tag>entry</tag>
	+ elements. Each <tag>entry</tag> element specifies
	+ one cell in the table.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>informaltable</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">informaltable pgwide="1"</tag>
	+ <tag class="starttag">tgroup cols="2"</tag>
	+ <tag class="starttag">thead</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 2<tag class="endtag">entry</tag>
	+ <tag class="endtag">row</tag>
	+ <tag class="endtag">thead</tag>
	+
	+ <tag class="starttag">tbody</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 2<tag class="endtag">entry</tag>
	+ <tag class="endtag">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 2<tag class="endtag">entry</tag>
	+ <tag class="endtag">row</tag>
	+ <tag class="endtag">tbody</tag>
	+ <tag class="endtag">tgroup</tag>
	+<tag class="endtag">informaltable</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <informaltable pgwide="1">
	+ <tgroup cols="2">
	+ <thead>
	+ <row>
	+ <entry xml:lang="en">This is Column Head 1</entry>
	+ <entry xml:lang="en">This is Column Head 2</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry xml:lang="en">Row 1, column 1</entry>
	+ <entry xml:lang="en">Row 1, column 2</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en">Row 2, column 1</entry>
	+ <entry xml:lang="en">Row 2, column 2</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </informaltable>
	+ </example>
	+
	+ <para xml:lang="en">Always use the <literal>pgwide</literal> attribute with
	+ a value of <literal>1</literal> with the
	+ <tag>informaltable</tag> element. A bug in Internet
	+ Explorer can cause the table to render incorrectly if this
	+ is omitted.</para>
	+
	+ <para xml:lang="en">Table borders can be suppressed by setting the
	+ <literal>frame</literal> attribute to <literal>none</literal>
	+ in the <tag>informaltable</tag> element. For example,
	+ <literal>informaltable frame="none"</literal>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Table with <literal>frame="none"</literal> Example</title>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <informaltable frame="none" pgwide="1">
	+ <tgroup cols="2">
	+ <thead>
	+ <row>
	+ <entry xml:lang="en">This is Column Head 1</entry>
	+ <entry xml:lang="en">This is Column Head 2</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry xml:lang="en">Row 1, column 1</entry>
	+ <entry xml:lang="en">Row 1, column 2</entry>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en">Row 2, column 1</entry>
	+ <entry xml:lang="en">Row 2, column 2</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </informaltable>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-examples">
	+ <title xml:lang="en">Examples for the User to Follow</title>
	+
	+ <para xml:lang="en">Examples for the user to follow are often necessary.
	+ Typically, these will consist of dialogs with the computer;
	+ the user types in a command, the user gets a response back,
	+ the user types another command, and so on.</para>
	+
	+ <para xml:lang="en">A number of distinct elements and entities come into
	+ play here.</para>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term xml:lang="en"><tag>screen</tag></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Everything the user sees in this example will be
	+ on the computer screen, so the next element is
	+ <tag>screen</tag>.</para>
	+
	+ <para xml:lang="en">Within <tag>screen</tag>, white space is
	+ significant.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><tag>prompt</tag>,
	+ <literal>&prompt.root;</literal> and
	+ <literal>&prompt.user;</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">Some of the things the user will be seeing on the
	+ screen are prompts from the computer (either from the
	+ operating system, command shell, or application). These
	+ should be marked up using
	+ <tag>prompt</tag>.</para>
	+
	+ <para xml:lang="en">As a special case, the two shell prompts for the
	+ normal user and the root user have been provided as
	+ entities. To indicate the user is at a shell prompt,
	+ use one of <literal>&prompt.root;</literal> and
	+ <literal>&prompt.user;</literal> as necessary. They
	+ do not need to be inside
	+ <tag>prompt</tag>.</para>
	+
	+ <note>
	+ <para xml:lang="en"><literal>&prompt.root;</literal> and
	+ <literal>&prompt.user;</literal> are FreeBSD
	+ extensions to DocBook, and are not part of the
	+ original <acronym>DTD</acronym>.</para>
	+ </note>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><tag>userinput</tag></term>
	+
	+ <listitem>
	+ <para xml:lang="en">When displaying text that the user should type in,
	+ wrap it in <tag>userinput</tag> tags. It will
	+ be displayed differently than system output text.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <example>
	+ <title xml:lang="en"><tag>screen</tag>, <tag>prompt</tag>,
	+ and <tag>userinput</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag>
	+foo1
	+foo2
	+foo3
	+&prompt.user; <tag class="starttag">userinput</tag>ls -1 \| grep foo2<tag class="endtag">userinput</tag>
	+foo2
	+&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</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>
	+This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>ls -1</userinput>
	+foo1
	+foo2
	+foo3
	+<prompt>%</prompt> <userinput>ls -1 \| grep foo2</userinput>
	+foo2
	+<prompt>%</prompt> <userinput>su</userinput>
	+<prompt>Password: </prompt>
	+<prompt>#</prompt> <userinput>cat foo2</userinput>
	+This is the file called 'foo2'</screen>
	+ </example>
	+
	+ <note>
	+ <para xml:lang="en">Even though we are displaying the contents of the file
	+ <filename>foo2</filename>, it is <emphasis>not</emphasis>
	+ marked up as <tag>programlisting</tag>. Reserve
	+ <tag>programlisting</tag> for showing fragments of
	+ files outside the context of user actions.</para>
	+ </note>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="docbook-markup-inline-elements">
	+ <title xml:lang="en">In-line Elements</title>
	+
	+ <sect2 xml:id="docbook-markup-inline-emphasizing">
	+ <title xml:lang="en">Emphasizing Information</title>
	+
	+ <para xml:lang="en">To emphasize a particular word or phrase, use
	+ <tag>emphasis</tag>. This may be presented as
	+ italic, or bold, or might be spoken differently with a
	+ text-to-speech system.</para>
	+
	+ <para xml:lang="en">There is no way to change the presentation of the
	+ emphasis within the document, no equivalent of
	+ <acronym>HTML</acronym>'s <tag>b</tag> and
	+ <tag>i</tag>. If the information being presented is
	+ important, then consider presenting it in
	+ <tag>important</tag> rather than
	+ <tag>emphasis</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>emphasis</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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>
	+ premiere &unix;-like operating system for the Intel
	+ architecture.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">FreeBSD is without doubt <emphasis>the</emphasis>
	+ premiere <trademark class="registered">UNIX</trademark>-like operating system for the Intel
	+ architecture.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-acronyms">
	+ <title xml:lang="en">Acronyms</title>
	+
	+ <para xml:lang="en">Many computer terms are <emphasis>acronyms</emphasis>,
	+ words formed from the first letter of each word in a
	+ phrase. Acronyms are marked up into
	+ <tag>acronym</tag> elements. It is helpful to the
	+ reader when an acronym is defined on the first use, as shown
	+ in the example below.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>acronym</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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
	+ defined the use of avian carriers for transmission of
	+ 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
	+ transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">Request For Comments (<acronym>RFC</acronym>) 1149
	+ defined the use of avian carriers for transmission of
	+ Internet Protocol (<acronym>IP</acronym>) data. The
	+ quantity of <acronym>IP</acronym> data currently
	+ transmitted in that manner is unknown.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-quotations">
	+ <title xml:lang="en">Quotations</title>
	+
	+ <para xml:lang="en">To quote text from another document or source, or to
	+ denote a phrase that is used figuratively, use
	+ <tag>quote</tag>. Most of the markup tags available
	+ for normal text are also available from within a
	+ <tag>quote</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>quote</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>,
	+ 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 xml:lang="en">However, make sure that the search does not go beyond
	+ the <quote>boundary between local and public
	+ administration</quote>, as <acronym>RFC</acronym> 1535
	+ calls it.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-keys">
	+ <title xml:lang="en">Keys, Mouse Buttons, and Combinations</title>
	+
	+ <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>mousebutton</tag>. And to refer to
	+ combinations of key presses or mouse clicks, wrap them all
	+ in <tag>keycombo</tag>.</para>
	+
	+ <para xml:lang="en"><tag>keycombo</tag> has an attribute called
	+ <literal>action</literal>, which may be one of
	+ <literal>click</literal>, <literal>double-click</literal>,
	+ <literal>other</literal>, <literal>press</literal>,
	+ <literal>seq</literal>, or <literal>simul</literal>. The
	+ last two values denote whether the keys or buttons should be
	+ pressed in sequence, or simultaneously.</para>
	+
	+ <para xml:lang="en">The stylesheets automatically add any connecting
	+ symbols, such as <literal>+</literal>, between the key
	+ names, when wrapped in <tag>keycombo</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en">Keys, Mouse Buttons, and Combinations Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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">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">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">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">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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">To switch to the second virtual terminal, press
	+ <keycombo action="simul"><keycap>Alt</keycap>
	+ <keycap>F1</keycap></keycombo>.</para>
	+
	+ <para xml:lang="en">To exit <command>vi</command> without saving changes,
	+ type <keycombo action="seq">
	+ <keycap>Esc</keycap>
	+ <keycap>:</keycap>
	+ <keycap>q</keycap>
	+ <keycap>!</keycap></keycombo>.</para>
	+
	+ <para xml:lang="en">My window manager is configured so that
	+ <keycombo action="simul">
	+ <keycap>Alt</keycap>
	+ <mousebutton>right</mousebutton></keycombo> mouse button
	+ is used to move windows.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-applications">
	+ <title xml:lang="en">Applications, Commands, Options, and Cites</title>
	+
	+ <para xml:lang="en">Both applications and commands are frequently referred to
	+ when writing documentation. The distinction between them is
	+ that an application is the name of a program or suite of
	+ programs that fulfill a particular task. A command is the
	+ filename of a program that the user can type and run at a
	+ command line.</para>
	+
	+ <para xml:lang="en">It is often necessary to show some of the options that a
	+ command might take.</para>
	+
	+ <para xml:lang="en">Finally, it is often useful to list a command with its
	+ manual section number, in the <quote>command(number)</quote>
	+ format so common in Unix manuals.</para>
	+
	+ <para xml:lang="en">Mark up application names with
	+ <tag>application</tag>.</para>
	+
	+ <para xml:lang="en">To list a command with its manual section
	+ number (which should be most of the time) the DocBook
	+ element is <tag>citerefentry</tag>. This will
	+ contain a further two elements,
	+ <tag>refentrytitle</tag> and
	+ <tag>manvolnum</tag>. The content of
	+ <tag>refentrytitle</tag> is the name of the command,
	+ and the content of <tag>manvolnum</tag> is the
	+ manual page section.</para>
	+
	+ <para xml:lang="en">This can be cumbersome to write, and so a series of
	+ <link linkend="xml-primer-general-entities">general
	+ entities</link> have been created to make this easier.
	+ Each entity takes the form
	+ <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
	+
	+ <para xml:lang="en">The file that contains these entities is in
	+ <filename>doc/share/xml/man-refs.ent</filename>, and can be
	+ referred to using this <acronym>FPI</acronym>:</para>
	+
	+ <programlisting xml:lang="en">PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
	+
	+ <para xml:lang="en">Therefore, the introduction to FreeBSD documentation will
	+ usually include this:</para>
	+
	+ <programlisting xml:lang="en"><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
	+
	+<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
	+%man;
	+
	+…
	+
	+]></programlisting>
	+
	+ <para xml:lang="en">Use <tag>command</tag> to include a command
	+ name <quote>in-line</quote> but present it as something the
	+ user should type.</para>
	+
	+ <para xml:lang="en">Use <tag>option</tag> to mark up the options
	+ which will be passed to a command.</para>
	+
	+ <para xml:lang="en">When referring to the same command multiple times in
	+ close proximity, it is preferred to use the
	+ <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
	+ notation to markup the first reference and use
	+ <tag>command</tag> to markup subsequent references.
	+ This makes the generated output, especially
	+ <acronym>HTML</acronym>, appear visually better.</para>
	+
	+ <example>
	+ <title xml:lang="en">Applications, Commands, and Options Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+
	+<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">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>
	+ <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>
	+ <tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1;
	+ 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">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</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
	+ 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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en"><application>Sendmail</application> is the most widely
	+ used Unix mail application.</para>
	+
	+ <para xml:lang="en"><application>Sendmail</application> includes the
	+ <citerefentry>
	+ <refentrytitle>sendmail</refentrytitle>
	+ <manvolnum>8</manvolnum>
	+ </citerefentry>, <citerefentry><refentrytitle>mailq</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and <citerefentry><refentrytitle>newaliases</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	+ programs.</para>
	+
	+ <para xml:lang="en">One of the command line parameters to
	+ <citerefentry>
	+ <refentrytitle>sendmail</refentrytitle>
	+ <manvolnum>8</manvolnum>
	+ </citerefentry>, <option>-bp</option>, will display the
	+ current status of messages in the mail queue. Check this
	+ on the command line by running
	+ <command>sendmail -bp</command>.</para>
	+ </example>
	+
	+ <note>
	+ <para xml:lang="en">Notice how the
	+ <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
	+ notation is easier to follow.</para>
	+ </note>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-files">
	+ <title xml:lang="en">Files, Directories, Extensions, Device Names</title>
	+
	+ <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>
	+
	+ <example>
	+ <title xml:lang="en"><tag>filename</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>.
	+ 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
	+ 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
	+ by the system, and appears in
	+ <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">The source for the Handbook in English is found in
	+ <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
	+ The main file is called <filename>book.xml</filename>.
	+ There is also a <filename>Makefile</filename> and a number
	+ of files with a <filename>.ent</filename> extension.</para>
	+
	+ <para xml:lang="en"><filename>kbd0</filename> is the first keyboard detected
	+ by the system, and appears in
	+ <filename>/dev</filename>.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-name-of-ports">
	+ <title xml:lang="en">The Name of Ports</title>
	+
	+ <note>
	+ <title xml:lang="en">FreeBSD Extension</title>
	+
	+ <para xml:lang="en">These elements are part of the FreeBSD extension to
	+ DocBook, and do not exist in the original DocBook
	+ <acronym>DTD</acronym>.</para>
	+ </note>
	+
	+ <para xml:lang="en">To include the name of a program from the FreeBSD
	+ Ports Collection in the document, use the <tag>package</tag>
	+ tag. Since the Ports Collection can be installed in any
	+ number of locations, only include the category and the port
	+ name; do not include <filename>/usr/ports</filename>.</para>
	+
	+ <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
	+ <literal>role</literal> attribute to
	+ <literal>port</literal>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>package</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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
	+ 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
	+ built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">Install the <package>net/wireshark</package> binary
	+ package to view network traffic.</para>
	+
	+ <para xml:lang="en"><package role="port">net/wireshark</package> can also be
	+ built and installed from the Ports Collection.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-hosts">
	+ <title xml:lang="en">Hosts, Domains, IP Addresses, User Names, Group Names,
	+ and Other System Items</title>
	+
	+ <note>
	+ <title xml:lang="en">FreeBSD Extension</title>
	+
	+ <para xml:lang="en">These elements are part of the FreeBSD extension to
	+ DocBook, and do not exist in the original DocBook
	+ <acronym>DTD</acronym>.</para>
	+ </note>
	+
	+ <para xml:lang="en">Information for <quote>system items</quote> is marked up
	+ with <tag>systemitem</tag>. The <literal>class</literal>
	+ attribute is used to identify the particular type of
	+ information shown.</para>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="domainname"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The text is a domain name, such as
	+ <literal>FreeBSD.org</literal> or
	+ <literal>ngo.org.uk</literal>. There is no hostname
	+ component.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="etheraddress"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The text is an Ethernet <acronym>MAC</acronym>
	+ address, expressed as a series of 2 digit hexadecimal
	+ numbers separated by colons.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="fqdomainname"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The text is a Fully Qualified Domain Name, with
	+ both hostname and domain name parts.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="ipaddress"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The text is an <acronym>IP</acronym> address,
	+ probably expressed as a dotted quad.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="netmask"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The text is a network mask, which might be
	+ expressed as a dotted quad, a hexadecimal string, or as
	+ a <literal>/</literal> followed by a number
	+ (<acronym>CIDR</acronym> notation).</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="systemname"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">With <literal>class="systemname"</literal>
	+ the marked up information is the simple hostname, such
	+ as <literal>freefall</literal> or
	+ <literal>wcarchive</literal>.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="username"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The text is a username, like
	+ <literal>root</literal>.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><literal>class="groupname"</literal></term>
	+
	+ <listitem>
	+ <para xml:lang="en">The text is a groupname, like
	+ <literal>wheel</literal>.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <example>
	+ <title xml:lang="en"><tag>systemitem</tag> and Classes Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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
	+ 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>
	+ 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>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>
	+
	+<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an
	+ interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>)
	+ <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of
	+ <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can
	+ also be expressed as
	+ <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag>
	+
	+<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
	+ <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">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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">The local machine can always be referred to by the name
	+ <systemitem>localhost</systemitem>, which will have the IP
	+ address
	+ <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>
	+
	+ <para xml:lang="en">The
	+ <systemitem class="fqdomainname">FreeBSD.org</systemitem>
	+ domain contains a number of different hosts, including
	+ <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
	+ <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>
	+
	+ <para xml:lang="en">When adding an <acronym>IP</acronym> alias to an
	+ interface (using <command>ifconfig</command>)
	+ <emphasis>always</emphasis> use a netmask of
	+ <systemitem class="netmask">255.255.255.255</systemitem>
	+ (which can also be expressed as
	+ <systemitem class="netmask">0xffffffff</systemitem>).</para>
	+
	+ <para xml:lang="en">The <acronym>MAC</acronym> address uniquely identifies
	+ every network card in existence. A typical
	+ <acronym>MAC</acronym> address looks like <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>
	+
	+ <para xml:lang="en">To carry out most system administration functions
	+ requires logging in as
	+ <systemitem class="username">root</systemitem>.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-uri">
	+ <title xml:lang="en">Uniform Resource Identifiers
	+ (<acronym>URI</acronym>s)</title>
	+
	+ <para xml:lang="en">Occasionally it is useful to show a
	+ Uniform Resource Identifier (<acronym>URI</acronym>) without
	+ making it an active hyperlink. The <tag>uri</tag> element
	+ makes this possible:</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>uri</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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
	+ create a link.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">This <acronym>URL</acronym> shows only as text:
	+ <uri>https://www.FreeBSD.org</uri>. It does not
	+ create a link.</para>
	+ </example>
	+
	+ <para xml:lang="en">To create links, see
	+ <xref linkend="docbook-markup-links"/>.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-email-addresses">
	+ <title xml:lang="en">Email Addresses</title>
	+
	+ <para xml:lang="en">Email addresses are marked up as <tag>email</tag>
	+ elements. In the <acronym>HTML</acronym> output format, the
	+ wrapped text becomes a hyperlink to the email address. Other
	+ output formats that support hyperlinks may also make the email
	+ address into a link.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>email</tag> with a Hyperlink Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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
	+ example.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">An email address that does not actually exist, like
	+ <email>notreal@example.com</email>, can be used as an
	+ example.</para>
	+ </example>
	+
	+ <para xml:lang="en">A FreeBSD-specific extension allows setting the
	+ <literal>role</literal> attribute to <literal>nolink</literal>
	+ to prevent the creation of the hyperlink to the email
	+ address.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>email</tag> Without a Hyperlink Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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
	+ desired.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">Sometimes a link to an email address like
	+ <email role="nolink">notreal@example.com</email> is not
	+ desired.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-describing-makefiles">
	+ <title xml:lang="en">Describing <filename>Makefile</filename>s</title>
	+
	+ <note>
	+ <title xml:lang="en">FreeBSD Extension</title>
	+
	+ <para xml:lang="en">These elements are part of the FreeBSD extension to
	+ DocBook, and do not exist in the original DocBook
	+ <acronym>DTD</acronym>.</para>
	+ </note>
	+
	+ <para xml:lang="en">Two elements exist to describe parts of
	+ <filename>Makefile</filename>s, <tag>buildtarget</tag>
	+ and <tag>varname</tag>.</para>
	+
	+ <para xml:lang="en"><tag>buildtarget</tag> identifies a build target
	+ exported by a <filename>Makefile</filename> that can be
	+ given as a parameter to <command>make</command>.
	+ <tag>varname</tag> identifies a variable that can be
	+ set (in the environment, on the command line with
	+ <command>make</command>, or within the
	+ <filename>Makefile</filename>) to influence the
	+ process.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>buildtarget</tag> and
	+ <tag>varname</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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>
	+ 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">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will
	+ rebuild the application, and invoking
	+ <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
	+ 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
	+ 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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">Two common targets in a <filename>Makefile</filename>
	+ are <buildtarget xml:lang="en">all</buildtarget> and
	+ <buildtarget xml:lang="en">clean</buildtarget>.</para>
	+
	+ <para xml:lang="en">Typically, invoking <buildtarget xml:lang="en">all</buildtarget> will
	+ rebuild the application, and invoking
	+ <buildtarget xml:lang="en">clean</buildtarget> will remove the temporary
	+ files (<filename>.o</filename> for example) created by the
	+ build process.</para>
	+
	+ <para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> may be controlled by a
	+ number of variables, including <varname>CLOBBER</varname>
	+ and <varname>RECURSE</varname>.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-literal-text">
	+ <title xml:lang="en">Literal Text</title>
	+
	+ <para xml:lang="en">Literal text, or text which should be entered verbatim, is
	+ often needed in documentation. This is text that is excerpted
	+ from another file, or which should be copied exactly as shown
	+ from the documentation into another file.</para>
	+
	+ <para xml:lang="en">Some of the time, <tag>programlisting</tag> will
	+ be sufficient to denote this text. But
	+ <tag>programlisting</tag> is not always appropriate,
	+ particularly when you want to include a portion of a file
	+ <quote>in-line</quote> with the rest of the
	+ paragraph.</para>
	+
	+ <para xml:lang="en">On these occasions, use
	+ <tag>literal</tag>.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>literal</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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
	+ configuration file determines the size of many system tables, and is
	+ a rough guide to how many simultaneous logins the system will
	+ support.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">The <literal>maxusers 10</literal> 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 support.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-replaceable">
	+ <title xml:lang="en">Showing Items That the User <emphasis>Must</emphasis>
	+ Fill In</title>
	+
	+ <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
	+ cannot simply copy the example provided. Instead, they
	+ must supply some information themselves.</para>
	+
	+ <para xml:lang="en"><tag>replaceable</tag> is designed for this
	+ eventuality. Use it <emphasis>inside</emphasis> other
	+ elements to indicate parts of that element's content that
	+ the user must replace.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>replaceable</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <informalexample>
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>man <replaceable>command</replaceable></userinput></screen>
	+ </informalexample>
	+
	+ <para xml:lang="en"><tag>replaceable</tag> can be used in many
	+ different elements, including <tag>literal</tag>.
	+ This example also shows that <tag>replaceable</tag>
	+ should only be wrapped around the content that the user
	+ <emphasis>is</emphasis> meant to provide. The other content
	+ should be left alone.</para>
	+
	+ <para xml:lang="en">Usage:</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>
	+ 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
	+ 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
	+ 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 xml:lang="en">The
	+ <literal>maxusers <replaceable>n</replaceable></literal>
	+ 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 support.</para>
	+
	+ <para xml:lang="en">For a desktop workstation, <literal>32</literal> is a
	+ good value for <replaceable>n</replaceable>.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-gui-buttons">
	+ <title xml:lang="en">Showing <acronym>GUI</acronym> Buttons</title>
	+
	+ <para xml:lang="en">Buttons presented by a graphical user interface are marked
	+ with <tag>guibutton</tag>. To make the text look more
	+ like a graphical button, brackets and non-breaking spaces are
	+ added surrounding the text.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>guibutton</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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
	+ changes.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">Edit the file, then click
	+ <guibutton>[ Save ]</guibutton> to save the
	+ changes.</para>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-system-errors">
	+ <title xml:lang="en">Quoting System Errors</title>
	+
	+ <para xml:lang="en">System errors generated by FreeBSD are marked with
	+ <tag>errorname</tag>. This indicates the exact error
	+ that appears.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>errorname</tag> Example</title>
	+
	+ <para xml:lang="en">Usage:</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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <informalexample>
	+ <screen xml:lang="en"><errorname>Panic: cannot mount root</errorname></screen>
	+ </informalexample>
	+ </example>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="docbook-markup-images">
	+ <title xml:lang="en">Images</title>
	+
	+ <important>
	+ <para xml:lang="en">Image support in the documentation is somewhat
	+ experimental. The mechanisms described here are unlikely to
	+ change, but that is not guaranteed.</para>
	+
	+ <para xml:lang="en">To provide conversion between different image formats, the
	+ <package>graphics/ImageMagick</package>
	+ port must be installed. This port is not included in the
	+ <package>textproc/docproj</package> meta
	+ port, and must be installed separately.</para>
	+
	+ <para xml:lang="en">A good example of the use of images is the
	+ <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
	+ document. Examine the files in that directory to see how
	+ these elements are used together. Build different output
	+ formats to see how the format determines what images are shown
	+ in the rendered document.</para>
	+ </important>
	+
	+ <sect2 xml:id="docbook-markup-image-formats">
	+ <title xml:lang="en">Image Formats</title>
	+
	+ <para xml:lang="en">The following image formats are currently supported. An
	+ image file will automatically be converted to bitmap or vector
	+ image depending on the output document format.</para>
	+
	+ <para xml:lang="en">These are the <emphasis>only</emphasis> formats in which
	+ images should be committed to the documentation
	+ repository.</para>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term xml:lang="en"><acronym>EPS</acronym> (Encapsulated
	+ Postscript)</term>
	+
	+ <listitem>
	+ <para xml:lang="en">Images that are primarily vector based, such as
	+ network diagrams, time lines, and similar, should be in
	+ this format. These images have a
	+ <filename>.eps</filename> extension.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><acronym>PNG</acronym> (Portable Network
	+ Graphic)</term>
	+
	+ <listitem>
	+ <para xml:lang="en">For bitmaps, such as screen captures, use this
	+ format. These images have the <filename>.png</filename>
	+ extension.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><acronym>PIC</acronym> (PIC graphics language)</term>
	+
	+ <listitem>
	+ <para xml:lang="en"><acronym>PIC</acronym> is a language for drawing
	+ simple vector-based figures used in the <citerefentry><refentrytitle>pic</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	+ utility. These images have the
	+ <filename>.pic</filename> extension.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en"><acronym>SCR</acronym> (SCReen capture)</term>
	+
	+ <listitem>
	+ <para xml:lang="en">This format is specific to screenshots of console
	+ output. The following command generates an SCR file
	+ <filename>shot.scr</filename> from video buffer of
	+ <filename>/dev/ttyv0</filename>:</para>
	+
	+ <screen xml:lang="en"><prompt>#</prompt> <userinput><command>vidcontrol -p</command> < <filename><replaceable>/dev/ttyv0</replaceable></filename> > <filename><replaceable>shot.scr</replaceable></filename></userinput></screen>
	+
	+ <para xml:lang="en">This is preferable to <acronym>PNG</acronym> format
	+ for screenshots because the <acronym>SCR</acronym> file
	+ contains plain text of the command lines so that it can
	+ be converted to a <acronym>PNG</acronym> image or a
	+ plain text depending on the output document
	+ format.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <para xml:lang="en">Use the appropriate format for each image. Documentation
	+ will often have a mix of <acronym>EPS</acronym> and
	+ <acronym>PNG</acronym> images. The
	+ <filename>Makefile</filename>s ensure that the correct format
	+ image is chosen depending on the output format used.
	+ <emphasis>Do not commit the same image to the repository in
	+ two different formats</emphasis>.</para>
	+
	+ <important>
	+ <para xml:lang="en">The Documentation Project may eventually switch to using
	+ the <acronym>SVG</acronym> (Scalable Vector Graphic) format
	+ for vector images. However, the current state of
	+ <acronym>SVG</acronym> capable editing tools makes this
	+ impractical.</para>
	+ </important>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-image-file-locations">
	+ <title xml:lang="en">Image File Locations</title>
	+
	+ <para xml:lang="en">Image files can be stored in one of several locations,
	+ depending on the document and image:</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para xml:lang="en">In the same directory as the document itself, usually
	+ done for articles and small books that keep all their
	+ files in a single directory.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">In a subdirectory of the main document. Typically
	+ done when a large book uses separate subdirectories to
	+ organize individual chapters.</para>
	+
	+ <para xml:lang="en">When images are stored in a subdirectory of the
	+ main document directory, the subdirectory name must be
	+ included in their paths in the
	+ <filename>Makefile</filename> and the
	+ <tag>imagedata</tag> element.</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en">In a subdirectory of
	+ <filename>doc/share/images</filename> named after the
	+ document. For example, images for the Handbook are stored
	+ in <filename>doc/share/images/books/handbook</filename>.
	+ Images that work for multiple translations are stored in
	+ this upper level of the documentation file tree.
	+ Generally, these are images that can be used unchanged in
	+ non-English translations of the document.</para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-image-markup">
	+ <title xml:lang="en">Image Markup</title>
	+
	+ <para xml:lang="en">Images are included as part of a <tag>mediaobject</tag>.
	+ The <tag>mediaobject</tag> can contain other, more specific
	+ objects. We are concerned with two, the
	+ <tag>imageobject</tag> and the <tag>textobject</tag>.</para>
	+
	+ <para xml:lang="en">Include one <tag>imageobject</tag>, and two
	+ <tag>textobject</tag> elements. The <tag>imageobject</tag>
	+ will point to the name of the image file without the
	+ extension. The <tag>textobject</tag> elements contain
	+ information that will be presented to the user as well as, or
	+ instead of, the image itself.</para>
	+
	+ <para xml:lang="en">Text elements are shown to the reader in several
	+ situations. When the document is viewed in
	+ <acronym>HTML</acronym>, text elements are shown while the
	+ image is loading, or if the mouse pointer is hovered over the
	+ image, or if a text-only browser is being used. In formats
	+ like plain text where graphics are not possible, the text
	+ elements are shown instead of the graphical ones.</para>
	+
	+ <para xml:lang="en">This example shows how to include an image called
	+ <filename>fig1.png</filename> in a document. The image is a
	+ rectangle with an A inside it:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">mediaobject</tag>
	+ <tag class="starttag">imageobject</tag>
	+ <tag class="emptytag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/>
	+ <tag class="endtag">imageobject</tag>
	+
	+ <tag class="starttag">textobject</tag>
	+ <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/>
	+\| A \|
	++---------------+<tag class="endtag">literallayout</tag>
	+ <tag class="endtag">textobject</tag>
	+
	+ <tag class="starttag">textobject</tag>
	+ <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/>
	+ <tag class="endtag">textobject</tag>
	+<tag class="endtag">mediaobject</tag></programlisting>
	+
	+ <calloutlist>
	+ <callout arearefs="co-image-ext">
	+ <para xml:lang="en">Include an <tag>imagedata</tag> element
	+ inside the <tag>imageobject</tag> element. The
	+ <literal>fileref</literal> attribute should contain the
	+ filename of the image to include, without the extension.
	+ The stylesheets will work out which extension should be
	+ added to the filename automatically.</para>
	+ </callout>
	+
	+ <callout arearefs="co-image-literal">
	+
	+ <para xml:lang="en">The first <tag>textobject</tag> contains a
	+ <tag>literallayout</tag> element, where the
	+ <literal>class</literal> attribute is set to
	+ <literal>monospaced</literal>. This is an opportunity to
	+ demonstrate <acronym>ASCII</acronym> art skills. This
	+ content will be used if the document is converted to plain
	+ text.</para>
	+
	+ <para xml:lang="en">Notice how the first and last lines of the content
	+ of the <tag>literallayout</tag> element butt up
	+ next to the element's tags. This ensures no extraneous
	+ white space is included.</para>
	+ </callout>
	+
	+ <callout arearefs="co-image-phrase">
	+ <para xml:lang="en">The second <tag>textobject</tag> contains a
	+ single <tag>phrase</tag> element. The contents of
	+ this phrase will become the <literal>alt</literal>
	+ attribute for the image when this document is converted to
	+ <acronym>HTML</acronym>.</para>
	+ </callout>
	+ </calloutlist>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-image-makefile-entries">
	+ <title xml:lang="en">Image <filename>Makefile</filename> Entries</title>
	+
	+ <para xml:lang="en">Images must be listed in the <filename>Makefile</filename>
	+ in the <varname>IMAGES</varname> variable. This variable must
	+ contain the names of all the <emphasis>source</emphasis>
	+ images. For example, if there are three figures,
	+ <filename>fig1.eps</filename>, <filename>fig2.png</filename>,
	+ <filename>fig3.png</filename>, then the
	+ <filename>Makefile</filename> should have lines like this in
	+ it.</para>
	+
	+ <programlisting xml:lang="en">…
	+IMAGES= fig1.eps fig2.png fig3.png
	+…</programlisting>
	+
	+ <para xml:lang="en">or</para>
	+
	+ <programlisting xml:lang="en">…
	+IMAGES= fig1.eps
	+IMAGES+= fig2.png
	+IMAGES+= fig3.png
	+…</programlisting>
	+
	+ <para xml:lang="en">Again, the <filename>Makefile</filename> will work out the
	+ complete list of images it needs to build the source document,
	+ you only need to list the image files <emphasis>you</emphasis>
	+ provided.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-images-in-subdirectories">
	+ <title xml:lang="en">Images and Chapters in Subdirectories</title>
	+
	+ <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>
	+
	+ <para xml:lang="en">Suppose there is a book with three chapters, and the
	+ chapters are stored in their own directories, called
	+ <filename>chapter1/chapter.xml</filename>,
	+ <filename>chapter2/chapter.xml</filename>, and
	+ <filename>chapter3/chapter.xml</filename>. If each chapter
	+ has images associated with it, place those images in each
	+ chapter's subdirectory (<filename>chapter1/</filename>,
	+ <filename>chapter2/</filename>, and
	+ <filename>chapter3/</filename>).</para>
	+
	+ <para xml:lang="en">However, doing this requires including the directory
	+ names in the <varname>IMAGES</varname> variable in the
	+ <filename>Makefile</filename>, <emphasis>and</emphasis>
	+ including the directory name in the <tag>imagedata</tag>
	+ element in the document.</para>
	+
	+ <para xml:lang="en">For example, if the book has
	+ <filename>chapter1/fig1.png</filename>, then
	+ <filename>chapter1/chapter.xml</filename> should
	+ contain:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">mediaobject</tag>
	+ <tag class="starttag">imageobject</tag>
	+ <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/>
	+ <tag class="endtag">imageobject</tag>
	+
	+ …
	+
	+<tag class="endtag">mediaobject</tag></programlisting>
	+
	+ <calloutlist>
	+ <callout arearefs="co-image-dir">
	+ <para xml:lang="en">The directory name must be included in the
	+ <literal>fileref</literal> attribute.</para>
	+ </callout>
	+ </calloutlist>
	+
	+ <para xml:lang="en">The <filename>Makefile</filename> must contain:</para>
	+
	+ <programlisting xml:lang="en">…
	+IMAGES= chapter1/fig1.png
	+…</programlisting>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="docbook-markup-links">
	+ <title xml:lang="en">Links</title>
	+
	+ <note>
	+ <para xml:lang="en">Links are also in-line elements. To show a
	+ <acronym>URI</acronym> without creating a link, see
	+ <xref linkend="docbook-markup-uri"/>.</para>
	+ </note>
	+
	+ <sect2 xml:id="docbook-markup-links-ids">
	+ <title xml:lang="en"><literal>xml:id</literal> Attributes</title>
	+
	+ <para xml:lang="en">Most DocBook elements accept an <literal>xml:id</literal>
	+ attribute to give that part of the document a unique name.
	+ The <literal>xml:id</literal> can be used as a target for a
	+ crossreference or link.</para>
	+
	+ <para xml:lang="en">Any portion of the document that will be a link target
	+ must have an <literal>xml:id</literal> attribute. Assigning
	+ an <literal>xml:id</literal> to all chapters and sections,
	+ 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
	+ reference points by anyone referring to the
	+ <acronym>HTML</acronym> version of the document.</para>
	+
	+ <example>
	+ <title xml:lang="en"><literal>xml:id</literal> on Chapters and
	+ Sections Example</title>
	+
	+ <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">para</tag>This is the introduction. It contains a subsection,
	+ which is identified as well.<tag class="endtag">para</tag>
	+
	+ <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag>
	+ <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag>
	+ <tag class="endtag">sect1</tag>
	+<tag class="endtag">chapter</tag></programlisting>
	+ </example>
	+
	+ <para xml:lang="en">Use descriptive values for <literal>xml:id</literal>
	+ names. The values must be unique within the entire document,
	+ not just in a single file. In the example, the subsection
	+ <literal>xml:id</literal> is constructed by appending text to
	+ the chapter <literal>xml:id</literal>. This ensures that the
	+ <literal>xml:id</literal>s are unique. It also helps both
	+ reader and anyone editing the document to see where the link
	+ is located within the document, similar to a directory path to
	+ a file.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-links-crossreferences">
	+ <title xml:lang="en">Crossreferences with <literal>xref</literal></title>
	+
	+ <para xml:lang="en"><tag>xref</tag> provides the reader with a link to jump to
	+ another section of the document. The target
	+ <literal>xml:id</literal> is specified in the
	+ <literal>linkend</literal> attribute, and <tag>xref</tag>
	+ generates the link text automatically.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>xref</tag> Example</title>
	+
	+ <para xml:lang="en">Assume that this fragment appears somewhere in a
	+ document that includes the <literal>xml:id</literal>
	+ example shown above:</para>
	+
	+ <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>
	+
	+<tag class="starttag">para</tag>More specific information can be found
	+ in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">The link text will be generated automatically, looking
	+ like (<emphasis>emphasized</emphasis> text indicates the
	+ link text):</para>
	+
	+ <blockquote>
	+ <para xml:lang="en">More information can be found in <emphasis>Chapter
	+ 1, Introduction</emphasis>.</para>
	+
	+ <para xml:lang="en">More specific information can be found in
	+ <emphasis>Section 1.1,
	+ <quote>More Details</quote></emphasis>.</para>
	+ </blockquote>
	+ </example>
	+
	+ <para xml:lang="en">The link text is generated automatically from the chapter
	+ and section number and <literal>title</literal>
	+ elements.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="docbook-markup-links-to-web-documents">
	+ <title xml:lang="en">Linking to Other Documents on the
	+ Web</title>
	+
	+ <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
	+ to give the reader an idea of where the link goes.
	+ Remember that DocBook can be rendered to multiple
	+ 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
	+ text is not descriptive enough, the reader might not be able to
	+ locate the linked section.</para>
	+
	+ <para xml:lang="en">The <literal>xlink:href</literal> attribute
	+ is the <acronym>URL</acronym> of the page,
	+ and the content of the element is the text that
	+ will be displayed for the user to activate.</para>
	+
	+ <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
	+ leaving out the element text entirely.</para>
	+
	+ <example>
	+ <title xml:lang="en"><tag>link</tag> to a FreeBSD Documentation Web
	+ Page Example</title>
	+
	+ <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
	+ slash and the chapter file name, followed by an optional
	+ anchor within the chapter. For articles, link to the
	+ article <acronym>URL</acronym> entity, followed by an
	+ optional anchor within the article.
	+ <acronym>URL</acronym> entities can be found in
	+ <filename>doc/share/xml/urls.ent</filename>.</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
	+ xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN
	+ introduction<tag class="endtag">link</tag>, then pick the nearest mirror from
	+ the list of <tag class="starttag">link
	+ xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion
	+ mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <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
	+ the list of <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion
	+ mirror sites</link>.</para>
	+
	+ <para xml:lang="en">Usage for FreeBSD article links:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>Read this
	+ <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article
	+ 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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">Read this
	+ <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>
	+ </example>
	+
	+ <example>
	+ <title xml:lang="en"><tag>link</tag> to a FreeBSD Web Page Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <para xml:lang="en">Of course, you could stop reading this document and go
	+ to the <link xlink:href="@@URL_RELPREFIX@@/index.html">FreeBSD
	+ home page</link> instead.</para>
	+ </example>
	+
	+ <example>
	+ <title xml:lang="en"><tag>link</tag> to an External Web
	+ Page Example</title>
	+
	+ <para xml:lang="en">Usage:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
	+ <tag class="starttag">link
	+ 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>
	+
	+ <para xml:lang="en">Appearance:</para>
	+
	+ <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>
	+
	+ <para xml:lang="en">The link text can be omitted to show the actual
	+ URL:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
	+ GUID Partition Tables: <tag class="starttag">link
	+ xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">The same link can be entered using shorter
	+ notation instead of a separate ending tag:</para>
	+
	+ <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
	+ GUID Partition Tables: <tag class="emptytag">link
	+ xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">The two methods are equivalent. Appearance:</para>
	+
	+ <para xml:lang="en">Wikipedia has an excellent reference on GUID Partition
	+ Tables: <uri xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para>
	+ </example>
	+ </sect2>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="stylesheets">
	+ <title xml:lang="en">Style Sheets</title>
	+
	+ <para xml:lang="en"><acronym>XML</acronym> is concerned with content, and says
	+ nothing about how that content should be presented to the reader
	+ or rendered on paper. Multiple <emphasis>style sheet</emphasis>
	+ languages have been developed to describe visual layout, including
	+ Extensible Stylesheet Language Transformation
	+ (<acronym>XSLT</acronym>), Document Style Semantics and
	+ Specification Language (<acronym>DSSSL</acronym>), and Cascading
	+ Style Sheets (<acronym>CSS</acronym>).</para>
	+
	+ <para xml:lang="en">The <acronym>FDP</acronym> documents use
	+ <acronym>XSLT</acronym> stylesheets to transform DocBook into
	+ <acronym>XHTML</acronym>, and then <acronym>CSS</acronym>
	+ formatting is applied to the <acronym>XHTML</acronym> pages.
	+ Printable output is currently rendered with legacy
	+ <acronym>DSSSL</acronym> stylesheets, but this will probably
	+ change in the future.</para>
	+
	+ <sect1 xml:id="stylesheets-css">
	+ <title xml:lang="en"><acronym>CSS</acronym></title>
	+
	+ <para xml:lang="en">Cascading Style Sheets (<acronym>CSS</acronym>) are a
	+ mechanism for attaching style information (font, weight, size,
	+ color, and so forth) to elements in an <acronym>XHTML</acronym>
	+ document without abusing <acronym>XHTML</acronym> to do
	+ so.</para>
	+
	+ <sect2>
	+ <title xml:lang="en">The DocBook Documents</title>
	+
	+ <para xml:lang="en">The FreeBSD <acronym>XSLT</acronym> and
	+ <acronym>DSSSL</acronym> stylesheets refer to
	+ <filename>docbook.css</filename>, which is expected to be
	+ present in the same directory as the <acronym>XHTML</acronym>
	+ files. The project-wide <acronym>CSS</acronym> file is copied
	+ from <filename>doc/share/misc/docbook.css</filename> when
	+ documents are converted to <acronym>XHTML</acronym>, and is
	+ installed automatically.</para>
	+ </sect2>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="translations">
	+ <title>翻譯</title>
	+
	+ <para>本章是翻譯 FreeBSD 文件(包含：FAQ, Handbook, tutorials, manual pages等)的常見問題(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>本 FAQ 是由文件工程團隊 <email>doceng@FreeBSD.org</email> 所維護。</para>
	+
	+ <qandaset>
	+ <qandaentry>
	+ <question>
	+ <para><phrase>i18n</phrase> 跟 <phrase>l10n</phrase> 是什麼呢？</para>
	+ </question>
	+
	+ <answer>
	+ <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>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>有專門給譯者參與討論的 mailing list 嗎？</para>
	+ </question>
	+
	+ <answer>
	+ <para>有的，不同的語系翻譯者都各自有自屬的 mailing lists。這份 <link xlink:href="http://www.freebsd.org/docproj/translations.html"> 翻譯計劃清單</link> 有列出各翻譯計劃的詳細 mailing lists 及相關網站。此外，有一般翻譯討論的<email>freebsd-translators@freebsd.org</email>郵件論壇。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>需要更多人一起參與翻譯嗎？</para>
	+ </question>
	+
	+ <answer>
	+ <para>當然囉，越多人參與翻譯，那麼就能夠越快翻完，而且英文版文件若有增減、更新的話，各翻譯版也可以儘快同步囉。</para>
	+
	+ <para>不一定得是專業譯者，才能參與翻譯的。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>有要求哪些語言能力呢</para>
	+ </question>
	+
	+ <answer>
	+ <para>理論上，必須要對英文非常熟稔，而且很明顯地，對想翻譯的語言必須要能運用自如。</para>
	+
	+ <para>英文也並非一定要會的。比如說，可以把西班牙文(Spanish)的 FAQ 翻譯為匈牙利文(Hungarian)。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>該學會哪些程式的使用呢？</para>
	+ </question>
	+
	+ <answer>
	+ <para>強烈建議在自己機器上也建立 FreeBSD Subversion repository 的備份(至少文件部分)，這可以執行：</para>
	+
	+ <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>
	+
	+ <note>
	+ <para>這需要安裝<package>devel/subversion</package> 套件。</para>
	+ </note>
	+
	+ <para>你可以很自在地使用<application>svn</application>。他可以讓你察看文件檔案不同版本之間的修改差異。</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>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>要怎麼找出來還有誰要跟我一起翻譯的呢？</para>
	+ </question>
	+
	+ <answer>
	+ <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>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>都沒人翻譯為我所使用的語言，該怎麼辦？</para>
	+ </question>
	+
	+ <answer>
	+ <para>恭喜啊，你剛好踏上 <quote>FreeBSD <replaceable>你的母語</replaceable> 文件翻譯計劃</quote>的啟程之路，歡迎上船。</para>
	+
	+ <para>首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已，因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para>
	+
	+ <para>寫信到 FreeBSD documentation project 郵遞論壇向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料</para>
	+
	+ <para>若你的國家已經有人提供 FreeBSD 的 mirror(映設) 服務的話，那麼就先跟他們聯繫，並詢問你是否在上面可以有網頁空間來放相關計劃資料，以及是否可以有提供 email 帳號或 mailing list 服務。</para>
	+
	+ <para>然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦，或是如何上手之類的說明文章。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>已經翻好一些文件了，該寄到哪呢？</para>
	+ </question>
	+
	+ <answer>
	+ <para>這要看情況而定。若你是在翻譯團隊內做的話(像是日本、德國)，他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。</para>
	+
	+ <para>若你是某語系的唯一翻譯者(或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃) ，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？</para>
	+
	+ <para xml:lang="en">or</para>
	+
	+ <para>我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？</para>
	+ </question>
	+
	+ <answer>
	+ <para>首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說：把它擺到現有文件架構內是可以正確編譯成功的。</para>
	+
	+ <para>目前，FreeBSD 文件都是放在最上層的 <filename>head/</filename> 目錄內。而該目錄下的則依其語系來做分類命名的，依照 ISO639 定義(在比比 1999/01/20 還新的 FreeBSD 版本的/usr/share/misc/iso639 )。</para>
	+
	+ <para>若你這個語系可能會有不同編碼方式(像是：中文) 那麼就應該會像下面這樣，來依你所使用的編碼方式細分</para>
	+
	+ <para>最後，你應該建立好各文件的目錄了。</para>
	+
	+ <para>舉例來說，假設有瑞典文(Swedish)版的翻譯，那麼應該會長像：</para>
	+
	+ <programlisting>head/
	+ sv_SE.ISO8859-1/
	+ Makefile
	+ htdocs/
	+ docproj/
	+ books/
	+ faq/
	+ Makefile
	+ book.xml</programlisting>
	+
	+ <para><literal>sv_SE.ISO8859-1</literal>是依照 <filename><replaceable>語系(lang)</replaceable>.<replaceable>編碼(encoding)</replaceable></filename> 的規則來建立的譯名。請注意：其中有兩個 Makefiles 檔，它們是用來建構文件的。</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>
	+<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
	+<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>還有，記得用 Bugzilla 提交一個報告以通知大家；你已經寄出翻譯文件了，還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好，因為這也有助於提升翻譯品質的流暢度。</para>
	+
	+ <para>最後，會有人(可能是文件計劃總管，或是 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 成員) 會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點：</para>
	+
	+ <orderedlist>
	+ <listitem>
	+ <para>你的檔案是否都有用 RCS tag (像是 "ID" 之類的)？</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><filename>sv_SE.ISO8859-1</filename> 是否可以順利<command>make all</command> 編譯呢？</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><command>make install</command> 是否結果有正確</para>
	+ </listitem>
	+ </orderedlist>
	+
	+ <para>若有問題的話，那麼檢閱者會叮嚀你，來讓這些翻譯成果可以正確使用。</para>
	+
	+ <para>若沒問題的話，那麼就會很快把你的翻譯成果 commit 進去了。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>可以加入某語系或某國家才有的東西到翻譯內容內嗎？</para>
	+ </question>
	+
	+ <answer>
	+ <para>我們希望不要這麼做。</para>
	+
	+ <para>舉例來說，假設你正準備把 Handbook 翻譯為韓文版，並希望把韓國零售商也加到你翻譯的 Handbook 韓文版內。</para>
	+
	+ <para>我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 …) 因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。</para>
	+
	+ <para>若你有某國才有的資料，請(用 Bugzilla )提供給英文版 Handbook 以作為修訂，然後再把英文版的修訂部分，翻為你要翻譯的 Handbook 吧。</para>
	+
	+ <para>謝謝。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>要怎麼把該語系特有的字元寫進去翻譯內容呢？</para>
	+ </question>
	+
	+ <answer>
	+ <para>文件內所有的非 ASCII(Non-ASCII) 字元，都要使用 SGML entities 才能寫進去。</para>
	+
	+ <para>簡單來說，長相一開頭會是 and 符號(&)，然後是該 entity 名稱，最後接上分號(;)。</para>
	+
	+ <para>這些 entity 名稱都是 ISO8879 所制訂的，而 port tree 內則 <package>textproc/iso8879</package>。</para>
	+
	+ <para>以下舉一些例子：</para>
	+
	+ <segmentedlist>
	+ <segtitle>Entity名稱</segtitle>
	+
	+ <segtitle>實際樣子</segtitle>
	+
	+ <segtitle xml:lang="en">Description</segtitle>
	+
	+ <seglistitem>
	+ <seg>&eacute;</seg>
	+ <seg>é</seg>
	+ <seg>小 <quote>e</quote>，並帶尖、重音(acute accent)</seg>
	+ </seglistitem>
	+
	+ <seglistitem>
	+ <seg>&Eacute;</seg>
	+ <seg>É</seg>
	+ <seg>大 <quote>E</quote>，並帶尖、重音(acute accent)</seg>
	+ </seglistitem>
	+
	+ <seglistitem>
	+ <seg>&uuml;</seg>
	+ <seg>ü</seg>
	+ <seg>小 <quote>u</quote>，並帶日耳曼語系中的母音變化(umlaut)</seg>
	+ </seglistitem>
	+ </segmentedlist>
	+
	+ <para>在裝了 iso8879 這個 port 之後，就可以在 <filename>/usr/local/share/xml/iso8879</filename> 找到這些的詳細列表。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>如何稱呼讀者呢？</para>
	+ </question>
	+
	+ <answer>
	+ <para>在英文文件內，讀者都是以 <quote>you</quote> 來稱呼，而有些語言並沒有正式/非正式的區隔。</para>
	+
	+ <para>若你所要翻的語言可以區別這些差異，那麼請用該語系在一般技術文件上所使用的稱呼吧。如果容易造成困惑的話，那麼請改用較中性的稱呼來取代。</para>
	+ </answer>
	+ </qandaentry>
	+
	+ <qandaentry>
	+ <question>
	+ <para>翻譯成果內要不要附上一些其他訊息呢？</para>
	+ </question>
	+
	+ <answer>
	+ <para>要。</para>
	+
	+ <para>每份英文版原稿的開頭，通常會有像下面的內容：</para>
	+
	+ <programlisting><!--
	+ The FreeBSD Documentation Project
	+
	+ $FreeBSD$
	+--></programlisting>
	+
	+ <para>實際上的內容可能稍有不同，但每份原稿都會附上 $FreeBSD$ 這一行以及<literal>The FreeBSD Documentation Project</literal> 宣告。請注意：$FreeBSD 開頭的這行是會由 Subversion 隨著每次異動而自動更改的，所以，新檔案的話請保持原狀(也就是只要寫 $FreeBSD$ 就好了)。</para>
	+
	+ <para>翻譯文件中，必須都要有 $FreeBSD$ 這行，並且把 <literal>FreeBSD Documentation Project</literal> 這行改為 <literal>The FreeBSD <replaceable>你的語系</replaceable> Documentation Project</literal>。</para>
	+
	+ <para>此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。</para>
	+
	+ <para>因此呢，西班牙文版(Spanish)的檔案開頭應該是長像這樣：</para>
	+
	+ <programlisting><!--
	+ The FreeBSD Spanish Documentation Project
	+
	+ $FreeBSD$
	+ Original revision: r38674
	+--></programlisting>
	+ </answer>
	+ </qandaentry>
	+ </qandaset>
	+</chapter>
	+
	+
	+<!--
	+ The FreeBSD Documentation Project
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="po-translations">
	+
	+ <title><acronym>PO</acronym> 翻譯</title>
	+
	+ <sect1 xml:id="po-translations-introduction">
	+ <title xml:lang="en">Introduction</title>
	+
	+ <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 xml:id="po-translations-quick-start">
	+ <title>快速上手</title>
	+
	+ <para xml:lang="en">The procedure shown in
	+ <xref linkend="overview-quick-start"/> is assumed to have
	+ already been performed, but the <literal>TRANSLATOR</literal>
	+ option must be enabled in the
	+ <package role="port">textproc/docproj</package> port. If that
	+ option was not enabled, display the options menu and enable
	+ it, then reinstall the port:</para>
	+
	+ <screen><prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput>
	+<prompt>#</prompt> <userinput>make config</userinput>
	+<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput></screen>
	+
	+ <para xml:lang="en">This example shows the creation of a Spanish translation of
	+ the short <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds">Leap
	+ Seconds</link> article.</para>
	+
	+ <procedure xml:id="po-translations-quick-start-install-po-editor">
	+ <title xml:lang="en">Install a <acronym>PO</acronym> Editor</title>
	+
	+ <step>
	+ <para>編輯翻譯檔案需要<acronym>PO</acronym>編輯器。這個範例使用<package role="ports">editors/poedit</package>。</para>
	+
	+ <screen><prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput>
	+<prompt>#</prompt> <userinput>make install clean</userinput></screen>
	+ </step>
	+ </procedure>
	+
	+ <procedure xml:id="po-translations-quick-start-initial-setup">
	+ <title xml:lang="en">Initial Setup</title>
	+
	+ <para xml:lang="en">When a new translation is first created, the directory
	+ structure and <filename>Makefile</filename> must be created or
	+ copied from the English original:</para>
	+
	+ <step>
	+ <para>建立新翻譯的目錄。英文文章原始碼位於 <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename> 。西班牙文翻譯將會放在 <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename> 。除了語系目錄的名稱外，其他路徑相同。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
	+ </step>
	+
	+ <step>
	+ <para>從原始文件處將 <filename>Makefile</filename> 複製到翻譯目錄。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
	+ ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
	+ </step>
	+ </procedure>
	+
	+ <procedure xml:id="po-translations-quick-start-translation">
	+ <title>翻譯</title>
	+
	+ <para xml:lang="en">Translating a document consists of two steps: extracting
	+ translatable strings from the original document, and entering
	+ translations for those strings. These steps are repeated
	+ until the translator feels that enough of the document has
	+ been translated to produce a usable translated
	+ document.</para>
	+
	+ <step>
	+ <para>從英文的原始文件提取字串到 <acronym>PO</acronym> 檔：</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
	+<prompt>%</prompt> <userinput>make po</userinput></screen>
	+ </step>
	+
	+ <step>
	+ <para>使用 <acronym>PO</acronym> 編輯器將翻譯輸入 <acronym>PO</acronym> 檔。有幾個不同的編輯器可以使用。這裡用的是 <package role="port">editors/poedit</package> 的 <filename>poedit</filename> 。</para>
	+
	+ <para><acronym>PO</acronym> 檔名是兩個字元的語系碼後面接底線和兩個字元的區域碼。以西班牙語來說，檔名是 <filename>es_ES.po</filename> 。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen>
	+ </step>
	+ </procedure>
	+
	+ <procedure xml:id="po-translations-quick-generating-a-translated-document">
	+ <title xml:lang="en">Generating a Translated Document</title>
	+
	+ <step>
	+ <para>產生翻譯文件</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
	+<prompt>%</prompt> <userinput>make tran</userinput></screen>
	+
	+ <para>產生的文件名稱與英文原始文件名稱相符，文章通常是 <filename>article.xml</filename> ，書籍是 <filename>book.xml</filename> 。</para>
	+ </step>
	+
	+ <step>
	+ <para>可以轉換成 <acronym>HTML</acronym> 來檢查產生的檔案，並用瀏覽器來察看。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>make FORMATS=html</userinput>
	+<prompt>%</prompt> <userinput>firefox article.html</userinput></screen>
	+ </step>
	+ </procedure>
	+ </sect1>
	+
	+ <sect1 xml:id="po-translations-creating">
	+ <title>建立新翻譯</title>
	+
	+ <para xml:lang="en">The first step to creating a new translated document is
	+ locating or creating a directory to hold it. FreeBSD puts
	+ translated documents in a subdirectory named for their
	+ language and region in the format
	+ <filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable></filename>.
	+ <replaceable>lang</replaceable> is a two-character lowercase
	+ code. It is followed by an underscore character and then the
	+ two-character uppercase <replaceable>REGION</replaceable>
	+ code.</para>
	+
	+ <table xml:id="po-translations-language-names" frame="none">
	+ <title>語系名稱</title>
	+
	+ <tgroup cols="5">
	+ <thead>
	+ <row>
	+ <entry>語言</entry>
	+ <entry>地區</entry>
	+ <entry>翻譯目錄名稱</entry>
	+ <entry><acronym>PO</acronym> 檔名稱</entry>
	+ <entry>字元集</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry>英文</entry>
	+ <entry>美國</entry>
	+ <entry><filename>en_US.ISO8859-1</filename></entry>
	+ <entry><filename>en_US.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>孟加拉文</entry>
	+ <entry>孟加拉</entry>
	+ <entry><filename>bn_BD.UTF-8</filename></entry>
	+ <entry><filename>bn_BD.po</filename></entry>
	+ <entry><acronym>UTF</acronym>-8</entry>
	+ </row>
	+
	+ <row>
	+ <entry>丹麥文</entry>
	+ <entry>丹麥</entry>
	+ <entry><filename>da_DK.ISO8859-1</filename></entry>
	+ <entry><filename>da_DK.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>德文</entry>
	+ <entry>德國</entry>
	+ <entry><filename>de_DE.ISO8859-1</filename></entry>
	+ <entry><filename>de_DE.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>希臘文</entry>
	+ <entry>希臘</entry>
	+ <entry><filename>el_GR.ISO8859-7</filename></entry>
	+ <entry><filename>el_GR.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-7</entry>
	+ </row>
	+
	+ <row>
	+ <entry>西班牙文</entry>
	+ <entry>西班牙</entry>
	+ <entry><filename>es_ES.ISO8859-1</filename></entry>
	+ <entry><filename>es_ES.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>法文</entry>
	+ <entry>法國</entry>
	+ <entry><filename>fr_FR.ISO8859-1</filename></entry>
	+ <entry><filename>fr_FR.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>匈牙利文</entry>
	+ <entry>匈牙利</entry>
	+ <entry><filename>hu_HU.ISO8859-2</filename></entry>
	+ <entry><filename>hu_HU.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-2</entry>
	+ </row>
	+
	+ <row>
	+ <entry>義大利文</entry>
	+ <entry>義大利</entry>
	+ <entry><filename>it_IT.ISO8859-15</filename></entry>
	+ <entry><filename>it_IT.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-15</entry>
	+ </row>
	+
	+ <row>
	+ <entry>日文</entry>
	+ <entry>日本</entry>
	+ <entry><filename>ja_JP.eucJP</filename></entry>
	+ <entry><filename>ja_JP.po</filename></entry>
	+ <entry><acronym>EUC</acronym> JP</entry>
	+ </row>
	+
	+ <row>
	+ <entry>韓文</entry>
	+ <entry>韓國</entry>
	+ <entry><filename>ko_KR.UTF-8</filename></entry>
	+ <entry><filename>ko_KR.po</filename></entry>
	+ <entry><acronym>UTF</acronym>-8</entry>
	+ </row>
	+
	+ <row>
	+ <entry>蒙古文</entry>
	+ <entry>蒙古</entry>
	+ <entry><filename>mn_MN.UTF-8</filename></entry>
	+ <entry><filename>mn_MN.po</filename></entry>
	+ <entry><acronym>UTF</acronym>-8</entry>
	+ </row>
	+
	+ <row>
	+ <entry>荷蘭文</entry>
	+ <entry>荷蘭</entry>
	+ <entry><filename>nl_NL.ISO8859-1</filename></entry>
	+ <entry><filename>nl_NL.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>挪威文</entry>
	+ <entry>挪威</entry>
	+ <entry><filename>no_NO.ISO8859-1</filename></entry>
	+ <entry><filename>no_NO.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>波蘭文</entry>
	+ <entry>波蘭</entry>
	+ <entry><filename>pl_PL.ISO8859-2</filename></entry>
	+ <entry><filename>pl_PL.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-2</entry>
	+ </row>
	+
	+ <row>
	+ <entry>葡萄牙文</entry>
	+ <entry>巴西</entry>
	+ <entry><filename>pt_BR.ISO8859-1</filename></entry>
	+ <entry><filename>pt_BR.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-1</entry>
	+ </row>
	+
	+ <row>
	+ <entry>俄文</entry>
	+ <entry>俄羅斯</entry>
	+ <entry><filename>ru_RU.KOI8-R</filename></entry>
	+ <entry><filename>ru_RU.po</filename></entry>
	+ <entry><acronym>KOI</acronym>8-R</entry>
	+ </row>
	+
	+ <row>
	+ <entry>賽爾維亞</entry>
	+ <entry>賽爾維亞文</entry>
	+ <entry><filename>sr_YU.ISO8859-2</filename></entry>
	+ <entry><filename>sr_YU.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-2</entry>
	+ </row>
	+
	+ <row>
	+ <entry>土耳其文</entry>
	+ <entry>土耳其</entry>
	+ <entry><filename>tr_TR.ISO8859-9</filename></entry>
	+ <entry><filename>tr_TR.po</filename></entry>
	+ <entry><acronym>ISO</acronym> 8859-9</entry>
	+ </row>
	+
	+ <row>
	+ <entry>中文</entry>
	+ <entry>中國</entry>
	+ <entry><filename>zh_CN.UTF-8</filename></entry>
	+ <entry><filename>zh_CN.po</filename></entry>
	+ <entry><acronym>UTF</acronym>-8</entry>
	+ </row>
	+
	+ <row>
	+ <entry>中文</entry>
	+ <entry>台灣</entry>
	+ <entry><filename>zh_TW.UTF-8</filename></entry>
	+ <entry><filename>zh_TW.po</filename></entry>
	+ <entry><acronym>UTF</acronym>-8</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </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>每個語系目錄包含不同文件類型的子目錄，通常是 <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>當翻譯到一個新語系時必須建立一個新的語系目錄。如果語系目錄已經存在，那只需要有 <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>
	+
	+ <example xml:id="po-translations-creating-example">
	+ <title xml:lang="en">Creating a Spanish Translation of the Porter's
	+ Handbook</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>
	+
	+ <procedure>
	+ <step>
	+ <para>西班牙文 books 目錄 <filename>~/doc/es_ES.ISO8859-1/books/</filename> 已經存在，所以只要建立 Porter 手冊的子目錄：</para>
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>
	+<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput>
	+A porters-handbook</screen>
	+ </step>
	+
	+ <step>
	+ <para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para>
	+
	+ <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>
	+A Makefile</screen>
	+
	+ <para>修改 <filename>Makefile</filename> 內容以產生單一的 <filename>book.xml</filename>：</para>
	+
	+ <programlisting>#
	+# $FreeBSD$
	+#
	+# Build the FreeBSD Porter's Handbook。
	+#
	+
	+MAINTAINER=doc@FreeBSD.org
	+
	+DOC?= book
	+
	+FORMATS?= html-split
	+
	+INSTALL_COMPRESSED?= gz
	+INSTALL_ONLY_COMPRESSED?=
	+
	+# XML content
	+SRCS= book.xml
	+
	+# Images from the cross-document image library
	+IMAGES_LIB+= callouts/1.png
	+IMAGES_LIB+= callouts/2.png
	+IMAGES_LIB+= callouts/3.png
	+IMAGES_LIB+= callouts/4.png
	+IMAGES_LIB+= callouts/5.png
	+IMAGES_LIB+= callouts/6.png
	+IMAGES_LIB+= callouts/7.png
	+IMAGES_LIB+= callouts/8.png
	+IMAGES_LIB+= callouts/9.png
	+IMAGES_LIB+= callouts/10.png
	+IMAGES_LIB+= callouts/11.png
	+IMAGES_LIB+= callouts/12.png
	+IMAGES_LIB+= callouts/13.png
	+IMAGES_LIB+= callouts/14.png
	+IMAGES_LIB+= callouts/15.png
	+IMAGES_LIB+= callouts/16.png
	+IMAGES_LIB+= callouts/17.png
	+IMAGES_LIB+= callouts/18.png
	+IMAGES_LIB+= callouts/19.png
	+IMAGES_LIB+= callouts/20.png
	+IMAGES_LIB+= callouts/21.png
	+
	+URL_RELPREFIX?= ../../../..
	+DOC_PREFIX?= ${.CURDIR}/../../..
	+
	+.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
	+
	+ <para xml:lang="en">Now the document structure is ready for the translator
	+ to begin translating with
	+ <command>make po</command>.</para>
	+ </step>
	+ </procedure>
	+ </example>
	+
	+ <example xml:id="po-translations-creating-example-french">
	+ <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>
	+
	+ <procedure>
	+ <step>
	+ <para>法文 article 目錄 <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> 已經存在，所以只要建立 <acronym>PGP</acronym> 金鑰文章的子目錄：</para>
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>
	+<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput>
	+A pgpkeys</screen>
	+ </step>
	+
	+ <step>
	+ <para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para>
	+
	+ <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>
	+A Makefile</screen>
	+
	+ <para>檢查 <filename>Makefile</filename> 的內容。因為這是簡單的文章，此例的 <filename>Makefile</filename> 不用修改。第二行的 <literal>$FreeBSD...$</literal> 版本字串將會在檔案提交時被版本控制系統替換掉。</para>
	+
	+ <programlisting>#
	+# $FreeBSD$
	+#
	+# Article：PGP Keys
	+
	+DOC?= article
	+
	+FORMATS?= html
	+WITH_ARTICLE_TOC?= YES
	+
	+INSTALL_COMPRESSED?= gz
	+INSTALL_ONLY_COMPRESSED?=
	+
	+SRCS= article.xml
	+
	+# To build with just key fingerprints, set FINGERPRINTS_ONLY。
	+
	+URL_RELPREFIX?= ../../../..
	+DOC_PREFIX?= ${.CURDIR}/../../..
	+
	+.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
	+
	+ <para>文章結構處理好後，可以執行建立 <command>make po</command> 建立 <acronym>PO</acronym> 檔。</para>
	+ </step>
	+ </procedure>
	+ </example>
	+ </sect1>
	+
	+ <sect1 xml:id="po-translations-translating">
	+ <title xml:lang="en">Translating</title>
	+
	+ <para><application>gettext</application>系統大幅減少翻譯者要追蹤的事情。字串從原始文件提取到<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> 檔是很重要的。它包含所有的翻譯成果。</para>
	+
	+ <example xml:id="po-translations-translating-example">
	+ <title>翻譯 Porter 手冊到西班牙文</title>
	+
	+ <para>輸入 Porter 手冊的西班牙文內容</para>
	+
	+ <procedure>
	+ <step>
	+ <para>切換到西班牙文 Porter 手冊的目錄並更新 <acronym>PO</acronym> 檔。產生的 <acronym>PO</acronym> 檔如 <xref linkend="po-translations-language-names"/> 所示，名叫 <filename>es_ES.po</filename> 。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
	+<prompt>%</prompt> <userinput>make po</userinput></screen>
	+ </step>
	+
	+ <step>
	+ <para>使用 <acronym>PO</acronym> 檔編輯器輸入翻譯：</para>
	+
	+ <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen>
	+ </step>
	+ </procedure>
	+ </example>
	+ </sect1>
	+
	+ <sect1 xml:id="po-translations-tips">
	+ <title xml:lang="en">Tips for Translators</title>
	+
	+ <sect2 xml:id="po-translations-tips-xmltags">
	+ <title>保留 <acronym>XML</acronym> 標籤</title>
	+
	+ <para xml:lang="en">Preserve <acronym>XML</acronym> tags that are shown in
	+ the English original.</para>
	+
	+ <example>
	+ <title>保留 <acronym>XML</acronym> 標籤</title>
	+
	+ <para>英文原文：</para>
	+
	+ <programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting>
	+
	+ <para>西班牙文翻譯：</para>
	+
	+ <programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting>
	+ </example>
	+ </sect2>
	+
	+ <sect2 xml:id="po-translations-tips-spaces">
	+ <title>保留空白</title>
	+
	+ <para>保留要翻譯字串前後的空白。翻譯的版本也要有這些空白。</para>
	+ </sect2>
	+
	+ <sect2 xml:id="po-translations-tips-verbatim">
	+ <title>不要翻譯的標籤</title>
	+
	+ <para>有些標籤的內容要一字不差地保留，不要翻譯。</para>
	+
	+ <itemizedlist xml:id="po-translations-tips-verbatim-list">
	+ <listitem>
	+ <para><tag class="starttag">citerefentry</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">command</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">filename</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">literal</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">manvolnum</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">orgname</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">package</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">programlisting</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">prompt</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">refentrytitle</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">screen</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">userinput</tag></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><tag class="starttag">varname</tag></para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect2>
	+
	+ <sect2 xml:id="po-translations-literal-dollar">
	+ <title><literal>$FreeBSD$</literal> 字串</title>
	+
	+ <para>檔案裡的 $FreeBSD$ 版本字串需要特別處理。例如 <xref linkend="po-translations-creating-example"/> 裡，這些字串不是要被展開 (expanded)。英文文件使用 <literal>&dollar;</literal> entities 來避免使用實際的金錢符號。</para>
	+
	+ <programlisting>&dollar;FreeBSD&dollar;</programlisting>
	+
	+ <para>版本控制符號不會把 <literal>&dollar;</literal> entities 看成金錢符號，所以不會把字串展開成版本字串。</para>
	+
	+ <para>當 <acronym>PO</acronym> 檔建立後，範例中的 <literal>&dollar;</literal> entities 被實際的金錢符號取代。當檔案提交時，產生的 <literal>$FreeBSD$</literal> 將會被版本控制系統展開。</para>
	+
	+ <para>英文文件用的相同技術可以被用在翻譯上。翻譯時用 <literal>&dollar;</literal> 來取代金錢符號，輸入到 <acronym>PO</acronym> 檔編輯器：</para>
	+
	+ <programlisting>&dollar;FreeBSD&dollar;</programlisting>
	+ </sect2>
	+
	+ <!--
	+ <sect2 xml:id="po-translations-tips-makefile">
	+ <title>Modifying the <filename>Makefile</filename></title>
	+
	+ <para>What needs to be changed in the
	+ <filename>Makefile</filename>?</para>
	+ </sect2>
	+
	+ <sect2 xml:id="po-translations-tips-locale">
	+ <title>Setting Locales for Editing</title>
	+
	+ <para>Locale settings so the <acronym>PO</acronym> editor works
	+ correctly?</para>
	+ </sect2>
	+
	+ <sect2 xml:id="po-translations-tips-poeditors">
	+ <title>Settings for Specific <acronym>PO</acronym>
	+ Editors</title>
	+
	+ <para>Per bcr: turn off "intelligent quotes" in
	+ Mac poedit.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="po-translations-tips-tm">
	+ <title>Using Translation Memory</title>
	+
	+ <para>Using translation memory. Saving, updating, sharing
	+ with other members of a translation team.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="po-translations-tips-submitting">
	+ <title>Submitting Translations</title>
	+
	+ <para>Submitting translations as diffs, committing
	+ <acronym>PO</acronym> files.</para>
	+ </sect2>
	+ -->
	+ </sect1>
	+
	+ <sect1 xml:id="po-translations-building">
	+ <title>編譯翻譯的文件</title>
	+
	+ <para>原文的翻譯版本可以在任何時候被建立。未翻譯的部份會以英文呈獻。大部份 <acronym>PO</acronym> 編輯器有指標可以顯示翻譯完成度。這讓翻譯者更容易看翻譯好的字串是否足夠來編譯最終的文件。</para>
	+
	+ <example xml:id="po-translations-building-example">
	+ <title xml:lang="en">Building the Spanish Porter's Handbook</title>
	+
	+ <para>編譯和預覽之前範例翻譯的西班牙文版 Porter 手冊</para>
	+
	+ <procedure>
	+ <step>
	+ <para>編譯翻譯好的文件。因為原文是書籍，所以產生的文件是<filename>book.xml</filename>。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
	+<prompt>%</prompt> <userinput>make tran</userinput></screen>
	+ </step>
	+
	+ <step>
	+ <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>
	+<prompt>%</prompt> <userinput>firefox book.html</userinput></screen>
	+ </step>
	+ </procedure>
	+ </example>
	+ </sect1>
	+
	+ <sect1 xml:id="po-translations-submitting">
	+ <title>提交新翻譯</title>
	+
	+ <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>
	+
	+ <example xml:id="po-translations-submitting-spanish">
	+ <title>NanoBSD 文章的西班牙文翻譯</title>
	+
	+ <procedure>
	+ <step>
	+ <para>增加 FreeBSD 版本字串註解到 <acronym>PO</acronym> 檔的第一行：</para>
	+
	+ <programlisting>#$FreeBSD$</programlisting>
	+ </step>
	+
	+ <step>
	+ <para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統：</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>
	+<prompt>%</prompt> <userinput>ls</userinput>
	+Makefile article.xml es_ES.po
	+<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput>
	+A Makefile
	+A article.xml
	+A es_ES.po</screen>
	+ </step>
	+
	+ <step>
	+ <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>
	+property 'svn:keywords' set on 'Makefile'
	+property 'svn:keywords' set on 'article.xml'
	+property 'svn:keywords' set on 'es_ES.po'</screen>
	+ </step>
	+
	+ <step>
	+ <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>
	+property 'svn:mime-type' set on 'es_ES.po'
	+<prompt>%</prompt> <userinput>svn propset svn:mime-type text/xml article.xml</userinput>
	+property 'svn:mime-type' set on 'article.xml'</screen>
	+ </step>
	+
	+ <step>
	+ <para>從 <filename>~/doc/</filename> 建立這些新檔案的 diff，讓檔名顯示完整的路徑。這可以幫助提交者辨識目標語系目錄。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput>
	+<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput></screen>
	+ </step>
	+ </procedure>
	+ </example>
	+
	+ <example xml:id="po-translations-submitting-korean-utf8">
	+ <title>Explaining-BSD 文章的韓文 <acronym>UTF-8</acronym> 翻譯</title>
	+
	+ <procedure>
	+ <step>
	+ <para>增加 FreeBSD 版本字串註解到 <acronym>PO</acronym> 檔的第一行：</para>
	+
	+ <programlisting>#$FreeBSD$</programlisting>
	+ </step>
	+
	+ <step>
	+ <para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統：</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput>
	+<prompt>%</prompt> <userinput>ls</userinput>
	+Makefile article.xml ko_KR.po
	+<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput>
	+A Makefile
	+A article.xml
	+A ko_KR.po</screen>
	+ </step>
	+
	+ <step>
	+ <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>
	+property 'svn:keywords' set on 'Makefile'
	+property 'svn:keywords' set on 'article.xml'
	+property 'svn:keywords' set on 'ko_KR.po'</screen>
	+ </step>
	+
	+ <step>
	+ <para>設定檔案的 <acronym>MIME</acronym> 類型。因為這些檔案使用 <acronym>UTF-8</acronym> 字元集，這也需要指定。為了防止版本控制系統將這些檔案誤認為二進位資料，<literal>fbsd:notbinary</literal> 屬性也需要設定。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/x-gettext-translation；charset=UTF-8' ko_KR.po</userinput>
	+property 'svn:mime-type' set on 'ko_KR.po'
	+<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput>
	+property 'fbsd:notbinary' set on 'ko_KR.po'
	+<prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/xml；charset=UTF-8' article.xml</userinput>
	+property 'svn:mime-type' set on 'article.xml'
	+<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes article.xml</userinput>
	+property 'fbsd:notbinary' set on 'article.xml'</screen>
	+ </step>
	+
	+ <step>
	+ <para>從 <filename>~/doc/</filename> 建立這些新檔案的 diff。</para>
	+
	+ <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput>
	+<userinput>svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff</userinput></screen>
	+ </step>
	+ </procedure>
	+ </example>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="writing-style">
	+ <title>寫作風格</title>
	+
	+ <sect1 xml:id="writing-style-tips">
	+ <title>叮嚀</title>
	+
	+ <para xml:lang="en">Technical documentation can be improved by consistent use of
	+ several principles. Most of these can be classified into three
	+ goals: <emphasis>be clear</emphasis>,
	+ <emphasis>be complete</emphasis>, and
	+ <emphasis>be concise</emphasis>. These goals can conflict with
	+ each other. Good writing consists of a balance between
	+ them.</para>
	+
	+ <sect2 xml:id="writing-style-be-clear">
	+ <title xml:lang="en">Be Clear</title>
	+
	+ <para xml:lang="en">Clarity is extremely important. The reader may be a
	+ novice, or reading the document in a second language. Strive
	+ for simple, uncomplicated text that clearly explains the
	+ concepts.</para>
	+
	+ <para xml:lang="en">Avoid flowery or embellished speech, jokes, or colloquial
	+ expressions. Write as simply and clearly as possible. Simple
	+ text is easier to understand and translate.</para>
	+
	+ <para xml:lang="en">Keep explanations as short, simple, and clear as possible.
	+ Avoid empty phrases like <quote>in order to</quote>, which
	+ usually just means <quote>to</quote>. Avoid potentially
	+ patronizing words like <quote>basically</quote>. Avoid Latin
	+ terms like <quote>i.e.</quote> or <quote>cf.</quote>, which
	+ may be unknown outside of academic or scientific
	+ groups.</para>
	+
	+ <para xml:lang="en">Write in a formal style. Avoid addressing the reader
	+ as <quote>you</quote>. For example, say
	+ <quote>copy the file to <filename>/tmp</filename></quote>
	+ rather than <quote>you can copy the file to
	+ <filename>/tmp</filename></quote>.</para>
	+
	+ <para xml:lang="en">Give clear, correct, <emphasis>tested</emphasis> examples.
	+ A trivial example is better than no example. A good example
	+ is better yet. Do not give bad examples, identifiable by
	+ apologies or sentences like <quote>but really it should never
	+ be done that way</quote>. Bad examples are worse than no
	+ examples. Give good examples, because <emphasis>even when
	+ warned not to use the example as shown</emphasis>, the
	+ reader will usually just use the example as shown.</para>
	+
	+ <para xml:lang="en">Avoid <emphasis>weasel words</emphasis> like
	+ <quote>should</quote>, <quote>might</quote>,
	+ <quote>try</quote>, or <quote>could</quote>. These words
	+ imply that the speaker is unsure of the facts, and
	+ create doubt in the reader.</para>
	+
	+ <para xml:lang="en">Similarly, give instructions as imperative commands: not
	+ <quote>you should do this</quote>, but merely
	+ <quote>do this</quote>.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="writing-style-be-complete">
	+ <title xml:lang="en">Be Complete</title>
	+
	+ <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
	+ other documents to provide background information without
	+ having to recreate it. Put yourself in the reader's place,
	+ anticipate the questions they will ask, and answer
	+ them.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="writing-style-be-concise">
	+ <title xml:lang="en">Be Concise</title>
	+
	+ <para xml:lang="en">While features should be documented completely, sometimes
	+ there is so much information that the reader cannot easily
	+ find the specific detail needed. The balance between being
	+ complete and being concise is a challenge. One approach is to
	+ have an introduction, then a <quote>quick start</quote>
	+ section that describes the most common situation, followed by
	+ an in-depth reference section.</para>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="writing-style-guidelines">
	+ <title xml:lang="en">Guidelines</title>
	+
	+ <para xml:lang="en">To promote consistency between the myriad authors of the
	+ FreeBSD documentation, some guidelines have been drawn up for
	+ authors to follow.</para>
	+
	+ <variablelist>
	+ <varlistentry>
	+ <term xml:lang="en">Use American English Spelling</term>
	+
	+ <listitem>
	+ <para xml:lang="en">There are several variants of English, with different
	+ spellings for the same word. Where spellings differ, use
	+ the American English variant. <quote>color</quote>, not
	+ <quote>colour</quote>, <quote>rationalize</quote>, not
	+ <quote>rationalise</quote>, and so on.</para>
	+
	+ <note>
	+ <para xml:lang="en">The use of British English may be accepted in the
	+ case of a contributed article, however the spelling must
	+ be consistent within the whole document. The other
	+ documents such as books, web site, manual pages, etc.
	+ will have to use American English.</para>
	+ </note>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en">Do not use contractions</term>
	+
	+ <listitem>
	+ <para xml:lang="en">Do not use contractions. Always spell the phrase out
	+ in full. <quote>Don't use contractions</quote> is
	+ wrong.</para>
	+
	+ <para xml:lang="en">Avoiding contractions makes for a more formal tone, is
	+ more precise, and is slightly easier for
	+ translators.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en">Use the serial comma</term>
	+
	+ <listitem>
	+ <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
	+ from the others with a comma and the word
	+ <quote>and</quote>.</para>
	+
	+ <para xml:lang="en">For example:</para>
	+
	+ <blockquote>
	+ <para xml:lang="en">This is a list of one, two and three items.</para>
	+ </blockquote>
	+
	+ <para xml:lang="en">Is this a list of three items, <quote>one</quote>,
	+ <quote>two</quote>, and <quote>three</quote>, or a list of
	+ two items, <quote>one</quote> and <quote>two and
	+ three</quote>?</para>
	+
	+ <para xml:lang="en">It is better to be explicit and include a serial
	+ comma:</para>
	+
	+ <blockquote>
	+ <para xml:lang="en">This is a list of one, two, and three items.</para>
	+ </blockquote>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en">Avoid redundant phrases</term>
	+
	+ <listitem>
	+ <para xml:lang="en">Do not use redundant phrases. In particular,
	+ <quote>the command</quote>, <quote>the file</quote>, and
	+ <quote>man command</quote> are often redundant.</para>
	+
	+ <para xml:lang="en">For example, commands:</para>
	+
	+ <informalexample>
	+ <para xml:lang="en">Wrong: Use the <command>svn</command> command to
	+ update sources.</para>
	+ </informalexample>
	+
	+ <informalexample>
	+ <para xml:lang="en">Right: Use <command>svn</command> to update
	+ sources.</para>
	+ </informalexample>
	+
	+ <para xml:lang="en">Filenames:</para>
	+
	+ <informalexample>
	+ <para xml:lang="en">Wrong: … in the filename
	+ <filename>/etc/rc.local</filename>…</para>
	+ </informalexample>
	+
	+ <informalexample>
	+ <para xml:lang="en">Right: … in
	+ <filename>/etc/rc.local</filename>…</para>
	+ </informalexample>
	+
	+ <para xml:lang="en">Manual page references (the second example uses
	+ <tag>citerefentry</tag> with the
	+ <literal>&man.csh.1;</literal> entity):.</para>
	+
	+ <informalexample>
	+ <para xml:lang="en">Wrong: See <command>man csh</command> for more
	+ information.</para>
	+ </informalexample>
	+
	+ <informalexample>
	+ <para xml:lang="en">Right: See <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
	+ </informalexample>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	+ <term xml:lang="en">Two spaces between sentences</term>
	+
	+ <listitem>
	+ <para xml:lang="en">Always use two spaces between sentences, as it
	+ improves readability and eases use of tools such as
	+ <application>Emacs</application>.</para>
	+
	+ <para xml:lang="en">A period and spaces followed by a capital letter
	+ does not always mark a new sentence, especially in names.
	+ <quote>Jordan K. Hubbard</quote> is a good example. It
	+ has a capital <literal>H</literal> following a period and
	+ a space, and is certainly not a new sentence.</para>
	+ </listitem>
	+ </varlistentry>
	+ </variablelist>
	+
	+ <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>
	+ </sect1>
	+
	+ <sect1 xml:id="writing-style-guide">
	+ <title>風格指南</title>
	+
	+ <para>由於文件是由眾多作者所維護，為了保持寫作風格的一貫性，請遵守下列撰寫風格慣例。</para>
	+
	+ <sect2>
	+ <title xml:lang="en">Letter Case</title>
	+
	+ <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>
	+ </sect2>
	+
	+ <sect2 xml:id="writing-style-acronyms">
	+ <title xml:lang="en">Acronyms</title>
	+
	+ <para>縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法，比如：<quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>。定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙，除非使用完整詞彙可以更能表達語意)來表達即可。通常每本書只會第一次提到時，才會列出完整詞彙，但若您高興也可以在每章第一次提到時又列出完整詞彙。</para>
	+
	+ <para>所有縮寫要包在<tag>acronym</tag>標籤內。</para>
	+ </sect2>
	+
	+ <sect2 xml:id="writing-style-indentation">
	+ <title>縮排</title>
	+
	+ <para><emphasis>無論</emphasis>檔案縮排設定為何，每個檔案的第一行都不縮排。</para>
	+
	+ <para>未完的標籤會以多兩個空白來增加縮排，結尾的標籤則少兩個空白來縮減縮排。若已達 8 個空白，則以 tab 取代之。此外，在 tab 前面不要再用空白，也不要在每行後面加上空白。每個 tag 的內文若超過一行的話，則接下來的就多兩個空白以做縮排。</para>
	+
	+ <para>舉個例子，這節所用的寫法大致是下面這樣：</para>
	+
	+ <programlisting><tag class="starttag">chapter</tag>
	+ <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">sect1</tag>
	+ <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">sect2</tag>
	+ <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">para</tag>The first line in each file starts with no indentation,
	+ <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of
	+ the file which might contain the current file。<tag class="endtag">para</tag>
	+
	+ ...
	+ <tag class="endtag">sect2</tag>
	+ <tag class="endtag">sect1</tag>
	+<tag class="endtag">chapter</tag></programlisting>
	+
	+ <para xml:lang="en">Tags containing long attributes follow the same
	+ rules. Following the indentation rules in this case helps
	+ editors and writers see which content is inside the
	+ tags:</para>
	+
	+ <programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link
	+ linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag>
	+ section if there are problems booting. Powering down and
	+ disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk
	+ will allow it to be kept as an offline backup.<tag class="endtag">para</tag>
	+
	+<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &os;
	+ system. Refer to the article <tag class="starttag">link
	+ xlink:href="&url.articles.gjournal-desktop;"</tag>Implementing UFS
	+ Journaling on a Desktop PC<tag class="endtag">link</tag> for detailed
	+ instructions.<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">When an element is too long to fit on the remainder of a
	+ line without wrapping, moving the start tag to the next line
	+ can make the source easier to read. In this example, the
	+ <literal>systemitem</literal> element has been moved to the
	+ next line to avoid wrapping and indenting:</para>
	+
	+ <programlisting><tag class="starttag">para</tag>With file flags, even
	+ <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be
	+ prevented from removing or altering files。<tag class="endtag">para</tag></programlisting>
	+
	+ <para xml:lang="en">Configurations to help various text editors conform to
	+ these guidelines can be found in
	+ <xref linkend="editor-config"/>.</para>
	+ </sect2>
	+
	+ <sect2 xml:id="writing-style-tag-style">
	+ <title>標籤風格</title>
	+
	+ <sect3 xml:id="writing-style-tag-style-spacing">
	+ <title>標籤空行</title>
	+
	+ <para>同一縮排等級的標籤要以空一行來做區隔，而不同縮排等級的則不必。比如：</para>
	+
	+ <informalexample>
	+ <programlisting><tag class="starttag">article lang='en'</tag>
	+ <tag class="starttag">articleinfo</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">abstract</tag>
	+ <tag class="starttag">para</tag>...
	+ ...
	+ ...<tag class="endtag">para</tag>
	+ <tag class="endtag">abstract</tag>
	+ <tag class="endtag">articleinfo</tag>
	+
	+ <tag class="starttag">sect1</tag>
	+ <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">para</tag>...<tag class="endtag">para</tag>
	+ <tag class="endtag">sect1</tag>
	+
	+ <tag class="starttag">sect1</tag>
	+ <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">para</tag>...<tag class="endtag">para</tag>
	+ <tag class="endtag">sect1</tag>
	+<tag class="endtag">article</tag></programlisting>
	+ </informalexample>
	+ </sect3>
	+
	+ <sect3 xml:id="writing-style-tag-style-separating">
	+ <title>標籤的分行</title>
	+
	+ <para>像是 <tag>itemizedlist</tag> 這類的標籤事實上本身不含任何文字資料，必須得由其他標籤來補充內文。這類的標籤會獨用一整行。</para>
	+
	+ <para>另外，像是 <tag>para</tag> 及 <tag>term</tag> 這類的標籤並不需搭配其他標籤，就可附上文字資料，並且在標籤後面的<emphasis>同一行</emphasis>內即可立即寫上這些內文。</para>
	+
	+ <para>當然，這兩類的標籤結尾時也是跟上面道理相同。</para>
	+
	+ <para>不過，當上述這兩種標籤混用時，會有很明顯的困擾。</para>
	+
	+ <para>當第一類標籤的後面接上第二類標籤的話，那麼要把這兩類標籤各自分行來寫。後者標籤的段落，也是需要做適當縮排調整。</para>
	+
	+ <para>而第二類標籤結尾時，可以與第一類標籤的結尾放在同一行。</para>
	+ </sect3>
	+ </sect2>
	+
	+ <sect2 xml:id="writing-style-whitespace-changes">
	+ <title>空白的更改</title>
	+
	+ <para><emphasis>在提交修改時，請別在修改內容的同時，也一起更改編排格式。</emphasis>。</para>
	+
	+ <para>如此一來，像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容，而不用費心思去判斷該行的改變，是由於格式重排或者內容異動。</para>
	+
	+ <para>舉例說明，若要在某段加上兩個句子，如此一來該段落的某行勢必會超出 80 縱列，這時請先 commmit 修改。接著，再修飾過長行落的換行，然後再次 commit 之。而第二次的 commit 紀錄，請明確說明這只是 whitespace-only (修改空白而已) 的更改，如此一來，翻譯團隊就可以忽略第二次 commit 了。</para>
	+ </sect2>
	+
	+ <sect2 xml:id="writing-style-nonbreaking-space">
	+ <title>Nonbreaking space</title>
	+
	+ <para>請避免一些情況下的斷行：造成版面醜醜的、或是須連貫表達的同一句子。斷行的情況會隨所閱讀的工具不同而有所不同。尤其是透過純文字瀏覽器來看 HTML 時會更明顯看到類似下面這樣不好的編排段落：</para>
	+
	+ <literallayout class="monospaced">Data capacity ranges from 40 MB to 15
	+GB。 Hardware compression …</literallayout>
	+
	+ <para>請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行，以下示範如何使用 nonbreaking spaces：</para>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para>在數字與單位之間：</para>
	+ <programlisting>57600&nbsp;bps</programlisting>
	+ </listitem>
	+
	+ <listitem>
	+ <para>在程式名稱與版號之間：</para>
	+ <programlisting>&os;&nbsp;9.2</programlisting>
	+ </listitem>
	+
	+ <listitem>
	+ <para>multiword 之間 (使用時請小心，像是 <quote>The FreeBSD Brazilian Portuguese Documentation Project</quote> 這類由三到四個字所組成的，則不用加。)：</para>
	+ <programlisting>Sun&nbsp;Microsystems</programlisting>
	+ </listitem>
	+ </itemizedlist>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="writing-style-word-list">
	+ <title>詞彙表</title>
	+
	+ <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">
	+ <tgroup cols="3">
	+ <thead>
	+ <row>
	+ <entry>Word</entry>
	+ <entry>XML Code</entry>
	+ <entry>Notes</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry>CD-ROM</entry>
	+
	+ <entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry>
	+ </row>
	+
	+ <row>
	+ <entry>DoS (Denial of Service)</entry>
	+ <entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry>
	+ </row>
	+
	+ <row>
	+ <entry>email</entry>
	+ </row>
	+
	+ <row>
	+ <entry>file system</entry>
	+ </row>
	+
	+ <row>
	+ <entry>IPsec</entry>
	+ </row>
	+
	+ <row>
	+ <entry>Internet</entry>
	+ </row>
	+
	+ <row>
	+ <entry>manual page</entry>
	+ </row>
	+
	+ <row>
	+ <entry>mail server</entry>
	+ </row>
	+
	+ <row>
	+ <entry>name server</entry>
	+ </row>
	+
	+ <row>
	+ <entry>Ports Collection</entry>
	+ </row>
	+
	+ <row>
	+ <entry>read-only</entry>
	+ </row>
	+
	+ <row>
	+ <entry>Soft Updates</entry>
	+ </row>
	+
	+ <row>
	+ <entry>stdin</entry>
	+ <entry><tag class="starttag">varname</tag>stdin<tag class="endtag">varname</tag></entry>
	+ </row>
	+
	+ <row>
	+ <entry>stdout</entry>
	+ <entry><tag class="starttag">varname</tag>stdout<tag class="endtag">varname</tag></entry>
	+ </row>
	+
	+ <row>
	+ <entry>stderr</entry>
	+ <entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry>
	+ </row>
	+
	+ <row>
	+ <entry>Subversion</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>
	+ </row>
	+
	+ <row>
	+ <entry xml:lang="en"><trademark class="registered">UNIX</trademark></entry>
	+ <entry xml:lang="en"><literal>&unix;</literal></entry>
	+ </row>
	+
	+ <row>
	+ <entry>userland</entry>
	+ <entry/>
	+ <entry xml:lang="en">things that apply to user space, not the
	+ kernel</entry>
	+ </row>
	+
	+ <row>
	+ <entry>web server</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </informaltable>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 2013 Warren Block
	+ All rights reserved.
	+
	+ Redistribution and use in source and binary forms, with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+ 1. Redistributions of source code must retain the above copyright
	+ notice, this list of conditions and the following disclaimer.
	+ 2. Redistributions in binary form must reproduce the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer in the documentation and/or other materials provided
	+ with the distribution.
	+
	+ THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS
	+ IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
	+ FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
	+ AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
	+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	+ OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
	+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="editor-config">
	+
	+ <title xml:lang="en">Editor Configuration</title>
	+
	+ <para xml:lang="en">Adjusting text editor configuration can make working on
	+ document files quicker and easier, and help documents conform to
	+ <acronym>FDP</acronym> guidelines.</para>
	+
	+ <sect1 xml:id="editor-config-vim">
	+ <title xml:lang="en"><application>Vim</application></title>
	+
	+ <para xml:lang="en">Install from <package>editors/vim</package>
	+ or <package>editors/vim-lite</package>.</para>
	+
	+ <sect2 xml:id="editor-config-vim-config">
	+ <title xml:lang="en">Configuration</title>
	+
	+ <para xml:lang="en">Edit <filename>~/.vimrc</filename>, adding these
	+ lines:</para>
	+
	+ <programlisting xml:lang="en">if has("autocmd")
	+ au BufNewFile,BufRead .sgml,.ent,.xsl,.xml call Set_SGML()
	+ au BufNewFile,BufRead *.[1-9] call ShowSpecial()
	+endif " has(autocmd)
	+
	+function Set_Highlights()
	+ "match ExtraWhitespace /^\s* \s*\\|\s\+$/
	+ highlight default link OverLength ErrorMsg
	+ match OverLength /\%71v.\+/
	+ return 0
	+endfunction
	+
	+function ShowSpecial()
	+ setlocal list listchars=tab:>>,trail:*,eol:$
	+ hi def link nontext ErrorMsg
	+ return 0
	+endfunction " ShowSpecial()
	+
	+function Set_SGML()
	+ setlocal number
	+ syn match sgmlSpecial "&[^;]*;"
	+ setlocal syntax=sgml
	+ setlocal filetype=xml
	+ setlocal shiftwidth=2
	+ setlocal textwidth=70
	+ setlocal tabstop=8
	+ setlocal softtabstop=2
	+ setlocal formatprg="fmt -p"
	+ setlocal autoindent
	+ setlocal smartindent
	+ " Rewrap paragraphs
	+ noremap P gqj
	+ " Replace spaces with tabs
	+ noremap T :s/ /\t/<CR>
	+ call ShowSpecial()
	+ call Set_Highlights()
	+ return 0
	+endfunction " Set_SGML()</programlisting>
	+ </sect2>
	+
	+ <sect2 xml:id="editor-config-vim-use">
	+ <title xml:lang="en">Use</title>
	+
	+ <para xml:lang="en">Press <keycap>P</keycap> to reformat paragraphs or text that has been selected in Visual mode. Press
	+ <keycap>T</keycap> to replace groups of eight spaces with a
	+ tab.</para>
	+ </sect2>
	+ </sect1>
	+
	+ <sect1 xml:id="editor-config-emacs">
	+ <title xml:lang="en"><application>Emacs</application></title>
	+
	+ <para xml:lang="en">Install from
	+ <package>editors/emacs</package>
	+ or <package>editors/xemacs</package>.</para>
	+
	+ <para xml:lang="en">Edit <filename>~/.emacs</filename>, adding this
	+ line:</para>
	+
	+ <programlisting xml:lang="en">(add-hook 'nxml-mode-hook 'turn-on-auto-fill)</programlisting>
	+ </sect1>
	+
	+ <sect1 xml:id="editor-config-nano">
	+ <title xml:lang="en"><application>nano</application></title>
	+
	+ <para xml:lang="en">Install from
	+ <package>editors/nano</package> or
	+ <package>editors/nano-devel</package>.</para>
	+
	+ <sect2 xml:id="editor-config-nano-config">
	+ <title xml:lang="en">Configuration</title>
	+
	+ <para xml:lang="en">Copy the sample <acronym>XML</acronym> syntax highlight
	+ 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>
	+
	+ <para xml:lang="en">Add these lines to the new
	+ <filename>~/.nanorc</filename>.</para>
	+
	+ <programlisting xml:lang="en">syntax "xml" "\.([jrs]html?\|xml\|xslt?)$"
	+# trailing whitespace
	+color ,blue "[[:space:]]+$"
	+# multiples of eight spaces at the start a line
	+# (after zero or more tabs) should be a tab
	+color ,blue "^([TAB]*[ ]{8})+"
	+# tabs after spaces
	+color ,yellow "( )+TAB"
	+# highlight indents that have an odd number of spaces
	+color ,red "^(([ ]{2})+\|(TAB+))*[ ]{1}[^ ]{1}"
	+# lines longer than 70 characters
	+color ,yellow "^(.{71})\|(TAB.{63})\|(TAB{2}.{55})\|(TAB{3}.{47}).+$"</programlisting>
	+
	+ <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>
	+ </sect2>
	+
	+ <sect2 xml:id="editor-config-nano-use">
	+ <title xml:lang="en">Use</title>
	+
	+ <para xml:lang="en">Specify additional helpful options when running the
	+ editor:</para>
	+
	+ <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
	+ <filename>~/.cshrc</filename> to automate these
	+ options:</para>
	+
	+ <programlisting xml:lang="en">alias nano "nano -AKipwz -r 70 -T8"</programlisting>
	+
	+ <para xml:lang="en">After the alias is defined, the options will be added
	+ automatically:</para>
	+
	+ <screen xml:lang="en"><prompt>%</prompt> <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen>
	+ </sect2>
	+ </sect1>
	+</chapter>
	+
	+
	+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<chapter version="5.0" xml:id="see-also">
	+ <title xml:lang="en">See Also</title>
	+
	+ <para xml:lang="en">This document is deliberately not an exhaustive discussion of
	+ XML, the DTDs listed, and the FreeBSD Documentation Project. For
	+ more information about these, you are encouraged to see the
	+ following web sites.</para>
	+
	+ <sect1 xml:id="see-also-fdp">
	+ <title>FreeBSD 文件計劃</title>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para><link xlink:href="@@URL_RELPREFIX@@/docproj/index.html">FreeBSD 文件計劃網頁</link></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">FreeBSD 使用手冊</link></para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect1>
	+
	+ <sect1 xml:id="see-also-xml">
	+ <title>XML</title>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para><link xlink:href="http://www.w3.org/XML/">W3C's XML 網頁 SGML/XML 網頁</link></para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect1>
	+
	+ <sect1 xml:id="see-also-html">
	+ <title>HTML</title>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para><link xlink:href="http://www.w3.org/">全球資訊網協會</link></para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><link xlink:href="http://www.w3.org/TR/REC-html40/">The HTML 4.0 規格表</link></para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect1>
	+
	+ <sect1 xml:id="see-also-docbook">
	+ <title>DocBook</title>
	+
	+ <itemizedlist>
	+ <listitem>
	+ <para><link xlink:href="http://www.oasis-open.org/docbook/">The DocBook 技術委員會</link>， DocBook DTD的維護者</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para><link xlink:href="http://www.docbook.org/">DocBook：The Definitive Guide</link>， DocBook DTD的線上文件。</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para xml:lang="en"><link xlink:href="http://docbook.sourceforge.net/">The DocBook
	+ Open Repository</link> contains DSSSL stylesheets and
	+ other resources for people using DocBook</para>
	+ </listitem>
	+ </itemizedlist>
	+ </sect1>
	+
	+</chapter>
	+
	+
	+
	+<!-- Copyright (c) 2000 Nik Clayton, All rights reserved.
	+
	+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
	+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
	+ modification, are permitted provided that the following conditions
	+ are met:
	+
	+ 1. Redistributions of source code (SGML DocBook) must retain the above
	+ copyright notice, this list of conditions and the following
	+ disclaimer as the first lines of this file unmodified.
	+
	+ 2. Redistributions in compiled form (transformed to other DTDs,
	+ converted to PDF, PostScript, RTF and other formats) must reproduce
	+ the above copyright notice, this list of conditions and the
	+ following disclaimer in the documentation and/or other materials
	+ provided with the distribution.
	+
	+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
	+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
	+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
	+ POSSIBILITY OF SUCH DAMAGE.
	+
	+ $FreeBSD$
	+-->
	+<appendix version="5.0" xml:id="examples">
	+
	+ <title>舉例</title>
	+
	+ <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
	+ document's front matter. For more examples of DocBook markup,
	+ examine the <acronym>XML</acronym> source for this and other
	+ documents available in the <application>Subversion</application>
	+ <literal>doc</literal> repository, or available online starting at
	+ <uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para>
	+
	+ <sect1 xml:id="examples-docbook-book">
	+ <title>DocBook <tag>book</tag></title>
	+
	+ <example>
	+ <title>DocBook <tag>book</tag></title>
	+
	+ <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
	+
	+<tag class="starttag">book 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">title</tag>An Example Book<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">author</tag>
	+ <tag class="starttag">personname</tag>
	+ <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
	+ <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
	+ <tag class="endtag">personname</tag>
	+
	+ <tag class="starttag">affiliation</tag>
	+ <tag class="starttag">address</tag>
	+ <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>
	+ <tag class="endtag">address</tag>
	+ <tag class="endtag">affiliation</tag>
	+ <tag class="endtag">author</tag>
	+
	+ <tag class="starttag">copyright</tag>
	+ <tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
	+ <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
	+ <tag class="endtag">copyright</tag>
	+
	+ <tag class="starttag">abstract</tag>
	+ <tag class="starttag">para</tag>If your book has an abstract then it should go here。<tag class="endtag">para</tag>
	+ <tag class="endtag">abstract</tag>
	+ <tag class="endtag">info</tag>
	+
	+ <tag class="starttag">preface</tag>
	+ <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed
	+ here。<tag class="endtag">para</tag>
	+ <tag class="endtag">preface</tag>
	+
	+ <tag class="starttag">chapter</tag>
	+ <tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">para</tag>This is the first chapter in my book。<tag class="endtag">para</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 book。<tag class="endtag">para</tag>
	+ <tag class="endtag">sect1</tag>
	+ <tag class="endtag">chapter</tag>
	+<tag class="endtag">book</tag></programlisting>
	+ </example>
	+ </sect1>
	+
	+ <sect1 xml:id="examples-docbook-article">
	+ <title>DocBook <tag>article</tag></title>
	+
	+ <example>
	+ <title>DocBook <tag>article</tag></title>
	+
	+ <programlisting><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	+ "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">title</tag>An Example Article<tag class="endtag">title</tag>
	+
	+ <tag class="starttag">author</tag>
	+ <tag class="starttag">personname</tag>
	+ <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
	+ <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
	+ <tag class="endtag">personname</tag>
	+
	+ <tag class="starttag">affiliation</tag>
	+ <tag class="starttag">address</tag>
	+ <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>
	+ <tag class="endtag">address</tag>
	+ <tag class="endtag">affiliation</tag>
	+ <tag class="endtag">author</tag>
	+
	+ <tag class="starttag">copyright</tag>
	+ <tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
	+ <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
	+ <tag class="endtag">copyright</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="endtag">abstract</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>
	+ </example>
	+ </sect1>
	+</appendix>

	- &app.examples;

	<index/>
	</book>
	Index: head/zh_TW.UTF-8/books/fdp-primer/zh_TW.po
	===================================================================
	--- head/zh_TW.UTF-8/books/fdp-primer/zh_TW.po
	+++ head/zh_TW.UTF-8/books/fdp-primer/zh_TW.po
	@@ -0,0 +1,9982 @@
	+# $FreeBSD$
	+# raycherng, 2016.
	+# raycherng, 2016.
	+# raycherng, 2016.
	+# raycherng, 2016.
	+# raycherng, 2016.
	+# raycherng, 2016.
	+msgid ""
	+msgstr ""
	+"Project-Id-Version: \n"
	+"POT-Creation-Date: 2016-06-06 18:36+0800\n"
	+"PO-Revision-Date: 2016-06-17 00:44+0800\n"
	+"Last-Translator: raycherng <>\n"
	+"Language-Team: Chinese <kde-i18n-doc@kde.org>\n"
	+"Language: zh_TW\n"
	+"MIME-Version: 1.0\n"
	+"Content-Type: text/plain; charset=UTF-8\n"
	+"Content-Transfer-Encoding: 8bit\n"
	+"Plural-Forms: nplurals=1; plural=0;\n"
	+"X-Generator: Poedit 1.8.4\n"
	+
	+#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
	+msgctxt "_"
	+msgid "translator-credits"
	+msgstr "translator-credits"
	+
	+#. (itstool) path: info/title
	+#: book.translate.xml:62
	+msgid "FreeBSD Documentation Project Primer for New Contributors"
	+msgstr "FreeBSD 文件計畫入門書"
	+
	+#. (itstool) path: info/author
	+#: book.translate.xml:66
	+msgid "<orgname>The FreeBSD Documentation Project</orgname>"
	+msgstr "<orgname>FreeBSD 文件計劃</orgname>"
	+
	+#. (itstool) path: info/copyright
	+#: book.translate.xml:68
	+msgid "<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>"
	+msgstr "<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>"
	+
	+#. (itstool) path: info/pubdate
	+#. (itstool) path: info/releaseinfo
	+#: book.translate.xml:89 book.translate.xml:91
	+msgid "$FreeBSD$"
	+msgstr "$FreeBSD$"
	+
	+#. (itstool) path: legalnotice/title
	+#: book.translate.xml:95
	+msgid "Copyright"
	+msgstr "版權"
	+
	+#. (itstool) path: legalnotice/para
	+#: book.translate.xml:97
	+msgid "Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:104
	+msgid "Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:110
	+msgid "Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:119
	+msgid ""
	+"THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT "
	+"LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
	+msgstr ""
	+
	+#. (itstool) path: abstract/para
	+#: book.translate.xml:136
	+msgid "Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable, and we appreciate it."
	+msgstr "感謝您參與 FreeBSD 文件計劃，您的點滴貢獻，都相當寶貴。"
	+
	+#. (itstool) path: abstract/para
	+#: book.translate.xml:140
	+msgid "This primer covers details needed to start contributing to the FreeBSD Documentation Project, or <acronym>FDP</acronym>, including tools, software, and the philosophy behind the Documentation Project."
	+msgstr "本入手書內容包括：如何開始著手貢獻FreeBSD 文件計劃 (簡稱： <acronym>FDP</acronym> )的各項細節，以及會用到的一些工具、軟體，以及文件計畫的宗旨。"
	+
	+#. (itstool) path: abstract/para
	+#: book.translate.xml:146
	+msgid "This is a work in progress. Corrections and additions are always welcome."
	+msgstr "本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。"
	+
	+#. (itstool) path: preface/title
	+#: book.translate.xml:152
	+msgid "Preface"
	+msgstr "序"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:155
	+msgid "Shell Prompts"
	+msgstr "Shell 提示符號(Prompts)"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:157
	+msgid "This table shows the default system prompt and superuser prompt. The examples use these prompts to indicate which type of user is running the example."
	+msgstr "下表顯示出一般使用者帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt) ，來提醒您該用哪種帳號才對。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:165
	+msgid "User"
	+msgstr "帳號"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:166
	+msgid "Prompt"
	+msgstr "提示符號"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:172
	+msgid "Normal user"
	+msgstr "一般使用者"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:173 book.translate.xml:4370
	+msgid "<prompt>%</prompt>"
	+msgstr "<prompt>%</prompt>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:177
	+msgid "<systemitem class=\"username\">root</systemitem>"
	+msgstr "<systemitem class=\"username\">root</systemitem>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:178 book.translate.xml:4363
	+msgid "<prompt>#</prompt>"
	+msgstr "<prompt>#</prompt>"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:186
	+msgid "Typographic Conventions"
	+msgstr "書中所用的編排風格"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:188
	+msgid "This table describes the typographic conventions used in this book."
	+msgstr "下表為本書中所使用編排風格方式"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:195
	+msgid "Meaning"
	+msgstr "代表意義"
	+
	+#. (itstool) path: row/entry
	+#. (itstool) path: sect2/title
	+#. (itstool) path: appendix/title
	+#: book.translate.xml:196 book.translate.xml:4870 book.translate.xml:9165
	+msgid "Examples"
	+msgstr "舉例"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:202
	+msgid "The names of commands."
	+msgstr "指令"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:203
	+msgid "Use <command>ls -l</command> to list all files."
	+msgstr "使用 <command>ls -l</command> 來列出所有的檔案。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:208
	+msgid "The names of files."
	+msgstr "檔名"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:209
	+msgid "Edit <filename>.login</filename>."
	+msgstr "編輯 <filename>.login</filename> 。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:213
	+msgid "On-screen computer output."
	+msgstr "螢幕上會出現的訊息"
	+
	+#. (itstool) path: entry/screen
	+#: book.translate.xml:214
	+#, no-wrap
	+msgid "You have mail."
	+msgstr "You have mail."
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:218
	+msgid "What the user types, contrasted with on-screen computer output."
	+msgstr "輸入指令後，螢幕上會出現的對應內容。"
	+
	+#. (itstool) path: entry/screen
	+#: book.translate.xml:221
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>date +\"The time is %H:%M\"</userinput>\n"
	+"The time is 09:18"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>date +\"The time is %H:%M\"</userinput>\n"
	+"The time is 09:18"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:226
	+msgid "Manual page references."
	+msgstr "要參考的線上手冊"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:227
	+msgid "Use <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> to change user identity."
	+msgstr "使用 <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來切換帳號。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:231
	+msgid "User and group names."
	+msgstr "使用者名稱和群組名稱"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:232
	+msgid "Only <systemitem class=\"username\">root</systemitem> can do this."
	+msgstr "只有 <systemitem class=\"username\">root</systemitem> 才可以做這件事。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:237
	+msgid "Emphasis."
	+msgstr "語氣的強調。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:238
	+msgid "The user <emphasis>must</emphasis> do this."
	+msgstr "使用者<emphasis>必須</emphasis>這樣做"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:243
	+msgid "Text that the user is expected to replace with the actual text."
	+msgstr "打指令時，可替換的部份"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:246
	+msgid "To search for a keyword in the manual pages, type <command>man -k <replaceable>keyword</replaceable></command>"
	+msgstr "要搜尋線上手冊的關鍵字，請輸入 <command>man -k <replaceable>關鍵字</replaceable></command>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:252
	+msgid "Environment variables."
	+msgstr "環境變數。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:253
	+msgid "<envar>$HOME</envar> is set to the user's home directory."
	+msgstr "<envar>$HOME</envar> 是指帳號的家目錄所在處。"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:262
	+msgid "Notes, Tips, Important Information, Warnings, and Examples"
	+msgstr "注意、技巧、重要訊息、警告、與範例的運用。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:265
	+msgid "Notes, warnings, and examples appear within the text."
	+msgstr "出現在本文中的注意、警告、與範例。"
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:269
	+msgid "Notes are represented like this, and contain information to take note of, as it may affect what the user does."
	+msgstr "注意：表示需要注意的事項，其中包括您需要注意的事情，因為這些事情可能會影響到操作結果。"
	+
	+#. (itstool) path: tip/para
	+#: book.translate.xml:275
	+msgid "Tips are represented like this, and contain information helpful to the user, like showing an easier way to do something."
	+msgstr "提示：提供可能對您有用的資訊，例如簡化操作方式的技巧說明。"
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:281
	+msgid "Important information is represented like this. Typically, these show extra steps the user may need to take."
	+msgstr "重要：表示要特別注意的事情。一般來說，它們會包括操作指令時需要加的額外參數。"
	+
	+#. (itstool) path: warning/para
	+#: book.translate.xml:287
	+msgid "Warnings are represented like this, and contain information warning about possible damage if the instructions are not followed. This damage may be physical, to the hardware or the user, or it may be non-physical, such as the inadvertent deletion of important files."
	+msgstr "警告：表示警告事項，比如如果您不則可能導致的損失。這些損失可能是對您或硬體造成實際傷害，也可能是無法估計的損害，例如一時疏忽而刪除重要檔案...。"
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:295
	+msgid "A Sample Example"
	+msgstr "一個範例"
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:297
	+msgid "Examples are represented like this, and typically contain examples showing a walkthrough, or the results of a particular action."
	+msgstr "這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:304
	+msgid "Acknowledgments"
	+msgstr "感謝"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:306
	+msgid "My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms."
	+msgstr "在此要感謝 Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, Christopher Maden 這些人的協助與閱讀初期草稿，並提供許多寶貴的潤稿意見與評論。"
	+
	+#. (itstool) path: chapter/title
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:346 book.translate.xml:2052
	+msgid "Overview"
	+msgstr "概論"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:348
	+msgid "Welcome to the FreeBSD Documentation Project (<acronym>FDP</acronym>). Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly."
	+msgstr "歡迎參與 FreeBSD 文件計劃( 簡稱 <acronym>FDP</acronym> ) 。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，您的點滴貢獻都是十分寶貴的。"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:353
	+msgid "This document describes how the <acronym>FDP</acronym> is organized, how to write and submit documentation, and how to effectively use the available tools."
	+msgstr "本文件描述：『 <acronym>FDP</acronym> 的架構有哪些』、『如何撰寫並提交文件』、『如何有效運用工具來協助撰稿』。"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:357
	+msgid "Everyone is welcome to contribute to the <acronym>FDP</acronym>. Willingness to contribute is the only membership requirement."
	+msgstr "歡迎大家對 <acronym>FDP</acronym> 做出貢獻。唯一的成員要求就有貢獻的意願。"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:361
	+msgid "This primer shows how to:"
	+msgstr "本入門書指出如何："
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:365
	+msgid "Identify which parts of FreeBSD are maintained by the <acronym>FDP</acronym>."
	+msgstr "瞭解有哪些文件是由 <acronym>FDP</acronym> 所維護的。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:370
	+msgid "Install the required documentation tools and files."
	+msgstr "安裝所需的文件工具和檔案"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:374
	+msgid "Make changes to the documentation."
	+msgstr "修改文件"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:378
	+msgid "Submit changes back for review and inclusion in the FreeBSD documentation."
	+msgstr "提交修改以供審核並納入 FreeBSD 文件"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:384
	+msgid "The FreeBSD Documentation Set"
	+msgstr "FreeBSD 文件組"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:386
	+msgid "The <acronym>FDP</acronym> is responsible for four categories of FreeBSD documentation."
	+msgstr "<acronym>FDP</acronym> 負責四類 FreeBSD 文件"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:391
	+msgid "<emphasis>Handbook</emphasis>: The Handbook is the comprehensive online resource and reference for FreeBSD users."
	+msgstr "<emphasis>使用手冊</emphasis>：使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:397
	+msgid "<emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym> uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to FreeBSD. This format does not permit long and comprehensive answers."
	+msgstr "<emphasis>FAQ</emphasis> 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:405
	+msgid "<emphasis>Manual pages</emphasis>: The English language system manual pages are usually not written by the <acronym>FDP</acronym>, as they are part of the base system. However, the <acronym>FDP</acronym> can reword parts of existing manual pages to make them clearer or to correct inaccuracies."
	+msgstr "<emphasis>線上手冊 ( manual pages )</emphasis>:英文版的系統 manual 並不是由 <acronym>FDP</acronym> 所撰寫的，因為它們是屬於 base system 的部份。然而，<acronym>FDP</acronym> 可以修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:414
	+msgid "<emphasis>Web site</emphasis>: This is the main FreeBSD presence on the web, visible at <link xlink:href=\"http://www.freebsd.org/index.html\">http://www.FreeBSD.org/</link> and many mirrors around the world. The web site is typically a new user's first exposure to FreeBSD."
	+msgstr "<emphasis>網站</emphasis>: 這是 FreeBSD 在網路上的主要部份，位於 <link xlink:href=\"http://www.freebsd.org/index.html\">http://www.FreeBSD.org/</link> 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:421
	+msgid "Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages are not translated at present."
	+msgstr "翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:425
	+msgid "Documentation source for the FreeBSD web site, Handbook, and <acronym>FAQ</acronym> is available in the documentation repository at <literal>https://svn.FreeBSD.org/doc/</literal>."
	+msgstr "FreeBSD 網站、使用手冊、和 <acronym>FAQ</acronym> 的文件原始碼可以在 <literal>https://svn.FreeBSD.org/doc/</literal> 的文件庫取得。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:430
	+msgid "Source for manual pages is available in a separate source repository located at <literal>https://svn.FreeBSD.org/base/</literal>."
	+msgstr "線上手冊的原始碼則是在 <literal>https://svn.FreeBSD.org/base/</literal> 的原始碼庫可以取得。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:434
	+msgid "Documentation commit messages are visible with <command>svn log</command>. Commit messages are also archived at <uri xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all\">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>."
	+msgstr "文件提交訊息可以用 <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>。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:438
	+msgid "Web frontends to both of these repositories are available at <link xlink:href=\"https://svnweb.FreeBSD.org/doc/\"/> and <link xlink:href=\"https://svnweb.FreeBSD.org/base/\"/>."
	+msgstr "這些儲存庫的網頁版位於<link xlink:href=\"https://svnweb.FreeBSD.org/doc/\"/> 和 <link xlink:href=\"https://svnweb.FreeBSD.org/base/\"/>。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:440
	+msgid "Many people have written tutorials or how-to articles about FreeBSD. Some are stored as part of the <acronym>FDP</acronym> files. In other cases, the author has decided to keep the documentation separate. The <acronym>FDP</acronym> endeavors to provide links to as much of this external documentation as possible."
	+msgstr "許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 <acronym>FDP</acronym> 的檔案中。其他一些文件則是作者希望放在他處。<acronym>FDP</acronym> 會盡力提供這些文件的連結。"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:449 book.translate.xml:7338
	+msgid "Quick Start"
	+msgstr "快速上手"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:451
	+msgid ""
	+"Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the <link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project mailing list</link>. Some team members also interact on the <literal>#bsddocs</literal> <acronym>IRC</acronym> channel on <link xlink:href=\"http://www.efnet.org/\">EFnet</link>. These people can help "
	+"with questions or problems involving the documentation."
	+msgstr "在編輯 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> 頻道。這些人可以幫忙解決文件相關的問題。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:461
	+msgid "Install the <package>textproc/docproj</package> package or port. This meta-port installs all of the software needed to edit and build FreeBSD documentation."
	+msgstr "安裝 <package>textproc/docproj</package> 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:468
	+msgid "Install a local working copy of the documentation from the FreeBSD repository in <filename>~/doc</filename> (see <xref linkend=\"working-copy\"/>)."
	+msgstr "在<filename>~/doc</filename>安裝 FreeBSD 文件庫的本地端工作副本 ( 請見 <xref linkend=\"working-copy\"/> )。"
	+
	+#. (itstool) path: step/screen
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:473 book.translate.xml:798
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput>"
	+msgstr "<prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:477
	+msgid "Configure the text editor:"
	+msgstr "設定文字編輯器："
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:481
	+msgid "Word wrap set to 70 characters."
	+msgstr "Word wrap 設為70個字元。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:485
	+msgid "Tab stops set to 2."
	+msgstr "Tab stops 設成。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:489
	+msgid "Replace each group of 8 leading spaces with a single tab."
	+msgstr "將句首每八個空白以一個 tab 替換。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:494
	+msgid "Specific editor configurations are listed in <xref linkend=\"editor-config\"/>."
	+msgstr "特定編輯器的設定方式列於 <xref linkend=\"editor-config\"/>。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:499
	+msgid "Update the local working copy:"
	+msgstr "更新本地端工作副本"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:501
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput>"
	+msgstr "<prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:505
	+msgid "Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input."
	+msgstr "編輯需要修改的文件檔案。如果檔案需要大幅度的編修，請先諮詢郵件論壇。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:509
	+msgid "References to tag and entity usage can be found in <xref linkend=\"xhtml-markup\"/> and <xref linkend=\"docbook-markup\"/>."
	+msgstr "標籤 ( tag ) 和 entity 的使用方式可以參考 <xref linkend=\"xhtml-markup\"/> 和 <xref linkend=\"docbook-markup\"/>. 。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:515
	+msgid "After editing, check for problems by running:"
	+msgstr "編輯完後，執行以下指令來檢查是否有問題："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:517
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>igor -R filename.xml \| less -RS</userinput>"
	+msgstr "<prompt>%</prompt> <userinput>igor -R filename.xml \| less -RS</userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:519
	+msgid "Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved."
	+msgstr "檢查輸出並重新編輯檔案來修正顯示的錯誤，然後重新執行指令來找出剩下的問題。重複執行直到所有錯誤都解決完。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:526
	+msgid "<emphasis>Always</emphasis> build-test changes before submitting them. Running <userinput>make</userinput> in the top-level directory of the documentation being edited will generate that documentation in split HTML format. For example, to build the English version of the Handbook in <acronym>HTML</acronym>, run <command>make</command> in the <filename>en_US.ISO8859-1/books/handbook/</filename> directory."
	+msgstr "修正送出前請先建構測試 (build-test ) 。在編輯的文件目錄最頂層執行 <userinput>make</userinput>，將會產生 split HTML 格式的文件。例如要建構 <acronym>HTML</acronym> 格式的英文版使用手冊，請在 <filename>en_US.ISO8859-1/books/handbook/</filename> 目錄執行 <command>make</command> 。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:537
	+msgid "When changes are complete and tested, generate a <quote>diff file</quote>:"
	+msgstr "修改並測試完後，產生<quote>diff 檔</quote>："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:540
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:543
	+msgid "Give the diff file a descriptive name. In the example above, changes have been made to the <filename>bsdinstall</filename> portion of the Handbook."
	+msgstr "設一個可辨識的檔名。如上例中，是使用手冊的<filename>bsdinstall</filename> 部份的修改。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:550
	+msgid ""
	+"Submit the diff file using the web-based <link xlink:href=\"@@URL_RELPREFIX@@/support.html#gnats\">Problem Report</link> system. If using the web form, enter a synopsis of <emphasis>[patch] <replaceable>short description of problem</replaceable></emphasis>. Select the category <literal>docs</literal> and the class <literal>doc-bug</literal>. In the body of the message, enter a short description of the changes "
	+"and any important details about them. Use the <guibutton>[ Browse... ]</guibutton> button to attach the diff file."
	+msgstr "使用網頁版 <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 檔。"
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:600
	+msgid "Tools"
	+msgstr "工具"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:602
	+msgid "Several software tools are used to manage the FreeBSD documentation and render it to different output formats. Some of these tools are required and must be installed before working through the examples in the following chapters. Some are optional, adding capabilities or making the job of creating documentation less demanding."
	+msgstr "有些工具軟體用來管理 FreeBSD 文件，並將他轉換成不同的輸出格式。有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:610
	+msgid "Required Tools"
	+msgstr "必備工具"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:612
	+msgid "Install <package>textproc/docproj</package> from the Ports Collection. This <emphasis>meta-port</emphasis> installs all the applications required to do useful work with the FreeBSD documentation. Some further notes on particular components are given below."
	+msgstr "從 Ports Collection 安裝 <package>textproc/docproj</package>。這個 <emphasis>組合型 port (meta-port)</emphasis> 會安裝處理 FreeBSD 文件需要的所有應用程式。以下列出特定元件的進一步說明。"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:620
	+msgid "<acronym>DTD</acronym>s and <acronym>Entities</acronym>"
	+msgstr "<acronym>DTD</acronym>s 與 <acronym>Entities</acronym>"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:623
	+msgid "FreeBSD documentation uses several Document Type Definitions (<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym> entities. These are all installed by the <package>textproc/docproj</package> port."
	+msgstr "FreeBSD 文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 組。這些都會經由 <package>textproc/docproj</package> port 來安裝。"
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:631
	+msgid "<acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)"
	+msgstr "<acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:635
	+msgid "<acronym>XHTML</acronym> is the markup language of choice for the World Wide Web, and is used throughout the FreeBSD web site."
	+msgstr "<acronym>XHTML</acronym> 是全球資訊網的一種標記語言，也是整個 FreeBSD 網站所使用的格式。"
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:642
	+msgid "DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)"
	+msgstr "DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:645
	+msgid "DocBook is designed for marking up technical documentation. Most of the FreeBSD documentation is written in DocBook."
	+msgstr "DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。"
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:652
	+msgid "ISO 8879 entities (<package>textproc/iso8879</package>)"
	+msgstr "ISO 8879 entities (<package>textproc/iso8879</package>)"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:656
	+msgid "Character entities from the ISO 8879:1986 standard used by many <acronym>DTD</acronym>s. Includes named mathematical symbols, additional characters in the Latin character set (accents, diacriticals, and so on), and Greek symbols."
	+msgstr "在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用，包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:668
	+msgid "Optional Tools"
	+msgstr "輔助工具"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:670
	+msgid "These applications are not required, but can make working on the documentation easier or add capabilities."
	+msgstr "不一定得裝下列的應用程式才行，但是，出的格式也更具彈性。"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:674
	+msgid "Software"
	+msgstr "軟體"
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:679
	+msgid "<application>Vim</application> (<package>editors/vim</package>)"
	+msgstr "<application>Vim</application> (<package>editors/vim</package>)"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:683
	+msgid "A popular editor for working with <acronym>XML</acronym> and derived documents, like DocBook <acronym>XML</acronym>."
	+msgstr "一個很受歡迎的編輯器，可以處理 <acronym>XML</acronym> 和他的衍生相關文件，例如 DocBook <acronym>XML</acronym>。"
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:690
	+msgid "<application>Emacs</application> or <application>XEmacs</application> (<package>editors/emacs</package> or <package>editors/xemacs</package>)"
	+msgstr "<application>Emacs</application> 或 <application>XEmacs</application> (<package>editors/emacs</package> 或 <package>editors/xemacs</package>)"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:696
	+msgid "Both of these editors include a special mode for editing documents marked up according to an <acronym>XML</acronym> <acronym>DTD</acronym>. This mode includes commands to reduce the amount of typing needed, and help reduce the possibility of errors."
	+msgstr "這兩個編輯器都包含特別模式來編輯用 <acronym>XML</acronym> <acronym>DTD</acronym> 標記的文件。這個模式包含指令來減少打字量，並可以幫忙減少錯誤的發生。"
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:739
	+msgid "The Working Copy"
	+msgstr "工作副本"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:741
	+msgid "The <emphasis>working copy</emphasis> is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository."
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:747
	+msgid "A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats."
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:752
	+msgid "<link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html\"><application>Subversion</application></link> is used to manage the FreeBSD documentation files. It is installed by <package>textproc/docproj</package> as one of the required applications."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:758
	+msgid "Documentation and Manual Pages"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:760
	+msgid ""
	+"FreeBSD documentation is not just books and articles. Manual pages for all the commands and configuration files are also part of the documentation, and part of the <acronym>FDP</acronym>'s territory. Two repositories are involved: <literal>doc</literal> for the books and articles, and <literal>base</literal> for the operating system and manual pages. To edit manual pages, the <literal>base</literal> "
	+"repository must be checked out separately."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:769
	+msgid "Repositories may contain multiple versions of documentation and source code. New modifications are almost always made only to the latest version, called <literal>head</literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:775
	+msgid "Choosing a Directory"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:777
	+msgid ""
	+"FreeBSD documentation is traditionally stored in <filename>/usr/doc/</filename>, and system source code with manual pages in <filename>/usr/src/</filename>. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use <filename>~/doc</filename> and <filename>~/src</"
	+"filename>, both subdirectories of the user's home directory."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:790
	+msgid "Checking Out a Copy"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:792
	+msgid "A download of a working copy from the repository is called a <emphasis>checkout</emphasis>, and done with <command>svn checkout</command>. This example checks out a copy of the latest version (<literal>head</literal>) of the main documentation tree:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:800
	+msgid "A checkout of the source code to work on manual pages is very similar:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:803
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:807
	+msgid "Updating a Working Copy"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:809
	+msgid ""
	+"The documents and files in the FreeBSD repository change daily. People modify files and commit changes frequently. Even a short time after an initial checkout, there will already be differences between the local working copy and the main FreeBSD repository. To update the local version with the changes that have been made to the main repository, use <command>svn update</command> on the directory containing the "
	+"local working copy:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:818
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput>"
	+msgstr "<prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput>"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:820
	+msgid "Get in the protective habit of using <command>svn update</command> before editing document files. Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:830
	+msgid "Reverting Changes"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:832
	+msgid "Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. Files can be <quote>reset</quote> to their unchanged form with <command>svn revert</command>. For example, to erase the edits made to <filename>chapter.xml</filename> and reset it to unmodified form:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:839
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn revert chapter.xml</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:843
	+msgid "Making a Diff"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:845
	+msgid "After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. These <emphasis>diff</emphasis> files are produced by redirecting the output of <command>svn diff</command> into a file:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:852
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>\n"
	+"<prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:855
	+msgid "Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:859
	+msgid "If the diff file is to be submitted with the web <quote><link xlink:href=\"https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi\">Submit a FreeBSD problem report</link></quote> interface, add a <filename>.txt</filename> extension to give the earnest and simple-minded web form a clue that the contents are plain text."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:866
	+msgid "Be careful: <command>svn diff</command> includes all changes made in the current directory and any subdirectories. If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:872
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>\n"
	+"<prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:877
	+msgid "<application>Subversion</application> References"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:879
	+msgid "These examples show very basic usage of <application>Subversion</application>. More detail is available in the <link xlink:href=\"http://svnbook.red-bean.com/\">Subversion Book</link> and the <link xlink:href=\"http://subversion.apache.org/docs/\">Subversion documentation</link>."
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:920
	+msgid "Documentation Directory Structure"
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:922
	+msgid "Files and directories in the <filename>doc/</filename> tree follow a structure meant to:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:928
	+msgid "Make it easy to automate converting the document to other formats."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:933
	+msgid "Promote consistency between the different documentation organizations, to make it easier to switch between working on different documents."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:939
	+msgid "Make it easy to decide where in the tree new documentation should be placed."
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:944
	+msgid "In addition, the documentation tree must accommodate documents in many different languages and encodings. It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:950
	+msgid "The Top Level, <filename>doc/</filename>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:953
	+msgid "There are two types of directory under <filename>doc/</filename>, each with very specific directory names and meanings."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:961 book.translate.xml:1015
	+msgid "Directory"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:962 book.translate.xml:1016
	+msgid "Usage"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:968
	+msgid "<filename>share</filename>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:971
	+msgid ""
	+"Contains files that are not specific to the various translations and encodings of the documentation. Contains subdirectories to further categorize the information. For example, the files that comprise the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> infrastructure are in <filename>share/mk</filename>, while the additional <acronym>XML</acronym> support files (such "
	+"as the FreeBSD extended DocBook <acronym>DTD</acronym>) are in <filename>share/xml</filename>."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:983
	+msgid "<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:986
	+msgid ""
	+"One directory exists for each available translation and encoding of the documentation, for example <filename>en_US.ISO8859-1/</filename> and <filename>zh_TW.UTF-8/</filename>. The names are long, but by fully specifying the language and encoding we prevent any future headaches when a translation team wants to provide documentation in the same language but in more than one encoding. This also avoids problems "
	+"that might be caused by a future switch to Unicode."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1003
	+msgid "The <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> Directories"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1007
	+msgid "These directories contain the documents themselves. The documentation is split into up to three more categories at this level, indicated by the different directory names."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1022
	+msgid "<filename>articles</filename>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1025
	+msgid "Documentation marked up as a DocBook <tag>article</tag> (or equivalent). Reasonably short, and broken up into sections. Normally only available as one <acronym>XHTML</acronym> file."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1032
	+msgid "<filename>books</filename>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1034
	+msgid "Documentation marked up as a DocBook <tag>book</tag> (or equivalent). Book length, and broken up into chapters. Normally available as both one large <acronym>XHTML</acronym> file (for people with fast connections, or who want to print it easily from a browser) and as a collection of linked, smaller files."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1044
	+msgid "<filename>man</filename>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1047
	+msgid "For translations of the system manual pages. This directory will contain one or more <filename role=\"directory\">man<replaceable>n</replaceable></filename> directories, corresponding to the sections that have been translated."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1056
	+msgid "Not every <filename role=\"directory\"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will have all of these subdirectories. It depends on how much translation has been accomplished by that translation team."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1063
	+msgid "Document-Specific Information"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1065
	+msgid "This section contains specific notes about particular documents managed by the FDP."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:1069
	+msgid "The Handbook"
	+msgstr ""
	+
	+#. (itstool) path: sect2/subtitle
	+#: book.translate.xml:1071
	+msgid "<filename>books/handbook/</filename>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1073
	+msgid "The Handbook is written in DocBook <acronym>XML</acronym> using the FreeBSD DocBook extended <acronym>DTD</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1076
	+msgid "The Handbook is organized as a DocBook <tag>book</tag>. The book is divided into <tag>part</tag>s, each of which contains several <tag>chapter</tag>s. <tag>chapter</tag>s are further subdivided into sections (<tag>sect1</tag>) and subsections (<tag>sect2</tag>, <tag>sect3</tag>) and so on."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:1085
	+msgid "Physical Organization"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1087
	+msgid "There are a number of files and directories within the <filename>handbook</filename> directory."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:1091
	+msgid "The Handbook's organization may change over time, and this document may lag in detailing the organizational changes. Post questions about Handbook organization to the <link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project mailing list</link>."
	+msgstr ""
	+
	+#. (itstool) path: sect4/title
	+#: book.translate.xml:1098
	+msgid "<filename>Makefile</filename>"
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1100
	+msgid "The <filename>Makefile</filename> defines some variables that affect how the <acronym>XML</acronym> source is converted to other formats, and lists the various source files that make up the Handbook. It then includes the standard <filename>doc.project.mk</filename>, to bring in the rest of the code that handles converting documents from one format to another."
	+msgstr ""
	+
	+#. (itstool) path: sect4/title
	+#: book.translate.xml:1110
	+msgid "<filename>book.xml</filename>"
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1112
	+msgid "This is the top level document in the Handbook. It contains the Handbook's <link linkend=\"xml-primer-doctype-declaration\">DOCTYPE declaration</link>, as well as the elements that describe the Handbook's structure."
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1117
	+msgid "<filename>book.xml</filename> uses <link linkend=\"xml-primer-parameter-entities\">parameter entities</link> to load in the files with the <filename>.ent</filename> extension. These files (described later) then define <link linkend=\"xml-primer-general-entities\">general entities</link> that are used throughout the rest of the Handbook."
	+msgstr ""
	+
	+#. (itstool) path: sect4/title
	+#: book.translate.xml:1126
	+msgid "<filename role=\"directory\"><replaceable>directory</replaceable>/chapter.xml</filename>"
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1128
	+msgid "Each chapter in the Handbook is stored in a file called <filename>chapter.xml</filename> in a separate directory from the other chapters. Each directory is named after the value of the <literal>id</literal> attribute on the <tag>chapter</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1135
	+msgid "For example, if one of the chapter files contains:"
	+msgstr ""
	+
	+#. (itstool) path: sect4/programlisting
	+#: book.translate.xml:1138
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">chapter id=\"kernelconfig\"</tag>\n"
	+"...\n"
	+"<tag class=\"endtag\">chapter</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1142
	+msgid "Then it will be called <filename>chapter.xml</filename> in the <filename>kernelconfig</filename> directory. In general, the entire contents of the chapter are in this one file."
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1148
	+msgid "When the <acronym>XHTML</acronym> version of the Handbook is produced, this will yield <filename>kernelconfig.html</filename>. This is because of the <literal>id</literal> value, and is not related to the name of the directory."
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1154
	+msgid ""
	+"In earlier versions of the Handbook, the files were stored in the same directory as <filename>book.xml</filename>, and named after the value of the <literal>id</literal> attribute on the file's <tag>chapter</tag> element. Now, it is possible to include images in each chapter. Images for each Handbook chapter are stored within <filename>share/images/books/handbook</filename>. The localized version of these "
	+"images should be placed in the same directory as the <acronym>XML</acronym> sources for each chapter. Namespace collisions are inevitable, and it is easier to work with several directories with a few files in them than it is to work with one directory that has many files in it."
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1168
	+msgid "A brief look will show that there are many directories with individual <filename>chapter.xml</filename> files, including <filename>basics/chapter.xml</filename>, <filename>introduction/chapter.xml</filename>, and <filename>printing/chapter.xml</filename>."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:1175
	+msgid "Do not name chapters or directories after their ordering within the Handbook. This ordering can change as the content within the Handbook is reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy."
	+msgstr ""
	+
	+#. (itstool) path: sect4/para
	+#: book.translate.xml:1183
	+msgid "The <filename>chapter.xml</filename> files are not complete <acronym>XML</acronym> documents that can be built individually. They can only be built as parts of the whole Handbook."
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:1226
	+msgid "The Documentation Build Process"
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:1228
	+msgid "This chapter covers organization of the documentation build process and how <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to control it."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1232
	+msgid "Rendering DocBook into Output"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1234
	+msgid "Different types of output can be produced from a single DocBook source file. The type of output desired is set with the <varname>FORMATS</varname> variable. A list of known formats is stored in <varname>KNOWN_FORMATS</varname>:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/screen
	+#. (itstool) id: book.translate.xml#doc-build-rendering-known-formats
	+#: book.translate.xml:1239
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: table/title
	+#: book.translate.xml:1243
	+msgid "Common Output Formats"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1248
	+msgid "<varname>FORMATS</varname> Value"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1249
	+msgid "File Type"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#. (itstool) path: segmentedlist/segtitle
	+#: book.translate.xml:1250 book.translate.xml:7223
	+msgid "Description"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:1256 book.translate.xml:2485
	+msgid "<literal>html</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1257
	+msgid "<acronym>HTML</acronym>, one file"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1258
	+msgid "A single <filename>book.html</filename> or <filename>article.html</filename>."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1263
	+msgid "<literal>html-split</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1264
	+msgid "<acronym>HTML</acronym>, multiple files"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1265
	+msgid "Multiple <acronym>HTML</acronym> files, one for each chapter or section, for use on a typical web site."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1271
	+msgid "<literal>pdf</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1272
	+msgid "<acronym>PDF</acronym>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:1273
	+msgid "Portable Document Format"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1279
	+msgid "The default output format can vary by document, but is usually <literal>html-split</literal>. Other formats are chosen by setting <varname>FORMATS</varname> to a specific value. Multiple output formats can be created at a single time by setting <varname>FORMATS</varname> to a list of formats."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:1286
	+msgid "Build a Single HTML Output File"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:1288
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>make FORMATS=html</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:1293
	+msgid "Build HTML-Split and <acronym>PDF</acronym> Output Files"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:1296
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>make FORMATS=\"html-split pdf\"</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1302
	+msgid "The FreeBSD Documentation Build Toolset"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1304
	+msgid "These are the tools used to build and install the <acronym>FDP</acronym> documentation."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1309
	+msgid "The primary build tool is <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, specifically <application>Berkeley Make</application>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1314
	+msgid "Package building is handled by FreeBSD's <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1319
	+msgid "<citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to create compressed versions of the document. <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> archives are also supported. <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used for package building."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1325
	+msgid "<citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to install the documentation."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1333
	+msgid "Understanding <filename>Makefile</filename>s in the Documentation Tree"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1336
	+msgid "There are three main types of <filename>Makefile</filename>s in the FreeBSD Documentation Project tree."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1341
	+msgid "<link linkend=\"sub-make\">Subdirectory <filename>Makefile</filename>s</link> simply pass commands to those directories below them."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1347
	+msgid "<link linkend=\"doc-make\">Documentation <filename>Makefile</filename>s</link> describe the documents that are produced from this directory."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1354
	+msgid "<link linkend=\"make-includes\"><application>Make</application> includes</link> are the glue that perform the document production, and are usually of the form <filename>doc.<replaceable>xxx</replaceable>.mk</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:1362
	+msgid "Subdirectory <filename>Makefile</filename>s"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1364
	+msgid "These <filename>Makefile</filename>s usually take the form of:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:1367
	+#, no-wrap
	+msgid ""
	+"SUBDIR =articles\n"
	+"SUBDIR+=books\n"
	+"\n"
	+"COMPAT_SYMLINK = en\n"
	+"\n"
	+"DOC_PREFIX?= ${.CURDIR}/..\n"
	+".include \"${DOC_PREFIX}/share/mk/doc.project.mk\""
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1375
	+msgid "The first four non-empty lines define the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables <varname>SUBDIR</varname>, <varname>COMPAT_SYMLINK</varname>, and <varname>DOC_PREFIX</varname>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1380
	+msgid "The <varname>SUBDIR</varname> statement and <varname>COMPAT_SYMLINK</varname> statement show how to assign a value to a variable, overriding any previous value."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1385
	+msgid "The second <varname>SUBDIR</varname> statement shows how a value is appended to the current value of a variable. The <varname>SUBDIR</varname> variable is now <literal>articles books</literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1390
	+msgid "The <varname>DOC_PREFIX</varname> assignment shows how a value is assigned to the variable, but only if it is not already defined. This is useful if <varname>DOC_PREFIX</varname> is not where this <filename>Makefile</filename> thinks it is - the user can override this and provide the correct value."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1397
	+msgid "What does it all mean? <varname>SUBDIR</varname> mentions which subdirectories below this one the build process should pass any work on to."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1401
	+msgid "<varname>COMPAT_SYMLINK</varname> is specific to compatibility symlinks (amazingly enough) for languages to their official encoding (<filename>doc/en</filename> would point to <filename>en_US.ISO-8859-1</filename>)."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1406
	+msgid "<varname>DOC_PREFIX</varname> is the path to the root of the FreeBSD Document Project tree. This is not always that easy to find, and is also easily overridden, to allow for flexibility. <varname>.CURDIR</varname> is a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> builtin variable with the path to the current directory."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1413
	+msgid "The final line includes the FreeBSD Documentation Project's project-wide <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> system file <filename>doc.project.mk</filename> which is the glue which converts these variables into build instructions."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:1420
	+msgid "Documentation <filename>Makefile</filename>s"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1422
	+msgid "These <filename>Makefile</filename>s set <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables that describe how to build the documentation contained in that directory."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1426
	+msgid "Here is an example:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:1428
	+#, no-wrap
	+msgid ""
	+"MAINTAINER=nik@FreeBSD.org\n"
	+"\n"
	+"DOC?= book\n"
	+"\n"
	+"FORMATS?= html-split html\n"
	+"\n"
	+"INSTALL_COMPRESSED?= gz\n"
	+"INSTALL_ONLY_COMPRESSED?=\n"
	+"\n"
	+"# SGML content\n"
	+"SRCS= book.xml\n"
	+"\n"
	+"DOC_PREFIX?= ${.CURDIR}/../../..\n"
	+"\n"
	+".include \"$(DOC_PREFIX)/share/mk/docproj.docbook.mk\""
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1444
	+msgid "The <varname>MAINTAINER</varname> variable allows committers to claim ownership of a document in the FreeBSD Documentation Project, and take responsibility for maintaining it."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1449
	+msgid "<varname>DOC</varname> is the name (sans the <filename>.xml</filename> extension) of the main document created by this directory. <varname>SRCS</varname> lists all the individual files that make up the document. This should also include important files in which a change should result in a rebuild."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1456
	+msgid "<varname>FORMATS</varname> indicates the default formats that should be built for this document. <varname>INSTALL_COMPRESSED</varname> is the default list of compression techniques that should be used in the document build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by default, should be non-empty if only compressed documents are desired in the build."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1464
	+msgid "The <varname>DOC_PREFIX</varname> and include statements should be familiar already."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1470
	+msgid "FreeBSD Documentation Project <application>Make</application> Includes"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1473
	+msgid "<citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes are best explained by inspection of the code. Here are the system include files:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1478
	+msgid "<filename>doc.project.mk</filename> is the main project include file, which includes all the following include files, as necessary."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1484
	+msgid "<filename>doc.subdir.mk</filename> handles traversing of the document tree during the build and install processes."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1490
	+msgid "<filename>doc.install.mk</filename> provides variables that affect ownership and installation of documents."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1495
	+msgid "<filename>doc.docbook.mk</filename> is included if <varname>DOCFORMAT</varname> is <literal>docbook</literal> and <varname>DOC</varname> is set."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:1502
	+msgid "<filename>doc.project.mk</filename>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1504
	+msgid "By inspection:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:1506
	+#, no-wrap
	+msgid ""
	+"DOCFORMAT?=\tdocbook\n"
	+"MAINTAINER?=\tdoc@FreeBSD.org\n"
	+"\n"
	+"PREFIX?=\t/usr/local\n"
	+"PRI_LANG?=\ten_US.ISO8859-1\n"
	+"\n"
	+".if defined(DOC)\n"
	+".if ${DOCFORMAT} == \"docbook\"\n"
	+".include \"doc.docbook.mk\"\n"
	+".endif\n"
	+".endif\n"
	+"\n"
	+".include \"doc.subdir.mk\"\n"
	+".include \"doc.install.mk\""
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:1523 book.translate.xml:1573
	+msgid "Variables"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1525
	+msgid "<varname>DOCFORMAT</varname> and <varname>MAINTAINER</varname> are assigned default values, if these are not set by the document make file."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1529
	+msgid "<varname>PREFIX</varname> is the prefix under which the <link linkend=\"tools\">documentation building tools</link> are installed. For normal package and port installation, this is <filename>/usr/local</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1534
	+msgid "<varname>PRI_LANG</varname> should be set to whatever language and encoding is natural amongst users these documents are being built for. US English is the default."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:1540
	+msgid "<varname>PRI_LANG</varname> does not affect which documents can, or even will, be built. Its main use is creating links to commonly referenced documents into the FreeBSD documentation install root."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:1548
	+msgid "Conditionals"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1550
	+msgid "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 programs, defines behavior if some condition is true or if it is false. <literal>defined</literal> is a function which returns whether the variable given is defined or not."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1556
	+msgid "<literal>.if ${DOCFORMAT} == \"docbook\"</literal>, next, tests whether the <varname>DOCFORMAT</varname> variable is <literal>\"docbook\"</literal>, and in this case, includes <filename>doc.docbook.mk</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1561
	+msgid "The two <literal>.endif</literal>s close the two above conditionals, marking the end of their application."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:1567
	+msgid "<filename>doc.subdir.mk</filename>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:1569
	+msgid "This file is too long to explain in detail. These notes describe the most important features."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1577
	+msgid "<varname>SUBDIR</varname> is a list of subdirectories that the build process should go further down into."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1583
	+msgid "<varname>ROOT_SYMLINKS</varname> is the name of directories that should be linked to the document install root from their actual locations, if the current language is the primary language (specified by <varname>PRI_LANG</varname>)."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1591
	+msgid "<varname>COMPAT_SYMLINK</varname> is described in the <link linkend=\"sub-make\">Subdirectory Makefile</link> section."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:1600
	+msgid "Targets and Macros"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1602
	+msgid "Dependencies are described by <literal><replaceable>target</replaceable>: <replaceable>dependency1 dependency2 ...</replaceable></literal> tuples, where to build <literal>target</literal>, the given dependencies must be built first."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1609
	+msgid "After that descriptive tuple, instructions on how to build the target may be given, if the conversion process between the target and its dependencies are not previously defined, or if this particular conversion is not the same as the default conversion method."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1615
	+msgid "A special dependency <literal>.USE</literal> defines the equivalent of a macro."
	+msgstr ""
	+
	+#. (itstool) path: sect3/programlisting
	+#: book.translate.xml:1618 book.translate.xml:1705
	+#, no-wrap
	+msgid ""
	+"_SUBDIRUSE: .USE\n"
	+".for entry in ${SUBDIR}\n"
	+"\t@${ECHO} \"===> ${DIRPRFX}${entry}\"\n"
	+"\t@(cd ${.CURDIR}/${entry} && \\\n"
	+"\t${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )\n"
	+".endfor"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:1625 book.translate.xml:1641
	+msgid "_SUBDIRUSE"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1625
	+msgid "In the above, <_:buildtarget-1/> is now a macro which will execute the given commands when it is listed as a dependency."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1629
	+msgid "What sets this macro apart from other targets? Basically, it is executed <emphasis>after</emphasis> the instructions given in the build procedure it is listed as a dependency to, and it does not adjust <varname>.TARGET</varname>, which is the variable which contains the name of the target currently being built."
	+msgstr ""
	+
	+#. (itstool) path: sect3/programlisting
	+#: book.translate.xml:1637
	+#, no-wrap
	+msgid ""
	+"clean: _SUBDIRUSE\n"
	+"\trm -f ${CLEANFILES}"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:1640 book.translate.xml:1644 book.translate.xml:1664 book.translate.xml:6091 book.translate.xml:6095 book.translate.xml:6099
	+msgid "clean"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1640
	+msgid "In the above, <_:buildtarget-1/> will use the <_:buildtarget-2/> macro after it has executed the instruction <command>rm -f ${CLEANFILES}</command>. In effect, this causes <_:buildtarget-3/> to go further and further down the directory tree, deleting built files as it goes <emphasis>down</emphasis>, not on the way back up."
	+msgstr ""
	+
	+#. (itstool) path: sect4/title
	+#: book.translate.xml:1650
	+msgid "Provided Targets"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:1654
	+msgid "install"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:1655
	+msgid "package"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:1658
	+msgid "realinstall"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:1659
	+msgid "realpackage"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1654
	+msgid "_:buildtarget-3/> and <_:buildtarget-4/> respectively).<_:buildtarget-1/> and <_:buildtarget-2/> both go down the directory tree calling the real versions of themselves in the subdirectories (<"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:1667
	+msgid "cleandir"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1664
	+msgid "<_:buildtarget-1/> removes files created by the build process (and goes down the directory tree too). <_:buildtarget-2/> does the same, and also removes the object directory, if any."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:1675
	+msgid "More on Conditionals"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1679
	+msgid "<literal>exists</literal> is another condition function which returns true if the given file exists."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1685
	+msgid "<literal>empty</literal> returns true if the given variable is empty."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1690
	+msgid "<literal>target</literal> returns true if the given target does not already exist."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:1697
	+msgid "Looping Constructs in <command>make (.for)</command>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1700
	+msgid "<literal>.for</literal> provides a way to repeat a set of instructions for each space-separated element in a variable. It does this by assigning a variable to contain the current element in the list being examined."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:1712
	+msgid "In the above, if <varname>SUBDIR</varname> is empty, no action is taken; if it has one or more elements, the instructions between <literal>.for</literal> and <literal>.endfor</literal> would repeat for every element, with <varname>entry</varname> being replaced with the value of the current element."
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:1756
	+msgid "The Website"
	+msgstr "網站"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:1758
	+msgid "The FreeBSD web site is part of the FreeBSD documents. Files for the web site are stored in the <filename>en_US.ISO8859-1/htdocs</filename> subdirectory of the document tree directory, <filename>~/doc</filename> in this example."
	+msgstr "FreeBSD 網站是 FreeBSD 文件的一部份。網站的檔案儲存在文件樹目錄，此例中是 <filename>~/doc</filename>，的 <filename>en_US.ISO8859-1/htdocs</filename> 子目錄。"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1765
	+msgid "Environment Variables"
	+msgstr "環境變數"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1767
	+msgid "Several environment variables control which parts of the the web site are built or installed, and to which directories."
	+msgstr "有些環境變數控制網站的建構或安裝，和裝到哪個目錄"
	+
	+#. (itstool) path: tip/para
	+#: book.translate.xml:1772
	+msgid "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 are empty. The examples here show the recommended ways of defining and using these variables. Setting or defining these variables with other values or methods might lead to unexpected surprises."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:1782
	+msgid "<varname>DESTDIR</varname>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1785
	+msgid "DESTDIR specifies the path where the web site files are to be installed."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1788
	+msgid ""
	+"This variable is best set with <citerefentry><refentrytitle>env</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the user shell's method of setting environment variables, <command>setenv</command> for <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> or <command>export</command> for <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></"
	+"citerefentry>."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:1798
	+msgid "<varname>ENGLISH_ONLY</varname>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1801
	+msgid "Default: undefined. Build and include all translations."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1804
	+msgid "<userinput>ENGLISH_ONLY=yes</userinput>: use only the English documents and ignore all translations."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:1810
	+msgid "<varname>WEB_ONLY</varname>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1813
	+msgid "Default: undefined. Build both the web site and all the books and articles."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1816
	+msgid "<userinput>WEB_ONLY=yes</userinput>: build or install only <acronym>HTML</acronym> pages from the <filename>en_US.ISO8859-1/htdocs</filename> directory. Other directories and documents, including books and articles, will be ignored."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:1825
	+msgid "<varname>WEB_LANG</varname>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1828
	+msgid "Default: undefined. Build and include all the available languages on the web site."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:1831
	+msgid "Set to a space-separated list of languages to be included in the build or install. The formats are the same as the directory names in the document root directory. For example, to include the German and French documents:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/screen
	+#: book.translate.xml:1837
	+#, no-wrap
	+msgid "<userinput>WEB_LANG=\"de_DE.ISO8859-1 fr_FR.ISO8859-1\"</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1842
	+msgid "<varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>, 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>, <filename>Makefile.inc</filename>, as environment variables on the command line, or in dot files."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:1850
	+msgid "Building and Installing the Web Pages"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1852
	+msgid "Having obtained the documentation and web site source files, the web site can be built."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1855
	+msgid "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 not allow files to be installed by an unprivileged user. For testing, it can be useful to install the files as a normal user to a temporary directory."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1861
	+msgid "In these examples, the web site files are built by user <systemitem class=\"username\">jru</systemitem> in their home directory, <filename>~/doc</filename>, with a full path of <filename>/usr/home/jru/doc</filename>."
	+msgstr ""
	+
	+#. (itstool) path: tip/para
	+#: book.translate.xml:1867
	+msgid "The web site build uses the <filename>INDEX</filename> from the Ports Collection and might fail if that file or <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 Collection</link>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:1875
	+msgid "Build the Full Web Site and All Documents"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:1877
	+msgid "Build the web site and all documents. The resulting files are left in the document tree:"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:1880
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>\n"
	+"<prompt>%</prompt> <userinput>make all</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:1885
	+msgid "Build Only the Web Site in English"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:1887
	+msgid "Build the web site only, in English, as user <systemitem class=\"username\">jru</systemitem>, and install the resulting files into <filename>/tmp/www</filename> for testing:"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:1892
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>\n"
	+"<prompt>%</prompt> <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:1895
	+msgid "Changes to static files can usually be tested by viewing the modified files directly with a web browser. If the site has been built as shown above, a modified main page can be viewed with:"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:1900
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>firefox /tmp/www/data/index.html</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:1902
	+msgid "Modifications to dynamic files can be tested with a web server running on the local system. After building the site as shown above, this <filename>/usr/local/etc/apache24/httpd.conf</filename> can be used with <package>www/apache24</package>:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:1908
	+#, no-wrap
	+msgid ""
	+"# httpd.conf for testing the FreeBSD website\n"
	+"Define TestRoot \"/tmp/www/data\"\n"
	+"\n"
	+"# directory for configuration files\n"
	+"ServerRoot \"/usr/local\"\n"
	+"\n"
	+"Listen 80\n"
	+"\n"
	+"# minimum required modules\n"
	+"LoadModule authz_core_module libexec/apache24/mod_authz_core.so\n"
	+"LoadModule mime_module libexec/apache24/mod_mime.so\n"
	+"LoadModule unixd_module libexec/apache24/mod_unixd.so\n"
	+"LoadModule cgi_module libexec/apache24/mod_cgi.so\n"
	+"LoadModule dir_module libexec/apache24/mod_dir.so\n"
	+"\n"
	+"# run the webserver as user and group\n"
	+"User www\n"
	+"Group www\n"
	+"\n"
	+"ServerAdmin you@example.com\n"
	+"ServerName fbsdtest\n"
	+"\n"
	+"# deny access to all files\n"
	+"<Directory />\n"
	+" AllowOverride none\n"
	+" Require all denied\n"
	+"</Directory>\n"
	+"\n"
	+"# allow access to the website directory\n"
	+"DocumentRoot \"${TestRoot}\"\n"
	+"<Directory \"${TestRoot}\">\n"
	+" Options Indexes FollowSymLinks\n"
	+" AllowOverride None\n"
	+" Require all granted\n"
	+"</Directory>\n"
	+"\n"
	+"# prevent access to .htaccess and .htpasswd files\n"
	+"<Files \".ht*\">\n"
	+" Require all denied\n"
	+"</Files>\n"
	+"\n"
	+"ErrorLog \"/var/log/httpd-error.log\"\n"
	+"LogLevel warn\n"
	+"\n"
	+"# set up the CGI script directory\n"
	+"<Directory \"${TestRoot}/cgi\">\n"
	+" AllowOverride None\n"
	+" Options None\n"
	+" Require all granted\n"
	+" Options +ExecCGI\n"
	+" AddHandler cgi-script .cgi\n"
	+"</Directory>\n"
	+"\n"
	+"Include etc/apache24/Includes/*.conf"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:1963
	+msgid "Start the web server with"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:1965
	+#, no-wrap
	+msgid "<prompt>#</prompt> <userinput>service apache24 onestart</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:1967
	+msgid ""
	+"The web site can be viewed at <link xlink:href=\"http://localhost\"/>. Be aware that many links refer to the real FreeBSD site by name, and those links will still go to the external site instead of the local test version. Fully testing the local site will require temporarily setting <acronym>DNS</acronym> so <literal>www.FreeBSD.org</literal> resolves to <literal>localhost</literal> or the local <acronym>IP</"
	+"acronym> address."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:1979
	+msgid "Build and Install the Web Site"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:1981
	+msgid "Build the web site and all documents as user <systemitem class=\"username\">jru</systemitem>. Install the resulting files as <systemitem class=\"username\">root</systemitem> into the default directory, <filename>/root/public_html</filename>:"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:1988
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>\n"
	+"<prompt>%</prompt> <userinput>make all</userinput>\n"
	+"<prompt>%</prompt> <userinput>su -</userinput>\n"
	+"Password:\n"
	+"<prompt>#</prompt> <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>\n"
	+"<prompt>#</prompt> <userinput>make install</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:1996
	+msgid "The install process does not delete any old or outdated files that existed previously in the same directory. If a new copy of the site is built and installed every day, this command will find and delete all files that have not been updated in three days:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:2002
	+#, no-wrap
	+msgid "<prompt>#</prompt> <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:2039
	+msgid "XML Primer"
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:2041
	+msgid "Most <acronym>FDP</acronym> documentation is written with markup languages based on <acronym>XML</acronym>. This chapter explains what that means, how to read and understand the documentation source, and the <acronym>XML</acronym> techniques used."
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:2047
	+msgid "Portions of this section were inspired by Mark Galassi's <link xlink:href=\"http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html\">Get Going With DocBook</link>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2054
	+msgid "In the original days of computers, electronic text was simple. There were a few character sets like <acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2060
	+msgid ""
	+"Inevitably, this was not enough. When text is in a machine-usable format, machines are expected to be able to use and manipulate it intelligently. Authors want to indicate that certain phrases should be emphasized, or added to a glossary, or made into hyperlinks. Filenames could be shown in a <quote>typewriter</quote> style font for viewing on screen, but as <quote>italics</quote> when printed, or any of a "
	+"myriad of other options for presentation."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2069
	+msgid "It was once hoped that Artificial Intelligence (AI) would make this easy. The computer would read the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more. Unfortunately, real life has not happened quite like that, and computers still require assistance before they can meaningfully process text."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2077
	+msgid "More precisely, they need help identifying what is what. Consider this text:"
	+msgstr ""
	+
	+#. (itstool) path: blockquote/para
	+#: book.translate.xml:2081
	+msgid "To remove <filename>/tmp/foo</filename>, use <citerefentry><refentrytitle>rm</refentrytitle><manvolnum>1</manvolnum></citerefentry>."
	+msgstr ""
	+
	+#. (itstool) path: blockquote/screen
	+#: book.translate.xml:2084
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>rm /tmp/foo</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2087
	+msgid "It is easy to see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document cannot. For this we need markup."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2092
	+msgid ""
	+"<quote>Markup</quote> is commonly used to describe <quote>adding value</quote> or <quote>increasing cost</quote>. The term takes on both these meanings when applied to text. Markup is additional text included in the document, distinguished from the document's content in some way, so that programs that process the document can read the markup and use it when making decisions about the document. Editors can "
	+"hide the markup from the user, so the user is not distracted by it."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2102
	+msgid "The extra information stored in the markup <emphasis>adds value</emphasis> to the document. Adding the markup to the document must typically be done by a person—after all, if computers could recognize the text sufficiently well to add the markup then there would be no need to add it in the first place. This <emphasis>increases the cost</emphasis> (the effort required) to create the document."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2111
	+msgid "The previous example is actually represented in this document like this:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/programlisting
	+#: book.translate.xml:2114
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>To remove <tag class=\"starttag\">filename</tag>/tmp/foo<tag class=\"endtag\">filename</tag>, use &man.rm.1;.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">screen</tag>&prompt.user; <tag class=\"starttag\">userinput</tag>rm /tmp/foo<tag class=\"endtag\">userinput</tag><tag class=\"endtag\">screen</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2118
	+msgid "The markup is clearly separate from the content."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2120
	+msgid "Markup languages define what the markup means and how it should be interpreted."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2123
	+msgid ""
	+"Of course, one markup language might not be enough. A markup language for technical documentation has very different requirements than a markup language that is intended for cookery recipes. This, in turn, would be very different from a markup language used to describe poetry. What is really needed is a first language used to write these other markup languages. A <emphasis>meta markup language</emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2131
	+msgid "This is exactly what the eXtensible Markup Language (<acronym>XML</acronym>) is. Many markup languages have been written in <acronym>XML</acronym>, including the two most used by the <acronym>FDP</acronym>, <acronym>XHTML</acronym> and DocBook."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2137
	+msgid "Each language definition is more properly called a grammar, vocabulary, schema or Document Type Definition (<acronym>DTD</acronym>). There are various languages to specify an <acronym>XML</acronym> grammar, or <emphasis>schema</emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#. (itstool) id: book.translate.xml#xml-primer-validating
	+#: book.translate.xml:2143
	+msgid ""
	+"A schema is a <emphasis>complete</emphasis> specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so forth. This makes it possible to write an <acronym>XML</acronym> <emphasis>parser</emphasis> which reads in both the schema and a document which claims to conform to the schema. The parser can then confirm "
	+"whether or not all the elements required by the vocabulary are in the document in the right order, and whether there are any errors in the markup. This is normally referred to as <quote>validating the document</quote>."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:2157
	+msgid ""
	+"Validation confirms that the choice of elements, their ordering, and so on, conforms to that listed in the grammar. It does <emphasis>not</emphasis> check whether <emphasis>appropriate</emphasis> markup has been used for the content. If all the filenames in a document were marked up as function names, the parser would not flag this as an error (assuming, of course, that the schema defines elements for "
	+"filenames and functions, and that they are allowed to appear in the same place)."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2168
	+msgid "Most contributions to the Documentation Project will be content marked up in either <acronym>XHTML</acronym> or DocBook, rather than alterations to the schemas. For this reason, this book will not touch on how to write a vocabulary."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:2176
	+msgid "Elements, Tags, and Attributes"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2178
	+msgid "All the vocabularies written in <acronym>XML</acronym> share certain characteristics. This is hardly surprising, as the philosophy behind <acronym>XML</acronym> will inevitably show through. One of the most obvious manifestations of this philosophy is that of <emphasis>content</emphasis> and <emphasis>elements</emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2185
	+msgid "Documentation, whether it is a single web page, or a lengthy book, is considered to consist of content. This content is then divided and further subdivided into elements. The purpose of adding markup is to name and identify the boundaries of these elements for further processing."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2191
	+msgid ""
	+"For example, consider a typical book. At the very top level, the book is itself an element. This <quote>book</quote> element obviously contains chapters, which can be considered to be elements in their own right. Each chapter will contain more elements, such as paragraphs, quotations, and footnotes. Each paragraph might contain further elements, identifying content that was direct speech, or the name of a "
	+"character in the story."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2200
	+msgid "It may be helpful to think of this as <quote>chunking</quote> content. At the very top level is one chunk, the book. Look a little deeper, and there are more chunks, the individual chapters. These are chunked further into paragraphs, footnotes, character names, and so on."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2206
	+msgid "Notice how this differentiation between different elements of the content can be made without resorting to any <acronym>XML</acronym> terms. It really is surprisingly straightforward. This could be done with a highlighter pen and a printout of the book, using different colors to indicate different chunks of content."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2213
	+msgid "Of course, we do not have an electronic highlighter pen, so we need some other way of indicating which element each piece of content belongs to. In languages written in <acronym>XML</acronym> (<acronym>XHTML</acronym>, DocBook, et al) this is done by means of <emphasis>tags</emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2219
	+msgid "A tag is used to identify where a particular element starts, and where the element ends. <emphasis>The tag is not part of the element itself</emphasis>. Because each grammar was normally written to mark up specific types of information, each one will recognize different elements, and will therefore have different names for the tags."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2226
	+msgid "For an element called <replaceable>element-name</replaceable> the start tag will 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>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2232
	+msgid "Using an Element (Start and End Tags)"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:2234
	+msgid "<acronym>XHTML</acronym> has an element for indicating that the content enclosed by the element is a paragraph, called <tag>p</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2238
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>This is a paragraph. It starts with the start tag for\n"
	+" the 'p' element, and it will end with the end tag for the 'p'\n"
	+" element.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">p</tag>This is another paragraph. But this one is much shorter.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2245
	+msgid "Some elements have no content. For example, in <acronym>XHTML</acronym>, a horizontal line can be included in the document. For these <quote>empty</quote> elements, <acronym>XML</acronym> introduced a shorthand form that is completely equivalent to the two-tag version:"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2252
	+msgid "Using an Element Without Content"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:2254
	+msgid "<acronym>XHTML</acronym> has an element for indicating a horizontal rule, called <tag>hr</tag>. This element does not wrap content, so it looks like this:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2258
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>One paragraph.<tag class=\"endtag\">p</tag>\n"
	+"<tag class=\"starttag\">hr</tag><tag class=\"endtag\">hr</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">p</tag>This is another paragraph. A horizontal rule separates this\n"
	+" from the previous paragraph.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:2264
	+msgid "The shorthand version consists of a single tag:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2266
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>One paragraph.<tag class=\"endtag\">p</tag>\n"
	+"<tag class=\"emptytag\">hr</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">p</tag>This is another paragraph. A horizontal rule separates this\n"
	+" from the previous paragraph.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2273
	+msgid "As shown above, elements can contain other elements. In the book example earlier, the book element contained all the chapter elements, which in turn contained all the paragraph elements, and so on."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2279
	+msgid "Elements Within Elements; <tag>em</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2281
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>This is a simple <tag class=\"starttag\">em</tag>paragraph<tag class=\"endtag\">em</tag> where some\n"
	+" 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>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2285
	+msgid "The grammar consists of rules that describe which elements can contain other elements, and exactly what they can contain."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:2290
	+msgid "People often confuse the terms tags and elements, and use the terms as if they were interchangeable. They are not."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:2294
	+msgid "An element is a conceptual part of your document. An element has a defined start and end. The tags mark where the element starts and ends."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:2298
	+msgid "When this document (or anyone else knowledgeable about <acronym>XML</acronym>) refers to <quote>the <tag class=\"starttag\">p</tag> tag</quote> they mean the literal text consisting of the three characters <literal><</literal>, <literal>p</literal>, and <literal>></literal>. But the phrase <quote>the <tag>p</tag> element</quote> refers to the whole element."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:2307
	+msgid "This distinction <emphasis>is</emphasis> very subtle. But keep it in mind."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2311
	+msgid "Elements can have attributes. An attribute has a name and a value, and is used for adding extra information to the element. This might be information that indicates how the content should be rendered, or might be something that uniquely identifies that occurrence of the element, or it might be something else."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2317
	+msgid "An element's attributes are written <emphasis>inside</emphasis> the start tag for that element, and take the form <literal><replaceable>attribute-name</replaceable>=\"<replaceable>attribute-value</replaceable>\"</literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2322
	+msgid "In <acronym>XHTML</acronym>, the <tag>p</tag> element has an attribute called <tag class=\"attribute\">align</tag>, which suggests an alignment (justification) for the paragraph to the program displaying the <acronym>XHTML</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2328
	+msgid "The <tag class=\"attribute\">align</tag> attribute can take one of four defined values, <literal>left</literal>, <literal>center</literal>, <literal>right</literal> and <literal>justify</literal>. If the attribute is not specified then the default is <literal>left</literal>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2335
	+msgid "Using an Element with an Attribute"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2337
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p align=\"left\"</tag>The inclusion of the align attribute\n"
	+" on this paragraph was superfluous, since the default is left.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">p align=\"center\"</tag>This may appear in the center.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2343
	+msgid "Some attributes only take specific values, such as <literal>left</literal> or <literal>justify</literal>. Others allow any value."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2348
	+msgid "Single Quotes Around Attributes"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2350
	+#, no-wrap
	+msgid "<tag class=\"starttag\">p align='right'</tag>I am on the right!<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2353
	+msgid "Attribute values in <acronym>XML</acronym> must be enclosed in either single or double quotes. Double quotes are traditional. Single quotes are useful when the attribute value contains double quotes."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2358
	+msgid "Information about attributes, elements, and tags is stored in catalog files. The Documentation Project uses standard DocBook catalogs and includes additional catalogs for FreeBSD-specific features. Paths to the catalog files are defined in an environment variable so they can be found by the document build tools."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:2366 book.translate.xml:2778 book.translate.xml:2912 book.translate.xml:3099 book.translate.xml:3392
	+msgid "To Do…"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2368
	+msgid ""
	+"Before running the examples in this document, install <package>textproc/docproj</package> from the FreeBSD Ports Collection. This is a <emphasis>meta-port</emphasis> that downloads and installs the standard programs and supporting files needed by the Documentation Project. <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> users must use <command>rehash</command> for the "
	+"shell to recognize new programs after they have been installed, or log out and then log back in again."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2380
	+msgid "Create <filename>example.xml</filename>, and enter this text:"
	+msgstr ""
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:2383
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">html xmlns=\"http://www.w3.org/1999/xhtml\"</tag>\n"
	+" <tag class=\"starttag\">head</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example XHTML File<tag class=\"endtag\">title</tag>\n"
	+" <tag class=\"endtag\">head</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">body</tag>\n"
	+" <tag class=\"starttag\">p</tag>This is a paragraph containing some text.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p</tag>This paragraph contains some more text.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p align=\"right\"</tag>This paragraph might be right-justified.<tag class=\"endtag\">p</tag>\n"
	+" <tag class=\"endtag\">body</tag>\n"
	+"<tag class=\"endtag\">html</tag>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2401
	+msgid "Try to validate this file using an <acronym>XML</acronym> parser."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2404
	+msgid "<package>textproc/docproj</package> includes the <command>xmllint</command> <link linkend=\"xml-primer-validating\">validating parser</link>."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2409
	+msgid "Use <command>xmllint</command> to validate the document:"
	+msgstr ""
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:2412
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2414
	+msgid "<command>xmllint</command> returns without displaying any output, showing that the document validated successfully."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2420
	+msgid "See what happens when required elements are omitted. Delete the line with the <tag class=\"starttag\">title</tag> and <tag class=\"endtag\">title</tag> tags, and re-run the validation."
	+msgstr ""
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:2426
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput>\n"
	+"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 ()"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2429
	+msgid "This shows that the validation error comes from the <replaceable>fifth</replaceable> line of the <replaceable>example.xml</replaceable> file and that the content of the <tag class=\"starttag\">head</tag> is the part which does not follow the rules of the <acronym>XHTML</acronym> grammar."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2436
	+msgid "Then <command>xmllint</command> shows the line where the error was found and marks the exact character position with a <literal>^</literal> sign."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2442
	+msgid "Replace the <tag>title</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:2449
	+msgid "The DOCTYPE Declaration"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2451
	+msgid "The beginning of each document can specify the name of the <acronym>DTD</acronym> to which the document conforms. This DOCTYPE declaration is used by <acronym>XML</acronym> parsers to identify the <acronym>DTD</acronym> and ensure that the document does conform to it."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2457
	+msgid "A typical declaration for a document written to conform with version 1.0 of the <acronym>XHTML</acronym> <acronym>DTD</acronym> looks like this:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/programlisting
	+#: book.translate.xml:2461
	+#, no-wrap
	+msgid "<tag class=\"starttag\">!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2463
	+msgid "That line contains a number of different components."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2467
	+msgid "<literal><!</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2470
	+msgid "The <emphasis>indicator</emphasis> shows this is an <acronym>XML</acronym> declaration."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2476
	+msgid "<literal>DOCTYPE</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2479
	+msgid "Shows that this is an <acronym>XML</acronym> declaration of the document type."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2488
	+msgid "Names the first <link linkend=\"xml-primer-elements\">element</link> that will appear in the document."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2495
	+msgid "<literal>PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: para/indexterm
	+#. (itstool) path: sect2/indexterm
	+#: book.translate.xml:2500 book.translate.xml:2541
	+msgid "<primary>Formal Public Identifier</primary>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2498
	+msgid "Lists the Formal Public Identifier (<acronym>FPI</acronym>) <_:indexterm-1/> for the <acronym>DTD</acronym> to which this document conforms. The <acronym>XML</acronym> parser uses this to find the correct <acronym>DTD</acronym> when processing this document."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2508
	+msgid "<literal>PUBLIC</literal> is not a part of the <acronym>FPI</acronym>, but indicates to the <acronym>XML</acronym> processor how to find the <acronym>DTD</acronym> referenced in the <acronym>FPI</acronym>. Other ways of telling the <acronym>XML</acronym> parser how to find the <acronym>DTD</acronym> are shown <link linkend=\"xml-primer-fpi-alternatives\">later</link>."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2519
	+msgid "<literal>\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2522
	+msgid "A local filename or a <acronym>URL</acronym> to find the <acronym>DTD</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2528
	+msgid "<literal>></literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2531
	+msgid "Ends the declaration and returns to the document."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:2538
	+msgid "Formal Public Identifiers (<acronym>FPI</acronym>s)"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:2546
	+msgid "It is not necessary to know this, but it is useful background, and might help debug problems when the <acronym>XML</acronym> processor can not locate the <acronym>DTD</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2552
	+msgid "<acronym>FPI</acronym>s must follow a specific syntax:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:2555
	+#, no-wrap
	+msgid "\"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>\""
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2559
	+msgid "<replaceable>Owner</replaceable>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2562
	+msgid "The owner of the <acronym>FPI</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2564
	+msgid ""
	+"The beginning of the string identifies the owner of the <acronym>FPI</acronym>. For example, the <acronym>FPI</acronym> <literal>\"ISO 8879:1986//ENTITIES Greek Symbols//EN\"</literal> lists <literal>ISO 8879:1986</literal> as being the owner for the set of entities for Greek symbols. <acronym>ISO</acronym> 8879:1986 is the International Organization for Standardization (<acronym>ISO</acronym>) number for the "
	+"<acronym>SGML</acronym> standard, the predecessor (and a superset) of <acronym>XML</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2577
	+msgid "Otherwise, this string will either look like <literal>-//<replaceable>Owner</replaceable></literal> or <literal>+//<replaceable>Owner</replaceable></literal> (notice the only difference is the leading <literal>+</literal> or <literal>-</literal>)."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2584
	+msgid "If the string starts with <literal>-</literal> then the owner information is unregistered, with a <literal>+</literal> identifying it as registered."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2589
	+msgid ""
	+"<acronym>ISO</acronym> 9070:1991 defines how registered names are generated. It might be derived from the number of an <acronym>ISO</acronym> publication, an <acronym>ISBN</acronym> code, or an organization code assigned according to <acronym>ISO</acronym> 6523. Additionally, a registration authority could be created in order to assign registered names. The <acronym>ISO</acronym> council delegated this to the "
	+"American National Standards Institute (<acronym>ANSI</acronym>)."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2600
	+msgid "Because the FreeBSD Project has not been registered, the owner string is <literal>-//FreeBSD</literal>. As seen in the example, the <acronym>W3C</acronym> are not a registered owner either."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2608
	+msgid "<replaceable>Keyword</replaceable>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2611
	+msgid ""
	+"There are several keywords that indicate the type of information in the file. Some of the most common keywords are <literal>DTD</literal>, <literal>ELEMENT</literal>, <literal>ENTITIES</literal>, and <literal>TEXT</literal>. <literal>DTD</literal> is used only for <acronym>DTD</acronym> files, <literal>ELEMENT</literal> is usually used for <acronym>DTD</acronym> fragments that contain only entity or element "
	+"declarations. <literal>TEXT</literal> is used for <acronym>XML</acronym> content (text and tags)."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2626
	+msgid "<replaceable>Description</replaceable>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2629
	+msgid "Any description can be given for the contents of this file. This may include version numbers or any short text that is meaningful and unique for the <acronym>XML</acronym> system."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:2637
	+msgid "<replaceable>Language</replaceable>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:2640
	+msgid "An <acronym>ISO</acronym> two-character code that identifies the native language for the file. <literal>EN</literal> is used for English."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:2648
	+msgid "<filename>catalog</filename> Files"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:2650
	+msgid "With the syntax above, an <acronym>XML</acronym> processor needs to have some way of turning the <acronym>FPI</acronym> into the name of the file containing the <acronym>DTD</acronym>. A catalog file (typically called <filename>catalog</filename>) contains lines that map <acronym>FPI</acronym>s to filenames. For example, if the catalog file contained the line:"
	+msgstr ""
	+
	+#. (itstool) path: sect3/programlisting
	+#: book.translate.xml:2660
	+#, no-wrap
	+msgid "PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"1.0/transitional.dtd\""
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:2662
	+msgid "The <acronym>XML</acronym> processor knows that the <acronym>DTD</acronym> is called <filename>transitional.dtd</filename> in the <filename>1.0</filename> subdirectory of the directory that held <filename>catalog</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:2668
	+msgid "Examine the contents of <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>. This is the catalog file for the <acronym>XHTML</acronym> <acronym>DTD</acronym>s that were installed as part of the <package>textproc/docproj</package> port."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:2677
	+msgid "Alternatives to <acronym>FPI</acronym>s"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2679
	+msgid "Instead of using an <acronym>FPI</acronym> to indicate the <acronym>DTD</acronym> to which the document conforms (and therefore, which file on the system contains the <acronym>DTD</acronym>), the filename can be explicitly specified."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2685
	+msgid "The syntax is slightly different:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:2687
	+#, no-wrap
	+msgid "<tag class=\"starttag\">!DOCTYPE html SYSTEM \"/path/to/file.dtd\"</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2689
	+msgid "The <literal>SYSTEM</literal> keyword indicates that the <acronym>XML</acronym> processor should locate the <acronym>DTD</acronym> in a system specific fashion. This typically (but not always) means the <acronym>DTD</acronym> will be provided as a filename."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2695
	+msgid "Using <acronym>FPI</acronym>s is preferred for reasons of portability. If the <literal>SYSTEM</literal> identifier is used, then the <acronym>DTD</acronym> must be provided and kept in the same location for everyone."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:2703
	+msgid "Escaping Back to <acronym>XML</acronym>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2705
	+msgid "Some of the underlying <acronym>XML</acronym> syntax can be useful within documents. For example, comments can be included in the document, and will be ignored by the parser. Comments are entered using <acronym>XML</acronym> syntax. Other uses for <acronym>XML</acronym> syntax will be shown later."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2711
	+msgid ""
	+"<acronym>XML</acronym> sections begin with a <literal><!</literal> tag and end with a <literal>></literal>. These sections contain instructions for the parser rather than elements of the document. Everything between these tags is <acronym>XML</acronym> syntax. The <link linkend=\"xml-primer-doctype-declaration\">DOCTYPE declaration</link> shown earlier is an example of <acronym>XML</acronym> syntax "
	+"included in the document."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:2723
	+msgid "Comments"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2725
	+msgid "Comments are an <acronym>XML</acronym> construct, and are normally only valid inside a <acronym>DTD</acronym>. However, as <xref linkend=\"xml-primer-xml-escape\"/> shows, it is possible to use <acronym>XML</acronym> syntax within the document."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2730
	+msgid "The delimiter for XML comments is the string <quote><literal>--</literal></quote>. The first occurrence of this string opens a comment, and the second closes it."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2735
	+msgid "<acronym>XML</acronym> Generic Comment"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2737
	+#, no-wrap
	+msgid ""
	+"<!-- This is inside the comment -->\n"
	+"\n"
	+"<!-- This is another comment -->\n"
	+"\n"
	+"<!-- This is one way\n"
	+" of doing multiline comments -->\n"
	+"\n"
	+"<!-- This is another way of --\n"
	+" -- doing multiline comments -->"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2748
	+msgid "<acronym>XHTML</acronym> users may be familiar with different rules for comments. In particular, it is often believed that the string <literal><!--</literal> opens a comment, and it is only closed by <literal>--></literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2753
	+msgid "This is <emphasis>not</emphasis> correct. Many web browsers have broken <acronym>XHTML</acronym> parsers, and will accept incorrect input as valid. However, the <acronym>XML</acronym> parsers used by the Documentation Project are more strict, and will reject documents with that error."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2760
	+msgid "Erroneous <acronym>XML</acronym> Comments"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2762
	+#, no-wrap
	+msgid ""
	+"<!-- This is in the comment --\n"
	+"\n"
	+" THIS IS OUTSIDE THE COMMENT!\n"
	+"\n"
	+" -- back inside the comment -->"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:2768
	+msgid "The <acronym>XML</acronym> parser will treat this as though it were actually:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2771
	+#, no-wrap
	+msgid "<!THIS IS OUTSIDE THE COMMENT>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:2773
	+msgid "That is not valid <acronym>XML</acronym>, and may give confusing error messages."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2782
	+msgid "Add some comments to <filename>example.xml</filename>, and check that the file still validates using <command>xmllint</command>."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2788
	+msgid "Add some invalid comments to <filename>example.xml</filename>, and see the error messages that <command>xmllint</command> gives when it encounters an invalid comment."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:2798
	+msgid "Entities"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2800
	+msgid "Entities are a mechanism for assigning names to chunks of content. As an <acronym>XML</acronym> parser processes a document, any entities it finds are replaced by the content of the entity."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2805
	+msgid "This is a good way to have re-usable, easily changeable chunks of content in <acronym>XML</acronym> documents. It is also the only way to include one marked up file inside another using <acronym>XML</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2810
	+msgid "There are two types of entities for two different situations: <emphasis>general entities</emphasis> and <emphasis>parameter entities</emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:2815
	+msgid "General Entities"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2817
	+msgid "General entities are used to assign names to reusable chunks of text. These entities can only be used in the document. They cannot be used in an <acronym>XML</acronym> context."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2822
	+msgid "To include the text of a general entity in the document, include <literal>&<replaceable>entity-name</replaceable>;</literal> in the text. For example, consider a general entity called <literal>current.version</literal> which expands to the current version number of a product. To use it in the document, write:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:2830
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>The current version of our product is\n"
	+" &current.version;.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2833
	+msgid "When the version number changes, edit the definition of the general entity, replacing the value. Then reprocess the document."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2837
	+msgid ""
	+"General entities can also be used to enter characters that could not otherwise be included in an <acronym>XML</acronym> document. For example, <literal><</literal> and <literal>&</literal> cannot normally appear in an <acronym>XML</acronym> document. The <acronym>XML</acronym> parser sees the <literal><</literal> symbol as the start of a tag. Likewise, when the <literal>&</literal> symbol is "
	+"seen, the next text is expected to be an entity name."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2846
	+msgid "These symbols can be included by using two predefined general entities: <literal>&lt;</literal> and <literal>&amp;</literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2850
	+msgid "General entities can only be defined within an <acronym>XML</acronym> context. Such definitions are usually done immediately after the DOCTYPE declaration."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2855
	+msgid "Defining General Entities"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2857
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n"
	+"\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n"
	+"<!ENTITY current.version \"3.0-RELEASE\">\n"
	+"<!ENTITY last.version \"2.2.7-RELEASE\">\n"
	+"]>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:2863
	+msgid "The DOCTYPE declaration has been extended by adding a square bracket at the end of the first line. The two entities are then defined over the next two lines, the square bracket is closed, and then the DOCTYPE declaration is closed."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:2869
	+msgid "The square brackets are necessary to indicate that the DTD indicated by the DOCTYPE declaration is being extended."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:2876
	+msgid "Parameter Entities"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2878
	+msgid "Parameter entities, like <link linkend=\"xml-primer-general-entities\">general entities</link>, are used to assign names to reusable chunks of text. But parameter entities can only be used within an <link linkend=\"xml-primer-xml-escape\">XML context</link>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2885
	+msgid "Parameter entity definitions are similar to those for general entities. However, parameter entries are included with <literal>%<replaceable>entity-name</replaceable>;</literal>. The definition also includes the <literal>%</literal> between the <literal>ENTITY</literal> keyword and the name of the entity."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:2893
	+msgid "For a mnemonic, think <quote><emphasis>P</emphasis>arameter entities use the <emphasis>P</emphasis>ercent symbol</quote>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:2898
	+msgid "Defining Parameter Entities"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:2900
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n"
	+"\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n"
	+"<!ENTITY % param.some \"some\">\n"
	+"<!ENTITY % param.text \"text\">\n"
	+"<!ENTITY % param.new \"%param.some more %param.text\">\n"
	+"\n"
	+"<!-- %param.new now contains \"some more text\" -->\n"
	+"]>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2916
	+msgid "Add a general entity to <filename>example.xml</filename>."
	+msgstr ""
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:2919
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n"
	+"\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n"
	+"<!ENTITY version \"1.1\">\n"
	+"]>\n"
	+"\n"
	+"<tag class=\"starttag\">html xmlns=\"http://www.w3.org/1999/xhtml\"</tag>\n"
	+" <tag class=\"starttag\">head</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example XHTML File<tag class=\"endtag\">title</tag>\n"
	+" <tag class=\"endtag\">head</tag>\n"
	+"\n"
	+" <!-- There may be some comments in here as well -->\n"
	+"\n"
	+" <tag class=\"starttag\">body</tag>\n"
	+" <tag class=\"starttag\">p</tag>This is a paragraph containing some text.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p</tag>This paragraph contains some more text.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p align=\"right\"</tag>This paragraph might be right-justified.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p</tag>The current version of this document is: &version;<tag class=\"endtag\">p</tag>\n"
	+" <tag class=\"endtag\">body</tag>\n"
	+"<tag class=\"endtag\">html</tag>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2944
	+msgid "Validate the document using <command>xmllint</command>."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2949
	+msgid "Load <filename>example.xml</filename> into a web browser. It may have to be copied to <filename>example.html</filename> before the browser recognizes it as an <acronym>XHTML</acronym> document."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2955
	+msgid "Older browsers with simple parsers may not render this file as expected. The entity reference <literal>&version;</literal> may not be replaced by the version number, or the <acronym>XML</acronym> context closing <literal>]></literal> may not be recognized and instead shown in the output."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2964
	+msgid "The solution is to <emphasis>normalize</emphasis> the document with an <acronym>XML</acronym> normalizer. The normalizer reads valid <acronym>XML</acronym> and writes equally valid <acronym>XML</acronym> which has been transformed in some way. One way the normalizer transforms the input is by expanding all the entity references in the document, replacing the entities with the text that they represent."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2973
	+msgid "<command>xmllint</command> can be used for this. It also has an option to drop the initial <acronym>DTD</acronym> section so that the closing <literal>]></literal> does not confuse browsers:"
	+msgstr ""
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:2978
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:2980
	+msgid "A normalized copy of the document with entities expanded is produced in <filename>example.html</filename>, ready to load into a web browser."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:2989
	+msgid "Using Entities to Include Files"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:2991
	+msgid "Both <link linkend=\"xml-primer-general-entities\">general</link> and <link linkend=\"xml-primer-parameter-entities\">parameter</link> entities are particularly useful for including one file inside another."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#. (itstool) path: example/title
	+#: book.translate.xml:2998 book.translate.xml:3014
	+msgid "Using General Entities to Include Files"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3000
	+msgid "Consider some content for an <acronym>XML</acronym> book organized into files, one file per chapter, called <filename>chapter1.xml</filename>, <filename>chapter2.xml</filename>, and so forth, with a <filename>book.xml</filename> that will contain these chapters."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3007
	+msgid "In order to use the contents of these files as the values for entities, they are declared with the <literal>SYSTEM</literal> keyword. This directs the <acronym>XML</acronym> parser to include the contents of the named file as the value of the entity."
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3016
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n"
	+"\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n"
	+"<!ENTITY chapter.1 SYSTEM \"chapter1.xml\">\n"
	+"<!ENTITY chapter.2 SYSTEM \"chapter2.xml\">\n"
	+"<!ENTITY chapter.3 SYSTEM \"chapter3.xml\">\n"
	+"<!-- And so forth -->\n"
	+"]>\n"
	+"\n"
	+"<tag class=\"starttag\">html xmlns=\"http://www.w3.org/1999/xhtml\"</tag>\n"
	+" <!-- Use the entities to load in the chapters -->\n"
	+"\n"
	+" &chapter.1;\n"
	+" &chapter.2;\n"
	+" &chapter.3;\n"
	+"<tag class=\"endtag\">html</tag>"
	+msgstr ""
	+
	+#. (itstool) path: warning/para
	+#: book.translate.xml:3034
	+msgid "When using general entities to include other files within a document, the files being included (<filename>chapter1.xml</filename>, <filename>chapter2.xml</filename>, and so on) <emphasis>must not</emphasis> start with a DOCTYPE declaration. This is a syntax error because entities are low-level constructs and they are resolved before any parsing happens."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#. (itstool) path: example/title
	+#: book.translate.xml:3046 book.translate.xml:3065
	+msgid "Using Parameter Entities to Include Files"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3048
	+msgid "Parameter entities can only be used inside an <acronym>XML</acronym> context. Including a file in an <acronym>XML</acronym> context can be used to ensure that general entities are reusable."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3053
	+msgid "Suppose that there are many chapters in the document, and these chapters were reused in two different books, each book organizing the chapters in a different fashion."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3057
	+msgid "The entities could be listed at the top of each book, but that quickly becomes cumbersome to manage."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3060
	+msgid "Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within the document."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:3067
	+msgid "Place the entity definitions in a separate file called <filename>chapters.ent</filename> and containing this text:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3071
	+#, no-wrap
	+msgid ""
	+"<!ENTITY chapter.1 SYSTEM \"chapter1.xml\">\n"
	+"<!ENTITY chapter.2 SYSTEM \"chapter2.xml\">\n"
	+"<!ENTITY chapter.3 SYSTEM \"chapter3.xml\">"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:3075
	+msgid "Create a parameter entity to refer to the contents of the file. Then use the parameter entity to load the file into the document, which will then make all the general entities available for use. Then use the general entities as before:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3081
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n"
	+"\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n"
	+"<!-- Define a parameter entity to load in the chapter general entities -->\n"
	+"<!ENTITY % chapters SYSTEM \"chapters.ent\">\n"
	+"\n"
	+"<!-- Now use the parameter entity to load in this file -->\n"
	+"%chapters;\n"
	+"]>\n"
	+"\n"
	+"<tag class=\"starttag\">html xmlns=\"http://www.w3.org/1999/xhtml\"</tag>\n"
	+" &chapter.1;\n"
	+" &chapter.2;\n"
	+" &chapter.3;\n"
	+"<tag class=\"endtag\">html</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:3102
	+msgid "Use General Entities to Include Files"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3106
	+msgid "Create three files, <filename>para1.xml</filename>, <filename>para2.xml</filename>, and <filename>para3.xml</filename>."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3110
	+msgid "Put content like this in each file:"
	+msgstr ""
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:3112
	+#, no-wrap
	+msgid "<tag class=\"starttag\">p</tag>This is the first paragraph.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3116 book.translate.xml:3169
	+msgid "Edit <filename>example.xml</filename> so that it looks like this:"
	+msgstr ""
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:3119
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n"
	+"\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n"
	+"<!ENTITY version \"1.1\">\n"
	+"<!ENTITY para1 SYSTEM \"para1.xml\">\n"
	+"<!ENTITY para2 SYSTEM \"para2.xml\">\n"
	+"<!ENTITY para3 SYSTEM \"para3.xml\">\n"
	+"]>\n"
	+"\n"
	+"<tag class=\"starttag\">html xmlns=\"http://www.w3.org/1999/xhtml\"</tag>\n"
	+" <tag class=\"starttag\">head</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example XHTML File<tag class=\"endtag\">title</tag>\n"
	+" <tag class=\"endtag\">head</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">body</tag>\n"
	+" <tag class=\"starttag\">p</tag>The current version of this document is: &version;<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" &para1;\n"
	+" &para2;\n"
	+" &para3;\n"
	+" <tag class=\"endtag\">body</tag>\n"
	+"<tag class=\"endtag\">html</tag>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3143 book.translate.xml:3204
	+msgid "Produce <filename>example.html</filename> by normalizing <filename>example.xml</filename>."
	+msgstr ""
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:3146 book.translate.xml:3207
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3150 book.translate.xml:3211
	+msgid "Load <filename>example.html</filename> into the web browser and confirm that the <filename>para<replaceable>n</replaceable>.xml</filename> files have been included in <filename>example.html</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:3160
	+msgid "Use Parameter Entities to Include Files"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:3163
	+msgid "The previous steps must have completed before this step."
	+msgstr ""
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:3172
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n"
	+"\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n"
	+"<!ENTITY % entities SYSTEM \"entities.ent\"> %entities;\n"
	+"]>\n"
	+"\n"
	+"<tag class=\"starttag\">html xmlns=\"http://www.w3.org/1999/xhtml\"</tag>\n"
	+" <tag class=\"starttag\">head</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example XHTML File<tag class=\"endtag\">title</tag>\n"
	+" <tag class=\"endtag\">head</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">body</tag>\n"
	+" <tag class=\"starttag\">p</tag>The current version of this document is: &version;<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" &para1;\n"
	+" &para2;\n"
	+" &para3;\n"
	+" <tag class=\"endtag\">body</tag>\n"
	+"<tag class=\"endtag\">html</tag>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3193
	+msgid "Create a new file called <filename>entities.ent</filename> with this content:"
	+msgstr ""
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:3197
	+#, no-wrap
	+msgid ""
	+"<!ENTITY version \"1.1\">\n"
	+"<!ENTITY para1 SYSTEM \"para1.xml\">\n"
	+"<!ENTITY para2 SYSTEM \"para2.xml\">\n"
	+"<!ENTITY para3 SYSTEM \"para3.xml\">"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3223
	+msgid "Marked Sections"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3225
	+msgid "<acronym>XML</acronym> provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are called <quote>marked sections</quote>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3231
	+msgid "Structure of a Marked Section"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3233
	+#, no-wrap
	+msgid ""
	+"<![<replaceable>KEYWORD</replaceable>[\n"
	+" Contents of marked section\n"
	+"]]>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3238
	+msgid "As expected of an <acronym>XML</acronym> construct, a marked section starts with <literal><!</literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3241
	+msgid "The first square bracket begins the marked section."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3243
	+msgid "<replaceable>KEYWORD</replaceable> describes how this marked section is to be processed by the parser."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3246
	+msgid "The second square bracket indicates the start of the marked section's content."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3249
	+msgid "The marked section is finished by closing the two square brackets, and then returning to the document context from the <acronym>XML</acronym> context with <literal>></literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3255
	+msgid "Marked Section Keywords"
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:3258
	+msgid "<literal>CDATA</literal>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3260
	+msgid "These keywords denote the marked sections <emphasis>content model</emphasis>, and allow you to change it from the default."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3264
	+msgid "When an <acronym>XML</acronym> parser is processing a document, it keeps track of the <quote>content model</quote>."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3268
	+msgid "The content model describes the content the parser is expecting to see and what it will do with that content."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3272
	+msgid "The <literal>CDATA</literal> content model is one of the most useful."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3275
	+msgid "<literal>CDATA</literal> is for <quote>Character Data</quote>. When the parser is in this content model, it expects to see only characters. In this model the <literal><</literal> and <literal>&</literal> symbols lose their special status, and will be treated as ordinary characters."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:3283
	+msgid "When using <literal>CDATA</literal> in examples of text marked up in <acronym>XML</acronym>, remember that the content of <literal>CDATA</literal> is not validated. The included text must be check with other means. For example, the content could be written in another document, validated, and then pasted into the <literal>CDATA</literal> section."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3293
	+msgid "Using a <literal>CDATA</literal> Marked Section"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3296
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Here is an example of how to include some text that contains\n"
	+" many <tag class=\"starttag\">literal</tag>&lt;<tag class=\"endtag\">literal</tag> and <tag class=\"starttag\">literal</tag>&amp;<tag class=\"endtag\">literal</tag>\n"
	+" symbols. The sample text is a fragment of\n"
	+" <tag class=\"starttag\">acronym</tag>XHTML<tag class=\"endtag\">acronym</tag>. The surrounding text (<tag class=\"starttag\">para</tag> and\n"
	+" <tag class=\"starttag\">programlisting</tag>) are from DocBook.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">programlisting</tag><![CDATA[<tag class=\"starttag\">p</tag>This is a sample that shows some of the\n"
	+" elements within <tag class=\"starttag\">acronym</tag>XHTML<tag class=\"endtag\">acronym</tag>. Since the angle\n"
	+" brackets are used so many times, it is simpler to say the whole\n"
	+" example is a CDATA marked section than to use the entity names for\n"
	+" the left and right angle brackets throughout.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">ul</tag>\n"
	+" <tag class=\"starttag\">li</tag>This is a listitem<tag class=\"endtag\">li</tag>\n"
	+" <tag class=\"starttag\">li</tag>This is a second listitem<tag class=\"endtag\">li</tag>\n"
	+" <tag class=\"starttag\">li</tag>This is a third listitem<tag class=\"endtag\">li</tag>\n"
	+" <tag class=\"endtag\">ul</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p</tag>This is the end of the example.<tag class=\"endtag\">p</tag>]]><tag class=\"endtag\">programlisting</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:3319
	+msgid "<literal>INCLUDE</literal> and <literal>IGNORE</literal>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3322
	+msgid "When the keyword is <literal>INCLUDE</literal>, then the contents of the marked section will be processed. When the keyword is <literal>IGNORE</literal>, the marked section is ignored and will not be processed. It will not appear in the output."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3329
	+msgid "Using <literal>INCLUDE</literal> and <literal>IGNORE</literal> in Marked Sections"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3332
	+#, no-wrap
	+msgid ""
	+"<![INCLUDE[\n"
	+" This text will be processed and included.\n"
	+"]]>\n"
	+"\n"
	+"<![IGNORE[\n"
	+" This text will not be processed or included.\n"
	+"]]>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3341
	+msgid "By itself, this is not too useful. Text to be removed from the document could be cut out, or wrapped in comments."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3345
	+msgid "It becomes more useful when controlled by <link linkend=\"xml-primer-parameter-entities\">parameter entities</link>, yet this usage is limited to entity files."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3350
	+msgid "For example, suppose that documentation was produced in a hard-copy version and an electronic version. Some extra text is desired in the electronic version content that was not to appear in the hard-copy."
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3355
	+msgid ""
	+"Create an entity file that defines general entities to include each chapter and guard these definitions with a parameter entity that can be set to either <literal>INCLUDE</literal> or <literal>IGNORE</literal> to control whether the entity is defined. After these conditional general entity definitions, place one more definition for each general entity to set them to an empty value. This technique makes use of "
	+"the fact that entity definitions cannot be overridden but the first definition always takes effect. So the inclusion of the chapter is controlled with the corresponding parameter entity. Set to <literal>INCLUDE</literal>, the first general entity definition will be read and the second one will be ignored. Set to <literal>IGNORE</literal>, the first definition will be ignored and the second one will take "
	+"effect."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3372
	+msgid "Using a Parameter Entity to Control a Marked Section"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3375
	+#, no-wrap
	+msgid ""
	+"<!ENTITY % electronic.copy \"INCLUDE\">\n"
	+"\n"
	+"<![%electronic.copy;[\n"
	+"<!ENTITY chap.preface\tSYSTEM \"preface.xml\">\n"
	+"]]>\n"
	+"\n"
	+"<!ENTITY chap.preface \"\">"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:3383
	+msgid "When producing the hard-copy version, change the parameter entity's definition to:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3386
	+#, no-wrap
	+msgid "<!ENTITY % electronic.copy \"IGNORE\">"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3396
	+msgid "Modify <filename>entities.ent</filename> to contain the following:"
	+msgstr ""
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:3399
	+#, no-wrap
	+msgid ""
	+"<!ENTITY version \"1.1\">\n"
	+"<!ENTITY % conditional.text \"IGNORE\">\n"
	+"\n"
	+"<![%conditional.text;[\n"
	+"<!ENTITY para1 SYSTEM \"para1.xml\">\n"
	+"]]>\n"
	+"\n"
	+"<!ENTITY para1 \"\">\n"
	+"\n"
	+"<!ENTITY para2 SYSTEM \"para2.xml\">\n"
	+"<!ENTITY para3 SYSTEM \"para3.xml\">"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:3413
	+msgid "Normalize <filename>example.xml</filename> and notice that the conditional text is not present in the output document. Set the parameter entity guard to <literal>INCLUDE</literal> and regenerate the normalized document and the text will appear again. This method makes sense if there are more conditional chunks depending on the same condition. For example, to control generating printed or online text."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3428
	+msgid "Conclusion"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3430
	+msgid "That is the conclusion of this <acronym>XML</acronym> primer. For reasons of space and complexity, several things have not been covered in depth (or at all). However, the previous sections cover enough <acronym>XML</acronym> to introduce the organization of the <acronym>FDP</acronym> documentation."
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:3472
	+msgid "<acronym>XHTML</acronym> Markup"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3475 book.translate.xml:4078 book.translate.xml:7325
	+msgid "Introduction"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3477
	+msgid "This chapter describes usage of the <acronym>XHTML</acronym> markup language used for the FreeBSD web site."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3480
	+msgid "<acronym>XHTML</acronym> is the <acronym>XML</acronym> version of the HyperText Markup Language, the markup language of choice on the World Wide Web. More information can be found at <uri xlink:href=\"http://www.w3.org/\">http://www.w3.org/</uri>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3485
	+msgid "<acronym>XHTML</acronym> is used to mark up pages on the FreeBSD web site. It is usually not used to mark up other documentation, since DocBook offers a far richer set of elements from which to choose. Consequently, <acronym>XHTML</acronym> pages will normally only be encountered when writing for the web site."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3492
	+msgid "<acronym>HTML</acronym> has gone through a number of versions. The <acronym>XML</acronym>-compliant version described here is called <acronym>XHTML</acronym>. The latest widespread version is <acronym>XHTML</acronym> 1.0, available in both <emphasis>strict</emphasis> and <emphasis>transitional</emphasis> variants."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3499
	+msgid "The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are available from the Ports Collection in <package>textproc/xhtml</package>. They are automatically installed by the <package>textproc/docproj</package> port."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:3505
	+msgid "This is <emphasis>not</emphasis> an exhaustive list of elements, since that would just repeat the documentation for <acronym>XHTML</acronym>. The aim is to list those elements most commonly used. Please post questions about elements or uses not covered here to the <link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project mailing list</link>."
	+msgstr ""
	+
	+#. (itstool) path: note/title
	+#: book.translate.xml:3513 book.translate.xml:4117
	+msgid "Inline Versus Block"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:3515 book.translate.xml:4119
	+msgid "In the remainder of this document, when describing elements, <emphasis>inline</emphasis> means that the element can occur within a block element, and does not cause a line break. A <emphasis>block</emphasis> element, by comparison, will cause a line break (and other processing) when it is encountered."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3525
	+msgid "Formal Public Identifier (<acronym>FPI</acronym>)"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3527
	+msgid "There are a number of <acronym>XHTML</acronym> <acronym>FPI</acronym>s, depending upon the version, or <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which a document conforms. Most <acronym>XHTML</acronym> documents on the FreeBSD web site comply with the transitional version of <acronym>XHTML</acronym> 1.0."
	+msgstr ""
	+
	+#. (itstool) path: sect1/programlisting
	+#: book.translate.xml:3534
	+#, no-wrap
	+msgid "PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\""
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3538
	+msgid "Sectional Elements"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3540
	+msgid "An <acronym>XHTML</acronym> document is normally split into two sections. The first section, called the <emphasis>head</emphasis>, contains meta-information about the document, such as its title, the name of the author, the parent document, and so on. The second section, the <emphasis>body</emphasis>, contains content that will be displayed to the user."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:3548
	+msgid "These sections are indicated with <tag>head</tag> and <tag>body</tag> elements respectively. These elements are contained within the top-level <tag>html</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3554
	+msgid "Normal <acronym>XHTML</acronym> Document Structure"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3557
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">html xmlns=\"http://www.w3.org/1999/xhtml\"</tag>\n"
	+" <tag class=\"starttag\">head</tag>\n"
	+"\t <tag class=\"starttag\">title</tag><replaceable>The Document's Title</replaceable><tag class=\"endtag\">title</tag>\n"
	+" <tag class=\"endtag\">head</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">body</tag>\n"
	+"\n"
	+" …\n"
	+"\n"
	+" <tag class=\"endtag\">body</tag>\n"
	+"<tag class=\"endtag\">html</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3572 book.translate.xml:4717
	+msgid "Block Elements"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3575
	+msgid "Headings"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3577
	+msgid "<acronym>XHTML</acronym> has tags to denote headings in the document at up to six different levels."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3580
	+msgid "The largest and most prominent heading is <tag>h1</tag>, then <tag>h2</tag>, continuing down to <tag>h6</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3584
	+msgid "The element's content is the text of the heading."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3587
	+msgid "<tag>h1</tag>, <tag>h2</tag>, and Other Header Tags"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:3590 book.translate.xml:3625 book.translate.xml:3641 book.translate.xml:3686 book.translate.xml:3718 book.translate.xml:3795 book.translate.xml:3823 book.translate.xml:3845 book.translate.xml:3867 book.translate.xml:3923 book.translate.xml:3940 book.translate.xml:3970 book.translate.xml:3995 book.translate.xml:4736 book.translate.xml:4762 book.translate.xml:4843 book.translate.xml:4877
	+#: book.translate.xml:4924 book.translate.xml:4984 book.translate.xml:5046 book.translate.xml:5126 book.translate.xml:5260 book.translate.xml:5421 book.translate.xml:5480 book.translate.xml:5507 book.translate.xml:5537 book.translate.xml:5576 book.translate.xml:5684 book.translate.xml:5741 book.translate.xml:5792 book.translate.xml:5911 book.translate.xml:5979 book.translate.xml:6008 book.translate.xml:6029
	+#: book.translate.xml:6071 book.translate.xml:6126 book.translate.xml:6159 book.translate.xml:6176 book.translate.xml:6210 book.translate.xml:6234 book.translate.xml:6714 book.translate.xml:6730
	+msgid "Usage:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3592
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">h1</tag>First section<tag class=\"endtag\">h1</tag>\n"
	+"\n"
	+"<!-- Document introduction goes here -->\n"
	+"\n"
	+"<tag class=\"starttag\">h2</tag>This is the heading for the first section<tag class=\"endtag\">h2</tag>\n"
	+"\n"
	+"<!-- Content for the first section goes here -->\n"
	+"\n"
	+"<tag class=\"starttag\">h3</tag>This is the heading for the first sub-section<tag class=\"endtag\">h3</tag>\n"
	+"\n"
	+"<!-- Content for the first sub-section goes here -->\n"
	+"\n"
	+"<tag class=\"starttag\">h2</tag>This is the heading for the second section<tag class=\"endtag\">h2</tag>\n"
	+"\n"
	+"<!-- Content for the second section goes here -->"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3609
	+msgid "Generally, an <acronym>XHTML</acronym> page should have one first level heading (<tag>h1</tag>). This can contain many second level headings (<tag>h2</tag>), which can in turn contain many third level headings. Do not leave gaps in the numbering."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3617 book.translate.xml:4720
	+msgid "Paragraphs"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3619
	+msgid "<acronym>XHTML</acronym> supports a single paragraph element, <tag>p</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3623
	+msgid "<tag>p</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3627
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>This is a paragraph. It can contain just about any\n"
	+" other element.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3633 book.translate.xml:4749
	+msgid "Block Quotations"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3635
	+msgid "A block quotation is an extended quotation from another document that will appear in a separate paragraph."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3639 book.translate.xml:4760
	+msgid "<tag>blockquote</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3643
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>A small excerpt from the US Constitution:<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">blockquote</tag>We the People of the United States, in Order to form\n"
	+" a more perfect Union, establish Justice, insure domestic\n"
	+" Tranquility, provide for the common defence, promote the general\n"
	+" Welfare, and secure the Blessings of Liberty to ourselves and our\n"
	+" Posterity, do ordain and establish this Constitution for the\n"
	+" United States of America.<tag class=\"endtag\">blockquote</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3655
	+msgid "Lists"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3657
	+msgid "<acronym>XHTML</acronym> can present the user with three types of lists: ordered, unordered, and definition."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3660
	+msgid "Entries in an ordered list will be numbered, while entries in an unordered list will be preceded by bullet points. Definition lists have two sections for each entry. The first section is the term being defined, and the second section is the definition."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3666
	+msgid "Ordered lists are indicated by the <tag>ol</tag> element, unordered lists by the <tag>ul</tag> element, and definition lists by the <tag>dl</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3671
	+msgid "Ordered and unordered lists contain listitems, indicated by the <tag>li</tag> element. A listitem can contain textual content, or it may be further wrapped in one or more <tag>p</tag> elements."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3676
	+msgid "Definition lists contain definition terms (<tag>dt</tag>) and definition descriptions (<tag>dd</tag>). A definition term can only contain inline elements. A definition description can contain other block elements."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3683
	+msgid "<tag>ul</tag> and <tag>ol</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3688
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>An unordered list. Listitems will probably be\n"
	+" preceded by bullets.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">ul</tag>\n"
	+" <tag class=\"starttag\">li</tag>First item<tag class=\"endtag\">li</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">li</tag>Second item<tag class=\"endtag\">li</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">li</tag>Third item<tag class=\"endtag\">li</tag>\n"
	+"<tag class=\"endtag\">ul</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">p</tag>An ordered list, with list items consisting of multiple\n"
	+" paragraphs. Each item (note: not each paragraph) will be\n"
	+" numbered.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">ol</tag>\n"
	+" <tag class=\"starttag\">li</tag><tag class=\"starttag\">p</tag>This is the first item. It only has one paragraph.<tag class=\"endtag\">p</tag><tag class=\"endtag\">li</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">li</tag><tag class=\"starttag\">p</tag>This is the first paragraph of the second item.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p</tag>This is the second paragraph of the second item.<tag class=\"endtag\">p</tag><tag class=\"endtag\">li</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">li</tag><tag class=\"starttag\">p</tag>This is the first and only paragraph of the third\n"
	+" item.<tag class=\"endtag\">p</tag><tag class=\"endtag\">li</tag>\n"
	+"<tag class=\"endtag\">ol</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3716
	+msgid "Definition Lists with <tag>dl</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3720
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">dl</tag>\n"
	+" <tag class=\"starttag\">dt</tag>Term 1<tag class=\"endtag\">dt</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">dd</tag><tag class=\"starttag\">p</tag>Paragraph 1 of definition 1.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">p</tag>Paragraph 2 of definition 1.<tag class=\"endtag\">p</tag><tag class=\"endtag\">dd</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">dt</tag>Term 2<tag class=\"endtag\">dt</tag>\n"
	+"\n"
	+" <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>\n"
	+"\n"
	+" <tag class=\"starttag\">dt</tag>Term 3<tag class=\"endtag\">dt</tag>\n"
	+"\n"
	+" <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>\n"
	+"<tag class=\"endtag\">dl</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3739
	+msgid "Pre-formatted Text"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3741
	+msgid "Pre-formatted text is shown to the user exactly as it is in the file. Text is shown in a fixed font. Multiple spaces and line breaks are shown exactly as they are in the file."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3746
	+msgid "Wrap pre-formatted text in the <tag>pre</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3750
	+msgid "<tag>pre</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:3752
	+msgid "For example, the <tag>pre</tag> tags could be used to mark up an email message:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3755
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">pre</tag> From: nik@FreeBSD.org\n"
	+" To: freebsd-doc@FreeBSD.org\n"
	+" Subject: New documentation available\n"
	+"\n"
	+" There is a new copy of my primer for contributors to the FreeBSD\n"
	+" Documentation Project available at\n"
	+"\n"
	+" &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;\n"
	+"\n"
	+" Comments appreciated.\n"
	+"\n"
	+" N<tag class=\"endtag\">pre</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:3768
	+msgid ""
	+"Keep in mind that <literal><</literal> and <literal>&</literal> still are recognized as special characters in pre-formatted text. This is why the example shown had to use <literal>&lt;</literal> instead of <literal><</literal>. For consistency, <literal>&gt;</literal> was used in place of <literal>></literal>, too. Watch out for the special characters that may appear in text copied from a "
	+"plain-text source, like an email message or program code."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3781 book.translate.xml:5233
	+msgid "Tables"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3783
	+msgid ""
	+"Mark up tabular information using the <tag>table</tag> element. A table consists of one or more table rows (<tag>tr</tag>), each containing one or more cells of table data (<tag>td</tag>). Each cell can contain other block elements, such as paragraphs or lists. It can also contain another table (this nesting can repeat indefinitely). If the cell only contains one paragraph then the <tag>p</tag>element is not "
	+"needed."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3793
	+msgid "Simple Use of <tag>table</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3797
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>This is a simple 2x2 table.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">table</tag>\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td</tag>Top left cell<tag class=\"endtag\">td</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Top right cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td</tag>Bottom left cell<tag class=\"endtag\">td</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Bottom right cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"<tag class=\"endtag\">table</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3814
	+msgid "A cell can span multiple rows and columns by adding the <tag class=\"attribute\">rowspan</tag> or <tag class=\"attribute\">colspan</tag> attributes with values for the number of rows or columns to be spanned."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3820
	+msgid "Using <tag class=\"attribute\">rowspan</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3825
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>One tall thin cell on the left, two short cells next to\n"
	+" it on the right.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">table</tag>\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td rowspan=\"2\"</tag>Long and thin<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td</tag>Top cell<tag class=\"endtag\">td</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Bottom cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"<tag class=\"endtag\">table</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3842
	+msgid "Using <tag class=\"attribute\">colspan</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3847
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>One long cell on top, two short cells below it.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">table</tag>\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td colspan=\"2\"</tag>Top cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td</tag>Bottom left cell<tag class=\"endtag\">td</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Bottom right cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"<tag class=\"endtag\">table</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3863
	+msgid "Using <tag class=\"attribute\">rowspan</tag> and <tag class=\"attribute\">colspan</tag> Together"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3869
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>On a 3x3 grid, the top left block is a 2x2 set of\n"
	+" cells merged into one. The other cells are normal.<tag class=\"endtag\">p</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">table</tag>\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td colspan=\"2\" rowspan=\"2\"</tag>Top left large cell<tag class=\"endtag\">td</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Top right cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <!-- Because the large cell on the left merges into\n"
	+" this row, the first <td> will occur on its\n"
	+" right -->\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Middle right cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">tr</tag>\n"
	+" <tag class=\"starttag\">td</tag>Bottom left cell<tag class=\"endtag\">td</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Bottom middle cell<tag class=\"endtag\">td</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">td</tag>Bottom right cell<tag class=\"endtag\">td</tag>\n"
	+" <tag class=\"endtag\">tr</tag>\n"
	+"<tag class=\"endtag\">table</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3900 book.translate.xml:5459
	+msgid "In-line Elements"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3903 book.translate.xml:5462
	+msgid "Emphasizing Information"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3905
	+msgid "Two levels of emphasis are available in <acronym>XHTML</acronym>, <tag>em</tag> and <tag>strong</tag>. <tag>em</tag> is for a normal level of emphasis and <tag>strong</tag> indicates stronger emphasis."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3911
	+msgid "<tag>em</tag> is typically rendered in italic and <tag>strong</tag> is rendered in bold. This is not always the case, and should not be relied upon. According to best practices, web pages only hold structural and semantical information, and stylesheets are later applied to them. Think of semantics, not formatting, when using these tags."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3920
	+msgid "<tag>em</tag> and <tag>strong</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3925
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag><tag class=\"starttag\">em</tag>This<tag class=\"endtag\">em</tag> has been emphasized, while\n"
	+" <tag class=\"starttag\">strong</tag>this<tag class=\"endtag\">strong</tag> has been strongly emphasized.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3931
	+msgid "Indicating Fixed-Pitch Text"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:3933
	+msgid "Content that should be rendered in a fixed pitch (typewriter) typeface is tagged with <tag>tt</tag> (for <quote>teletype</quote>)."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3938
	+msgid "<tag>tt</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3942
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>Many system settings are stored in\n"
	+" <tag class=\"starttag\">tt</tag>/etc<tag class=\"endtag\">tt</tag>.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:3948 book.translate.xml:6552
	+msgid "Links"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:3951
	+msgid "Links are also inline elements."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:3955 book.translate.xml:6647
	+msgid "Linking to Other Documents on the Web"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3957
	+msgid "A link points to the <acronym>URL</acronym> of a document on the web. The link is indicated with <tag>a</tag>, and the <tag class=\"attribute\">href</tag> attribute contains the <acronym>URL</acronym> of the target document. The content of the element becomes the link, indicated to the user by showing it in a different color or with an underline."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3967
	+msgid "Using <tag class=\"starttag\">a href=\"...\"</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3972
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>More information is available at the\n"
	+" <tag class=\"starttag\">a href=\"http://www.&os;.org/\"</tag>&os; web site<tag class=\"endtag\">a</tag>.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3976
	+msgid "This link always takes the user to the top of the linked document."
	+msgstr ""
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:3981
	+msgid "Linking to Specific Parts of Documents"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:3983
	+msgid "To link to a specific point within a document, that document must include an <emphasis>anchor</emphasis> at the desired point. Anchors are included by setting the <tag class=\"attribute\">id</tag> attribute of an element to a name. This example creates an anchor by setting the <tag class=\"attribute\">id</tag> attribute of a <tag class=\"element\">p</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:3993
	+msgid "Creating an Anchor"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:3997
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p id=\"samplepara\"</tag>This paragraph can be referenced\n"
	+" in other links with the name <tag class=\"starttag\">tt</tag>samplepara<tag class=\"endtag\">tt</tag>.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:4001
	+msgid "Links to anchors are similar to plain links, but include a <literal>#</literal> symbol and the anchor's <acronym>ID</acronym> at the end of the <acronym>URL</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4007
	+msgid "Linking to a Named Part of a Different Document"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:4010
	+msgid "The <literal>samplepara</literal> example is part of a document called <filename>foo.html</filename>. A link to that specific paragraph in the document is constructed in this example."
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4015
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>More information can be found in the\n"
	+" <tag class=\"starttag\">a href=\"foo.html#samplepara\"</tag>sample paragraph<tag class=\"endtag\">a</tag> of\n"
	+" <tag class=\"starttag\">tt</tag>foo.html<tag class=\"endtag\">tt</tag>.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:4020
	+msgid "To link to a named anchor within the same document, omit the document's <acronym>URL</acronym>, and just use the <literal>#</literal> symbol followed by the name of the anchor."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4026
	+msgid "Linking to a Named Part of the Same Document"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:4028
	+msgid "The <literal>samplepara</literal> example resides in this document. To link to it:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4031
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">p</tag>More information can be found in the\n"
	+" <tag class=\"starttag\">a href=\"#samplepara\"</tag>sample paragraph<tag class=\"endtag\">a</tag> of this\n"
	+" document.<tag class=\"endtag\">p</tag>"
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:4075
	+msgid "DocBook Markup"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4080
	+msgid ""
	+"This chapter is an introduction to DocBook as it is used for FreeBSD documentation. DocBook is a large and complex markup system, but the subset described here covers the parts that are most widely used for FreeBSD documentation. While a moderate subset is covered, it is impossible to anticipate every 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>."
	+msgstr ""
	+
	+#. (itstool) path: footnote/para
	+#: book.translate.xml:4091
	+msgid "A short history can be found under <link xlink:href=\"http://www.oasis-open.org/docbook/intro.shtml#d0e41\">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4088
	+msgid ""
	+"DocBook was originally developed by HaL Computer Systems and O'Reilly & Associates to be a Document Type Definition (<acronym>DTD</acronym>) for writing technical documentation <_:footnote-1/>. Since 1998 it is maintained by the <link xlink:href=\"http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook\"> DocBook Technical Committee</link>. As such, and unlike LinuxDoc and <acronym>XHTML</"
	+"acronym>, DocBook is very heavily oriented towards markup that describes <emphasis>what</emphasis> something is, rather than describing <emphasis>how</emphasis> it should be presented."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4099
	+msgid "The DocBook <acronym>DTD</acronym> is available from the Ports Collection in the <package>textproc/docbook-xml</package> port. It is automatically installed as part of the <package>textproc/docproj</package> port."
	+msgstr ""
	+
	+#. (itstool) path: note/title
	+#: book.translate.xml:4107
	+msgid "Formal Versus Informal"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:4109
	+msgid "Some elements may exist in two forms, <emphasis>formal</emphasis> and <emphasis>informal</emphasis>. Typically, the formal version of the element will consist of a title followed by the informal version of the element. The informal version will not have a title."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:4129
	+msgid "FreeBSD Extensions"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4131
	+msgid "The FreeBSD Documentation Project has extended the DocBook <acronym>DTD</acronym> with additional elements and entities. These additions serve to make some of the markup easier or more precise."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4136
	+msgid "Throughout the rest of this document, the term <quote>DocBook</quote> is used to mean the FreeBSD-extended DocBook <acronym>DTD</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:4141
	+msgid "Most of these extensions are not unique to FreeBSD, it was just felt that they were useful enhancements for this particular project. Should anyone from any of the other *nix camps (NetBSD, OpenBSD, Linux, …) be interested in collaborating on a standard DocBook extension set, please contact Documentation Engineering Team <email>doceng@FreeBSD.org</email>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4150
	+msgid "FreeBSD Elements"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4152
	+msgid "The additional FreeBSD elements are not (currently) in the 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>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4156
	+msgid "FreeBSD-specific elements used in the examples below are clearly marked."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4161
	+msgid "FreeBSD Entities"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4163
	+msgid "This table shows some of the most useful entities available in the <acronym>FDP</acronym>. For a complete list, see the <filename>*.ent</filename> files in <filename>doc/share/xml</filename>."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4183
	+msgid "<emphasis>FreeBSD Name Entities</emphasis>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4188
	+msgid "<literal>&os;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4189
	+msgid "<literal>FreeBSD</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4194
	+msgid "<literal>&os.stable;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4195
	+msgid "<literal>FreeBSD-STABLE</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4200
	+msgid "<literal>&os.current;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4201
	+msgid "<literal>FreeBSD-CURRENT</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4212
	+msgid "Manual Page Entities"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4217
	+msgid "<literal>&man.ls.1;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4218
	+msgid "<citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4219
	+msgid "Usage: <literal>&man.ls.1; is the manual page for <command>ls</command>.</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4225
	+msgid "<literal>&man.cp.1;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4226
	+msgid "<citerefentry><refentrytitle>cp</refentrytitle><manvolnum>1</manvolnum></citerefentry>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4227
	+msgid "Usage: <literal>The manual page for <command>cp</command> is &man.cp.1;.</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4233
	+msgid "<literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4234
	+msgid "<emphasis>link to <replaceable>command</replaceable> manual page in section <replaceable>sectionnumber</replaceable></emphasis>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4238
	+msgid "Entities are defined for all the <link xlink:href=\"@@URL_RELPREFIX@@/cgi/man.cgi\">FreeBSD manual pages</link>."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4250
	+msgid "FreeBSD Mailing List Entities"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4255
	+msgid "<literal>&a.doc;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4256
	+msgid "<literal><link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project mailing list</link></literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4257
	+msgid "Usage: <literal>A link to the &a.doc;.</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4262
	+msgid "<literal>&a.questions;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4263
	+msgid "<literal><link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions\">FreeBSD general questions mailing list</link></literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4264
	+msgid "Usage: <literal>A link to the &a.questions;.</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4269
	+msgid "<literal>&a.<replaceable>listname</replaceable>;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4270
	+msgid "<emphasis>link to <replaceable>listname</replaceable></emphasis>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4272
	+msgid "Entities are defined for all the <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/eresources.html#eresources-mail\">FreeBSD mailing lists</link>."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4283
	+msgid "FreeBSD Document Link Entities"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4288
	+msgid "<literal>&url.books.handbook;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4289
	+msgid "<literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4290
	+msgid "Usage: <literal>A link to the <link xlink:href=\"&url.books.handbook;/advanced-networking.html\">Advanced Networking</link> chapter of the Handbook.</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4297
	+msgid "<literal>&url.books.<replaceable>bookname</replaceable>;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4298
	+msgid "<emphasis>relative path to <replaceable>bookname</replaceable></emphasis>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4300
	+msgid "Entities are defined for all the <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/\">FreeBSD books</link>."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4305
	+msgid "<literal>&url.articles.committers-guide;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4306
	+msgid "<literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4307
	+msgid "Usage: <literal>A link to the <link xlink:href=\"&url.articles.committers-guide;\">Committer's Guide</link> article.</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4314
	+msgid "<literal>&url.articles.<replaceable>articlename</replaceable>;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4315
	+msgid "<emphasis>relative path to <replaceable>articlename</replaceable></emphasis>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4317
	+msgid "Entities are defined for all the <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/\">FreeBSD articles</link>."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4328
	+msgid "Other Operating System Name Entities"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4333
	+msgid "<literal>&linux;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4334
	+msgid "<trademark class=\"registered\">Linux</trademark>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4335
	+msgid "The <trademark class=\"registered\">Linux</trademark> operating system."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4339 book.translate.xml:8833
	+msgid "<literal>&unix;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4340 book.translate.xml:8832
	+msgid "<trademark class=\"registered\">UNIX</trademark>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4341
	+msgid "The <trademark class=\"registered\">UNIX</trademark> operating system."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4345
	+msgid "<literal>&windows;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4346
	+msgid "<trademark class=\"registered\">Windows</trademark>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4347
	+msgid "The <trademark class=\"registered\">Windows</trademark> operating system."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4357
	+msgid "Miscellaneous Entities"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4362
	+msgid "<literal>&prompt.root;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4364
	+msgid "The <systemitem class=\"username\">root</systemitem> user prompt."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4369
	+msgid "<literal>&prompt.user;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4371
	+msgid "A prompt for an unprivileged user."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4375
	+msgid "<literal>&postscript;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4376
	+msgid "<trademark class=\"registered\">PostScript</trademark>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4377
	+msgid "The <trademark class=\"registered\">PostScript</trademark> programming language."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4382
	+msgid "<literal>&tex;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4383
	+msgid "<application>TeX</application>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4384
	+msgid "The <application>TeX</application> typesetting language."
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4389
	+msgid "<literal>&xorg;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4390
	+msgid "Xorg"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:4391
	+msgid "The Xorg open source X Window System."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:4401
	+msgid "Formal Public Identifier (FPI)"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4403
	+msgid "In compliance with the DocBook guidelines for writing <acronym>FPI</acronym>s for DocBook customizations, the <acronym>FPI</acronym> for the FreeBSD extended DocBook <acronym>DTD</acronym> is:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/programlisting
	+#: book.translate.xml:4408
	+#, no-wrap
	+msgid "PUBLIC \"-//FreeBSD//DTD DocBook V4.2-Based Extension//EN\""
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:4412
	+msgid "Document Structure"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4414
	+msgid "DocBook allows structuring documentation in several ways. The FreeBSD Documentation Project uses two primary types of DocBook document: the book and the article."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4418
	+msgid "Books are organized into <tag>chapter</tag>s. This is a mandatory requirement. There may be <tag>part</tag>s between the book and the chapter to provide another layer of organization. For example, the Handbook is arranged in this way."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4424
	+msgid "A chapter may (or may not) contain one or more sections. These are indicated with the <tag>sect1</tag> element. If a section contains another section then use the <tag>sect2</tag> element, and so on, up to <tag>sect5</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4430
	+msgid "Chapters and sections contain the remainder of the content."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4433
	+msgid "An article is simpler than a book, and does not use chapters. Instead, the content of an article is organized into one or more sections, using the same <tag>sect1</tag> (and <tag>sect2</tag> and so on) elements that are used in books."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4439
	+msgid ""
	+"The nature of the document being written should be used to determine whether it is best marked up as a book or an article. Articles are well suited to information that does not need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are best suited to information that can be broken up into several chapters, possibly with appendices "
	+"and similar content as well."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:4448
	+msgid "The <link xlink:href=\"@@URL_RELPREFIX@@/docs.html\">FreeBSD 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>, 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."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4455
	+msgid "Starting a Book"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4457
	+msgid "The content of a book is contained within the <tag>book</tag> element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4464 book.translate.xml:4519
	+msgid "This additional information is contained within <tag>info</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4468
	+msgid "Boilerplate <tag>book</tag> with <tag>info</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4474
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">book</tag>\n"
	+" <tag class=\"starttag\">info</tag>\n"
	+" <tag class=\"starttag\">title</tag><replaceable>Your Title Here</replaceable><tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">author</tag>\n"
	+" <tag class=\"starttag\">personname</tag>\n"
	+" <tag class=\"starttag\">firstname</tag><replaceable>Your first name</replaceable><tag class=\"endtag\">firstname</tag>\n"
	+" <tag class=\"starttag\">surname</tag><replaceable>Your surname</replaceable><tag class=\"endtag\">surname</tag>\n"
	+" <tag class=\"endtag\">personname</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">affiliation</tag>\n"
	+"\t<tag class=\"starttag\">address</tag>\n"
	+" <tag class=\"starttag\">email</tag><replaceable>Your email address</replaceable><tag class=\"endtag\">email</tag>\n"
	+"\t<tag class=\"endtag\">address</tag>\n"
	+" <tag class=\"endtag\">affiliation</tag>\n"
	+" <tag class=\"endtag\">author</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">copyright</tag>\n"
	+" <tag class=\"starttag\">year</tag><replaceable>1998</replaceable><tag class=\"endtag\">year</tag>\n"
	+" <tag class=\"starttag\">holder role=\"mailto:<replaceable>your email address</replaceable>\"</tag><replaceable>Your name</replaceable><tag class=\"endtag\">holder</tag>\n"
	+" <tag class=\"endtag\">copyright</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">releaseinfo</tag>$FreeBSD$<tag class=\"endtag\">releaseinfo</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">info</tag>\n"
	+"\n"
	+" …\n"
	+"\n"
	+"<tag class=\"endtag\">book</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4510
	+msgid "Starting an Article"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4512
	+msgid "The content of the article is contained within the <tag>article</tag> element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4523
	+msgid "Boilerplate <tag>article</tag> with <tag>info</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4529
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">article</tag>\n"
	+" <tag class=\"starttag\">info</tag>\n"
	+" <tag class=\"starttag\">title</tag><replaceable>Your title here</replaceable><tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">author</tag>\n"
	+" <tag class=\"starttag\">personname</tag>\n"
	+"\t<tag class=\"starttag\">firstname</tag><replaceable>Your first name</replaceable><tag class=\"endtag\">firstname</tag>\n"
	+"\t<tag class=\"starttag\">surname</tag><replaceable>Your surname</replaceable><tag class=\"endtag\">surname</tag>\n"
	+" <tag class=\"endtag\">personname</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">affiliation</tag>\n"
	+"\t<tag class=\"starttag\">address</tag>\n"
	+"\t <tag class=\"starttag\">email</tag><replaceable>Your email address</replaceable><tag class=\"endtag\">email</tag><tag class=\"endtag\">address</tag>\n"
	+"\t<tag class=\"endtag\">address</tag>\n"
	+" <tag class=\"endtag\">affiliation</tag>\n"
	+" <tag class=\"endtag\">author</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">copyright</tag>\n"
	+" <tag class=\"starttag\">year</tag><replaceable>1998</replaceable><tag class=\"endtag\">year</tag>\n"
	+" <tag class=\"starttag\">holder role=\"mailto:<replaceable>your email address</replaceable>\"</tag><replaceable>Your name</replaceable><tag class=\"endtag\">holder</tag>\n"
	+" <tag class=\"endtag\">copyright</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">releaseinfo</tag>$FreeBSD$<tag class=\"endtag\">releaseinfo</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">info</tag>\n"
	+"\n"
	+" …\n"
	+"\n"
	+"<tag class=\"endtag\">article</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4565
	+msgid "Indicating Chapters"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4567
	+msgid "Use <tag>chapter</tag> to mark up your chapters. Each chapter has a mandatory <tag>title</tag>. Articles do not contain chapters, they are reserved for books."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4573
	+msgid "A Simple Chapter"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4575
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>The Chapter's Title<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" ...\n"
	+"<tag class=\"endtag\">chapter</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4582
	+msgid "A chapter cannot be empty; it must contain elements in addition to <tag>title</tag>. If you need to include an empty chapter then just use an empty paragraph."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4588
	+msgid "Empty Chapters"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4590
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>This is An Empty Chapter<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag><tag class=\"endtag\">para</tag>\n"
	+"<tag class=\"endtag\">chapter</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4599
	+msgid "Sections Below Chapters"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4601
	+msgid "In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the <tag>sect<replaceable>n</replaceable></tag> element. The <replaceable>n</replaceable> indicates the section number, which identifies the section level."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4609
	+msgid "The first <tag>sect<replaceable>n</replaceable></tag> is <tag>sect1</tag>. You can have one or more of these in a chapter. They can contain one or more <tag>sect2</tag> elements, and so on, down to <tag>sect5</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4617
	+msgid "Sections in Chapters"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4619
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>A Sample Chapter<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>Some text in the chapter.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>First Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" …\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>Second Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect2</tag>\n"
	+" <tag class=\"starttag\">title</tag>First Sub-Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect3</tag>\n"
	+"\t<tag class=\"starttag\">title</tag>First Sub-Sub-Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+"\t…\n"
	+" <tag class=\"endtag\">sect3</tag>\n"
	+" <tag class=\"endtag\">sect2</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect2</tag>\n"
	+" <tag class=\"starttag\">title</tag>Second Sub-Section (1.2.2)<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" …\n"
	+" <tag class=\"endtag\">sect2</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">chapter</tag>"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:4653
	+msgid "Section numbers are automatically generated and prepended to titles when the document is rendered to an output format. The generated section numbers and titles from the example above will be:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4660
	+msgid "1.1. First Section"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4664
	+msgid "1.2. Second Section"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4668
	+msgid "1.2.1. First Sub-Section"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4672
	+msgid "1.2.1.1. First Sub-Sub-Section"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4676
	+msgid "1.2.2. Second Sub-Section"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4683
	+msgid "Subdividing Using <tag>part</tag> Elements"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4686
	+msgid "<tag>part</tag>s introduce another level of organization between <tag>book</tag> and <tag>chapter</tag> with one or more <tag>part</tag>s. This cannot be done in an <tag>article</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:4692
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">part</tag>\n"
	+" <tag class=\"starttag\">title</tag>Introduction<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>Overview<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" ...\n"
	+" <tag class=\"endtag\">chapter</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>What is FreeBSD?<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" ...\n"
	+" <tag class=\"endtag\">chapter</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>History<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" ...\n"
	+" <tag class=\"endtag\">chapter</tag>\n"
	+"<tag class=\"endtag\">part</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4722
	+msgid "DocBook supports three types of paragraphs: <tag>formalpara</tag>, <tag>para</tag>, and <tag>simpara</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4726
	+msgid "Almost all paragraphs in FreeBSD documentation use <tag>para</tag>. <tag>formalpara</tag> includes a <tag>title</tag> element, and <tag>simpara</tag> disallows some elements from within <tag>para</tag>. Stick with <tag>para</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4734
	+msgid "<tag>para</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4738
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>This is a paragraph. It can contain just about any\n"
	+" other element.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4741 book.translate.xml:4779 book.translate.xml:4856 book.translate.xml:4887 book.translate.xml:4946 book.translate.xml:5008 book.translate.xml:5076 book.translate.xml:5143 book.translate.xml:5201 book.translate.xml:5285 book.translate.xml:5325 book.translate.xml:5434 book.translate.xml:5486 book.translate.xml:5515 book.translate.xml:5543 book.translate.xml:5591 book.translate.xml:5703
	+#: book.translate.xml:5753 book.translate.xml:5800 book.translate.xml:5937 book.translate.xml:5985 book.translate.xml:6014 book.translate.xml:6035 book.translate.xml:6087 book.translate.xml:6133 book.translate.xml:6163 book.translate.xml:6186 book.translate.xml:6216 book.translate.xml:6238 book.translate.xml:6690 book.translate.xml:6704 book.translate.xml:6719 book.translate.xml:6737
	+msgid "Appearance:"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:4743
	+msgid "This is a paragraph. It can contain just about any other element."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4751
	+msgid "A block quotation is an extended quotation from another document that should not appear within the current paragraph. These are rarely needed."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4755
	+msgid "Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed)."
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4764
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>A small excerpt from the US Constitution:<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">blockquote</tag>\n"
	+" <tag class=\"starttag\">title</tag>Preamble to the Constitution of the United States<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">attribution</tag>Copied from a web site somewhere<tag class=\"endtag\">attribution</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>We the People of the United States, in Order to form a more\n"
	+" perfect Union, establish Justice, insure domestic Tranquility,\n"
	+" provide for the common defence, promote the general Welfare, and\n"
	+" secure the Blessings of Liberty to ourselves and our Posterity, do\n"
	+" ordain and establish this Constitution for the United States of\n"
	+" America.<tag class=\"endtag\">para</tag>\n"
	+"<tag class=\"endtag\">blockquote</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:4781
	+msgid "A small excerpt from the US Constitution:"
	+msgstr ""
	+
	+#. (itstool) path: blockquote/title
	+#: book.translate.xml:4784
	+msgid "Preamble to the Constitution of the United States"
	+msgstr ""
	+
	+#. (itstool) path: blockquote/attribution
	+#: book.translate.xml:4787
	+msgid "Copied from a web site somewhere"
	+msgstr ""
	+
	+#. (itstool) path: blockquote/para
	+#: book.translate.xml:4790
	+msgid "We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4802
	+msgid "Tips, Notes, Warnings, Cautions, and Important Information"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4805
	+msgid "Extra information may need to be separated from the main body of the text. Typically this is <quote>meta</quote> information of which the user should be aware."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4810
	+msgid "Several types of admonitions are available: <tag>tip</tag>, <tag>note</tag>, <tag>warning</tag>, <tag>caution</tag>, and <tag>important</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4815
	+msgid "Which admonition to choose depends on the situation. The DocBook documentation suggests:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4821
	+msgid "Note is for information that should be heeded by all readers."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4826
	+msgid "Important is a variation on Note."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4830
	+msgid "Caution is for information regarding possible data loss or software damage."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4835
	+msgid "Warning is for information regarding possible hardware damage or injury to life or limb."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4841
	+msgid "<tag>tip</tag> and <tag>important</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4845
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">tip</tag>\n"
	+" <tag class=\"starttag\">para</tag>&os; may reduce stress.<tag class=\"endtag\">para</tag>\n"
	+"<tag class=\"endtag\">tip</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">important</tag>\n"
	+" <tag class=\"starttag\">para</tag>Please use admonitions sparingly. Too many admonitions\n"
	+" are visually jarring and can have the opposite of the\n"
	+" intended effect.<tag class=\"endtag\">para</tag>\n"
	+"<tag class=\"endtag\">important</tag>"
	+msgstr ""
	+
	+#. (itstool) path: tip/para
	+#: book.translate.xml:4859
	+msgid "FreeBSD may reduce stress."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:4863
	+msgid "Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4872
	+msgid "Examples can be shown with <tag>example</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4875
	+msgid "<tag>example</tag> Source"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4879
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">example</tag>\n"
	+" <tag class=\"starttag\">para</tag>Empty files can be created easily:<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <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>\n"
	+"<tag class=\"endtag\">example</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4890
	+msgid "Rendered <tag>example</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:4892
	+msgid "Empty files can be created easily:"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:4894
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>touch file1 file2 file3</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:4899
	+msgid "Lists and Procedures"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4901
	+msgid "Information often needs to be presented as lists, or as a number of steps that must be carried out in order to accomplish a particular goal."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4905
	+msgid "To do this, use <tag>itemizedlist</tag>, <tag>orderedlist</tag>, <tag>variablelist</tag>, or <tag>procedure</tag>. There are other types of list elements in DocBook, but we will not cover them here."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4910
	+msgid ""
	+"<tag>itemizedlist</tag> and <tag>orderedlist</tag> are similar to their counterparts in <acronym>HTML</acronym>, <tag>ul</tag> and <tag>ol</tag>. Each one consists of one or more <tag>listitem</tag> elements, and each <tag>listitem</tag> contains one or more block elements. The <tag>listitem</tag> elements are analogous to <acronym>HTML</acronym>'s <tag>li</tag> tags. However, unlike HTML, they are required."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4921
	+msgid "<tag>itemizedlist</tag> and <tag>orderedlist</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4926
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">itemizedlist</tag>\n"
	+" <tag class=\"starttag\">listitem</tag>\n"
	+" <tag class=\"starttag\">para</tag>This is the first itemized item.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">listitem</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">listitem</tag>\n"
	+" <tag class=\"starttag\">para</tag>This is the second itemized item.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">listitem</tag>\n"
	+"<tag class=\"endtag\">itemizedlist</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">orderedlist</tag>\n"
	+" <tag class=\"starttag\">listitem</tag>\n"
	+" <tag class=\"starttag\">para</tag>This is the first ordered item.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">listitem</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">listitem</tag>\n"
	+" <tag class=\"starttag\">para</tag>This is the second ordered item.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">listitem</tag>\n"
	+"<tag class=\"endtag\">orderedlist</tag>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4950
	+msgid "This is the first itemized item."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4954
	+msgid "This is the second itemized item."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4960
	+msgid "This is the first ordered item."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:4964
	+msgid "This is the second ordered item."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#. (itstool) id: book.translate.xml#docbook-markup-varlist
	+#: book.translate.xml:4969
	+msgid "An alternate and often useful way of presenting information is the <tag>variablelist</tag>. These are lists where each entry has a term and a description. They are well suited for many types of descriptions, and present information in a form that is often easier for the reader than sections and subsections."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:4977
	+msgid "A <tag>variablelist</tag> has a <tag>title</tag>, and then pairs of <tag>term</tag> and <tag>listitem</tag> entries."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:4982
	+msgid "<tag>variablelist</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:4986
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">variablelist</tag>\n"
	+" <tag class=\"starttag\">varlistentry</tag>\n"
	+" <tag class=\"starttag\">term</tag>Parallel<tag class=\"endtag\">term</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">listitem</tag>\n"
	+" <tag class=\"starttag\">para</tag>In parallel communications, groups of bits arrive\n"
	+"\tat the same time over multiple communications\n"
	+"\tchannels.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">listitem</tag>\n"
	+" <tag class=\"endtag\">varlistentry</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">varlistentry</tag>\n"
	+" <tag class=\"starttag\">term</tag>Serial<tag class=\"endtag\">term</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">listitem</tag>\n"
	+" <tag class=\"starttag\">para</tag>In serial communications, bits arrive one at a\n"
	+"\ttime over a single communications\n"
	+"\tchannel.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">listitem</tag>\n"
	+" <tag class=\"endtag\">varlistentry</tag>\n"
	+"<tag class=\"endtag\">variablelist</tag>"
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5012
	+msgid "Parallel"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5015
	+msgid "In parallel communications, groups of bits arrive at the same time over multiple communications channels."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5022
	+msgid "Serial"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5025
	+msgid "In serial communications, bits arrive one at a time over a single communications channel."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5032
	+msgid "A <tag>procedure</tag> shows a series of <tag>step</tag>s, which may in turn consist of more <tag>step</tag>s or <tag>substep</tag>s. Each <tag>step</tag> contains block elements and may include an optional title."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5038
	+msgid "Sometimes, steps are not sequential, but present a choice: do <emphasis>this</emphasis> or do <emphasis>that</emphasis>, but not both. For these alternative choices, use <tag>stepalternatives</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5044
	+msgid "<tag>procedure</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5048
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">procedure</tag>\n"
	+" <tag class=\"starttag\">step</tag>\n"
	+" <tag class=\"starttag\">para</tag>Do this.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">step</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">step</tag>\n"
	+" <tag class=\"starttag\">para</tag>Then do this.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">step</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">step</tag>\n"
	+" <tag class=\"starttag\">para</tag>And now do this.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">step</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">step</tag>\n"
	+" <tag class=\"starttag\">para</tag>Finally, do one of these.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">stepalternatives</tag>\n"
	+" <tag class=\"starttag\">step</tag>\n"
	+"\t<tag class=\"starttag\">para</tag>Go left.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">step</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">step</tag>\n"
	+"\t<tag class=\"starttag\">para</tag>Go right.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">step</tag>\n"
	+" <tag class=\"endtag\">stepalternatives</tag>\n"
	+" <tag class=\"endtag\">step</tag>\n"
	+"<tag class=\"endtag\">procedure</tag>"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:5080
	+msgid "Do this."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:5084
	+msgid "Then do this."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:5088
	+msgid "And now do this."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:5092
	+msgid "Finally, do one of these:"
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:5096
	+msgid "Go left."
	+msgstr ""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:5100
	+msgid "Go right."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5109
	+msgid "Showing File Samples"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5111
	+msgid "Fragments of a file (or perhaps a complete file) are shown by wrapping them in the <tag>programlisting</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5115
	+msgid "White space and line breaks within <tag>programlisting</tag> <emphasis>are</emphasis> significant. In particular, this means that the opening tag should appear on the same line as the first line of the output, and the closing tag should appear on the same line as the last line of the output, otherwise spurious blank lines may be included."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5124
	+msgid "<tag>programlisting</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5128
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>When finished, the program will look like\n"
	+" this:<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">programlisting</tag>#include &lt;stdio.h&gt;\n"
	+"\n"
	+"int\n"
	+"main(void)\n"
	+"{\n"
	+" printf(\"hello, world\\n\");\n"
	+"}<tag class=\"endtag\">programlisting</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5139
	+msgid "Notice how the angle brackets in the <literal>#include</literal> line need to be referenced by their entities instead of being included literally."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5145 book.translate.xml:5203
	+msgid "When finished, the program will look like this:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5147
	+#, no-wrap
	+msgid ""
	+"#include <stdio.h>\n"
	+"\n"
	+"int\n"
	+"main(void)\n"
	+"{\n"
	+" printf(\"hello, world\\n\");\n"
	+"}"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5158
	+msgid "Callouts"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5160
	+msgid "A callout is a visual marker for referring to a piece of text or specific position within an example."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5164
	+msgid "Callouts are marked with the <tag>co</tag> element. Each element must have a unique <literal>id</literal> assigned to it. After the example, include a <tag>calloutlist</tag> that describes each callout."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5171
	+msgid "<tag>co</tag> and <tag>calloutlist</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5174
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>When finished, the program will look like\n"
	+" this:<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">programlisting</tag>#include &lt;stdio.h&gt; <tag class=\"emptytag\">co xml:id=\"co-ex-include\"</tag>\n"
	+"\n"
	+"int <tag class=\"emptytag\">co xml:id=\"co-ex-return\"</tag>\n"
	+"main(void)\n"
	+"{\n"
	+" printf(\"hello, world\\n\"); <tag class=\"emptytag\">co xml:id=\"co-ex-printf\"</tag>\n"
	+"}<tag class=\"endtag\">programlisting</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">calloutlist</tag>\n"
	+" <tag class=\"starttag\">callout arearefs=\"co-ex-include\"</tag>\n"
	+" <tag class=\"starttag\">para</tag>Includes the standard IO header file.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">callout</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">callout arearefs=\"co-ex-return\"</tag>\n"
	+" <tag class=\"starttag\">para</tag>Specifies that <tag class=\"starttag\">function</tag>main()<tag class=\"endtag\">function</tag> returns an\n"
	+" int.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">callout</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">callout arearefs=\"co-ex-printf\"</tag>\n"
	+" <tag class=\"starttag\">para</tag>The <tag class=\"starttag\">function</tag>printf()<tag class=\"endtag\">function</tag> call that writes\n"
	+" <tag class=\"starttag\">literal</tag>hello, world<tag class=\"endtag\">literal</tag> to standard output.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">callout</tag>\n"
	+"<tag class=\"endtag\">calloutlist</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5205
	+#, no-wrap
	+msgid ""
	+"#include <stdio.h> <co xml:id=\"co-ex-include\"/>\n"
	+"\n"
	+"int <co xml:id=\"co-ex-return\"/>\n"
	+"main(void)\n"
	+"{\n"
	+" printf(\"hello, world\\n\"); <co xml:id=\"co-ex-printf\"/>\n"
	+"}"
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:5215
	+msgid "Includes the standard IO header file."
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:5219
	+msgid "Specifies that <function>main()</function> returns an int."
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:5224
	+msgid "The <function>printf()</function> call that writes <literal>hello, world</literal> to standard output."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5235
	+msgid "Unlike <acronym>HTML</acronym>, DocBook does not need tables for layout purposes, as the stylesheet handles those issues. Instead, just use tables for marking up tabular data."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5240
	+msgid ""
	+"In general terms (and see the DocBook documentation for more detail) a table (which can be either formal or informal) consists of a <tag>table</tag> element. This contains at least one <tag>tgroup</tag> element, which specifies (as an attribute) the number of columns in this table group. Within the tablegroup there is one <tag>thead</tag> element, which contains elements for the table headings (column "
	+"headings), and one <tag>tbody</tag> which contains the body of the table."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5251
	+msgid "Both <tag>tgroup</tag> and <tag>thead</tag> contain <tag>row</tag> elements, which in turn contain <tag>entry</tag> elements. Each <tag>entry</tag> element specifies one cell in the table."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5258
	+msgid "<tag>informaltable</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5262
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">informaltable pgwide=\"1\"</tag>\n"
	+" <tag class=\"starttag\">tgroup cols=\"2\"</tag>\n"
	+" <tag class=\"starttag\">thead</tag>\n"
	+" <tag class=\"starttag\">row</tag>\n"
	+" <tag class=\"starttag\">entry</tag>This is Column Head 1<tag class=\"endtag\">entry</tag>\n"
	+" <tag class=\"starttag\">entry</tag>This is Column Head 2<tag class=\"endtag\">entry</tag>\n"
	+" <tag class=\"endtag\">row</tag>\n"
	+" <tag class=\"endtag\">thead</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">tbody</tag>\n"
	+" <tag class=\"starttag\">row</tag>\n"
	+"\t<tag class=\"starttag\">entry</tag>Row 1, column 1<tag class=\"endtag\">entry</tag>\n"
	+"\t<tag class=\"starttag\">entry</tag>Row 1, column 2<tag class=\"endtag\">entry</tag>\n"
	+" <tag class=\"endtag\">row</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">row</tag>\n"
	+"\t<tag class=\"starttag\">entry</tag>Row 2, column 1<tag class=\"endtag\">entry</tag>\n"
	+"\t<tag class=\"starttag\">entry</tag>Row 2, column 2<tag class=\"endtag\">entry</tag>\n"
	+" <tag class=\"endtag\">row</tag>\n"
	+" <tag class=\"endtag\">tbody</tag>\n"
	+" <tag class=\"endtag\">tgroup</tag>\n"
	+"<tag class=\"endtag\">informaltable</tag>"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:5291 book.translate.xml:5331
	+msgid "This is Column Head 1"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:5292 book.translate.xml:5332
	+msgid "This is Column Head 2"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:5298 book.translate.xml:5338
	+msgid "Row 1, column 1"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:5299 book.translate.xml:5339
	+msgid "Row 1, column 2"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:5303 book.translate.xml:5343
	+msgid "Row 2, column 1"
	+msgstr ""
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:5304 book.translate.xml:5344
	+msgid "Row 2, column 2"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5311
	+msgid "Always use the <literal>pgwide</literal> attribute with a value of <literal>1</literal> with the <tag>informaltable</tag> element. A bug in Internet Explorer can cause the table to render incorrectly if this is omitted."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5317
	+msgid "Table borders can be suppressed by setting the <literal>frame</literal> attribute to <literal>none</literal> in the <tag>informaltable</tag> element. For example, <literal>informaltable frame=\"none\"</literal>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5323
	+msgid "Table with <literal>frame=\"none\"</literal> Example"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5353
	+msgid "Examples for the User to Follow"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5355
	+msgid "Examples for the user to follow are often necessary. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, the user types another command, and so on."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5360
	+msgid "A number of distinct elements and entities come into play here."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5365
	+msgid "<tag>screen</tag>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5368
	+msgid "Everything the user sees in this example will be on the computer screen, so the next element is <tag>screen</tag>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5372
	+msgid "Within <tag>screen</tag>, white space is significant."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5378
	+msgid "<tag>prompt</tag>, <literal>&prompt.root;</literal> and <literal>&prompt.user;</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5383
	+msgid "Some of the things the user will be seeing on the screen are prompts from the computer (either from the operating system, command shell, or application). These should be marked up using <tag>prompt</tag>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5389
	+msgid "As a special case, the two shell prompts for the normal user and the root user have been provided as entities. To indicate the user is at a shell prompt, use one of <literal>&prompt.root;</literal> and <literal>&prompt.user;</literal> as necessary. They do not need to be inside <tag>prompt</tag>."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:5398
	+msgid "<literal>&prompt.root;</literal> and <literal>&prompt.user;</literal> are FreeBSD extensions to DocBook, and are not part of the original <acronym>DTD</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5407
	+msgid "<tag>userinput</tag>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5410
	+msgid "When displaying text that the user should type in, wrap it in <tag>userinput</tag> tags. It will be displayed differently than system output text."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5418
	+msgid "<tag>screen</tag>, <tag>prompt</tag>, and <tag>userinput</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5423
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">screen</tag>&prompt.user; <tag class=\"starttag\">userinput</tag>ls -1<tag class=\"endtag\">userinput</tag>\n"
	+"foo1\n"
	+"foo2\n"
	+"foo3\n"
	+"&prompt.user; <tag class=\"starttag\">userinput</tag>ls -1 \| grep foo2<tag class=\"endtag\">userinput</tag>\n"
	+"foo2\n"
	+"&prompt.user; <tag class=\"starttag\">userinput</tag>su<tag class=\"endtag\">userinput</tag>\n"
	+"<tag class=\"starttag\">prompt</tag>Password: <tag class=\"endtag\">prompt</tag>\n"
	+"&prompt.root; <tag class=\"starttag\">userinput</tag>cat foo2<tag class=\"endtag\">userinput</tag>\n"
	+"This is the file called 'foo2'<tag class=\"endtag\">screen</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/screen
	+#: book.translate.xml:5436
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>ls -1</userinput>\n"
	+"foo1\n"
	+"foo2\n"
	+"foo3\n"
	+"<prompt>%</prompt> <userinput>ls -1 \| grep foo2</userinput>\n"
	+"foo2\n"
	+"<prompt>%</prompt> <userinput>su</userinput>\n"
	+"<prompt>Password: </prompt>\n"
	+"<prompt>#</prompt> <userinput>cat foo2</userinput>\n"
	+"This is the file called 'foo2'"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:5449
	+msgid "Even though we are displaying the contents of the file <filename>foo2</filename>, it is <emphasis>not</emphasis> marked up as <tag>programlisting</tag>. Reserve <tag>programlisting</tag> for showing fragments of files outside the context of user actions."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5464
	+msgid "To emphasize a particular word or phrase, use <tag>emphasis</tag>. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5469
	+msgid "There is no way to change the presentation of the emphasis within the document, no equivalent of <acronym>HTML</acronym>'s <tag>b</tag> and <tag>i</tag>. If the information being presented is important, then consider presenting it in <tag>important</tag> rather than <tag>emphasis</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5478
	+msgid "<tag>emphasis</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5482
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>&os; is without doubt <tag class=\"starttag\">emphasis</tag>the<tag class=\"endtag\">emphasis</tag>\n"
	+" premiere &unix;-like operating system for the Intel\n"
	+" architecture.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5488
	+msgid "FreeBSD is without doubt <emphasis>the</emphasis> premiere <trademark class=\"registered\">UNIX</trademark>-like operating system for the Intel architecture."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5495 book.translate.xml:8529
	+msgid "Acronyms"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5497
	+msgid "Many computer terms are <emphasis>acronyms</emphasis>, words formed from the first letter of each word in a phrase. Acronyms are marked up into <tag>acronym</tag> elements. It is helpful to the reader when an acronym is defined on the first use, as shown in the example below."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5505
	+msgid "<tag>acronym</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5509
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Request For Comments (<tag class=\"starttag\">acronym</tag>RFC<tag class=\"endtag\">acronym</tag>) 1149\n"
	+" defined the use of avian carriers for transmission of\n"
	+" Internet Protocol (<tag class=\"starttag\">acronym</tag>IP<tag class=\"endtag\">acronym</tag>) data. The\n"
	+" quantity of <tag class=\"starttag\">acronym</tag>IP<tag class=\"endtag\">acronym</tag> data currently\n"
	+" transmitted in that manner is unknown.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5517
	+msgid "Request For Comments (<acronym>RFC</acronym>) 1149 defined the use of avian carriers for transmission of Internet Protocol (<acronym>IP</acronym>) data. The quantity of <acronym>IP</acronym> data currently transmitted in that manner is unknown."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5526
	+msgid "Quotations"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5528
	+msgid "To quote text from another document or source, or to denote a phrase that is used figuratively, use <tag>quote</tag>. Most of the markup tags available for normal text are also available from within a <tag>quote</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5535
	+msgid "<tag>quote</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5539
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>However, make sure that the search does not go beyond the\n"
	+" <tag class=\"starttag\">quote</tag>boundary between local and public administration<tag class=\"endtag\">quote</tag>,\n"
	+" as <tag class=\"starttag\">acronym</tag>RFC<tag class=\"endtag\">acronym</tag> 1535 calls it.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5545
	+msgid "However, make sure that the search does not go beyond the <quote>boundary between local and public administration</quote>, as <acronym>RFC</acronym> 1535 calls it."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5553
	+msgid "Keys, Mouse Buttons, and Combinations"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5555
	+msgid "To refer to a specific key on the keyboard, use <tag>keycap</tag>. To refer to a mouse button, use <tag>mousebutton</tag>. And to refer to combinations of key presses or mouse clicks, wrap them all in <tag>keycombo</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5561
	+msgid "<tag>keycombo</tag> has an attribute called <literal>action</literal>, which may be one of <literal>click</literal>, <literal>double-click</literal>, <literal>other</literal>, <literal>press</literal>, <literal>seq</literal>, or <literal>simul</literal>. The last two values denote whether the keys or buttons should be pressed in sequence, or simultaneously."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5569
	+msgid "The stylesheets automatically add any connecting symbols, such as <literal>+</literal>, between the key names, when wrapped in <tag>keycombo</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5574
	+msgid "Keys, Mouse Buttons, and Combinations Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5578
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>To switch to the second virtual terminal, press\n"
	+" <tag class=\"starttag\">keycombo action=\"simul\"</tag><tag class=\"starttag\">keycap</tag>Alt<tag class=\"endtag\">keycap</tag>\n"
	+" <tag class=\"starttag\">keycap</tag>F1<tag class=\"endtag\">keycap</tag><tag class=\"endtag\">keycombo</tag>.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>To exit <tag class=\"starttag\">command</tag>vi<tag class=\"endtag\">command</tag> without saving changes, type\n"
	+" <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>\n"
	+" <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>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>My window manager is configured so that\n"
	+" <tag class=\"starttag\">keycombo action=\"simul\"</tag><tag class=\"starttag\">keycap</tag>Alt<tag class=\"endtag\">keycap</tag>\n"
	+" <tag class=\"starttag\">mousebutton</tag>right<tag class=\"endtag\">mousebutton</tag>\n"
	+" <tag class=\"endtag\">keycombo</tag> mouse button is used to move windows.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5593
	+msgid "To switch to the second virtual terminal, press <keycombo action=\"simul\"><keycap>Alt</keycap> <keycap>F1</keycap></keycombo>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5597
	+msgid "To exit <command>vi</command> without saving changes, type <keycombo action=\"seq\"> <keycap>Esc</keycap> <keycap>:</keycap> <keycap>q</keycap> <keycap>!</keycap></keycombo>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5604
	+msgid "My window manager is configured so that <keycombo action=\"simul\"> <keycap>Alt</keycap> <mousebutton>right</mousebutton></keycombo> mouse button is used to move windows."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5613
	+msgid "Applications, Commands, Options, and Cites"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5615
	+msgid "Both applications and commands are frequently referred to when writing documentation. The distinction between them is that an application is the name of a program or suite of programs that fulfill a particular task. A command is the filename of a program that the user can type and run at a command line."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5622
	+msgid "It is often necessary to show some of the options that a command might take."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5625
	+msgid "Finally, it is often useful to list a command with its manual section number, in the <quote>command(number)</quote> format so common in Unix manuals."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5629
	+msgid "Mark up application names with <tag>application</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5632
	+msgid "To list a command with its manual section number (which should be most of the time) the DocBook element is <tag>citerefentry</tag>. This will contain a further two elements, <tag>refentrytitle</tag> and <tag>manvolnum</tag>. The content of <tag>refentrytitle</tag> is the name of the command, and the content of <tag>manvolnum</tag> is the manual page section."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5642
	+msgid "This can be cumbersome to write, and so a series of <link linkend=\"xml-primer-general-entities\">general entities</link> have been created to make this easier. Each entity takes the form <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5648
	+msgid "The file that contains these entities is in <filename>doc/share/xml/man-refs.ent</filename>, and can be referred to using this <acronym>FPI</acronym>:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:5652
	+#, no-wrap
	+msgid "PUBLIC \"-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN\""
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5654
	+msgid "Therefore, the introduction to FreeBSD documentation will usually include this:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:5657
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE book PUBLIC \"-//FreeBSD//DTD DocBook V4.1-Based Extension//EN\" [\n"
	+"\n"
	+"<!ENTITY % man PUBLIC \"-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN\">\n"
	+"%man;\n"
	+"\n"
	+"…\n"
	+"\n"
	+"]>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5666
	+msgid "Use <tag>command</tag> to include a command name <quote>in-line</quote> but present it as something the user should type."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5670
	+msgid "Use <tag>option</tag> to mark up the options which will be passed to a command."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5673
	+msgid "When referring to the same command multiple times in close proximity, it is preferred to use the <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation to markup the first reference and use <tag>command</tag> to markup subsequent references. This makes the generated output, especially <acronym>HTML</acronym>, appear visually better."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5682
	+msgid "Applications, Commands, and Options Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5686
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag><tag class=\"starttag\">application</tag>Sendmail<tag class=\"endtag\">application</tag> is the most\n"
	+" widely used Unix mail application.<tag class=\"starttag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag><tag class=\"starttag\">application</tag>Sendmail<tag class=\"endtag\">application</tag> includes the\n"
	+" <tag class=\"starttag\">citerefentry</tag>\n"
	+" <tag class=\"starttag\">refentrytitle</tag>sendmail<tag class=\"endtag\">refentrytitle</tag>\n"
	+" <tag class=\"starttag\">manvolnum</tag>8<tag class=\"endtag\">manvolnum</tag>\n"
	+" <tag class=\"endtag\">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1;\n"
	+" programs.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>One of the command line parameters to <tag class=\"starttag\">citerefentry</tag>\n"
	+" <tag class=\"starttag\">refentrytitle</tag>sendmail<tag class=\"endtag\">refentrytitle</tag>\n"
	+" <tag class=\"starttag\">manvolnum</tag>8<tag class=\"endtag\">manvolnum</tag>\n"
	+" <tag class=\"endtag\">citerefentry</tag>, <tag class=\"starttag\">option</tag>-bp<tag class=\"endtag\">option</tag>, will display the current\n"
	+" status of messages in the mail queue. Check this on the command\n"
	+" line by running <tag class=\"starttag\">command</tag>sendmail -bp<tag class=\"endtag\">command</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5705
	+msgid "<application>Sendmail</application> is the most widely used Unix mail application."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5708
	+msgid "<application>Sendmail</application> includes the <citerefentry> <refentrytitle>sendmail</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>, <citerefentry><refentrytitle>mailq</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and <citerefentry><refentrytitle>newaliases</refentrytitle><manvolnum>1</manvolnum></citerefentry> programs."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5715
	+msgid "One of the command line parameters to <citerefentry> <refentrytitle>sendmail</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>, <option>-bp</option>, will display the current status of messages in the mail queue. Check this on the command line by running <command>sendmail -bp</command>."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:5726
	+msgid "Notice how the <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5733
	+msgid "Files, Directories, Extensions, Device Names"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5735
	+msgid "To refer to the name of a file, a directory, a file extension, or a device name, use <tag>filename</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5739
	+msgid "<tag>filename</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5743
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>The source for the Handbook in English is found in\n"
	+" <tag class=\"starttag\">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class=\"endtag\">filename</tag>.\n"
	+" The main file is called <tag class=\"starttag\">filename</tag>book.xml<tag class=\"endtag\">filename</tag>.\n"
	+" There is also a <tag class=\"starttag\">filename</tag>Makefile<tag class=\"endtag\">filename</tag> and a\n"
	+" number of files with a <tag class=\"starttag\">filename</tag>.ent<tag class=\"endtag\">filename</tag> extension.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag><tag class=\"starttag\">filename</tag>kbd0<tag class=\"endtag\">filename</tag> is the first keyboard detected\n"
	+" by the system, and appears in\n"
	+" <tag class=\"starttag\">filename</tag>/dev<tag class=\"endtag\">filename</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5755
	+msgid "The source for the Handbook in English is found in <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The main file is called <filename>book.xml</filename>. There is also a <filename>Makefile</filename> and a number of files with a <filename>.ent</filename> extension."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5761
	+msgid "<filename>kbd0</filename> is the first keyboard detected by the system, and appears in <filename>/dev</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5768
	+msgid "The Name of Ports"
	+msgstr ""
	+
	+#. (itstool) path: note/title
	+#: book.translate.xml:5771 book.translate.xml:5815 book.translate.xml:6047
	+msgid "FreeBSD Extension"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:5773 book.translate.xml:5817 book.translate.xml:6049
	+msgid "These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook <acronym>DTD</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5778
	+msgid "To include the name of a program from the FreeBSD Ports Collection in the document, use the <tag>package</tag> tag. Since the Ports Collection can be installed in any number of locations, only include the category and the port name; do not include <filename>/usr/ports</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5784
	+msgid "By default, <tag>package</tag> refers to a binary package. To refer to a port that will be built from source, set the <literal>role</literal> attribute to <literal>port</literal>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5790
	+msgid "<tag>package</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5794
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Install the <tag class=\"starttag\">package</tag>net/wireshark<tag class=\"endtag\">package</tag> binary\n"
	+" package to view network traffic.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag><tag class=\"starttag\">package role=\"port\"</tag>net/wireshark<tag class=\"endtag\">package</tag> can also be\n"
	+" built and installed from the Ports Collection.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5802
	+msgid "Install the <package>net/wireshark</package> binary package to view network traffic."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5805
	+msgid "<package role=\"port\">net/wireshark</package> can also be built and installed from the Ports Collection."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5811
	+msgid "Hosts, Domains, IP Addresses, User Names, Group Names, and Other System Items"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5822
	+msgid "Information for <quote>system items</quote> is marked up with <tag>systemitem</tag>. The <literal>class</literal> attribute is used to identify the particular type of information shown."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5829
	+msgid "<literal>class=\"domainname\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5832
	+msgid "The text is a domain name, such as <literal>FreeBSD.org</literal> or <literal>ngo.org.uk</literal>. There is no hostname component."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5840
	+msgid "<literal>class=\"etheraddress\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5843
	+msgid "The text is an Ethernet <acronym>MAC</acronym> address, expressed as a series of 2 digit hexadecimal numbers separated by colons."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5850
	+msgid "<literal>class=\"fqdomainname\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5853
	+msgid "The text is a Fully Qualified Domain Name, with both hostname and domain name parts."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5859
	+msgid "<literal>class=\"ipaddress\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5862
	+msgid "The text is an <acronym>IP</acronym> address, probably expressed as a dotted quad."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5868
	+msgid "<literal>class=\"netmask\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5871
	+msgid "The text is a network mask, which might be expressed as a dotted quad, a hexadecimal string, or as a <literal>/</literal> followed by a number (<acronym>CIDR</acronym> notation)."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5879
	+msgid "<literal>class=\"systemname\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5882
	+msgid "With <literal>class=\"systemname\"</literal> the marked up information is the simple hostname, such as <literal>freefall</literal> or <literal>wcarchive</literal>."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5890
	+msgid "<literal>class=\"username\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5893
	+msgid "The text is a username, like <literal>root</literal>."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:5899
	+msgid "<literal>class=\"groupname\"</literal>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:5902
	+msgid "The text is a groupname, like <literal>wheel</literal>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5909
	+msgid "<tag>systemitem</tag> and Classes Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5913
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>The local machine can always be referred to by the\n"
	+" name <tag class=\"starttag\">systemitem class=\"systemname\"</tag>localhost<tag class=\"endtag\">systemitem</tag>, which will have the IP\n"
	+" address <tag class=\"starttag\">systemitem class=\"ipaddress\"</tag>127.0.0.1<tag class=\"endtag\">systemitem</tag>.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>The <tag class=\"starttag\">systemitem class=\"domainname\"</tag>FreeBSD.org<tag class=\"endtag\">systemitem</tag>\n"
	+" domain contains a number of different hosts, including\n"
	+" <tag class=\"starttag\">systemitem class=\"fqdomainname\"</tag>freefall.FreeBSD.org<tag class=\"endtag\">systemitem</tag> and\n"
	+" <tag class=\"starttag\">systemitem class=\"fqdomainname\"</tag>bento.FreeBSD.org<tag class=\"endtag\">systemitem</tag>.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>When adding an <tag class=\"starttag\">acronym</tag>IP<tag class=\"endtag\">acronym</tag> alias to an\n"
	+" interface (using <tag class=\"starttag\">command</tag>ifconfig<tag class=\"endtag\">command</tag>)\n"
	+" <tag class=\"starttag\">emphasis</tag>always<tag class=\"endtag\">emphasis</tag> use a netmask of\n"
	+" <tag class=\"starttag\">systemitem class=\"netmask\"</tag>255.255.255.255<tag class=\"endtag\">systemitem</tag> (which can\n"
	+" also be expressed as\n"
	+" <tag class=\"starttag\">systemitem class=\"netmask\"</tag>0xffffffff<tag class=\"endtag\">systemitem</tag>).<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>The <tag class=\"starttag\">acronym</tag>MAC<tag class=\"endtag\">acronym</tag> address uniquely identifies\n"
	+" every network card in existence. A typical\n"
	+" <tag class=\"starttag\">acronym</tag>MAC<tag class=\"endtag\">acronym</tag> address looks like\n"
	+" <tag class=\"starttag\">systemitem class=\"etheraddress\"</tag>08:00:20:87:ef:d0<tag class=\"endtag\">systemitem</tag>.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>To carry out most system administration functions\n"
	+" requires logging in as <tag class=\"starttag\">systemitem class=\"username\"</tag>root<tag class=\"endtag\">systemitem</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5939
	+msgid "The local machine can always be referred to by the name <systemitem>localhost</systemitem>, which will have the IP address <systemitem class=\"ipaddress\">127.0.0.1</systemitem>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5944
	+msgid "The <systemitem class=\"fqdomainname\">FreeBSD.org</systemitem> domain contains a number of different hosts, including <systemitem class=\"fqdomainname\">freefall.FreeBSD.org</systemitem> and <systemitem class=\"fqdomainname\">bento.FreeBSD.org</systemitem>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5950
	+msgid "When adding an <acronym>IP</acronym> alias to an interface (using <command>ifconfig</command>) <emphasis>always</emphasis> use a netmask of <systemitem class=\"netmask\">255.255.255.255</systemitem> (which can also be expressed as <systemitem class=\"netmask\">0xffffffff</systemitem>)."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5957
	+msgid "The <acronym>MAC</acronym> address uniquely identifies every network card in existence. A typical <acronym>MAC</acronym> address looks like <systemitem class=\"etheraddress\">08:00:20:87:ef:d0</systemitem>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5961
	+msgid "To carry out most system administration functions requires logging in as <systemitem class=\"username\">root</systemitem>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5968
	+msgid "Uniform Resource Identifiers (<acronym>URI</acronym>s)"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5971
	+msgid "Occasionally it is useful to show a Uniform Resource Identifier (<acronym>URI</acronym>) without making it an active hyperlink. The <tag>uri</tag> element makes this possible:"
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:5977
	+msgid "<tag>uri</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:5981
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>This <acronym>URL</acronym> shows only as text:\n"
	+" <tag class=\"starttag\">uri</tag>https://www.FreeBSD.org<tag class=\"endtag\">uri</tag>. It does not\n"
	+" create a link.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:5987
	+msgid "This <acronym>URL</acronym> shows only as text: <uri>https://www.FreeBSD.org</uri>. It does not create a link."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5992
	+msgid "To create links, see <xref linkend=\"docbook-markup-links\"/>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:5997
	+msgid "Email Addresses"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:5999
	+msgid "Email addresses are marked up as <tag>email</tag> elements. In the <acronym>HTML</acronym> output format, the wrapped text becomes a hyperlink to the email address. Other output formats that support hyperlinks may also make the email address into a link."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6006
	+msgid "<tag>email</tag> with a Hyperlink Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6010
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>An email address that does not actually exist, like\n"
	+" <tag class=\"starttag\">email</tag>notreal@example.com<tag class=\"endtag\">email</tag>, can be used as an\n"
	+" example.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6016
	+msgid "An email address that does not actually exist, like <email>notreal@example.com</email>, can be used as an example."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6021
	+msgid "A FreeBSD-specific extension allows setting the <literal>role</literal> attribute to <literal>nolink</literal> to prevent the creation of the hyperlink to the email address."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6027
	+msgid "<tag>email</tag> Without a Hyperlink Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6031
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Sometimes a link to an email address like\n"
	+" <tag class=\"starttag\">email role=\"nolink\"</tag>notreal@example.com<tag class=\"endtag\">email</tag> is not\n"
	+" desired.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6037
	+msgid "Sometimes a link to an email address like <email role=\"nolink\">notreal@example.com</email> is not desired."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6044
	+msgid "Describing <filename>Makefile</filename>s"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6054
	+msgid "Two elements exist to describe parts of <filename>Makefile</filename>s, <tag>buildtarget</tag> and <tag>varname</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6058
	+msgid "<tag>buildtarget</tag> identifies a build target exported by a <filename>Makefile</filename> that can be given as a parameter to <command>make</command>. <tag>varname</tag> identifies a variable that can be set (in the environment, on the command line with <command>make</command>, or within the <filename>Makefile</filename>) to influence the process."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6068
	+msgid "<tag>buildtarget</tag> and <tag>varname</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6073
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Two common targets in a <tag class=\"starttag\">filename</tag>Makefile<tag class=\"endtag\">filename</tag>\n"
	+" are <tag class=\"starttag\">buildtarget</tag>all<tag class=\"endtag\">buildtarget</tag> and\n"
	+" <tag class=\"starttag\">buildtarget</tag>clean<tag class=\"endtag\">buildtarget</tag>.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>Typically, invoking <tag class=\"starttag\">buildtarget</tag>all<tag class=\"endtag\">buildtarget</tag> will\n"
	+" rebuild the application, and invoking\n"
	+" <tag class=\"starttag\">buildtarget</tag>clean<tag class=\"endtag\">buildtarget</tag> will remove the temporary\n"
	+" files (<tag class=\"starttag\">filename</tag>.o<tag class=\"endtag\">filename</tag> for example) created by the\n"
	+" build process.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag><tag class=\"starttag\">buildtarget</tag>clean<tag class=\"endtag\">buildtarget</tag> may be controlled by a\n"
	+" number of variables, including <tag class=\"starttag\">varname</tag>CLOBBER<tag class=\"endtag\">varname</tag>\n"
	+" and <tag class=\"starttag\">varname</tag>RECURSE<tag class=\"endtag\">varname</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: para/buildtarget
	+#: book.translate.xml:6090 book.translate.xml:6093
	+msgid "all"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6089
	+msgid "Two common targets in a <filename>Makefile</filename> are <_:buildtarget-1/> and <_:buildtarget-2/>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6093
	+msgid "Typically, invoking <_:buildtarget-1/> will rebuild the application, and invoking <_:buildtarget-2/> will remove the temporary files (<filename>.o</filename> for example) created by the build process."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6099
	+msgid "<_:buildtarget-1/> may be controlled by a number of variables, including <varname>CLOBBER</varname> and <varname>RECURSE</varname>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6106
	+msgid "Literal Text"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6108
	+msgid "Literal text, or text which should be entered verbatim, is often needed in documentation. This is text that is excerpted from another file, or which should be copied exactly as shown from the documentation into another file."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6113
	+msgid "Some of the time, <tag>programlisting</tag> will be sufficient to denote this text. But <tag>programlisting</tag> is not always appropriate, particularly when you want to include a portion of a file <quote>in-line</quote> with the rest of the paragraph."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6120
	+msgid "On these occasions, use <tag>literal</tag>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6124
	+msgid "<tag>literal</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6128
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>The <tag class=\"starttag\">literal</tag>maxusers 10<tag class=\"endtag\">literal</tag> line in the kernel\n"
	+" configuration file determines the size of many system tables, and is\n"
	+" a rough guide to how many simultaneous logins the system will\n"
	+" support.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6135
	+msgid "The <literal>maxusers 10</literal> 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 support."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6143
	+msgid "Showing Items That the User <emphasis>Must</emphasis> Fill In"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6146
	+msgid "There will often be times when the user is shown what to do, or referred to a file or command line, but cannot simply copy the example provided. Instead, they must supply some information themselves."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6151
	+msgid "<tag>replaceable</tag> is designed for this eventuality. Use it <emphasis>inside</emphasis> other elements to indicate parts of that element's content that the user must replace."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6157
	+msgid "<tag>replaceable</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6161
	+#, no-wrap
	+msgid "<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>"
	+msgstr ""
	+
	+#. (itstool) path: informalexample/screen
	+#: book.translate.xml:6166
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>man <replaceable>command</replaceable></userinput>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6169
	+msgid "<tag>replaceable</tag> can be used in many different elements, including <tag>literal</tag>. This example also shows that <tag>replaceable</tag> should only be wrapped around the content that the user <emphasis>is</emphasis> meant to provide. The other content should be left alone."
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6178
	+#, no-wrap
	+msgid ""
	+"<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>\n"
	+" line in the kernel configuration file determines the size of many system\n"
	+" tables, and is a rough guide to how many simultaneous logins the system will\n"
	+" support.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>For a desktop workstation, <tag class=\"starttag\">literal</tag>32<tag class=\"endtag\">literal</tag> is a good value\n"
	+" for <tag class=\"starttag\">replaceable</tag>n<tag class=\"endtag\">replaceable</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6188
	+msgid "The <literal>maxusers <replaceable>n</replaceable></literal> 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 support."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6194
	+msgid "For a desktop workstation, <literal>32</literal> is a good value for <replaceable>n</replaceable>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6200
	+msgid "Showing <acronym>GUI</acronym> Buttons"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6202
	+msgid "Buttons presented by a graphical user interface are marked with <tag>guibutton</tag>. To make the text look more like a graphical button, brackets and non-breaking spaces are added surrounding the text."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6208
	+msgid "<tag>guibutton</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6212
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Edit the file, then click\n"
	+" <tag class=\"starttag\">guibutton</tag>[&nbsp;Save&nbsp;]<tag class=\"endtag\">guibutton</tag> to save the\n"
	+" changes.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6218
	+msgid "Edit the file, then click <guibutton>[ Save ]</guibutton> to save the changes."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6225
	+msgid "Quoting System Errors"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6227
	+msgid "System errors generated by FreeBSD are marked with <tag>errorname</tag>. This indicates the exact error that appears."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6232
	+msgid "<tag>errorname</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6236
	+#, no-wrap
	+msgid "<tag class=\"starttag\">screen</tag><tag class=\"starttag\">errorname</tag>Panic: cannot mount root<tag class=\"endtag\">errorname</tag><tag class=\"endtag\">screen</tag>"
	+msgstr ""
	+
	+#. (itstool) path: informalexample/screen
	+#: book.translate.xml:6241
	+#, no-wrap
	+msgid "<errorname>Panic: cannot mount root</errorname>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:6248
	+msgid "Images"
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:6251
	+msgid "Image support in the documentation is somewhat experimental. The mechanisms described here are unlikely to change, but that is not guaranteed."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:6255
	+msgid "To provide conversion between different image formats, the <package>graphics/ImageMagick</package> port must be installed. This port is not included in the <package>textproc/docproj</package> meta port, and must be installed separately."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:6261
	+msgid "A good example of the use of images is the <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> document. Examine the files in that directory to see how these elements are used together. Build different output formats to see how the format determines what images are shown in the rendered document."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6270
	+msgid "Image Formats"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6272
	+msgid "The following image formats are currently supported. An image file will automatically be converted to bitmap or vector image depending on the output document format."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6276
	+msgid "These are the <emphasis>only</emphasis> formats in which images should be committed to the documentation repository."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:6282
	+msgid "<acronym>EPS</acronym> (Encapsulated Postscript)"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6286
	+msgid "Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in this format. These images have a <filename>.eps</filename> extension."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:6294
	+msgid "<acronym>PNG</acronym> (Portable Network Graphic)"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6298
	+msgid "For bitmaps, such as screen captures, use this format. These images have the <filename>.png</filename> extension."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:6305
	+msgid "<acronym>PIC</acronym> (PIC graphics language)"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6308
	+msgid "<acronym>PIC</acronym> is a language for drawing simple vector-based figures used in the <citerefentry><refentrytitle>pic</refentrytitle><manvolnum>1</manvolnum></citerefentry> utility. These images have the <filename>.pic</filename> extension."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:6316
	+msgid "<acronym>SCR</acronym> (SCReen capture)"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6319
	+msgid "This format is specific to screenshots of console output. The following command generates an SCR file <filename>shot.scr</filename> from video buffer of <filename>/dev/ttyv0</filename>:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/screen
	+#: book.translate.xml:6324
	+#, no-wrap
	+msgid "<prompt>#</prompt> <userinput><command>vidcontrol -p</command> < <filename><replaceable>/dev/ttyv0</replaceable></filename> > <filename><replaceable>shot.scr</replaceable></filename></userinput>"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6326
	+msgid "This is preferable to <acronym>PNG</acronym> format for screenshots because the <acronym>SCR</acronym> file contains plain text of the command lines so that it can be converted to a <acronym>PNG</acronym> image or a plain text depending on the output document format."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6336
	+msgid "Use the appropriate format for each image. Documentation will often have a mix of <acronym>EPS</acronym> and <acronym>PNG</acronym> images. The <filename>Makefile</filename>s ensure that the correct format image is chosen depending on the output format used. <emphasis>Do not commit the same image to the repository in two different formats</emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: important/para
	+#: book.translate.xml:6345
	+msgid "The Documentation Project may eventually switch to using the <acronym>SVG</acronym> (Scalable Vector Graphic) format for vector images. However, the current state of <acronym>SVG</acronym> capable editing tools makes this impractical."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6354
	+msgid "Image File Locations"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6356
	+msgid "Image files can be stored in one of several locations, depending on the document and image:"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6361
	+msgid "In the same directory as the document itself, usually done for articles and small books that keep all their files in a single directory."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6367
	+msgid "In a subdirectory of the main document. Typically done when a large book uses separate subdirectories to organize individual chapters."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6371
	+msgid "When images are stored in a subdirectory of the main document directory, the subdirectory name must be included in their paths in the <filename>Makefile</filename> and the <tag>imagedata</tag> element."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:6379
	+msgid "In a subdirectory of <filename>doc/share/images</filename> named after the document. For example, images for the Handbook are stored in <filename>doc/share/images/books/handbook</filename>. Images that work for multiple translations are stored in this upper level of the documentation file tree. Generally, these are images that can be used unchanged in non-English translations of the document."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6392
	+msgid "Image Markup"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6394
	+msgid "Images are included as part of a <tag>mediaobject</tag>. The <tag>mediaobject</tag> can contain other, more specific objects. We are concerned with two, the <tag>imageobject</tag> and the <tag>textobject</tag>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6399
	+msgid "Include one <tag>imageobject</tag>, and two <tag>textobject</tag> elements. The <tag>imageobject</tag> will point to the name of the image file without the extension. The <tag>textobject</tag> elements contain information that will be presented to the user as well as, or instead of, the image itself."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6406
	+msgid "Text elements are shown to the reader in several situations. When the document is viewed in <acronym>HTML</acronym>, text elements are shown while the image is loading, or if the mouse pointer is hovered over the image, or if a text-only browser is being used. In formats like plain text where graphics are not possible, the text elements are shown instead of the graphical ones."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6414
	+msgid "This example shows how to include an image called <filename>fig1.png</filename> in a document. The image is a rectangle with an A inside it:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:6418
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">mediaobject</tag>\n"
	+" <tag class=\"starttag\">imageobject</tag>\n"
	+" <tag class=\"emptytag\">imagedata fileref=\"fig1\"</tag> <co xml:id=\"co-image-ext\"/>\n"
	+" <tag class=\"endtag\">imageobject</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">textobject</tag>\n"
	+" <tag class=\"starttag\">literallayout class=\"monospaced\"</tag>+---------------+ <co xml:id=\"co-image-literal\"/>\n"
	+"\| A \|\n"
	+"+---------------+<tag class=\"endtag\">literallayout</tag>\n"
	+" <tag class=\"endtag\">textobject</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">textobject</tag>\n"
	+" <tag class=\"starttag\">phrase</tag>A picture<tag class=\"endtag\">phrase</tag> <co xml:id=\"co-image-phrase\"/>\n"
	+" <tag class=\"endtag\">textobject</tag>\n"
	+"<tag class=\"endtag\">mediaobject</tag>"
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:6436
	+msgid "Include an <tag>imagedata</tag> element inside the <tag>imageobject</tag> element. The <literal>fileref</literal> attribute should contain the filename of the image to include, without the extension. The stylesheets will work out which extension should be added to the filename automatically."
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:6446
	+msgid "The first <tag>textobject</tag> contains a <tag>literallayout</tag> element, where the <literal>class</literal> attribute is set to <literal>monospaced</literal>. This is an opportunity to demonstrate <acronym>ASCII</acronym> art skills. This content will be used if the document is converted to plain text."
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:6454
	+msgid "Notice how the first and last lines of the content of the <tag>literallayout</tag> element butt up next to the element's tags. This ensures no extraneous white space is included."
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:6461
	+msgid "The second <tag>textobject</tag> contains a single <tag>phrase</tag> element. The contents of this phrase will become the <literal>alt</literal> attribute for the image when this document is converted to <acronym>HTML</acronym>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6471
	+msgid "Image <filename>Makefile</filename> Entries"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6473
	+msgid "Images must be listed in the <filename>Makefile</filename> in the <varname>IMAGES</varname> variable. This variable must contain the names of all the <emphasis>source</emphasis> images. For example, if there are three figures, <filename>fig1.eps</filename>, <filename>fig2.png</filename>, <filename>fig3.png</filename>, then the <filename>Makefile</filename> should have lines like this in it."
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:6482
	+#, no-wrap
	+msgid ""
	+"…\n"
	+"IMAGES= fig1.eps fig2.png fig3.png\n"
	+"…"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#. (itstool) path: question/para
	+#: book.translate.xml:6486 book.translate.xml:7074
	+msgid "or"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:6488
	+#, no-wrap
	+msgid ""
	+"…\n"
	+"IMAGES= fig1.eps\n"
	+"IMAGES+= fig2.png\n"
	+"IMAGES+= fig3.png\n"
	+"…"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6494
	+msgid "Again, the <filename>Makefile</filename> will work out the complete list of images it needs to build the source document, you only need to list the image files <emphasis>you</emphasis> provided."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6501
	+msgid "Images and Chapters in Subdirectories"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6503
	+msgid "Be careful when separating documentation into smaller files in different directories (see <xref linkend=\"xml-primer-include-using-gen-entities\"/>)."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6506
	+msgid ""
	+"Suppose there is a book with three chapters, and the chapters are stored in their own directories, called <filename>chapter1/chapter.xml</filename>, <filename>chapter2/chapter.xml</filename>, and <filename>chapter3/chapter.xml</filename>. If each chapter has images associated with it, place those images in each chapter's subdirectory (<filename>chapter1/</filename>, <filename>chapter2/</filename>, and "
	+"<filename>chapter3/</filename>)."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6516
	+msgid "However, doing this requires including the directory names in the <varname>IMAGES</varname> variable in the <filename>Makefile</filename>, <emphasis>and</emphasis> including the directory name in the <tag>imagedata</tag> element in the document."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6522
	+msgid "For example, if the book has <filename>chapter1/fig1.png</filename>, then <filename>chapter1/chapter.xml</filename> should contain:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:6527
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">mediaobject</tag>\n"
	+" <tag class=\"starttag\">imageobject</tag>\n"
	+" <tag class=\"emptytag\">imagedata fileref=\"chapter1/fig1\"</tag> <co xml:id=\"co-image-dir\"/>\n"
	+" <tag class=\"endtag\">imageobject</tag>\n"
	+"\n"
	+" …\n"
	+"\n"
	+"<tag class=\"endtag\">mediaobject</tag>"
	+msgstr ""
	+
	+#. (itstool) path: callout/para
	+#: book.translate.xml:6538
	+msgid "The directory name must be included in the <literal>fileref</literal> attribute."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6543
	+msgid "The <filename>Makefile</filename> must contain:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:6545
	+#, no-wrap
	+msgid ""
	+"…\n"
	+"IMAGES= chapter1/fig1.png\n"
	+"…"
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:6555
	+msgid "Links are also in-line elements. To show a <acronym>URI</acronym> without creating a link, see <xref linkend=\"docbook-markup-uri\"/>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6561
	+msgid "<literal>xml:id</literal> Attributes"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6563
	+msgid "Most DocBook elements accept an <literal>xml:id</literal> attribute to give that part of the document a unique name. The <literal>xml:id</literal> can be used as a target for a crossreference or link."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6568
	+msgid "Any portion of the document that will be a link target must have an <literal>xml:id</literal> attribute. Assigning an <literal>xml:id</literal> to all chapters and sections, 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 reference points by anyone referring to the <acronym>HTML</acronym> version of the document."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6577
	+msgid "<literal>xml:id</literal> on Chapters and Sections Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6580
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">chapter xml:id=\"introduction\"</tag>\n"
	+" <tag class=\"starttag\">title</tag>Introduction<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the introduction. It contains a subsection,\n"
	+" which is identified as well.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1 xml:id=\"introduction-moredetails\"</tag>\n"
	+" <tag class=\"starttag\">title</tag>More Details<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is a subsection.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">chapter</tag>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6594
	+msgid ""
	+"Use descriptive values for <literal>xml:id</literal> names. The values must be unique within the entire document, not just in a single file. In the example, the subsection <literal>xml:id</literal> is constructed by appending text to the chapter <literal>xml:id</literal>. This ensures that the <literal>xml:id</literal>s are unique. It also helps both reader and anyone editing the document to see where the "
	+"link is located within the document, similar to a directory path to a file."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6606
	+msgid "Crossreferences with <literal>xref</literal>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6608
	+msgid "<tag>xref</tag> provides the reader with a link to jump to another section of the document. The target <literal>xml:id</literal> is specified in the <literal>linkend</literal> attribute, and <tag>xref</tag> generates the link text automatically."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6615
	+msgid "<tag>xref</tag> Example"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6617
	+msgid "Assume that this fragment appears somewhere in a document that includes the <literal>xml:id</literal> example shown above:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6621
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>More information can be found\n"
	+" in <tag class=\"emptytag\">xref linkend=\"introduction\"</tag>.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>More specific information can be found\n"
	+" in <tag class=\"emptytag\">xref linkend=\"introduction-moredetails\"</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6627
	+msgid "The link text will be generated automatically, looking like (<emphasis>emphasized</emphasis> text indicates the link text):"
	+msgstr ""
	+
	+#. (itstool) path: blockquote/para
	+#: book.translate.xml:6632
	+msgid "More information can be found in <emphasis>Chapter 1, Introduction</emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: blockquote/para
	+#: book.translate.xml:6635
	+msgid "More specific information can be found in <emphasis>Section 1.1, <quote>More Details</quote></emphasis>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6641
	+msgid "The link text is generated automatically from the chapter and section number and <literal>title</literal> elements."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6650
	+msgid ""
	+"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 to give the reader an idea of where the link goes. Remember that DocBook can be rendered to multiple 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 text is not descriptive enough, the reader might "
	+"not be able to locate the linked section."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6659
	+msgid "The <literal>xlink:href</literal> attribute is the <acronym>URL</acronym> of the page, and the content of the element is the text that will be displayed for the user to activate."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6664
	+msgid "In many situations, it is preferable to show the actual <acronym>URL</acronym> rather than text. This can be done by leaving out the element text entirely."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6669
	+msgid "<tag>link</tag> to a FreeBSD Documentation Web Page Example"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6672
	+msgid "Link to the book or article <acronym>URL</acronym> entity. To link to a specific chapter in a book, add a slash and the chapter file name, followed by an optional anchor within the chapter. For articles, link to the article <acronym>URL</acronym> entity, followed by an optional anchor within the article. <acronym>URL</acronym> entities can be found in <filename>doc/share/xml/urls.ent</filename>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6681
	+msgid "Usage for FreeBSD book links:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6683
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Read the <tag class=\"starttag\">link\n"
	+" xlink:href=\"&url.books.handbook;/svn.html#svn-intro\"</tag>SVN\n"
	+" introduction<tag class=\"endtag\">link</tag>, then pick the nearest mirror from\n"
	+" the list of <tag class=\"starttag\">link\n"
	+" xlink:href=\"&url.books.handbook;/svn.html#svn-mirrors\"</tag>Subversion\n"
	+" mirror sites<tag class=\"endtag\">link</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6692
	+msgid "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 the list of <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors\">Subversion mirror sites</link>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6697
	+msgid "Usage for FreeBSD article links:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6699
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Read this\n"
	+" <tag class=\"starttag\">link xlink:href=\"&url.articles.bsdl-gpl;\"</tag>article\n"
	+" about the BSD license<tag class=\"endtag\">link</tag>, or just the\n"
	+" <tag class=\"starttag\">link xlink:href=\"&url.articles.bsdl-gpl;#intro\"</tag>introduction<tag class=\"endtag\">link</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6706
	+msgid "Read this <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>."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6712
	+msgid "<tag>link</tag> to a FreeBSD Web Page Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6716
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Of course, you could stop reading this document and go to the\n"
	+" <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>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6721
	+msgid "Of course, you could stop reading this document and go to the <link xlink:href=\"@@URL_RELPREFIX@@/index.html\">FreeBSD home page</link> instead."
	+msgstr ""
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:6727
	+msgid "<tag>link</tag> to an External Web Page Example"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6732
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Wikipedia has an excellent reference on\n"
	+" <tag class=\"starttag\">link\n"
	+" xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\"</tag>GUID\n"
	+" Partition Tables<tag class=\"endtag\">link</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6739
	+msgid "Wikipedia has an excellent reference on <link xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\">GUID Partition Tables</link>."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6742
	+msgid "The link text can be omitted to show the actual URL:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6745
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Wikipedia has an excellent reference on\n"
	+" GUID Partition Tables: <tag class=\"starttag\">link\n"
	+" xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\"</tag><tag class=\"endtag\">link</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6749
	+msgid "The same link can be entered using shorter notation instead of a separate ending tag:"
	+msgstr ""
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:6752
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>Wikipedia has an excellent reference on\n"
	+" GUID Partition Tables: <tag class=\"emptytag\">link\n"
	+" xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\"</tag>.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6756
	+msgid "The two methods are equivalent. Appearance:"
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:6758
	+msgid "Wikipedia has an excellent reference on GUID Partition Tables: <uri xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>."
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:6798
	+msgid "Style Sheets"
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:6800
	+msgid ""
	+"<acronym>XML</acronym> is concerned with content, and says nothing about how that content should be presented to the reader or rendered on paper. Multiple <emphasis>style sheet</emphasis> languages have been developed to describe visual layout, including Extensible Stylesheet Language Transformation (<acronym>XSLT</acronym>), Document Style Semantics and Specification Language (<acronym>DSSSL</acronym>), and "
	+"Cascading Style Sheets (<acronym>CSS</acronym>)."
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:6809
	+msgid "The <acronym>FDP</acronym> documents use <acronym>XSLT</acronym> stylesheets to transform DocBook into <acronym>XHTML</acronym>, and then <acronym>CSS</acronym> formatting is applied to the <acronym>XHTML</acronym> pages. Printable output is currently rendered with legacy <acronym>DSSSL</acronym> stylesheets, but this will probably change in the future."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:6818
	+msgid "<acronym>CSS</acronym>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:6820
	+msgid "Cascading Style Sheets (<acronym>CSS</acronym>) are a mechanism for attaching style information (font, weight, size, color, and so forth) to elements in an <acronym>XHTML</acronym> document without abusing <acronym>XHTML</acronym> to do so."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:6827
	+msgid "The DocBook Documents"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:6829
	+msgid ""
	+"The FreeBSD <acronym>XSLT</acronym> and <acronym>DSSSL</acronym> stylesheets refer to <filename>docbook.css</filename>, which is expected to be present in the same directory as the <acronym>XHTML</acronym> files. The project-wide <acronym>CSS</acronym> file is copied from <filename>doc/share/misc/docbook.css</filename> when documents are converted to <acronym>XHTML</acronym>, and is installed automatically."
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:6874
	+msgid "Translations"
	+msgstr "翻譯"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:6876
	+msgid "This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, manual pages, and others) to different languages."
	+msgstr "本章是翻譯 FreeBSD 文件(包含：FAQ, Handbook, tutorials, manual pages等)的常見問題(FAQ)。"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:6880
	+msgid "It is <emphasis>very</emphasis> heavily based on the translation FAQ from the FreeBSD German Documentation Project, originally written by Frank Gründer <email>elwood@mc5sys.in-berlin.de</email> and translated back to English by Bernd Warken <email>bwarken@mayn.de</email>."
	+msgstr "本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文翻譯計劃的翻譯 FAQ 為母本而來的，原始撰稿者為 Frank Gründer <email>elwood@mc5sys.in-berlin.de</email>，並由 Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:6886
	+msgid "The FAQ is maintained by the Documentation Engineering Team <email>doceng@FreeBSD.org</email>."
	+msgstr "本 FAQ 是由文件工程團隊 <email>doceng@FreeBSD.org</email> 所維護。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:6891
	+msgid "What do <phrase>i18n</phrase> and <phrase>l10n</phrase> mean?"
	+msgstr "<phrase>i18n</phrase> 跟 <phrase>l10n</phrase> 是什麼呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6896
	+msgid "<phrase>i18n</phrase> means <phrase>internationalization</phrase> and <phrase>l10n</phrase> means <phrase>localization</phrase>. They are just a convenient shorthand."
	+msgstr "<phrase>i18n</phrase> 是 <phrase>internationalization</phrase> 而 <phrase>l10n</phrase> 是 <phrase>localization</phrase>。這些都是為了書寫方便而用的簡寫。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6901
	+msgid "<phrase>i18n</phrase> can be read as <quote>i</quote> followed by 18 letters, followed by <quote>n</quote>. Similarly, <phrase>l10n</phrase> is <quote>l</quote> followed by 10 letters, followed by <quote>n</quote>."
	+msgstr "<phrase>i18n</phrase> 就是開頭為 <quote>i</quote> 後面有 18 個字母，最後接 <quote>n</quote>。同樣地， <phrase>l10n</phrase> 是開頭為 <quote>l</quote> 後面有 10 個字母，最後接 <quote>n</quote>。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:6910
	+msgid "Is there a mailing list for translators?"
	+msgstr "有專門給譯者參與討論的 mailing list 嗎？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6914
	+msgid "Yes. Different translation groups have their own mailing lists. The <link xlink:href=\"http://www.freebsd.org/docproj/translations.html\">list of translation projects</link> has more information about the mailing lists and web sites run by each translation project. In addition there is <email>freebsd-translators@freebsd.org</email> for general translation discussion."
	+msgstr "有的，不同的語系翻譯者都各自有自屬的 mailing lists。這份 <link xlink:href=\"http://www.freebsd.org/docproj/translations.html\"> 翻譯計劃清單</link> 有列出各翻譯計劃的詳細 mailing lists 及相關網站。此外，有一般翻譯討論的<email>freebsd-translators@freebsd.org</email>郵件論壇。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:6926
	+msgid "Are more translators needed?"
	+msgstr "需要更多人一起參與翻譯嗎？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6930
	+msgid "Yes. The more people work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents."
	+msgstr "當然囉，越多人參與翻譯，那麼就能夠越快翻完，而且英文版文件若有增減、更新的話，各翻譯版也可以儘快同步囉。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6935
	+msgid "You do not have to be a professional translator to be able to help."
	+msgstr "不一定得是專業譯者，才能參與翻譯的。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:6942
	+msgid "What languages do I need to know?"
	+msgstr "有要求哪些語言能力呢"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6946
	+msgid "Ideally, you will have a good knowledge of written English, and obviously you will need to be fluent in the language you are translating to."
	+msgstr "理論上，必須要對英文非常熟稔，而且很明顯地，對想翻譯的語言必須要能運用自如。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6950
	+msgid "English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation."
	+msgstr "英文也並非一定要會的。比如說，可以把西班牙文(Spanish)的 FAQ 翻譯為匈牙利文(Hungarian)。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:6958
	+msgid "What software do I need to know?"
	+msgstr "該學會哪些程式的使用呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6962
	+msgid "It is strongly recommended that you maintain a local copy of the FreeBSD Subversion repository (at least the documentation part). This can be done by running:"
	+msgstr "強烈建議在自己機器上也建立 FreeBSD Subversion repository 的備份(至少文件部分)，這可以執行："
	+
	+#. (itstool) path: answer/screen
	+#: book.translate.xml:6966
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput>"
	+msgstr "<prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput>"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6968
	+msgid "<link xlink:href=\"https://svn.FreeBSD.org/\">svn.FreeBSD.org</link> is a public <literal>SVN</literal> server. Verify the server certificate from the list of <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors\">Subversion mirror sites</link>."
	+msgstr "<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>清單檢查認證的伺服器。"
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:6975
	+msgid "This will require the <package>devel/subversion</package> package to be installed."
	+msgstr "這需要安裝<package>devel/subversion</package> 套件。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6979
	+msgid "You should be comfortable using <application>svn</application>. This will allow you to see what has changed between different versions of the files that make up the documentation."
	+msgstr "你可以很自在地使用<application>svn</application>。他可以讓你察看文件檔案不同版本之間的修改差異。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:6984
	+msgid "For example, to view the differences between revisions <literal>r33733</literal> and <literal>r33734</literal> of <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>, run:"
	+msgstr "例如你要看<filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename> 版本<literal>r33733</literal> 和 <literal>r33734</literal> 的差異，請執行："
	+
	+#. (itstool) path: answer/screen
	+#: book.translate.xml:6989
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput>"
	+msgstr "<prompt>%</prompt> <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput>"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:6995
	+msgid "How do I find out who else might be translating to the same language?"
	+msgstr "要怎麼找出來還有誰要跟我一起翻譯的呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7000
	+msgid "The <link xlink:href=\"http://www.FreeBSD.org/docproj/translations.html\">Documentation Project translations page</link> lists the translation efforts that are currently known about. If others are already working on translating documentation to your language, please do not duplicate their efforts. Instead, contact them to see how you can help."
	+msgstr "<link xlink:href=\"http://www.FreeBSD.org/docproj/translations.html\">文件計劃的翻譯 </link> 列了目前已知的各翻譯者成果，如果已經有其他人也在做跟你一樣的翻譯工作，那麼請不要重複浪費人力，請與他們聯繫看看還有哪些地方可以幫上忙的。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7007
	+msgid "If no one is listed on that page as translating for your language, then send a message to the <link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project mailing list</link> in case someone else is thinking of doing a translation, but has not announced it yet."
	+msgstr "若上面並未列出你母語的翻譯，或是也有人要翻譯但還未公開宣布的話，那麼就寄信到 <link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project 郵遞論壇 </link>。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7016
	+msgid "No one else is translating to my language. What do I do?"
	+msgstr "都沒人翻譯為我所使用的語言，該怎麼辦？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7021
	+msgid "Congratulations, you have just started the <quote>FreeBSD <replaceable>your-language-here</replaceable> Documentation Translation Project</quote>. Welcome aboard."
	+msgstr "恭喜啊，你剛好踏上 <quote>FreeBSD <replaceable>你的母語</replaceable> 文件翻譯計劃</quote>的啟程之路，歡迎上船。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7026
	+msgid "First, decide whether or not you have got the time to spare. Since you are the only person working on your language at the moment it is going to be your responsibility to publicize your work and coordinate any volunteers that might want to help you."
	+msgstr "首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已，因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7032
	+msgid "Write an email to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained."
	+msgstr "寫信到 FreeBSD documentation project 郵遞論壇向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7037
	+msgid "If there is already someone in your country providing FreeBSD mirroring services you should contact them and ask if you can have some webspace for your project, and possibly an email address or mailing list services."
	+msgstr "若你的國家已經有人提供 FreeBSD 的 mirror(映設) 服務的話，那麼就先跟他們聯繫，並詢問你是否在上面可以有網頁空間來放相關計劃資料，以及是否可以有提供 email 帳號或 mailing list 服務。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7042
	+msgid "Then pick a document and start translating. It is best to start with something fairly small—either the FAQ, or one of the tutorials."
	+msgstr "然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦，或是如何上手之類的說明文章。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7050
	+msgid "I have translated some documentation, where do I send it?"
	+msgstr "已經翻好一些文件了，該寄到哪呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7055
	+msgid "That depends. If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages."
	+msgstr "這要看情況而定。若你是在翻譯團隊內做的話(像是日本、德國)，他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7061
	+msgid "If you are the only person working on a particular language (or you are responsible for a translation project and want to submit your changes back to the FreeBSD project) then you should send your translation to the FreeBSD project (see the next question)."
	+msgstr "若你是某語系的唯一翻譯者(或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃) ，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7071
	+msgid "I am the only person working on translating to this language, how do I submit my translation?"
	+msgstr "我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7076
	+msgid "We are a translation team, and want to submit documentation that our members have translated for us."
	+msgstr "我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7082
	+msgid "First, make sure your translation is organized properly. This means that it should drop into the existing documentation tree and build straight away."
	+msgstr "首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說：把它擺到現有文件架構內是可以正確編譯成功的。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7086
	+msgid "Currently, the FreeBSD documentation is stored in a top level directory called <filename>head/</filename>. Directories below this are named according to the language code they are written in, as defined in ISO639 (<filename>/usr/share/misc/iso639</filename> on a version of FreeBSD newer than 20th January 1999)."
	+msgstr "目前，FreeBSD 文件都是放在最上層的 <filename>head/</filename> 目錄內。而該目錄下的則依其語系來做分類命名的，依照 ISO639 定義(在比比 1999/01/20 還新的 FreeBSD 版本的/usr/share/misc/iso639 )。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7093
	+msgid "If your language can be encoded in different ways (for example, Chinese) then there should be directories below this, one for each encoding format you have provided."
	+msgstr "若你這個語系可能會有不同編碼方式(像是：中文) 那麼就應該會像下面這樣，來依你所使用的編碼方式細分"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7097
	+msgid "Finally, you should have directories for each document."
	+msgstr "最後，你應該建立好各文件的目錄了。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7100
	+msgid "For example, a hypothetical Swedish translation might look like:"
	+msgstr "舉例來說，假設有瑞典文(Swedish)版的翻譯，那麼應該會長像："
	+
	+#. (itstool) path: answer/programlisting
	+#: book.translate.xml:7103
	+#, no-wrap
	+msgid ""
	+"head/\n"
	+" sv_SE.ISO8859-1/\n"
	+" Makefile\n"
	+" htdocs/\n"
	+" docproj/\n"
	+" books/\n"
	+" faq/\n"
	+" Makefile\n"
	+" book.xml"
	+msgstr ""
	+"head/\n"
	+" sv_SE.ISO8859-1/\n"
	+" Makefile\n"
	+" htdocs/\n"
	+" docproj/\n"
	+" books/\n"
	+" faq/\n"
	+" Makefile\n"
	+" book.xml"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7113
	+msgid "<literal>sv_SE.ISO8859-1</literal> is the name of the translation, in <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> form. Note the two Makefiles, which will be used to build the documentation."
	+msgstr "<literal>sv_SE.ISO8859-1</literal>是依照 <filename><replaceable>語系(lang)</replaceable>.<replaceable>編碼(encoding)</replaceable></filename> 的規則來建立的譯名。請注意：其中有兩個 Makefiles 檔，它們是用來建構文件的。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7119
	+msgid "Use <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> to compress up your documentation, and send it to the project."
	+msgstr "然後請用 <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 與 <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來把你的翻譯文件壓縮起來，並寄到本計劃來。"
	+
	+#. (itstool) path: answer/screen
	+#: book.translate.xml:7122
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd doc</userinput>\n"
	+"<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>\n"
	+"<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd doc</userinput>\n"
	+"<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>\n"
	+"<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput>"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7126
	+msgid "Put <filename>swedish-docs.tar.gz</filename> somewhere. If you do not have access to your own webspace (perhaps your ISP does not let you have any) then you can email Documentation Engineering Team <email>doceng@FreeBSD.org</email>, and arrange to email the files when it is convenient."
	+msgstr "接著，把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上，若你沒有自己網頁空間的話(ISP不提供) ，那麼可以該檔寄到 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 來。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7132
	+msgid "Either way, you should use Bugzilla to submit a report indicating that you have submitted the documentation. It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language."
	+msgstr "還有，記得用 Bugzilla 提交一個報告以通知大家；你已經寄出翻譯文件了，還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好，因為這也有助於提升翻譯品質的流暢度。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7139
	+msgid "Someone (probably the Documentation Project Manager, currently Documentation Engineering Team <email>doceng@FreeBSD.org</email>) will then take your translation and confirm that it builds. In particular, the following things will be looked at:"
	+msgstr "最後，會有人(可能是文件計劃總管，或是 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 成員) 會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點："
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7146
	+msgid "Do all your files use RCS strings (such as \"ID\")?"
	+msgstr "你的檔案是否都有用 RCS tag (像是 \"ID\" 之類的)？"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7151
	+msgid "Does <command>make all</command> in the <filename>sv_SE.ISO8859-1</filename> directory work correctly?"
	+msgstr "<filename>sv_SE.ISO8859-1</filename> 是否可以順利<command>make all</command> 編譯呢？"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7157
	+msgid "Does <command>make install</command> work correctly?"
	+msgstr "<command>make install</command> 是否結果有正確"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7162
	+msgid "If there are any problems then whoever is looking at the submission will get back to you to work them out."
	+msgstr "若有問題的話，那麼檢閱者會叮嚀你，來讓這些翻譯成果可以正確使用。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7165
	+msgid "If there are no problems your translation will be committed as soon as possible."
	+msgstr "若沒問題的話，那麼就會很快把你的翻譯成果 commit 進去了。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7172
	+msgid "Can I include language or country specific text in my translation?"
	+msgstr "可以加入某語系或某國家才有的東西到翻譯內容內嗎？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7177
	+msgid "We would prefer that you did not."
	+msgstr "我們希望不要這麼做。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7179
	+msgid "For example, suppose that you are translating the Handbook to Korean, and want to include a section about retailers in Korea in your Handbook."
	+msgstr "舉例來說，假設你正準備把 Handbook 翻譯為韓文版，並希望把韓國零售商也加到你翻譯的 Handbook 韓文版內。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7183
	+msgid "There is no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or …) versions as well. It is feasible that an English speaker in Korea might try to pick up a copy of FreeBSD whilst over there. It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing."
	+msgstr "我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 …) 因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7191
	+msgid "If you have country specific information, please submit it as a change to the English Handbook (using Bugzilla) and then translate the change back to your language in the translated Handbook."
	+msgstr "若你有某國才有的資料，請(用 Bugzilla )提供給英文版 Handbook 以作為修訂，然後再把英文版的修訂部分，翻為你要翻譯的 Handbook 吧。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7196
	+msgid "Thanks."
	+msgstr "謝謝。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7202
	+msgid "How should language specific characters be included?"
	+msgstr "要怎麼把該語系特有的字元寫進去翻譯內容呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7207
	+msgid "Non-ASCII characters in the documentation should be included using SGML entities."
	+msgstr "文件內所有的非 ASCII(Non-ASCII) 字元，都要使用 SGML entities 才能寫進去。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7210
	+msgid "Briefly, these look like an ampersand (&), the name of the entity, and a semi-colon (;)."
	+msgstr "簡單來說，長相一開頭會是 and 符號(&)，然後是該 entity 名稱，最後接上分號(;)。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7213
	+msgid "The entity names are defined in ISO8879, which is in the ports tree as <package>textproc/iso8879</package>."
	+msgstr "這些 entity 名稱都是 ISO8879 所制訂的，而 port tree 內則 <package>textproc/iso8879</package>。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7216
	+msgid "A few examples include:"
	+msgstr "以下舉一些例子："
	+
	+#. (itstool) path: segmentedlist/segtitle
	+#: book.translate.xml:7219
	+msgid "Entity"
	+msgstr "Entity名稱"
	+
	+#. (itstool) path: segmentedlist/segtitle
	+#: book.translate.xml:7221
	+msgid "Appearance"
	+msgstr "實際樣子"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7226
	+msgid "&eacute;"
	+msgstr "&eacute;"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7227
	+msgid "é"
	+msgstr "é"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7228
	+msgid "Small <quote>e</quote> with an acute accent"
	+msgstr "小 <quote>e</quote>，並帶尖、重音(acute accent)"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7232
	+msgid "&Eacute;"
	+msgstr "&Eacute;"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7233
	+msgid "É"
	+msgstr "É"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7234
	+msgid "Large <quote>E</quote> with an acute accent"
	+msgstr "大 <quote>E</quote>，並帶尖、重音(acute accent)"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7238
	+msgid "&uuml;"
	+msgstr "&uuml;"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7239
	+msgid "ü"
	+msgstr "ü"
	+
	+#. (itstool) path: seglistitem/seg
	+#: book.translate.xml:7240
	+msgid "Small <quote>u</quote> with an umlaut"
	+msgstr "小 <quote>u</quote>，並帶日耳曼語系中的母音變化(umlaut)"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7244
	+msgid "After you have installed the iso8879 port, the files in <filename>/usr/local/share/xml/iso8879</filename> contain the complete list."
	+msgstr "在裝了 iso8879 這個 port 之後，就可以在 <filename>/usr/local/share/xml/iso8879</filename> 找到這些的詳細列表。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7252
	+msgid "Addressing the reader"
	+msgstr "如何稱呼讀者呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7256
	+msgid "In the English documents, the reader is addressed as <quote>you</quote>, there is no formal/informal distinction as there is in some languages."
	+msgstr "在英文文件內，讀者都是以 <quote>you</quote> 來稱呼，而有些語言並沒有正式/非正式的區隔。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7260
	+msgid "If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. If in doubt, use a mildly polite form."
	+msgstr "若你所要翻的語言可以區別這些差異，那麼請用該語系在一般技術文件上所使用的稱呼吧。如果容易造成困惑的話，那麼請改用較中性的稱呼來取代。"
	+
	+#. (itstool) path: question/para
	+#: book.translate.xml:7269
	+msgid "Do I need to include any additional information in my translations?"
	+msgstr "翻譯成果內要不要附上一些其他訊息呢？"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7274
	+msgid "Yes."
	+msgstr "要。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7276
	+msgid "The header of the English version of each document will look something like this:"
	+msgstr "每份英文版原稿的開頭，通常會有像下面的內容："
	+
	+#. (itstool) path: answer/programlisting
	+#: book.translate.xml:7279
	+#, no-wrap
	+msgid ""
	+"<!--\n"
	+" The FreeBSD Documentation Project\n"
	+"\n"
	+" $FreeBSD$\n"
	+"-->"
	+msgstr ""
	+"<!--\n"
	+" The FreeBSD Documentation Project\n"
	+"\n"
	+" $FreeBSD$\n"
	+"-->"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7285
	+msgid "The exact boilerplate may change, but it will always 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."
	+msgstr "實際上的內容可能稍有不同，但每份原稿都會附上 $FreeBSD$ 這一行以及<literal>The FreeBSD Documentation Project</literal> 宣告。請注意：$FreeBSD 開頭的這行是會由 Subversion 隨著每次異動而自動更改的，所以，新檔案的話請保持原狀(也就是只要寫 $FreeBSD$ 就好了)。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7293
	+msgid "Your translated documents should include their own $FreeBSD$ line, and change the <literal>FreeBSD Documentation Project</literal> line to <literal>The FreeBSD <replaceable>language</replaceable> Documentation Project</literal>."
	+msgstr "翻譯文件中，必須都要有 $FreeBSD$ 這行，並且把 <literal>FreeBSD Documentation Project</literal> 這行改為 <literal>The FreeBSD <replaceable>你的語系</replaceable> Documentation Project</literal>。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7299
	+msgid "In addition, you should add a third line which indicates which revision of the English text this is based on."
	+msgstr "此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。"
	+
	+#. (itstool) path: answer/para
	+#: book.translate.xml:7302
	+msgid "So, the Spanish version of this file might start:"
	+msgstr "因此呢，西班牙文版(Spanish)的檔案開頭應該是長像這樣："
	+
	+#. (itstool) path: answer/programlisting
	+#: book.translate.xml:7304
	+#, no-wrap
	+msgid ""
	+"<!--\n"
	+" The FreeBSD Spanish Documentation Project\n"
	+"\n"
	+" $FreeBSD$\n"
	+" Original revision: r38674\n"
	+"-->"
	+msgstr ""
	+"<!--\n"
	+" The FreeBSD Spanish Documentation Project\n"
	+"\n"
	+" $FreeBSD$\n"
	+" Original revision: r38674\n"
	+"-->"
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:7322
	+msgid "<acronym>PO</acronym> Translations"
	+msgstr "<acronym>PO</acronym> 翻譯"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7327
	+msgid ""
	+"The <link xlink:href=\"http://www.gnu.org/software/gettext/\"><acronym>GNU</acronym> <application>gettext</application></link> system offers translators an easy way to create and maintain translations of documents. Translatable strings are extracted from the original document into a <acronym>PO</acronym> (Portable Object) file. Translated versions of the strings are entered with a separate editor. The strings "
	+"can be used directly or built into a complete translated version of the original document."
	+msgstr "<link xlink:href=\"http://www.gnu.org/software/gettext/\"><acronym>GNU</acronym> <application>gettext</application></link> 系統提供翻譯者一個簡單的方法來建立和維護文件的翻譯。翻譯的字串從原始文件題取出來到<acronym>PO</acronym> (Portable Object) 檔。字串的翻譯用另外的編輯器輸入。翻譯的字串可以直接使用，或是編譯成原始文件的完整翻譯版本。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7340
	+#, fuzzy
	+msgid "The procedure shown in <xref linkend=\"overview-quick-start\"/> is assumed to have already been performed, but the <literal>TRANSLATOR</literal> option must be enabled in the <package role=\"port\">textproc/docproj</package> port. If that option was not enabled, display the options menu and enable it, then reinstall the port:"
	+msgstr "在 <xref linkend=\"overview-quick-start\"/> 的步驟還必須打開 <package role=\"port\">textproc/docproj</package> port <literal>TRANSLATOR</literal> 選項。如果沒有打開這個選項，請打開選項後，重新安裝 port。"
	+
	+#. (itstool) path: sect1/screen
	+#: book.translate.xml:7348
	+#, no-wrap
	+msgid ""
	+"<prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput>\n"
	+"<prompt>#</prompt> <userinput>make config</userinput>\n"
	+"<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput>"
	+msgstr ""
	+"<prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput>\n"
	+"<prompt>#</prompt> <userinput>make config</userinput>\n"
	+"<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput>"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7352
	+#, fuzzy
	+msgid "This example shows the creation of a Spanish translation of the short <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds\">Leap Seconds</link> article."
	+msgstr "這個範例示範如何建立<link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds\">Leap Seconds</link> 短文的西班牙文翻譯"
	+
	+#. (itstool) path: procedure/title
	+#: book.translate.xml:7357
	+#, fuzzy
	+msgid "Install a <acronym>PO</acronym> Editor"
	+msgstr "安裝 <acronym>PO</acronym> 編輯器"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7360
	+msgid "A <acronym>PO</acronym> editor is needed to edit translation files. This example uses <package role=\"ports\">editors/poedit</package>."
	+msgstr "編輯翻譯檔案需要<acronym>PO</acronym>編輯器。這個範例使用<package role=\"ports\">editors/poedit</package>。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7364
	+#, no-wrap
	+msgid ""
	+"<prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput>\n"
	+"<prompt>#</prompt> <userinput>make install clean</userinput>"
	+msgstr ""
	+"<prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput>\n"
	+"<prompt>#</prompt> <userinput>make install clean</userinput>"
	+
	+#. (itstool) path: procedure/title
	+#: book.translate.xml:7370
	+#, fuzzy
	+msgid "Initial Setup"
	+msgstr "初始設定"
	+
	+#. (itstool) path: procedure/para
	+#: book.translate.xml:7372
	+#, fuzzy
	+msgid "When a new translation is first created, the directory structure and <filename>Makefile</filename> must be created or copied from the English original:"
	+msgstr "第一次建立新的翻譯時，目錄結構和 <filename>Makefile</filename> 必須建立或是從英文版複製過來。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7377
	+msgid "Create a directory for the new translation. The English article source is in <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename>. The Spanish translation will go in <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename>. The path is the same except for the name of the language directory."
	+msgstr "建立新翻譯的目錄。英文文章原始碼位於 <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename> 。西班牙文翻譯將會放在 <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename> 。除了語系目錄的名稱外，其他路徑相同。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7385
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>"
	+msgstr "<prompt>%</prompt> <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7389
	+msgid "Copy the <filename>Makefile</filename> from the original document into the translation directory:"
	+msgstr "從原始文件處將 <filename>Makefile</filename> 複製到翻譯目錄。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7392
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \\\n"
	+" ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \\\n"
	+" ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>"
	+
	+#. (itstool) path: procedure/title
	+#: book.translate.xml:7398
	+msgid "Translation"
	+msgstr "翻譯"
	+
	+#. (itstool) path: procedure/para
	+#: book.translate.xml:7400
	+#, fuzzy
	+msgid "Translating a document consists of two steps: extracting translatable strings from the original document, and entering translations for those strings. These steps are repeated until the translator feels that enough of the document has been translated to produce a usable translated document."
	+msgstr "翻譯文件公有兩個步驟：將可翻譯的字串從原始文件提去出來，然後翻譯這些字串。重複這些步驟，直到翻譯者認為文件的翻譯部份已經足夠用來產生可讀的翻譯文件。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7408
	+msgid "Extract the translatable strings from the original English version into a <acronym>PO</acronym> file:"
	+msgstr "從英文的原始文件提取字串到 <acronym>PO</acronym> 檔："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7411
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>\n"
	+"<prompt>%</prompt> <userinput>make po</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>\n"
	+"<prompt>%</prompt> <userinput>make po</userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7416
	+msgid "Use a <acronym>PO</acronym> editor to enter translations in the <acronym>PO</acronym> file. There are several different editors available. <filename>poedit</filename> from <package role=\"port\">editors/poedit</package> is shown here."
	+msgstr "使用 <acronym>PO</acronym> 編輯器將翻譯輸入 <acronym>PO</acronym> 檔。有幾個不同的編輯器可以使用。這裡用的是 <package role=\"port\">editors/poedit</package> 的 <filename>poedit</filename> 。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7422
	+msgid "The <acronym>PO</acronym> file name is the two-character language code followed by an underline and a two-character region code. For Spanish, the file name is <filename>es_ES.po</filename>."
	+msgstr "<acronym>PO</acronym> 檔名是兩個字元的語系碼後面接底線和兩個字元的區域碼。以西班牙語來說，檔名是 <filename>es_ES.po</filename> 。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7427 book.translate.xml:7891
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>poedit es_ES.po</userinput>"
	+msgstr "<prompt>%</prompt> <userinput>poedit es_ES.po</userinput>"
	+
	+#. (itstool) path: procedure/title
	+#: book.translate.xml:7432
	+#, fuzzy
	+msgid "Generating a Translated Document"
	+msgstr "產生翻譯文件"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7435
	+msgid "Generate the translated document:"
	+msgstr "產生翻譯文件"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7437
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>\n"
	+"<prompt>%</prompt> <userinput>make tran</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>\n"
	+"<prompt>%</prompt> <userinput>make tran</userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7440
	+msgid "The name of the generated document matches the name of the English original, usually <filename>article.xml</filename> for articles or <filename>book.xml</filename> for books."
	+msgstr "產生的文件名稱與英文原始文件名稱相符，文章通常是 <filename>article.xml</filename> ，書籍是 <filename>book.xml</filename> 。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7447
	+msgid "Check the generated file by rendering it to <acronym>HTML</acronym> and viewing it with a web browser:"
	+msgstr "可以轉換成 <acronym>HTML</acronym> 來檢查產生的檔案，並用瀏覽器來察看。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7451
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>make FORMATS=html</userinput>\n"
	+"<prompt>%</prompt> <userinput>firefox article.html</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>make FORMATS=html</userinput>\n"
	+"<prompt>%</prompt> <userinput>firefox article.html</userinput>"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:7458
	+msgid "Creating New Translations"
	+msgstr "建立新翻譯"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7460
	+#, fuzzy
	+msgid ""
	+"The first step to creating a new translated document is locating or creating a directory to hold it. FreeBSD puts translated documents in a subdirectory named for their language and region in the format <filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable></filename>. <replaceable>lang</replaceable> is a two-character lowercase code. It is followed by an underscore character and then the "
	+"two-character uppercase <replaceable>REGION</replaceable> code."
	+msgstr "建立新翻譯文件的第一步是找到或建立一個目錄來放它。FreeBSD 將翻譯文件放在子目錄，用語系和區域以<filename><replaceable>語系</replaceable>_<replaceable>區域</replaceable></filename>來命名。<replaceable>語系</replaceable> 是小寫的兩個字元碼。接著是底線和兩個字元的大寫 <replaceable>REGION</replaceable> 碼。"
	+
	+#. (itstool) path: table/title
	+#: book.translate.xml:7471
	+msgid "Language Names"
	+msgstr "語系名稱"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7476
	+msgid "Language"
	+msgstr "語言"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7477
	+msgid "Region"
	+msgstr "地區"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7478
	+msgid "Translated Directory Name"
	+msgstr "翻譯目錄名稱"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7479
	+msgid "<acronym>PO</acronym> File Name"
	+msgstr "<acronym>PO</acronym> 檔名稱"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7480
	+msgid "Character Set"
	+msgstr "字元集"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7486
	+msgid "English"
	+msgstr "英文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7487
	+msgid "United States"
	+msgstr "美國"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7488
	+msgid "<filename>en_US.ISO8859-1</filename>"
	+msgstr "<filename>en_US.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7489
	+msgid "<filename>en_US.po</filename>"
	+msgstr "<filename>en_US.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7490 book.translate.xml:7506 book.translate.xml:7514 book.translate.xml:7530 book.translate.xml:7538 book.translate.xml:7586 book.translate.xml:7594 book.translate.xml:7610
	+msgid "<acronym>ISO</acronym> 8859-1"
	+msgstr "<acronym>ISO</acronym> 8859-1"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7494
	+msgid "Bengali"
	+msgstr "孟加拉文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7495
	+msgid "Bangladesh"
	+msgstr "孟加拉"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7496
	+msgid "<filename>bn_BD.UTF-8</filename>"
	+msgstr "<filename>bn_BD.UTF-8</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7497
	+msgid "<filename>bn_BD.po</filename>"
	+msgstr "<filename>bn_BD.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7498 book.translate.xml:7570 book.translate.xml:7578 book.translate.xml:7642 book.translate.xml:7650
	+msgid "<acronym>UTF</acronym>-8"
	+msgstr "<acronym>UTF</acronym>-8"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7502
	+msgid "Danish"
	+msgstr "丹麥文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7503
	+msgid "Denmark"
	+msgstr "丹麥"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7504
	+msgid "<filename>da_DK.ISO8859-1</filename>"
	+msgstr "<filename>da_DK.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7505
	+msgid "<filename>da_DK.po</filename>"
	+msgstr "<filename>da_DK.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7510
	+msgid "German"
	+msgstr "德文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7511
	+msgid "Germany"
	+msgstr "德國"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7512
	+msgid "<filename>de_DE.ISO8859-1</filename>"
	+msgstr "<filename>de_DE.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7513
	+msgid "<filename>de_DE.po</filename>"
	+msgstr "<filename>de_DE.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7518
	+msgid "Greek"
	+msgstr "希臘文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7519
	+msgid "Greece"
	+msgstr "希臘"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7520
	+msgid "<filename>el_GR.ISO8859-7</filename>"
	+msgstr "<filename>el_GR.ISO8859-7</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7521
	+msgid "<filename>el_GR.po</filename>"
	+msgstr "<filename>el_GR.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7522
	+msgid "<acronym>ISO</acronym> 8859-7"
	+msgstr "<acronym>ISO</acronym> 8859-7"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7526
	+msgid "Spanish"
	+msgstr "西班牙文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7527
	+msgid "Spain"
	+msgstr "西班牙"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7528
	+msgid "<filename>es_ES.ISO8859-1</filename>"
	+msgstr "<filename>es_ES.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7529
	+msgid "<filename>es_ES.po</filename>"
	+msgstr "<filename>es_ES.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7534
	+msgid "French"
	+msgstr "法文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7535
	+msgid "France"
	+msgstr "法國"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7536
	+msgid "<filename>fr_FR.ISO8859-1</filename>"
	+msgstr "<filename>fr_FR.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7537
	+msgid "<filename>fr_FR.po</filename>"
	+msgstr "<filename>fr_FR.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7542
	+msgid "Hungarian"
	+msgstr "匈牙利文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7543
	+msgid "Hungary"
	+msgstr "匈牙利"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7544
	+msgid "<filename>hu_HU.ISO8859-2</filename>"
	+msgstr "<filename>hu_HU.ISO8859-2</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7545
	+msgid "<filename>hu_HU.po</filename>"
	+msgstr "<filename>hu_HU.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7546 book.translate.xml:7602 book.translate.xml:7626
	+msgid "<acronym>ISO</acronym> 8859-2"
	+msgstr "<acronym>ISO</acronym> 8859-2"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7550
	+msgid "Italian"
	+msgstr "義大利文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7551
	+msgid "Italy"
	+msgstr "義大利"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7552
	+msgid "<filename>it_IT.ISO8859-15</filename>"
	+msgstr "<filename>it_IT.ISO8859-15</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7553
	+msgid "<filename>it_IT.po</filename>"
	+msgstr "<filename>it_IT.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7554
	+msgid "<acronym>ISO</acronym> 8859-15"
	+msgstr "<acronym>ISO</acronym> 8859-15"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7558
	+msgid "Japanese"
	+msgstr "日文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7559
	+msgid "Japan"
	+msgstr "日本"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7560
	+msgid "<filename>ja_JP.eucJP</filename>"
	+msgstr "<filename>ja_JP.eucJP</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7561
	+msgid "<filename>ja_JP.po</filename>"
	+msgstr "<filename>ja_JP.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7562
	+msgid "<acronym>EUC</acronym> JP"
	+msgstr "<acronym>EUC</acronym> JP"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7566
	+msgid "Korean"
	+msgstr "韓文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7567
	+msgid "Korea"
	+msgstr "韓國"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7568
	+msgid "<filename>ko_KR.UTF-8</filename>"
	+msgstr "<filename>ko_KR.UTF-8</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7569
	+msgid "<filename>ko_KR.po</filename>"
	+msgstr "<filename>ko_KR.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7574
	+msgid "Mongolian"
	+msgstr "蒙古文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7575
	+msgid "Mongolia"
	+msgstr "蒙古"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7576
	+msgid "<filename>mn_MN.UTF-8</filename>"
	+msgstr "<filename>mn_MN.UTF-8</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7577
	+msgid "<filename>mn_MN.po</filename>"
	+msgstr "<filename>mn_MN.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7582
	+msgid "Dutch"
	+msgstr "荷蘭文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7583
	+msgid "Netherlands"
	+msgstr "荷蘭"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7584
	+msgid "<filename>nl_NL.ISO8859-1</filename>"
	+msgstr "<filename>nl_NL.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7585
	+msgid "<filename>nl_NL.po</filename>"
	+msgstr "<filename>nl_NL.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7590
	+msgid "Norwegian"
	+msgstr "挪威文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7591
	+msgid "Norway"
	+msgstr "挪威"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7592
	+msgid "<filename>no_NO.ISO8859-1</filename>"
	+msgstr "<filename>no_NO.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7593
	+msgid "<filename>no_NO.po</filename>"
	+msgstr "<filename>no_NO.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7598
	+msgid "Polish"
	+msgstr "波蘭文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7599
	+msgid "Poland"
	+msgstr "波蘭"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7600
	+msgid "<filename>pl_PL.ISO8859-2</filename>"
	+msgstr "<filename>pl_PL.ISO8859-2</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7601
	+msgid "<filename>pl_PL.po</filename>"
	+msgstr "<filename>pl_PL.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7606
	+msgid "Portuguese"
	+msgstr "葡萄牙文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7607
	+msgid "Brazil"
	+msgstr "巴西"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7608
	+msgid "<filename>pt_BR.ISO8859-1</filename>"
	+msgstr "<filename>pt_BR.ISO8859-1</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7609
	+msgid "<filename>pt_BR.po</filename>"
	+msgstr "<filename>pt_BR.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7614
	+msgid "Russian"
	+msgstr "俄文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7615
	+msgid "Russia"
	+msgstr "俄羅斯"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7616
	+msgid "<filename>ru_RU.KOI8-R</filename>"
	+msgstr "<filename>ru_RU.KOI8-R</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7617
	+msgid "<filename>ru_RU.po</filename>"
	+msgstr "<filename>ru_RU.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7618
	+msgid "<acronym>KOI</acronym>8-R"
	+msgstr "<acronym>KOI</acronym>8-R"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7622
	+msgid "Serbian"
	+msgstr "賽爾維亞"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7623
	+msgid "Serbia"
	+msgstr "賽爾維亞文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7624
	+msgid "<filename>sr_YU.ISO8859-2</filename>"
	+msgstr "<filename>sr_YU.ISO8859-2</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7625
	+msgid "<filename>sr_YU.po</filename>"
	+msgstr "<filename>sr_YU.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7630
	+msgid "Turkish"
	+msgstr "土耳其文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7631
	+msgid "Turkey"
	+msgstr "土耳其"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7632
	+msgid "<filename>tr_TR.ISO8859-9</filename>"
	+msgstr "<filename>tr_TR.ISO8859-9</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7633
	+msgid "<filename>tr_TR.po</filename>"
	+msgstr "<filename>tr_TR.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7634
	+msgid "<acronym>ISO</acronym> 8859-9"
	+msgstr "<acronym>ISO</acronym> 8859-9"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7638 book.translate.xml:7646
	+msgid "Chinese"
	+msgstr "中文"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7639
	+msgid "China"
	+msgstr "中國"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7640
	+msgid "<filename>zh_CN.UTF-8</filename>"
	+msgstr "<filename>zh_CN.UTF-8</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7641
	+msgid "<filename>zh_CN.po</filename>"
	+msgstr "<filename>zh_CN.po</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7647
	+msgid "Taiwan"
	+msgstr "台灣"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7648
	+msgid "<filename>zh_TW.UTF-8</filename>"
	+msgstr "<filename>zh_TW.UTF-8</filename>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:7649
	+msgid "<filename>zh_TW.po</filename>"
	+msgstr "<filename>zh_TW.po</filename>"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7656
	+msgid "The translations are in subdirectories of the main documentation directory, here assumed to be <filename>~/doc/</filename> as shown in <xref linkend=\"overview-quick-start\"/>. For example, German translations are located in <filename>~/doc/de_DE.ISO8859-1/</filename>, and French translations are in <filename>~/doc/fr_FR.ISO8859-1/</filename>."
	+msgstr "翻譯位於主要文件目錄的子目錄，這裡假設如 <xref linkend=\"overview-quick-start\"/> 所示，是 <filename>~/doc/</filename>。例如德文位於 <filename>~/doc/de_DE.ISO8859-1/</filename>，法文位於 <filename>~/doc/fr_FR.ISO8859-1/</filename>。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7665
	+msgid "Each language directory contains separate subdirectories named for the type of documents, usually <filename>articles/</filename> and <filename>books/</filename>."
	+msgstr "每個語系目錄包含不同文件類型的子目錄，通常是 <filename>articles/</filename> 和 <filename>books/</filename>。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7670
	+msgid "Combining these directory names gives the complete path to an article or book. For example, the French translation of the NanoBSD article is in <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename>, and the Mongolian translation of the Handbook is in <filename>~/doc/mn_MN.UTF-8/books/handbook/</filename>."
	+msgstr "將目錄名稱組合起來就是文章或書的完整路徑。例如，NanoBSD 文章的法語翻譯在 <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename> 。而使用手冊的蒙古文翻譯在<filename>~/doc/mn_MN.UTF-8/books/handbook/</filename> 。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7677
	+msgid "A new language directory must be created when translating a document to a new language. If the language directory already exists, only a subdirectory in the <filename>articles/</filename> or <filename>books/</filename> directory is needed."
	+msgstr "當翻譯到一個新語系時必須建立一個新的語系目錄。如果語系目錄已經存在，那只需要有 <filename>articles/</filename> 或 <filename>books/</filename> 的子目錄。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7683
	+msgid ""
	+"FreeBSD documentation builds are controlled by a <filename>Makefile</filename> in the same directory. With simple articles, the <filename>Makefile</filename> can often just be copied verbatim from the original English directory. The translation process combines multiple separate <filename>book.xml</filename> and <filename>chapter.xml</filename> files in books into a single file, so the <filename>Makefile</"
	+"filename> for book translations must be copied and modified."
	+msgstr "FreeBSD 文件的編譯是由同一個目錄的 <filename>Makefile</filename> 控制。簡單的文章可以從原始的英語目錄直接複製 <filename>Makefile</filename> 過來。書籍的翻譯流程結合多個獨立的 <filename>book.xml</filename> 和 <filename>chapter.xml</filename> 成為一個檔案，所以書籍翻譯的 <filename>Makefile</filename> 必須複製並修改。"
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:7694
	+#, fuzzy
	+msgid "Creating a Spanish Translation of the Porter's Handbook"
	+msgstr "建立 Porter 手冊的西班牙語翻譯"
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:7697
	+msgid "Create a new Spanish translation of the <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook\">Porter's Handbook</link>. The original is a book in <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename>."
	+msgstr "建立<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> 的書籍。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7704
	+msgid "The Spanish language books directory <filename>~/doc/es_ES.ISO8859-1/books/</filename> already exists, so only a new subdirectory for the Porter's Handbook is needed:"
	+msgstr "西班牙文 books 目錄 <filename>~/doc/es_ES.ISO8859-1/books/</filename> 已經存在，所以只要建立 Porter 手冊的子目錄："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7708
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput>\n"
	+"A porters-handbook"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput>\n"
	+"A porters-handbook"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7714
	+msgid "Copy the <filename>Makefile</filename> from the original book:"
	+msgstr "從原始文件的目錄複製 <filename>Makefile</filename> ："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7717
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>\n"
	+"A Makefile"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>\n"
	+"A Makefile"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7721
	+msgid "Modify the contents of the <filename>Makefile</filename> to only expect a single <filename>book.xml</filename>:"
	+msgstr "修改 <filename>Makefile</filename> 內容以產生單一的 <filename>book.xml</filename>："
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:7725
	+#, no-wrap
	+msgid ""
	+"#\n"
	+"# $FreeBSD$\n"
	+"#\n"
	+"# Build the FreeBSD Porter's Handbook.\n"
	+"#\n"
	+"\n"
	+"MAINTAINER=doc@FreeBSD.org\n"
	+"\n"
	+"DOC?= book\n"
	+"\n"
	+"FORMATS?= html-split\n"
	+"\n"
	+"INSTALL_COMPRESSED?= gz\n"
	+"INSTALL_ONLY_COMPRESSED?=\n"
	+"\n"
	+"# XML content\n"
	+"SRCS= book.xml\n"
	+"\n"
	+"# Images from the cross-document image library\n"
	+"IMAGES_LIB+= callouts/1.png\n"
	+"IMAGES_LIB+= callouts/2.png\n"
	+"IMAGES_LIB+= callouts/3.png\n"
	+"IMAGES_LIB+= callouts/4.png\n"
	+"IMAGES_LIB+= callouts/5.png\n"
	+"IMAGES_LIB+= callouts/6.png\n"
	+"IMAGES_LIB+= callouts/7.png\n"
	+"IMAGES_LIB+= callouts/8.png\n"
	+"IMAGES_LIB+= callouts/9.png\n"
	+"IMAGES_LIB+= callouts/10.png\n"
	+"IMAGES_LIB+= callouts/11.png\n"
	+"IMAGES_LIB+= callouts/12.png\n"
	+"IMAGES_LIB+= callouts/13.png\n"
	+"IMAGES_LIB+= callouts/14.png\n"
	+"IMAGES_LIB+= callouts/15.png\n"
	+"IMAGES_LIB+= callouts/16.png\n"
	+"IMAGES_LIB+= callouts/17.png\n"
	+"IMAGES_LIB+= callouts/18.png\n"
	+"IMAGES_LIB+= callouts/19.png\n"
	+"IMAGES_LIB+= callouts/20.png\n"
	+"IMAGES_LIB+= callouts/21.png\n"
	+"\n"
	+"URL_RELPREFIX?= ../../../..\n"
	+"DOC_PREFIX?= ${.CURDIR}/../../..\n"
	+"\n"
	+".include \"${DOC_PREFIX}/share/mk/doc.project.mk\""
	+msgstr ""
	+"#\n"
	+"# $FreeBSD$\n"
	+"#\n"
	+"# Build the FreeBSD Porter's Handbook。\n"
	+"#\n"
	+"\n"
	+"MAINTAINER=doc@FreeBSD.org\n"
	+"\n"
	+"DOC?= book\n"
	+"\n"
	+"FORMATS?= html-split\n"
	+"\n"
	+"INSTALL_COMPRESSED?= gz\n"
	+"INSTALL_ONLY_COMPRESSED?=\n"
	+"\n"
	+"# XML content\n"
	+"SRCS= book.xml\n"
	+"\n"
	+"# Images from the cross-document image library\n"
	+"IMAGES_LIB+= callouts/1.png\n"
	+"IMAGES_LIB+= callouts/2.png\n"
	+"IMAGES_LIB+= callouts/3.png\n"
	+"IMAGES_LIB+= callouts/4.png\n"
	+"IMAGES_LIB+= callouts/5.png\n"
	+"IMAGES_LIB+= callouts/6.png\n"
	+"IMAGES_LIB+= callouts/7.png\n"
	+"IMAGES_LIB+= callouts/8.png\n"
	+"IMAGES_LIB+= callouts/9.png\n"
	+"IMAGES_LIB+= callouts/10.png\n"
	+"IMAGES_LIB+= callouts/11.png\n"
	+"IMAGES_LIB+= callouts/12.png\n"
	+"IMAGES_LIB+= callouts/13.png\n"
	+"IMAGES_LIB+= callouts/14.png\n"
	+"IMAGES_LIB+= callouts/15.png\n"
	+"IMAGES_LIB+= callouts/16.png\n"
	+"IMAGES_LIB+= callouts/17.png\n"
	+"IMAGES_LIB+= callouts/18.png\n"
	+"IMAGES_LIB+= callouts/19.png\n"
	+"IMAGES_LIB+= callouts/20.png\n"
	+"IMAGES_LIB+= callouts/21.png\n"
	+"\n"
	+"URL_RELPREFIX?= ../../../..\n"
	+"DOC_PREFIX?= ${.CURDIR}/../../..\n"
	+"\n"
	+".include \"${DOC_PREFIX}/share/mk/doc.project.mk\""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7771
	+#, fuzzy
	+msgid "Now the document structure is ready for the translator to begin translating with <command>make po</command>."
	+msgstr "現在文件結構已經準備好讓翻譯者執行 <command>make po</command> 開始翻譯。"
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:7779
	+msgid "Creating a French Translation of the <acronym>PGP</acronym> Keys Article"
	+msgstr "建立 <acronym>PGP</acronym> 金鑰文章的法語翻譯。"
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:7782
	+msgid "Create a new French translation of the <link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/pgpkeys\"><acronym>PGP</acronym> Keys article</link>. The original is an article in <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename>."
	+msgstr "建立 <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> 的文章。"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7789
	+msgid "The French language article directory <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> already exists, so only a new subdirectory for the <acronym>PGP</acronym> Keys article is needed:"
	+msgstr "法文 article 目錄 <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> 已經存在，所以只要建立 <acronym>PGP</acronym> 金鑰文章的子目錄："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7793
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput>\n"
	+"A pgpkeys"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput>\n"
	+"A pgpkeys"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7799
	+msgid "Copy the <filename>Makefile</filename> from the original article:"
	+msgstr "從原始文件的目錄複製 <filename>Makefile</filename> ："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7802
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>\n"
	+"A Makefile"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>\n"
	+"<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>\n"
	+"A Makefile"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7806
	+msgid "Check the contents of the <filename>Makefile</filename>. Because this is a simple article, in this case the <filename>Makefile</filename> can be used unchanged. The <literal>$FreeBSD...$</literal> version string on the second line will be replaced by the version control system when this file is committed."
	+msgstr "檢查 <filename>Makefile</filename> 的內容。因為這是簡單的文章，此例的 <filename>Makefile</filename> 不用修改。第二行的 <literal>$FreeBSD...$</literal> 版本字串將會在檔案提交時被版本控制系統替換掉。"
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:7813
	+#, no-wrap
	+msgid ""
	+"#\n"
	+"# $FreeBSD$\n"
	+"#\n"
	+"# Article: PGP Keys\n"
	+"\n"
	+"DOC?= article\n"
	+"\n"
	+"FORMATS?= html\n"
	+"WITH_ARTICLE_TOC?= YES\n"
	+"\n"
	+"INSTALL_COMPRESSED?= gz\n"
	+"INSTALL_ONLY_COMPRESSED?=\n"
	+"\n"
	+"SRCS= article.xml\n"
	+"\n"
	+"# To build with just key fingerprints, set FINGERPRINTS_ONLY.\n"
	+"\n"
	+"URL_RELPREFIX?= ../../../..\n"
	+"DOC_PREFIX?= ${.CURDIR}/../../..\n"
	+"\n"
	+".include \"${DOC_PREFIX}/share/mk/doc.project.mk\""
	+msgstr ""
	+"#\n"
	+"# $FreeBSD$\n"
	+"#\n"
	+"# Article：PGP Keys\n"
	+"\n"
	+"DOC?= article\n"
	+"\n"
	+"FORMATS?= html\n"
	+"WITH_ARTICLE_TOC?= YES\n"
	+"\n"
	+"INSTALL_COMPRESSED?= gz\n"
	+"INSTALL_ONLY_COMPRESSED?=\n"
	+"\n"
	+"SRCS= article.xml\n"
	+"\n"
	+"# To build with just key fingerprints, set FINGERPRINTS_ONLY。\n"
	+"\n"
	+"URL_RELPREFIX?= ../../../..\n"
	+"DOC_PREFIX?= ${.CURDIR}/../../..\n"
	+"\n"
	+".include \"${DOC_PREFIX}/share/mk/doc.project.mk\""
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7835
	+msgid "With the document structure complete, the <acronym>PO</acronym> file can be created with <command>make po</command>."
	+msgstr "文章結構處理好後，可以執行建立 <command>make po</command> 建立 <acronym>PO</acronym> 檔。"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:7844
	+#, fuzzy
	+msgid "Translating"
	+msgstr "翻譯"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7846
	+msgid "The <application>gettext</application> system greatly reduces the number of things that must be tracked by a translator. Strings to be translated are extracted from the original document into a <acronym>PO</acronym> file. Then a <acronym>PO</acronym> editor is used to enter the translated versions of each string."
	+msgstr "<application>gettext</application>系統大幅減少翻譯者要追蹤的事情。字串從原始文件提取到<acronym>PO</acronym> 檔。再用 <acronym>PO</acronym> 檔編輯器輸入字串的翻譯。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7853
	+msgid "The FreeBSD <acronym>PO</acronym> translation system does not overwrite <acronym>PO</acronym> files, so the extraction step can be run at any time to update the <acronym>PO</acronym> file."
	+msgstr "FreeBSD <acronym>PO</acronym> 翻譯系統不會覆蓋掉 <acronym>PO</acronym> 檔。所以提取步驟可以在任何時候重複執行來更新 <acronym>PO</acronym> 檔。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7858
	+msgid "A <acronym>PO</acronym> editor is used to edit the file. <package role=\"port\">editors/poedit</package> is shown in these examples because it is simple and has minimal requirements. Other <acronym>PO</acronym> editors offer features to make the job of translating easier. The Ports Collection offers several of these editors, including <package role=\"port\">devel/gtranslator</package>."
	+msgstr "用 <acronym>PO</acronym> 檔編輯器來編輯檔案。此例是用 <package role=\"port\">editors/poedit</package>，因為它很簡單而且系統需求低。其他的 <acronym>PO</acronym> 檔編輯器提供一些特點，能使翻譯工作更輕鬆。Ports 裡有數個編輯器，包括 <package role=\"port\">devel/gtranslator</package> 。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:7866
	+msgid "It is important to preserve the <acronym>PO</acronym> file. It contains all of the work that translators have done."
	+msgstr "保留 <acronym>PO</acronym> 檔是很重要的。它包含所有的翻譯成果。"
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:7870
	+msgid "Translating the Porter's Handbook to Spanish"
	+msgstr "翻譯 Porter 手冊到西班牙文"
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:7872
	+msgid "Enter Spanish translations of the contents of the Porter's Handbook."
	+msgstr "輸入 Porter 手冊的西班牙文內容"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7877
	+msgid "Change to the Spanish Porter's Handbook directory and update the <acronym>PO</acronym> file. The generated <acronym>PO</acronym> file is called <filename>es_ES.po</filename> as shown in <xref linkend=\"po-translations-language-names\"/>."
	+msgstr "切換到西班牙文 Porter 手冊的目錄並更新 <acronym>PO</acronym> 檔。產生的 <acronym>PO</acronym> 檔如 <xref linkend=\"po-translations-language-names\"/> 所示，名叫 <filename>es_ES.po</filename> 。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:7883
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>make po</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>make po</userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:7888
	+msgid "Enter translations using a <acronym>PO</acronym> editor:"
	+msgstr "使用 <acronym>PO</acronym> 檔編輯器輸入翻譯："
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:7898
	+#, fuzzy
	+msgid "Tips for Translators"
	+msgstr "給翻譯者的提示"
	+
	+#. (itstool) path: sect2/title
	+#. (itstool) path: example/title
	+#: book.translate.xml:7901 book.translate.xml:7907
	+msgid "Preserving <acronym>XML</acronym> Tags"
	+msgstr "保留 <acronym>XML</acronym> 標籤"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:7903
	+msgid "Preserve <acronym>XML</acronym> tags that are shown in the English original."
	+msgstr ""
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:7909
	+msgid "English original:"
	+msgstr "英文原文："
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:7911
	+#, no-wrap
	+msgid "If <tag class=\"starttag\">acronym</tag>NTP<tag class=\"endtag\">acronym</tag> is not being used"
	+msgstr "If <tag class=\"starttag\">acronym</tag>NTP<tag class=\"endtag\">acronym</tag> is not being used"
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:7913
	+msgid "Spanish translation:"
	+msgstr "西班牙文翻譯："
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:7915
	+#, no-wrap
	+msgid "Si <tag class=\"starttag\">acronym</tag>NTP<tag class=\"endtag\">acronym</tag> no se utiliza"
	+msgstr "Si <tag class=\"starttag\">acronym</tag>NTP<tag class=\"endtag\">acronym</tag> no se utiliza"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:7920
	+msgid "Preserving Spaces"
	+msgstr "保留空白"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:7922
	+msgid "Preserve existing spaces at the beginning and end of strings to be translated. The translated version must have these spaces also."
	+msgstr "保留要翻譯字串前後的空白。翻譯的版本也要有這些空白。"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:7928
	+msgid "Verbatim Tags"
	+msgstr "不要翻譯的標籤"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:7930
	+msgid "The contents of some tags should be copied verbatim, not translated:"
	+msgstr "有些標籤的內容要一字不差地保留，不要翻譯。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7935
	+msgid "<tag class=\"starttag\">citerefentry</tag>"
	+msgstr "<tag class=\"starttag\">citerefentry</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7939
	+msgid "<tag class=\"starttag\">command</tag>"
	+msgstr "<tag class=\"starttag\">command</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7943
	+msgid "<tag class=\"starttag\">filename</tag>"
	+msgstr "<tag class=\"starttag\">filename</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7947
	+msgid "<tag class=\"starttag\">literal</tag>"
	+msgstr "<tag class=\"starttag\">literal</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7951
	+msgid "<tag class=\"starttag\">manvolnum</tag>"
	+msgstr "<tag class=\"starttag\">manvolnum</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7955
	+msgid "<tag class=\"starttag\">orgname</tag>"
	+msgstr "<tag class=\"starttag\">orgname</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7959
	+msgid "<tag class=\"starttag\">package</tag>"
	+msgstr "<tag class=\"starttag\">package</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7963
	+msgid "<tag class=\"starttag\">programlisting</tag>"
	+msgstr "<tag class=\"starttag\">programlisting</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7967
	+msgid "<tag class=\"starttag\">prompt</tag>"
	+msgstr "<tag class=\"starttag\">prompt</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7971
	+msgid "<tag class=\"starttag\">refentrytitle</tag>"
	+msgstr "<tag class=\"starttag\">refentrytitle</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7975
	+msgid "<tag class=\"starttag\">screen</tag>"
	+msgstr "<tag class=\"starttag\">screen</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7979
	+msgid "<tag class=\"starttag\">userinput</tag>"
	+msgstr "<tag class=\"starttag\">userinput</tag>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:7983
	+msgid "<tag class=\"starttag\">varname</tag>"
	+msgstr "<tag class=\"starttag\">varname</tag>"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:7989
	+msgid "<literal>$FreeBSD$</literal> Strings"
	+msgstr "<literal>$FreeBSD$</literal> 字串"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:7992
	+msgid "The $FreeBSD$ version strings used in 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:"
	+msgstr "檔案裡的 $FreeBSD$ 版本字串需要特別處理。例如 <xref linkend=\"po-translations-creating-example\"/> 裡，這些字串不是要被展開 (expanded)。英文文件使用 <literal>&dollar;</literal> entities 來避免使用實際的金錢符號。"
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:7999 book.translate.xml:8017
	+#, no-wrap
	+msgid "&dollar;FreeBSD&dollar;"
	+msgstr "&dollar;FreeBSD&dollar;"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8001
	+msgid "The <literal>&dollar;</literal> entities are not seen as dollar signs by the version control system and so the string is not expanded into a version string."
	+msgstr "版本控制符號不會把 <literal>&dollar;</literal> entities 看成金錢符號，所以不會把字串展開成版本字串。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8005
	+msgid "When a <acronym>PO</acronym> file is created, the <literal>&dollar;</literal> entities used in examples are replaced with actual dollar signs. The resulting literal <literal>$FreeBSD$</literal> string will be wrongly expanded by the version control system when the file is committed."
	+msgstr "當 <acronym>PO</acronym> 檔建立後，範例中的 <literal>&dollar;</literal> entities 被實際的金錢符號取代。當檔案提交時，產生的 <literal>$FreeBSD$</literal> 將會被版本控制系統展開。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8012
	+msgid "The same technique as used in the English documents can be used in the translation. The <literal>&dollar;</literal> is used to replace the dollar sign in the translation entered into the <acronym>PO</acronym> editor:"
	+msgstr "英文文件用的相同技術可以被用在翻譯上。翻譯時用 <literal>&dollar;</literal> 來取代金錢符號，輸入到 <acronym>PO</acronym> 檔編輯器："
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8060
	+msgid "Building a Translated Document"
	+msgstr "編譯翻譯的文件"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8062
	+msgid ""
	+"A translated version of the original document can be created at any time. Any untranslated portions of the original will be included in English in the resulting document. Most <acronym>PO</acronym> editors have an indicator that shows how much of the translation has been completed. This makes it easy for the translator to see when enough strings have been translated to make building the final document "
	+"worthwhile."
	+msgstr "原文的翻譯版本可以在任何時候被建立。未翻譯的部份會以英文呈獻。大部份 <acronym>PO</acronym> 編輯器有指標可以顯示翻譯完成度。這讓翻譯者更容易看翻譯好的字串是否足夠來編譯最終的文件。"
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:8072
	+#, fuzzy
	+msgid "Building the Spanish Porter's Handbook"
	+msgstr "編譯西班牙文 Porter 手冊"
	+
	+#. (itstool) path: example/para
	+#: book.translate.xml:8074
	+msgid "Build and preview the Spanish version of the Porter's Handbook that was created in an earlier example."
	+msgstr "編譯和預覽之前範例翻譯的西班牙文版 Porter 手冊"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8079
	+msgid "Build the translated document. Because the original is a book, the generated document is <filename>book.xml</filename>."
	+msgstr "編譯翻譯好的文件。因為原文是書籍，所以產生的文件是<filename>book.xml</filename>。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8083
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>make tran</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>\n"
	+"<prompt>%</prompt> <userinput>make tran</userinput>"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8088
	+msgid "Render the translated <filename>book.xml</filename> to <acronym>HTML</acronym> and view it with <application>Firefox</application>. This is the same procedure used with the English version of the documents, and other <varname>FORMATS</varname> can be used here in the same way. See <xref linkend=\"doc-build-rendering-common-formats\"/>."
	+msgstr "轉換翻譯好的<filename>book.xml</filename>成<acronym>HTML</acronym>並用<application>Firefox</application>來瀏覽。這和英文版是相同的步驟，其他 <varname>FORMATS</varname> 也可以這樣做。請見<xref linkend=\"doc-build-rendering-common-formats\"/> 。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8095
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>make FORMATS=html</userinput>\n"
	+"<prompt>%</prompt> <userinput>firefox book.html</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>make FORMATS=html</userinput>\n"
	+"<prompt>%</prompt> <userinput>firefox book.html</userinput>"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8103
	+msgid "Submitting the New Translation"
	+msgstr "提交新翻譯"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8105
	+msgid "Prepare the new translation files for submission. This includes adding the files to the version control system, setting additional properties on them, then creating a diff for submission."
	+msgstr "準備要提交的新翻譯。這包含新增檔案到版本控制系統，對檔案設定額外的屬性，並建立 diff 來提交。"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8110
	+msgid "The diff files created by these examples can be attached to a <link xlink:href=\"https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation\">documentation bug report</link> or <link xlink:href=\"https://reviews.freebsd.org/\">code review</link>."
	+msgstr "範例中產生的 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> 。"
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:8116
	+msgid "Spanish Translation of the NanoBSD Article"
	+msgstr "NanoBSD 文章的西班牙文翻譯"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8120 book.translate.xml:8187
	+msgid "Add a FreeBSD version string comment as the first line of the <acronym>PO</acronym> file:"
	+msgstr "增加 FreeBSD 版本字串註解到 <acronym>PO</acronym> 檔的第一行："
	+
	+#. (itstool) path: step/programlisting
	+#: book.translate.xml:8123 book.translate.xml:8190
	+#, no-wrap
	+msgid "#$FreeBSD$"
	+msgstr "#$FreeBSD$"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8127 book.translate.xml:8194
	+msgid "Add the <filename>Makefile</filename>, the <acronym>PO</acronym> file, and the generated <acronym>XML</acronym> translation to version control:"
	+msgstr "增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統："
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8132
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>\n"
	+"<prompt>%</prompt> <userinput>ls</userinput>\n"
	+"Makefile\tarticle.xml\tes_ES.po\n"
	+"<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput>\n"
	+"A Makefile\n"
	+"A article.xml\n"
	+"A es_ES.po"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>\n"
	+"<prompt>%</prompt> <userinput>ls</userinput>\n"
	+"Makefile\tarticle.xml\tes_ES.po\n"
	+"<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput>\n"
	+"A Makefile\n"
	+"A article.xml\n"
	+"A es_ES.po"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8142 book.translate.xml:8209
	+msgid "Set the <application>Subversion</application> <literal>svn:keywords</literal> properties on these files to <literal>FreeBSD=%H</literal> so <literal>$FreeBSD$</literal> strings are expanded into the path, revision, date, and author when committed:"
	+msgstr "設定這些檔案的 <application>Subversion</application> <literal>svn:keywords</literal> 屬性到 <literal>FreeBSD=%H</literal>，讓提交時 <literal>$FreeBSD$</literal> 字串可以被展開成路徑、版本、日期和作者。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8150
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput>\n"
	+"property 'svn:keywords' set on 'Makefile'\n"
	+"property 'svn:keywords' set on 'article.xml'\n"
	+"property 'svn:keywords' set on 'es_ES.po'"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput>\n"
	+"property 'svn:keywords' set on 'Makefile'\n"
	+"property 'svn:keywords' set on 'article.xml'\n"
	+"property 'svn:keywords' set on 'es_ES.po'"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8157
	+msgid "Set the <acronym>MIME</acronym> types of the files. These are <literal>text/xml</literal> for books and articles, and <literal>text/x-gettext-translation</literal> for the <acronym>PO</acronym> file."
	+msgstr "設定檔案的<acronym>MIME</acronym> 類型。書籍和文章是 <literal>text/xml</literal> ，<acronym>PO</acronym> 檔是 <literal>text/x-gettext-translation</literal> 。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8163
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput>\n"
	+"property 'svn:mime-type' set on 'es_ES.po'\n"
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type text/xml article.xml</userinput>\n"
	+"property 'svn:mime-type' set on 'article.xml'"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput>\n"
	+"property 'svn:mime-type' set on 'es_ES.po'\n"
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type text/xml article.xml</userinput>\n"
	+"property 'svn:mime-type' set on 'article.xml'"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8170
	+msgid "Create a diff of the new files from the <filename>~/doc/</filename> base directory so the full path is shown with the filenames. This helps committers identify the target language directory."
	+msgstr "從 <filename>~/doc/</filename> 建立這些新檔案的 diff，讓檔名顯示完整的路徑。這可以幫助提交者辨識目標語系目錄。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8175
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc</userinput>\n"
	+"<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc</userinput>\n"
	+"<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput>"
	+
	+#. (itstool) path: example/title
	+#: book.translate.xml:8182
	+msgid "Korean <acronym>UTF-8</acronym> Translation of the Explaining-BSD Article"
	+msgstr "Explaining-BSD 文章的韓文 <acronym>UTF-8</acronym> 翻譯"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8199
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput>\n"
	+"<prompt>%</prompt> <userinput>ls</userinput>\n"
	+"Makefile\tarticle.xml\tko_KR.po\n"
	+"<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput>\n"
	+"A Makefile\n"
	+"A article.xml\n"
	+"A ko_KR.po"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput>\n"
	+"<prompt>%</prompt> <userinput>ls</userinput>\n"
	+"Makefile\tarticle.xml\tko_KR.po\n"
	+"<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput>\n"
	+"A Makefile\n"
	+"A article.xml\n"
	+"A ko_KR.po"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8216
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput>\n"
	+"property 'svn:keywords' set on 'Makefile'\n"
	+"property 'svn:keywords' set on 'article.xml'\n"
	+"property 'svn:keywords' set on 'ko_KR.po'"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput>\n"
	+"property 'svn:keywords' set on 'Makefile'\n"
	+"property 'svn:keywords' set on 'article.xml'\n"
	+"property 'svn:keywords' set on 'ko_KR.po'"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8223
	+msgid "Set the <acronym>MIME</acronym> types of the files. Because these files use the <acronym>UTF-8</acronym> character set, that is also specified. To prevent the version control system from mistaking these files for binary data, the <literal>fbsd:notbinary</literal> property is also set:"
	+msgstr "設定檔案的 <acronym>MIME</acronym> 類型。因為這些檔案使用 <acronym>UTF-8</acronym> 字元集，這也需要指定。為了防止版本控制系統將這些檔案誤認為二進位資料，<literal>fbsd:notbinary</literal> 屬性也需要設定。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8230
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/x-gettext-translation; charset=UTF-8' ko_KR.po</userinput>\n"
	+"property 'svn:mime-type' set on 'ko_KR.po'\n"
	+"<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput>\n"
	+"property 'fbsd:notbinary' set on 'ko_KR.po'\n"
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/xml; charset=UTF-8' article.xml</userinput>\n"
	+"property 'svn:mime-type' set on 'article.xml'\n"
	+"<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes article.xml</userinput>\n"
	+"property 'fbsd:notbinary' set on 'article.xml'"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/x-gettext-translation；charset=UTF-8' ko_KR.po</userinput>\n"
	+"property 'svn:mime-type' set on 'ko_KR.po'\n"
	+"<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput>\n"
	+"property 'fbsd:notbinary' set on 'ko_KR.po'\n"
	+"<prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/xml；charset=UTF-8' article.xml</userinput>\n"
	+"property 'svn:mime-type' set on 'article.xml'\n"
	+"<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes article.xml</userinput>\n"
	+"property 'fbsd:notbinary' set on 'article.xml'"
	+
	+#. (itstool) path: step/para
	+#: book.translate.xml:8241
	+msgid "Create a diff of these new files from the <filename>~/doc/</filename> base directory:"
	+msgstr "從 <filename>~/doc/</filename> 建立這些新檔案的 diff。"
	+
	+#. (itstool) path: step/screen
	+#: book.translate.xml:8244
	+#, no-wrap
	+msgid ""
	+"<prompt>%</prompt> <userinput>cd ~/doc</userinput>\n"
	+"<userinput>svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff</userinput>"
	+msgstr ""
	+"<prompt>%</prompt> <userinput>cd ~/doc</userinput>\n"
	+"<userinput>svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff</userinput>"
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:8285
	+msgid "Writing Style"
	+msgstr "寫作風格"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8288
	+msgid "Tips"
	+msgstr "叮嚀"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8290
	+msgid "Technical documentation can be improved by consistent use of several principles. Most of these can be classified into three goals: <emphasis>be clear</emphasis>, <emphasis>be complete</emphasis>, and <emphasis>be concise</emphasis>. These goals can conflict with each other. Good writing consists of a balance between them."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8299
	+msgid "Be Clear"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8301
	+msgid "Clarity is extremely important. The reader may be a novice, or reading the document in a second language. Strive for simple, uncomplicated text that clearly explains the concepts."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8306
	+msgid "Avoid flowery or embellished speech, jokes, or colloquial expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8310
	+msgid "Keep explanations as short, simple, and clear as possible. Avoid empty phrases like <quote>in order to</quote>, which usually just means <quote>to</quote>. Avoid potentially patronizing words like <quote>basically</quote>. Avoid Latin terms like <quote>i.e.</quote> or <quote>cf.</quote>, which may be unknown outside of academic or scientific groups."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8318
	+msgid "Write in a formal style. Avoid addressing the reader as <quote>you</quote>. For example, say <quote>copy the file to <filename>/tmp</filename></quote> rather than <quote>you can copy the file to <filename>/tmp</filename></quote>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8324
	+msgid ""
	+"Give clear, correct, <emphasis>tested</emphasis> examples. A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like <quote>but really it should never be done that way</quote>. Bad examples are worse than no examples. Give good examples, because <emphasis>even when warned not to use the example as shown</emphasis>, the "
	+"reader will usually just use the example as shown."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8333
	+msgid "Avoid <emphasis>weasel words</emphasis> like <quote>should</quote>, <quote>might</quote>, <quote>try</quote>, or <quote>could</quote>. These words imply that the speaker is unsure of the facts, and create doubt in the reader."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8339
	+msgid "Similarly, give instructions as imperative commands: not <quote>you should do this</quote>, but merely <quote>do this</quote>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8345
	+msgid "Be Complete"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8347
	+msgid "Do not make assumptions about the reader's abilities or skill level. Tell them what they need to know. Give links to other documents to provide background information without having to recreate it. Put yourself in the reader's place, anticipate the questions they will ask, and answer them."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8356
	+msgid "Be Concise"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8358
	+msgid "While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. One approach is to have an introduction, then a <quote>quick start</quote> section that describes the most common situation, followed by an in-depth reference section."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8369
	+msgid "Guidelines"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8371
	+msgid "To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:8377
	+msgid "Use American English Spelling"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8380
	+msgid "There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. <quote>color</quote>, not <quote>colour</quote>, <quote>rationalize</quote>, not <quote>rationalise</quote>, and so on."
	+msgstr ""
	+
	+#. (itstool) path: note/para
	+#: book.translate.xml:8387
	+msgid "The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. The other documents such as books, web site, manual pages, etc. will have to use American English."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:8397
	+msgid "Do not use contractions"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8400
	+msgid "Do not use contractions. Always spell the phrase out in full. <quote>Don't use contractions</quote> is wrong."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8404
	+msgid "Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:8411
	+msgid "Use the serial comma"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8414
	+msgid "In a list of items within a paragraph, separate each item from the others with a comma. Separate the last item from the others with a comma and the word <quote>and</quote>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8419
	+msgid "For example:"
	+msgstr ""
	+
	+#. (itstool) path: blockquote/para
	+#: book.translate.xml:8422
	+msgid "This is a list of one, two and three items."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8425
	+msgid "Is this a list of three items, <quote>one</quote>, <quote>two</quote>, and <quote>three</quote>, or a list of two items, <quote>one</quote> and <quote>two and three</quote>?"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8430
	+msgid "It is better to be explicit and include a serial comma:"
	+msgstr ""
	+
	+#. (itstool) path: blockquote/para
	+#: book.translate.xml:8434
	+msgid "This is a list of one, two, and three items."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:8440
	+msgid "Avoid redundant phrases"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8443
	+msgid "Do not use redundant phrases. In particular, <quote>the command</quote>, <quote>the file</quote>, and <quote>man command</quote> are often redundant."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8447
	+msgid "For example, commands:"
	+msgstr ""
	+
	+#. (itstool) path: informalexample/para
	+#: book.translate.xml:8450
	+msgid "Wrong: Use the <command>svn</command> command to update sources."
	+msgstr ""
	+
	+#. (itstool) path: informalexample/para
	+#: book.translate.xml:8455
	+msgid "Right: Use <command>svn</command> to update sources."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8459
	+msgid "Filenames:"
	+msgstr ""
	+
	+#. (itstool) path: informalexample/para
	+#: book.translate.xml:8462
	+msgid "Wrong: … in the filename <filename>/etc/rc.local</filename>…"
	+msgstr ""
	+
	+#. (itstool) path: informalexample/para
	+#: book.translate.xml:8467
	+msgid "Right: … in <filename>/etc/rc.local</filename>…"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8471
	+msgid "Manual page references (the second example uses <tag>citerefentry</tag> with the <literal>&man.csh.1;</literal> entity):."
	+msgstr ""
	+
	+#. (itstool) path: informalexample/para
	+#: book.translate.xml:8476
	+msgid "Wrong: See <command>man csh</command> for more information."
	+msgstr ""
	+
	+#. (itstool) path: informalexample/para
	+#: book.translate.xml:8481
	+msgid "Right: See <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry>."
	+msgstr ""
	+
	+#. (itstool) path: varlistentry/term
	+#: book.translate.xml:8487
	+msgid "Two spaces between sentences"
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8490
	+msgid "Always use two spaces between sentences, as it improves readability and eases use of tools such as <application>Emacs</application>."
	+msgstr ""
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8494
	+msgid "A period and spaces followed by a capital letter does not always mark a new sentence, especially in names. <quote>Jordan K. Hubbard</quote> is a good example. It has a capital <literal>H</literal> following a period and a space, and is certainly not a new sentence."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8503
	+msgid "For more information about writing style, see <link xlink:href=\"http://www.bartleby.com/141/\">Elements of Style</link>, by William Strunk."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8508
	+msgid "Style Guide"
	+msgstr "風格指南"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8510
	+msgid "To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions."
	+msgstr "由於文件是由眾多作者所維護，為了保持寫作風格的一貫性，請遵守下列撰寫風格慣例。"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8515
	+#, fuzzy
	+msgid "Letter Case"
	+msgstr "大小寫"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8517
	+msgid "Tags are entered in lower case, <tag>para</tag>, <emphasis>not</emphasis> <tag>PARA</tag>."
	+msgstr "Tag 的部份都是用小寫字母，譬如是用 <tag>para</tag> ，<emphasis>而非</emphasis><tag>PARA</tag>。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8520
	+msgid "Text that appears in SGML contexts is generally written in upper case, <literal><!ENTITY…></literal>, and <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> <literal><!entity…></literal> and <literal><!doctype…></literal>."
	+msgstr "而 SGML 內文則是用大寫字母表示，像是： <literal><!ENTITY…></literal> 及 <literal><!DOCTYPE…></literal>， <emphasis>而不是</emphasis> <literal><!entity…></literal> 及 <literal><!doctype…></literal>。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8531
	+msgid "Acronyms should be defined the first time they appear in a document, as in: <quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>. After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document."
	+msgstr "縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法，比如：<quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>。定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙，除非使用完整詞彙可以更能表達語意)來表達即可。通常每本書只會第一次提到時，才會列出完整詞彙，但若您高興也可以在每章第一次提到時又列出完整詞彙。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8539
	+msgid "All acronyms should be enclosed in <tag>acronym</tag> tags."
	+msgstr "所有縮寫要包在<tag>acronym</tag>標籤內。"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8544
	+msgid "Indentation"
	+msgstr "縮排"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8546
	+msgid "The first line in each file starts with no indentation, <emphasis>regardless</emphasis> of the indentation level of the file which might contain the current file."
	+msgstr "<emphasis>無論</emphasis>檔案縮排設定為何，每個檔案的第一行都不縮排。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8550
	+msgid "Opening tags increase the indentation level by two spaces. Closing tags decrease the indentation level by two spaces. Blocks of eight spaces at the start of a line should be replaced with a tab. Do not use spaces in front of tabs, and do not add extraneous whitespace at the end of a line. Content within elements should be indented by two spaces if the content runs over more than one line."
	+msgstr "未完的標籤會以多兩個空白來增加縮排，結尾的標籤則少兩個空白來縮減縮排。若已達 8 個空白，則以 tab 取代之。此外，在 tab 前面不要再用空白，也不要在每行後面加上空白。每個 tag 的內文若超過一行的話，則接下來的就多兩個空白以做縮排。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8558
	+msgid "For example, the source for this section looks like this:"
	+msgstr "舉個例子，這節所用的寫法大致是下面這樣："
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:8561
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect2</tag>\n"
	+" <tag class=\"starttag\">title</tag>Indentation<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>The first line in each file starts with no indentation,\n"
	+"\t<tag class=\"starttag\">emphasis</tag>regardless<tag class=\"endtag\">emphasis</tag> of the indentation level of\n"
	+"\tthe file which might contain the current file.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" ...\n"
	+" <tag class=\"endtag\">sect2</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">chapter</tag>"
	+msgstr ""
	+"<tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect2</tag>\n"
	+" <tag class=\"starttag\">title</tag>Indentation<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>The first line in each file starts with no indentation,\n"
	+"\t<tag class=\"starttag\">emphasis</tag>regardless<tag class=\"endtag\">emphasis</tag> of the indentation level of\n"
	+"\tthe file which might contain the current file。<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" ...\n"
	+" <tag class=\"endtag\">sect2</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">chapter</tag>"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8579
	+#, fuzzy
	+msgid "Tags containing long attributes follow the same rules. Following the indentation rules in this case helps editors and writers see which content is inside the tags:"
	+msgstr "有長屬性的標籤也是遵循一樣的原則。遵守縮排規則可以幫助編輯和作者了解哪些內容在標籤內："
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:8584
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>See the <tag class=\"starttag\">link\n"
	+" linkend=\"gmirror-troubleshooting\"</tag>Troubleshooting<tag class=\"endtag\">link</tag>\n"
	+" section if there are problems booting. Powering down and\n"
	+" disconnecting the original <tag class=\"starttag\">filename</tag>ada0<tag class=\"endtag\">filename</tag> disk\n"
	+" will allow it to be kept as an offline backup.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>It is also possible to journal the boot disk of a &os;\n"
	+" system. Refer to the article <tag class=\"starttag\">link\n"
	+" xlink:href=\"&url.articles.gjournal-desktop;\"</tag>Implementing UFS\n"
	+" Journaling on a Desktop PC<tag class=\"endtag\">link</tag> for detailed\n"
	+" instructions.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+"<tag class=\"starttag\">para</tag>See the <tag class=\"starttag\">link\n"
	+" linkend=\"gmirror-troubleshooting\"</tag>Troubleshooting<tag class=\"endtag\">link</tag>\n"
	+" section if there are problems booting. Powering down and\n"
	+" disconnecting the original <tag class=\"starttag\">filename</tag>ada0<tag class=\"endtag\">filename</tag> disk\n"
	+" will allow it to be kept as an offline backup.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+"<tag class=\"starttag\">para</tag>It is also possible to journal the boot disk of a &os;\n"
	+" system. Refer to the article <tag class=\"starttag\">link\n"
	+" xlink:href=\"&url.articles.gjournal-desktop;\"</tag>Implementing UFS\n"
	+" Journaling on a Desktop PC<tag class=\"endtag\">link</tag> for detailed\n"
	+" instructions.<tag class=\"endtag\">para</tag>"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8596
	+msgid "When an element is too long to fit on the remainder of a line without wrapping, moving the start tag to the next line can make the source easier to read. In this example, the <literal>systemitem</literal> element has been moved to the next line to avoid wrapping and indenting:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:8602
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">para</tag>With file flags, even\n"
	+" <tag class=\"starttag\">systemitem class=\"username\"</tag>root<tag class=\"endtag\">systemitem</tag> can be\n"
	+" prevented from removing or altering files.<tag class=\"endtag\">para</tag>"
	+msgstr ""
	+"<tag class=\"starttag\">para</tag>With file flags, even\n"
	+" <tag class=\"starttag\">systemitem class=\"username\"</tag>root<tag class=\"endtag\">systemitem</tag> can be\n"
	+" prevented from removing or altering files。<tag class=\"endtag\">para</tag>"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8606
	+msgid "Configurations to help various text editors conform to these guidelines can be found in <xref linkend=\"editor-config\"/>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8612
	+msgid "Tag Style"
	+msgstr "標籤風格"
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:8615
	+msgid "Tag Spacing"
	+msgstr "標籤空行"
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:8617
	+msgid "Tags that start at the same indent as a previous tag should be separated by a blank line, and those that are not at the same indent as a previous tag should not:"
	+msgstr "同一縮排等級的標籤要以空一行來做區隔，而不同縮排等級的則不必。比如："
	+
	+#. (itstool) path: informalexample/programlisting
	+#: book.translate.xml:8622
	+#, no-wrap
	+msgid ""
	+"<tag class=\"starttag\">article lang='en'</tag>\n"
	+" <tag class=\"starttag\">articleinfo</tag>\n"
	+" <tag class=\"starttag\">title</tag>NIS<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">pubdate</tag>October 1999<tag class=\"endtag\">pubdate</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag>...\n"
	+"\t...\n"
	+"\t...<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">articleinfo</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>...<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>...<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">article</tag>"
	+msgstr ""
	+"<tag class=\"starttag\">article lang='en'</tag>\n"
	+" <tag class=\"starttag\">articleinfo</tag>\n"
	+" <tag class=\"starttag\">title</tag>NIS<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">pubdate</tag>October 1999<tag class=\"endtag\">pubdate</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag>...\n"
	+"\t...\n"
	+"\t...<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">articleinfo</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>...<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>...<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>...<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">article</tag>"
	+
	+#. (itstool) path: sect3/title
	+#: book.translate.xml:8651
	+msgid "Separating Tags"
	+msgstr "標籤的分行"
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:8653
	+msgid "Tags like <tag>itemizedlist</tag> which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves."
	+msgstr "像是 <tag>itemizedlist</tag> 這類的標籤事實上本身不含任何文字資料，必須得由其他標籤來補充內文。這類的標籤會獨用一整行。"
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:8658
	+msgid "Tags like <tag>para</tag> and <tag>term</tag> do not need other tags to contain normal character data, and their contents begin immediately after the tag, <emphasis>on the same line</emphasis>."
	+msgstr "另外，像是 <tag>para</tag> 及 <tag>term</tag> 這類的標籤並不需搭配其他標籤，就可附上文字資料，並且在標籤後面的<emphasis>同一行</emphasis>內即可立即寫上這些內文。"
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:8663
	+msgid "The same applies to when these two types of tags close."
	+msgstr "當然，這兩類的標籤結尾時也是跟上面道理相同。"
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:8666
	+msgid "This leads to an obvious problem when mixing these tags."
	+msgstr "不過，當上述這兩種標籤混用時，會有很明顯的困擾。"
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:8669
	+msgid "When a starting tag which cannot contain character data directly follows a tag of the type that requires other tags within it to use character data, they are on separate lines. The second tag should be properly indented."
	+msgstr "當第一類標籤的後面接上第二類標籤的話，那麼要把這兩類標籤各自分行來寫。後者標籤的段落，也是需要做適當縮排調整。"
	+
	+#. (itstool) path: sect3/para
	+#: book.translate.xml:8674
	+msgid "When a tag which can contain character data closes directly after a tag which cannot contain character data closes, they co-exist on the same line."
	+msgstr "而第二類標籤結尾時，可以與第一類標籤的結尾放在同一行。"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8681
	+msgid "Whitespace Changes"
	+msgstr "空白的更改"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8683
	+msgid "<emphasis>Do not commit changes to content at the same time as changes to formatting</emphasis>."
	+msgstr "<emphasis>在提交修改時，請別在修改內容的同時，也一起更改編排格式。</emphasis>。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8687
	+msgid "When content and whitespace changes are kept separate, translation teams can easily see whether a change was content that must be translated or only whitespace."
	+msgstr "如此一來，像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容，而不用費心思去判斷該行的改變，是由於格式重排或者內容異動。"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8691
	+msgid "For example, if two sentences have been added to a paragraph so that the line lengths now go over 80 columns, first commit the change with the too-long lines. Then fix the line wrapping, and commit this second change. In the commit message for the second change, indicate that this is a whitespace-only change that can be ignored by translators."
	+msgstr "舉例說明，若要在某段加上兩個句子，如此一來該段落的某行勢必會超出 80 縱列，這時請先 commmit 修改。接著，再修飾過長行落的換行，然後再次 commit 之。而第二次的 commit 紀錄，請明確說明這只是 whitespace-only (修改空白而已) 的更改，如此一來，翻譯團隊就可以忽略第二次 commit 了。"
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8701
	+msgid "Non-Breaking Space"
	+msgstr "Nonbreaking space"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8703
	+msgid "Avoid line breaks in places where they look ugly or make it difficult to follow a sentence. Line breaks depend on the width of the chosen output medium. In particular, viewing the HTML documentation with a text browser can lead to badly formatted paragraphs like the next one:"
	+msgstr "請避免一些情況下的斷行：造成版面醜醜的、或是須連貫表達的同一句子。斷行的情況會隨所閱讀的工具不同而有所不同。尤其是透過純文字瀏覽器來看 HTML 時會更明顯看到類似下面這樣不好的編排段落："
	+
	+#. (itstool) path: sect2/literallayout
	+#: book.translate.xml:8709
	+#, no-wrap
	+msgid ""
	+"Data capacity ranges from 40 MB to 15\n"
	+"GB. Hardware compression …"
	+msgstr ""
	+"Data capacity ranges from 40 MB to 15\n"
	+"GB。 Hardware compression …"
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8712
	+msgid "The general entity <literal>&nbsp;</literal> prohibits line breaks between parts belonging together. Use non-breaking spaces in the following places:"
	+msgstr "請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行，以下示範如何使用 nonbreaking spaces："
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8718
	+msgid "between numbers and units:"
	+msgstr "在數字與單位之間："
	+
	+#. (itstool) path: listitem/programlisting
	+#: book.translate.xml:8719
	+#, no-wrap
	+msgid "57600&nbsp;bps"
	+msgstr "57600&nbsp;bps"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8723
	+msgid "between program names and version numbers:"
	+msgstr "在程式名稱與版號之間："
	+
	+#. (itstool) path: listitem/programlisting
	+#: book.translate.xml:8724
	+#, no-wrap
	+msgid "&os;&nbsp;9.2"
	+msgstr "&os;&nbsp;9.2"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:8728
	+msgid "between multiword names (use with caution when applying this to more than 3-4 word names like <quote>The FreeBSD Brazilian Portuguese Documentation Project</quote>):"
	+msgstr "multiword 之間 (使用時請小心，像是 <quote>The FreeBSD Brazilian Portuguese Documentation Project</quote> 這類由三到四個字所組成的，則不用加。)："
	+
	+#. (itstool) path: listitem/programlisting
	+#: book.translate.xml:8732
	+#, no-wrap
	+msgid "Sun&nbsp;Microsystems"
	+msgstr "Sun&nbsp;Microsystems"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8739
	+msgid "Word List"
	+msgstr "詞彙表"
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8741
	+msgid "This list of words shows the correct spelling and capitalization when used in FreeBSD documentation. If a word is not on this list, ask about it on the <link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project mailing list</link>."
	+msgstr "以下詞彙表列出使用在 FreeBSD 文件的正確拼法和大小寫。若找不到要找的詞彙，請詢問 <link xlink:href=\"http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc\">FreeBSD documentation project mailing list</link> 。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8749
	+msgid "Word"
	+msgstr "Word"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8750
	+msgid "XML Code"
	+msgstr "XML Code"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8751
	+msgid "Notes"
	+msgstr "Notes"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8757
	+msgid "CD-ROM"
	+msgstr "CD-ROM"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8759
	+msgid "<tag class=\"starttag\">acronym</tag><literal>CD-ROM</literal><tag class=\"endtag\">acronym</tag>"
	+msgstr "<tag class=\"starttag\">acronym</tag><literal>CD-ROM</literal><tag class=\"endtag\">acronym</tag>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8763
	+msgid "DoS (Denial of Service)"
	+msgstr "DoS (Denial of Service)"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8764
	+msgid "<tag class=\"starttag\">acronym</tag><literal>DoS</literal><tag class=\"endtag\">acronym</tag>"
	+msgstr "<tag class=\"starttag\">acronym</tag><literal>DoS</literal><tag class=\"endtag\">acronym</tag>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8768
	+msgid "email"
	+msgstr "email"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8772
	+msgid "file system"
	+msgstr "file system"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8776
	+msgid "IPsec"
	+msgstr "IPsec"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8780
	+msgid "Internet"
	+msgstr "Internet"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8784
	+msgid "manual page"
	+msgstr "manual page"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8788
	+msgid "mail server"
	+msgstr "mail server"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8792
	+msgid "name server"
	+msgstr "name server"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8796
	+msgid "Ports Collection"
	+msgstr "Ports Collection"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8800
	+msgid "read-only"
	+msgstr "read-only"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8804
	+msgid "Soft Updates"
	+msgstr "Soft Updates"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8808
	+msgid "stdin"
	+msgstr "stdin"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8809
	+msgid "<tag class=\"starttag\">varname</tag>stdin<tag class=\"endtag\">varname</tag>"
	+msgstr "<tag class=\"starttag\">varname</tag>stdin<tag class=\"endtag\">varname</tag>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8813
	+msgid "stdout"
	+msgstr "stdout"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8814
	+msgid "<tag class=\"starttag\">varname</tag>stdout<tag class=\"endtag\">varname</tag>"
	+msgstr "<tag class=\"starttag\">varname</tag>stdout<tag class=\"endtag\">varname</tag>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8818
	+msgid "stderr"
	+msgstr "stderr"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8819
	+msgid "<tag class=\"starttag\">varname</tag>stderr<tag class=\"endtag\">varname</tag>"
	+msgstr "<tag class=\"starttag\">varname</tag>stderr<tag class=\"endtag\">varname</tag>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8823
	+msgid "Subversion"
	+msgstr "Subversion"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8825
	+msgid "<tag class=\"starttag\">application</tag><literal>Subversion</literal><tag class=\"endtag\">application</tag>"
	+msgstr "<tag class=\"starttag\">application</tag><literal>Subversion</literal><tag class=\"endtag\">application</tag>"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8826
	+msgid "Do not refer to the Subversion application as <literal>SVN</literal> in upper case. To refer to the command, use <tag class=\"starttag\">command</tag><literal>svn</literal><tag class=\"endtag\">command</tag>."
	+msgstr "不要用大寫<literal>SVN</literal>來表示 Subversion應用程式。以<tag class=\"starttag\">command</tag><literal>svn</literal><tag class=\"endtag\">command</tag>來表示指令。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8837
	+msgid "userland"
	+msgstr "userland"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8839
	+#, fuzzy
	+msgid "things that apply to user space, not the kernel"
	+msgstr "指user space，不是核心。"
	+
	+#. (itstool) path: row/entry
	+#: book.translate.xml:8844
	+msgid "web server"
	+msgstr "web server"
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:8883
	+msgid "Editor Configuration"
	+msgstr ""
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:8885
	+msgid "Adjusting text editor configuration can make working on document files quicker and easier, and help documents conform to <acronym>FDP</acronym> guidelines."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8890
	+msgid "<application>Vim</application>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8892
	+msgid "Install from <package>editors/vim</package> or <package>editors/vim-lite</package>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8896 book.translate.xml:8971
	+msgid "Configuration"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8898
	+msgid "Edit <filename>~/.vimrc</filename>, adding these lines:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:8901
	+#, no-wrap
	+msgid ""
	+"if has(\"autocmd\")\n"
	+" au BufNewFile,BufRead .sgml,.ent,.xsl,.xml call Set_SGML()\n"
	+" au BufNewFile,BufRead *.[1-9] call ShowSpecial()\n"
	+"endif \" has(autocmd)\n"
	+"\n"
	+"function Set_Highlights()\n"
	+" \"match ExtraWhitespace /^\\s* \\s*\\\|\\s\\+$/\n"
	+" highlight default link OverLength ErrorMsg\n"
	+" match OverLength /\\%71v.\\+/\n"
	+" return 0\n"
	+"endfunction\n"
	+"\n"
	+"function ShowSpecial()\n"
	+" setlocal list listchars=tab:>>,trail:*,eol:$\n"
	+" hi def link nontext ErrorMsg\n"
	+" return 0\n"
	+"endfunction \" ShowSpecial()\n"
	+"\n"
	+"function Set_SGML()\n"
	+" setlocal number\n"
	+" syn match sgmlSpecial \"&[^;]*;\"\n"
	+" setlocal syntax=sgml\n"
	+" setlocal filetype=xml\n"
	+" setlocal shiftwidth=2\n"
	+" setlocal textwidth=70\n"
	+" setlocal tabstop=8\n"
	+" setlocal softtabstop=2\n"
	+" setlocal formatprg=\"fmt -p\"\n"
	+" setlocal autoindent\n"
	+" setlocal smartindent\n"
	+" \" Rewrap paragraphs\n"
	+" noremap P gqj\n"
	+" \" Replace spaces with tabs\n"
	+" noremap T :s/ /\\t/<CR>\n"
	+" call ShowSpecial()\n"
	+" call Set_Highlights()\n"
	+" return 0\n"
	+"endfunction \" Set_SGML()"
	+msgstr ""
	+
	+#. (itstool) path: sect2/title
	+#: book.translate.xml:8942 book.translate.xml:9000
	+msgid "Use"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8944
	+msgid "Press <keycap>P</keycap> to reformat paragraphs or text that has been selected in Visual mode. Press <keycap>T</keycap> to replace groups of eight spaces with a tab."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8951
	+msgid "<application>Emacs</application>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8953
	+msgid "Install from <package>editors/emacs</package> or <package>editors/xemacs</package>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8957
	+msgid "Edit <filename>~/.emacs</filename>, adding this line:"
	+msgstr ""
	+
	+#. (itstool) path: sect1/programlisting
	+#: book.translate.xml:8960
	+#, no-wrap
	+msgid "(add-hook 'nxml-mode-hook 'turn-on-auto-fill)"
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:8964
	+msgid "<application>nano</application>"
	+msgstr ""
	+
	+#. (itstool) path: sect1/para
	+#: book.translate.xml:8966
	+msgid "Install from <package>editors/nano</package> or <package>editors/nano-devel</package>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8973
	+msgid "Copy the sample <acronym>XML</acronym> syntax highlight file to the user's home directory:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/screen
	+#: book.translate.xml:8976
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8978
	+msgid "Add these lines to the new <filename>~/.nanorc</filename>."
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:8981
	+#, no-wrap
	+msgid ""
	+"syntax \"xml\" \"\\.([jrs]html?\|xml\|xslt?)$\"\n"
	+"# trailing whitespace\n"
	+"color ,blue \"[[:space:]]+$\"\n"
	+"# multiples of eight spaces at the start a line\n"
	+"# (after zero or more tabs) should be a tab\n"
	+"color ,blue \"^([TAB]*[ ]{8})+\"\n"
	+"# tabs after spaces\n"
	+"color ,yellow \"( )+TAB\"\n"
	+"# highlight indents that have an odd number of spaces\n"
	+"color ,red \"^(([ ]{2})+\|(TAB+))*[ ]{1}[^ ]{1}\"\n"
	+"# lines longer than 70 characters\n"
	+"color ,yellow \"^(.{71})\|(TAB.{63})\|(TAB{2}.{55})\|(TAB{3}.{47}).+$\""
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:8994
	+msgid "Process the file to create embedded tabs:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/screen
	+#: book.translate.xml:8996
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>perl -i'' -pe 's/TAB/\\t/g' ~/.nanorc</userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:9002
	+msgid "Specify additional helpful options when running the editor:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/screen
	+#: book.translate.xml:9005
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput>"
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:9007
	+msgid "Users of <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> can define an alias in <filename>~/.cshrc</filename> to automate these options:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/programlisting
	+#: book.translate.xml:9011
	+#, no-wrap
	+msgid "alias nano \"nano -AKipwz -r 70 -T8\""
	+msgstr ""
	+
	+#. (itstool) path: sect2/para
	+#: book.translate.xml:9013
	+msgid "After the alias is defined, the options will be added automatically:"
	+msgstr ""
	+
	+#. (itstool) path: sect2/screen
	+#: book.translate.xml:9016
	+#, no-wrap
	+msgid "<prompt>%</prompt> <userinput>nano <replaceable>chapter.xml</replaceable></userinput>"
	+msgstr ""
	+
	+#. (itstool) path: chapter/title
	+#: book.translate.xml:9054
	+#, fuzzy
	+msgid "See Also"
	+msgstr "他山之石"
	+
	+#. (itstool) path: chapter/para
	+#: book.translate.xml:9056
	+msgid "This document is deliberately not an exhaustive discussion of XML, the DTDs listed, and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:9062
	+msgid "The FreeBSD Documentation Project"
	+msgstr "FreeBSD 文件計劃"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9066
	+msgid "<link xlink:href=\"@@URL_RELPREFIX@@/docproj/index.html\">The FreeBSD Documentation Project web pages</link>"
	+msgstr "<link xlink:href=\"@@URL_RELPREFIX@@/docproj/index.html\">FreeBSD 文件計劃網頁</link>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9071
	+msgid "<link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html\">The FreeBSD Handbook</link>"
	+msgstr "<link xlink:href=\"@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html\">FreeBSD 使用手冊</link>"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:9078
	+msgid "XML"
	+msgstr "XML"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9082
	+msgid "<link xlink:href=\"http://www.w3.org/XML/\">W3C's XML page SGML/XML web page</link>"
	+msgstr "<link xlink:href=\"http://www.w3.org/XML/\">W3C's XML 網頁 SGML/XML 網頁</link>"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:9089
	+msgid "HTML"
	+msgstr "HTML"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9093
	+msgid "<link xlink:href=\"http://www.w3.org/\">The World Wide Web Consortium</link>"
	+msgstr "<link xlink:href=\"http://www.w3.org/\">全球資訊網協會</link>"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9098
	+msgid "<link xlink:href=\"http://www.w3.org/TR/REC-html40/\">The HTML 4.0 specification</link>"
	+msgstr "<link xlink:href=\"http://www.w3.org/TR/REC-html40/\">The HTML 4.0 規格表</link>"
	+
	+#. (itstool) path: sect1/title
	+#: book.translate.xml:9105
	+msgid "DocBook"
	+msgstr "DocBook"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9109
	+msgid "<link xlink:href=\"http://www.oasis-open.org/docbook/\">The DocBook Technical Committee</link>, maintainers of the DocBook DTD"
	+msgstr "<link xlink:href=\"http://www.oasis-open.org/docbook/\">The DocBook 技術委員會</link>， DocBook DTD的維護者"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9115
	+msgid "<link xlink:href=\"http://www.docbook.org/\">DocBook: The Definitive Guide</link>, the online documentation for the DocBook DTD"
	+msgstr "<link xlink:href=\"http://www.docbook.org/\">DocBook：The Definitive Guide</link>， DocBook DTD的線上文件。"
	+
	+#. (itstool) path: listitem/para
	+#: book.translate.xml:9121
	+msgid "<link xlink:href=\"http://docbook.sourceforge.net/\">The DocBook Open Repository</link> contains DSSSL stylesheets and other resources for people using DocBook"
	+msgstr ""
	+
	+#. (itstool) path: appendix/para
	+#: book.translate.xml:9167
	+msgid ""
	+"These examples are not exhaustive—they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of DocBook markup, examine the <acronym>XML</acronym> source for this and other documents available in the <application>Subversion</application> <literal>doc</literal> repository, or available online starting at <uri xlink:href=\"http://svnweb."
	+"FreeBSD.org/doc/\">http://svnweb.FreeBSD.org/doc/</uri>."
	+msgstr ""
	+
	+#. (itstool) path: sect1/title
	+#. (itstool) path: example/title
	+#: book.translate.xml:9176 book.translate.xml:9179
	+msgid "DocBook <tag>book</tag>"
	+msgstr "DocBook <tag>book</tag>"
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:9181
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE book PUBLIC \"-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN\"\n"
	+"\t\"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd\">\n"
	+"\n"
	+"<tag class=\"starttag\">book xmlns=\"http://docbook.org/ns/docbook\"\n"
	+" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"5.0\"\n"
	+" xml:lang=\"en\"</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">info</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example Book<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">author</tag>\n"
	+" <tag class=\"starttag\">personname</tag>\n"
	+" <tag class=\"starttag\">firstname</tag>Your first name<tag class=\"endtag\">firstname</tag>\n"
	+" <tag class=\"starttag\">surname</tag>Your surname<tag class=\"endtag\">surname</tag>\n"
	+" <tag class=\"endtag\">personname</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">affiliation</tag>\n"
	+"\t<tag class=\"starttag\">address</tag>\n"
	+"\t <tag class=\"starttag\">email</tag>foo@example.com<tag class=\"endtag\">email</tag>\n"
	+"\t<tag class=\"endtag\">address</tag>\n"
	+" <tag class=\"endtag\">affiliation</tag>\n"
	+" <tag class=\"endtag\">author</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">copyright</tag>\n"
	+" <tag class=\"starttag\">year</tag>2000<tag class=\"endtag\">year</tag>\n"
	+" <tag class=\"starttag\">holder</tag>Copyright string here<tag class=\"endtag\">holder</tag>\n"
	+" <tag class=\"endtag\">copyright</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag>If your book has an abstract then it should go here.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">info</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">preface</tag>\n"
	+" <tag class=\"starttag\">title</tag>Preface<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>Your book may have a preface, in which case it should be placed\n"
	+" here.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">preface</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Chapter<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first chapter in my book.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first section in my book.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+" <tag class=\"endtag\">chapter</tag>\n"
	+"<tag class=\"endtag\">book</tag>"
	+msgstr ""
	+"<!DOCTYPE book PUBLIC \"-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN\"\n"
	+"\t\"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd\">\n"
	+"\n"
	+"<tag class=\"starttag\">book xmlns=\"http://docbook.org/ns/docbook\"\n"
	+" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"5.0\"\n"
	+" xml:lang=\"en\"</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">info</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example Book<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">author</tag>\n"
	+" <tag class=\"starttag\">personname</tag>\n"
	+" <tag class=\"starttag\">firstname</tag>Your first name<tag class=\"endtag\">firstname</tag>\n"
	+" <tag class=\"starttag\">surname</tag>Your surname<tag class=\"endtag\">surname</tag>\n"
	+" <tag class=\"endtag\">personname</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">affiliation</tag>\n"
	+"\t<tag class=\"starttag\">address</tag>\n"
	+"\t <tag class=\"starttag\">email</tag>foo@example.com<tag class=\"endtag\">email</tag>\n"
	+"\t<tag class=\"endtag\">address</tag>\n"
	+" <tag class=\"endtag\">affiliation</tag>\n"
	+" <tag class=\"endtag\">author</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">copyright</tag>\n"
	+" <tag class=\"starttag\">year</tag>2000<tag class=\"endtag\">year</tag>\n"
	+" <tag class=\"starttag\">holder</tag>Copyright string here<tag class=\"endtag\">holder</tag>\n"
	+" <tag class=\"endtag\">copyright</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag>If your book has an abstract then it should go here。<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">info</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">preface</tag>\n"
	+" <tag class=\"starttag\">title</tag>Preface<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>Your book may have a preface, in which case it should be placed\n"
	+" here。<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">preface</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">chapter</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Chapter<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first chapter in my book。<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first section in my book。<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+" <tag class=\"endtag\">chapter</tag>\n"
	+"<tag class=\"endtag\">book</tag>"
	+
	+#. (itstool) path: sect1/title
	+#. (itstool) path: example/title
	+#: book.translate.xml:9237 book.translate.xml:9240
	+msgid "DocBook <tag>article</tag>"
	+msgstr "DocBook <tag>article</tag>"
	+
	+#. (itstool) path: example/programlisting
	+#: book.translate.xml:9242
	+#, no-wrap
	+msgid ""
	+"<!DOCTYPE article PUBLIC \"-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN\"\n"
	+"\t\"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd\">\n"
	+"\n"
	+"<tag class=\"starttag\">article xmlns=\"http://docbook.org/ns/docbook\"\n"
	+" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"5.0\"\n"
	+" xml:lang=\"en\"</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">info</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example Article<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">author</tag>\n"
	+" <tag class=\"starttag\">personname</tag>\n"
	+" <tag class=\"starttag\">firstname</tag>Your first name<tag class=\"endtag\">firstname</tag>\n"
	+" <tag class=\"starttag\">surname</tag>Your surname<tag class=\"endtag\">surname</tag>\n"
	+" <tag class=\"endtag\">personname</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">affiliation</tag>\n"
	+"\t<tag class=\"starttag\">address</tag>\n"
	+"\t <tag class=\"starttag\">email</tag>foo@example.com<tag class=\"endtag\">email</tag>\n"
	+"\t<tag class=\"endtag\">address</tag>\n"
	+" <tag class=\"endtag\">affiliation</tag>\n"
	+" <tag class=\"endtag\">author</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">copyright</tag>\n"
	+" <tag class=\"starttag\">year</tag>2000<tag class=\"endtag\">year</tag>\n"
	+" <tag class=\"starttag\">holder</tag>Copyright string here<tag class=\"endtag\">holder</tag>\n"
	+" <tag class=\"endtag\">copyright</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag>If your article has an abstract then it should go here.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">info</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first section in my article.<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect2</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Sub-Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first sub-section in my article.<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect2</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">article</tag>"
	+msgstr ""
	+"<!DOCTYPE article PUBLIC \"-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN\"\n"
	+"\t\"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd\">\n"
	+"\n"
	+"<tag class=\"starttag\">article xmlns=\"http://docbook.org/ns/docbook\"\n"
	+" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"5.0\"\n"
	+" xml:lang=\"en\"</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">info</tag>\n"
	+" <tag class=\"starttag\">title</tag>An Example Article<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">author</tag>\n"
	+" <tag class=\"starttag\">personname</tag>\n"
	+" <tag class=\"starttag\">firstname</tag>Your first name<tag class=\"endtag\">firstname</tag>\n"
	+" <tag class=\"starttag\">surname</tag>Your surname<tag class=\"endtag\">surname</tag>\n"
	+" <tag class=\"endtag\">personname</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">affiliation</tag>\n"
	+"\t<tag class=\"starttag\">address</tag>\n"
	+"\t <tag class=\"starttag\">email</tag>foo@example.com<tag class=\"endtag\">email</tag>\n"
	+"\t<tag class=\"endtag\">address</tag>\n"
	+" <tag class=\"endtag\">affiliation</tag>\n"
	+" <tag class=\"endtag\">author</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">copyright</tag>\n"
	+" <tag class=\"starttag\">year</tag>2000<tag class=\"endtag\">year</tag>\n"
	+" <tag class=\"starttag\">holder</tag>Copyright string here<tag class=\"endtag\">holder</tag>\n"
	+" <tag class=\"endtag\">copyright</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">abstract</tag>\n"
	+" <tag class=\"starttag\">para</tag>If your article has an abstract then it should go here。<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">abstract</tag>\n"
	+" <tag class=\"endtag\">info</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect1</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first section in my article。<tag class=\"endtag\">para</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">sect2</tag>\n"
	+" <tag class=\"starttag\">title</tag>My First Sub-Section<tag class=\"endtag\">title</tag>\n"
	+"\n"
	+" <tag class=\"starttag\">para</tag>This is the first sub-section in my article。<tag class=\"endtag\">para</tag>\n"
	+" <tag class=\"endtag\">sect2</tag>\n"
	+" <tag class=\"endtag\">sect1</tag>\n"
	+"<tag class=\"endtag\">article</tag>"

File Metadata

Mime Type: text/plain
Expires: Wed, Apr 8, 12:20 AM (11 h, 49 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 31058669
Default Alt Text: D6869.id.diff (796 KB)

D6869.id.diffNo OneTemporaryActions

D6869.id.diffView Options

File Metadata

Event Timeline

D6869.id.diff
No OneTemporary
Actions

D6869.id.diff
View Options