Convert zh_TW from Big5 to UTF-8.

Approved by:	bcr

16 files changed, 7509 insertions, 0 deletions

diff --git a/zh_TW.UTF-8/books/fdp-primer/Makefile b/zh_TW.UTF-8/books/fdp-primer/Makefile
new file mode 100644
index 0000000000..60eaeea096
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/Makefile
@@ -0,0 +1,51 @@
+#
+# $FreeBSD$
+#
+# Build the FreeBSD Documentation Project Primer.
+#
+
+MAINTAINER=doc@FreeBSD.org
+
+DOC?= book
+
+FORMATS?= html-split html
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+#
+# SRCS lists the individual XML files that make up the document. Changes
+# to any of these files will force a rebuild
+#
+
+# 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
+IMAGES_LIB+=	callouts/2.png
+IMAGES_LIB+=	callouts/3.png
+IMAGES_LIB+=	callouts/4.png
+IMAGES_LIB+=	callouts/5.png
+
+# Entities
+SRCS+= chapters.ent
+
+URL_RELPREFIX?=	../../../..
+DOC_PREFIX?=	${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/books/fdp-primer/book.xml b/zh_TW.UTF-8/books/fdp-primer/book.xml
new file mode 100644
index 0000000000..0863eb87ba
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/book.xml
@@ -0,0 +1,234 @@
+<?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;
+]>
+<!-- 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$
+     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">
+  <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>
+
+    <pubdate role="rcs">$FreeBSD$</pubdate>
+
+    <releaseinfo>$FreeBSD$</releaseinfo>
+
+    &legalnotice;
+
+    <abstract>
+      <para>感謝您參與 FreeBSD 文件計劃(簡稱：FDP, FreeBSD Documentation Project)，您的點滴貢獻，都相當寶貴。</para>
+
+      <para>本入手書內容包括：如何開始著手翻譯的各項細節，以及會用到的一些好用工具(包括：必備工具、輔助工具)
+        ，以及文件計畫的宗旨。</para>
+
+      <para>本文件還在草稿，尚未完稿。未完成的章節，我們會在章節名稱旁邊加註『<literal>*</literal> 』以作識別。</para>
+    </abstract>
+  </info>
+
+  <preface xml:id="preface">
+    <title>序言</title>
+
+    <sect1 xml:id="preface-prompts">
+      <title>Shell 提示符號(Prompts)</title>
+
+      <para>下表顯示出一般帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt)
+	，來提醒您該用哪種帳號才對。</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>帳號</entry>
+	      <entry>提示符號(Prompt)</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>普通帳號</entry>
+	      <entry>&prompt.user;</entry>
+	    </row>
+
+	    <row>
+	      <entry><systemitem class="username">root</systemitem></entry>
+	      <entry>&prompt.root;</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+    </sect1>
+
+    <sect1 xml:id="preface-conventions">
+      <title>書中所用的編排風格</title>
+
+      <para>下表為本書中所使用編排風格方式：</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>代表意義</entry>
+	      <entry>舉例</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>指令</entry>
+	      <entry>使用 <command>ls -a</command> 來列出所有的檔案。</entry>
+	    </row>
+
+	    <row>
+	      <entry>檔名</entry>
+	      <entry>修改 <filename>.login</filename> 檔。</entry>
+	    </row>
+
+	    <row>
+	      <entry>螢幕上會出現的訊息</entry>
+	      <entry><screen>You have mail.</screen></entry>
+	    </row>
+
+	    <row>
+	      <entry>輸入指令後，螢幕上會出現的對應內容。</entry>
+
+	      <entry><screen>&prompt.user; <userinput>su</userinput>
+Password:</screen></entry>
+	    </row>
+
+	    <row>
+	      <entry>要參考的線上手冊(manual)</entry>
+
+	      <entry>以 <citerefentry>
+		  <refentrytitle>su</refentrytitle>
+		  <manvolnum>1</manvolnum>
+		</citerefentry> 來切換帳號。</entry>
+	    </row>
+
+	    <row>
+	      <entry>在講到帳號(user)、群組(group)的名稱的時候...</entry>
+
+	      <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry>
+	    </row>
+
+	    <row>
+	      <entry>語氣的強調</entry>
+
+	      <entry>你『必須』這麼做才行。</entry>
+	    </row>
+
+	    <row>
+	      <entry>打指令時，可替換的部份</entry>
+
+	      <entry>要刪除檔案的話，請打 <command>rm 要刪除的檔名</command></entry>
+	    </row>
+
+	    <row>
+	      <entry>環境變數設定</entry>
+
+	      <entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+    </sect1>
+
+    <sect1 xml:id="preface-notes">
+      <title>『Note、Tip、Important、Warning、Example』的運用</title>
+
+      <para>以下文字是『注意』、『技巧』、『重要訊息』、『警告』、『範例』的運用。</para>
+
+      <note>
+	<para>表示需要注意的事項，其中包括您需要注意的事情，因為這些事情可能會影響到操作結果。</para>
+      </note>
+
+      <tip>
+	<para>提供可能對您有用或簡化操作方式的技巧說明。</para>
+      </tip>
+
+      <important>
+	<para>表示要特別注意的事情。一般來說，它們會包括操作指令時需要加的額外參數。</para>
+      </important>
+
+      <warning>
+	<para>表示警告事項，比如如果您不注意則可能導致的損失。這些損失可能是對您或硬體造成實際傷害，
+	  也可能是無法估計的損害，例如一時疏忽而刪除重要檔案...。</para>
+      </warning>
+
+      <example>
+	<title>這是舉例說明</title>
+
+	<para>這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。</para>
+      </example>
+    </sect1>
+
+    <sect1 xml:id="preface-acknowledgements">
+      <title>感謝</title>
+
+      <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;
+
+  &app.examples;
+
+  <index/>
+</book>
diff --git a/zh_TW.UTF-8/books/fdp-primer/chapters.ent b/zh_TW.UTF-8/books/fdp-primer/chapters.ent
new file mode 100644
index 0000000000..a3d22b4c72
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/chapters.ent
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+     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$
+     Original revision: 1.6
+-->
+
+<!ENTITY chap.overview		SYSTEM "overview/chapter.xml">
+<!ENTITY chap.xml-primer	SYSTEM "sgml-primer/chapter.xml">
+<!ENTITY chap.tools		SYSTEM "tools/chapter.xml">
+<!ENTITY chap.xml-markup       SYSTEM "sgml-markup/chapter.xml">
+<!ENTITY chap.stylesheets	SYSTEM "stylesheets/chapter.xml">
+<!ENTITY chap.structure         SYSTEM "structure/chapter.xml">
+<!ENTITY chap.the-website	SYSTEM "the-website/chapter.xml">
+<!ENTITY chap.translations	SYSTEM "translations/chapter.xml">
+<!ENTITY chap.writing-style	SYSTEM "writing-style/chapter.xml">
+<!ENTITY chap.psgml-mode	SYSTEM "psgml-mode/chapter.xml">
+<!ENTITY chap.see-also		SYSTEM "see-also/chapter.xml">
+<!ENTITY chap.doc-build		SYSTEM "doc-build/chapter.xml">
+
+<!ENTITY app.examples		SYSTEM "examples/appendix.xml">
diff --git a/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml
new file mode 100644
index 0000000000..9932157881
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml
@@ -0,0 +1,486 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.16
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="doc-build">
+  <title>The Documentation Build Process</title>
+
+  <para>This chapter's main purpose is to clearly explain <emphasis>how
+    the documentation build process is organized</emphasis>, and
+    <emphasis>how to affect modifications to this process</emphasis>.
+    </para>
+
+  <para>After you have finished reading this chapter you should:</para>
+
+  <itemizedlist>
+    <listitem>
+      <para>Know what you need to build the FDP documentation, in
+	addition to those mentioned in the <link linkend="tools">SGML tools chapter</link>.</para>
+    </listitem>
+
+    <listitem>
+      <para>Be able to read and understand the
+	<application>make</application> instructions that are present in
+	each document's <filename>Makefile</filename>s, as well as an
+	overview of the <filename>doc.project.mk</filename> includes.</para>
+    </listitem>
+
+    <listitem>
+      <para>Be able to customize the build process by using
+	<application>make</application> variables and
+	<application>make</application> targets.</para>
+    </listitem>
+  </itemizedlist>
+
+  <sect1 xml:id="doc-build-toolset">
+    <title>The FreeBSD Documentation Build Toolset</title>
+
+    <para>Here are your tools.  Use them every way you can.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The primary build tool you will need is
+	  <application>make</application>, but specifically
+	  <application>Berkeley Make</application>.</para>
+      </listitem>
+
+      <listitem>
+	<para>Package building is handled by FreeBSD's
+	  <application>pkg_create</application>.  If you are not using
+	  FreeBSD, you will either have to live without packages, or
+	  compile the source yourself.</para>
+      </listitem>
+
+      <listitem>
+	<para><application>gzip</application> is needed to create
+	  compressed versions of the document.
+	  <application>bzip2</application> compression and
+	  <application>zip</application> archives are also supported.
+	  <application>tar</application> is supported, but package
+	  building demands it.</para>
+      </listitem>
+
+      <listitem>
+	<para><application>install</application> is the default method
+	  to install the documentation.  There are alternatives,
+	  however.</para>
+      </listitem>
+    </itemizedlist>
+
+    <note>
+      <para>It is unlikely you will have any trouble finding these last two, they
+	are mentioned for completeness only.</para>
+    </note>
+  </sect1>
+
+  <sect1 xml:id="doc-build-makefiles">
+    <title>Understanding Makefiles in the Documentation tree</title>
+
+    <para>There are three main types of <filename>Makefile</filename>s
+      in the FreeBSD Documentation Project tree.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><link linkend="sub-make">Subdirectory
+	  <filename>Makefile</filename>s</link> simply pass
+	  commands to those directories below them.</para>
+      </listitem>
+
+      <listitem>
+	<para><link linkend="doc-make">Documentation
+	  <filename>Makefile</filename>s</link> describe the
+	  document(s) that should be produced from this directory.</para>
+      </listitem>
+
+      <listitem>
+	<para><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.xxx.mk</filename>.</para>
+      </listitem>
+    </itemizedlist>
+
+    <sect2 xml:id="sub-make">
+      <title>Subdirectory Makefiles</title>
+
+      <para>These <filename>Makefile</filename>s usually take the form of:</para>
+
+      <programlisting>SUBDIR =articles
+SUBDIR+=books
+
+COMPAT_SYMLINK = en
+
+DOC_PREFIX?= ${.CURDIR}/..
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
+
+      <para>In quick summary, the first four non-empty lines define the
+	<application>make</application> variables,
+	<varname>SUBDIR</varname>, <varname>COMPAT_SYMLINK</varname>,
+	and <varname>DOC_PREFIX</varname>.</para>
+
+      <para>The first <varname>SUBDIR</varname> statement, as well as
+	the <varname>COMPAT_SYMLINK</varname> statement, shows how to
+	assign a value to a variable, overriding any previous
+	value.</para>
+
+      <para>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>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>Now 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><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><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 <application>make</application>
+	builtin variable with the path to the current directory.</para>
+
+      <para>The final line includes the FreeBSD Documentation Project's
+	project-wide <application>make</application> 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>Documentation Makefiles</title>
+
+      <para>These <filename>Makefile</filename>s set a bunch of
+	<application>make</application> variables that describe how to
+	build the documentation contained in that directory.</para>
+
+      <para>Here is an example:</para>
+
+      <programlisting>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>The <varname>MAINTAINER</varname> variable is a very
+	important one.  This variable provides the ability to claim
+	ownership over a document in the FreeBSD Documentation
+	Project, whereby you gain the responsibility for maintaining
+	it.</para>
+
+      <para><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><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>
+
+      <note>
+	<para>We covered optional variable assignments in the
+	  <link linkend="sub-make">previous section</link>.</para>
+      </note>
+
+      <para>The <varname>DOC_PREFIX</varname> and include statements
+	should be familiar already.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="make-includes">
+    <title>FreeBSD Documentation Project make includes</title>
+
+    <para>This is best explained by inspection of the code.  Here are
+      the system include files:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><filename>doc.project.mk</filename> is the main project
+	  include file, which includes all the following include files, as
+	  necessary.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>doc.subdir.mk</filename> handles traversing of
+	  the document tree during the build and install processes.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>doc.install.mk</filename> provides variables
+	  that affect ownership and installation of documents.</para>
+      </listitem>
+
+      <listitem>
+	<para><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>doc.project.mk</title>
+
+      <para>By inspection:</para>
+
+      <programlisting>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>Variables</title>
+
+	<para><varname>DOCFORMAT</varname> and <varname>MAINTAINER</varname>
+	  are assigned default values, if these are not set by the
+	  document make file.</para>
+
+	<para><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><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><varname>PRI_LANG</varname> in no way affects what 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>Conditionals</title>
+
+	<para>The <literal>.if defined(DOC)</literal> line is an example of
+	  a <application>make</application> 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><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>The two <literal>.endif</literal>s close the two above
+	  conditionals, marking the end of their application.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>doc.subdir.mk</title>
+
+      <para>This is too long to explain by inspection, you should be
+	able to work it out with the knowledge gained from the previous
+	chapters, and a little help given here.</para>
+
+      <sect3>
+	<title>Variables</title>
+
+	<itemizedlist>
+	  <listitem>
+	    <para><varname>SUBDIR</varname> is a list of subdirectories
+	      that the build process should go further down
+	      into.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para><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><varname>COMPAT_SYMLINK</varname> is described in the
+	      <link linkend="sub-make">Subdirectory Makefile</link>
+	      section.</para>
+	  </listitem>
+	</itemizedlist>
+      </sect3>
+
+      <sect3>
+	<title>Targets and macros</title>
+
+	<para>Dependencies are described by
+	  <literal>target:
+	  dependency1 dependency2 ...</literal>
+	  tuples, where to build <literal>target</literal>, you need to build
+	  the given dependencies first.</para>
+
+	<para>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>A special dependency <literal>.USE</literal> defines
+	  the equivalent of a macro.</para>
+
+<programlisting>_SUBDIRUSE: .USE
+.for entry in ${SUBDIR}
+	@${ECHO} "===&gt; ${DIRPRFX}${entry}"
+	@(cd ${.CURDIR}/${entry} &amp;&amp; \
+	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
+.endfor</programlisting>
+
+	<para>In the above, <buildtarget>_SUBDIRUSE</buildtarget> is now a
+	  macro which will execute the given commands when it is listed
+	  as a dependency.</para>
+
+	<para>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>clean: _SUBDIRUSE
+	rm -f ${CLEANFILES}</programlisting>
+
+	<para>In the above, <buildtarget>clean</buildtarget> will use the
+	  <buildtarget>_SUBDIRUSE</buildtarget> macro after it has
+	  executed the instruction
+	  <command>rm -f ${CLEANFILES}</command>.  In effect, this causes
+	  <buildtarget>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>Provided targets</title>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para><buildtarget>install</buildtarget> and
+		<buildtarget>package</buildtarget> both go down the
+		directory tree calling the real versions of themselves
+		in the subdirectories
+		(<buildtarget>realinstall</buildtarget> and
+		<buildtarget>realpackage</buildtarget>
+		 respectively).</para>
+	    </listitem>
+
+	    <listitem>
+	      <para><buildtarget>clean</buildtarget> removes files created
+		by the build process (and goes down the directory tree
+		too).  <buildtarget>cleandir</buildtarget> does the same,
+		and also removes the object directory, if any.</para>
+	    </listitem>
+	  </itemizedlist>
+	</sect4>
+      </sect3>
+
+      <sect3>
+	<title>More on conditionals</title>
+
+	<itemizedlist>
+	  <listitem>
+	    <para><literal>exists</literal> is another condition
+	      function which returns true if the given file exists.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para><literal>empty</literal> returns true if the given
+	      variable is empty.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para><literal>target</literal> returns true if the given
+	      target does not already exist.</para>
+	  </listitem>
+	</itemizedlist>
+      </sect3>
+
+      <sect3>
+	<title>Looping constructs in make (.for)</title>
+
+	<para><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>_SUBDIRUSE: .USE
+.for entry in ${SUBDIR}
+	@${ECHO} "===&gt; ${DIRPRFX}${entry}"
+	@(cd ${.CURDIR}/${entry} &amp;&amp; \
+	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
+.endfor</programlisting>
+
+	<para>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>
diff --git a/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml b/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml
new file mode 100644
index 0000000000..5fc6839c92
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml
@@ -0,0 +1,336 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.17
+-->
+<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="examples">
+  <title>範例</title>
+
+  <para>本附錄收錄一些 SGML 檔範例，以及用來轉換格式的相關指令。
+    若已成功安裝文件計畫工具包的話，那麼就可以直接照下面範例來使用。</para>
+
+  <para>這些例子並不是很詳細 &mdash; 並未包括你可能想用的元件，
+    尤其像是你文件的前頁(正文前的書頁，包括扉頁、序言、目錄等)
+    若需參考更多 DocBook 標記語言文件的話，那麼可以透過 <application>CSup</application>、<application>CVSup</application>
+    程式來抓 <literal>doc</literal> tree 部分，以察看本文件或其他文件的 SGML 原稿。
+    或者，也可以線上瀏覽
+    <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/">http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/</uri>。</para>
+
+  <para>為了避免不必要的困擾，這些例子採用標準的 DocBook 4.1 DTD 而非 FreeBSD 額外的 DTD。
+    同時並採用 Norm Walsh 氏的樣式表(stylesheets)，而非 FreeBSD 文件計劃有自行改過的樣式表。
+    在一般使用 DocBook 的例子，這樣子會比較簡化環境，而不會造成額外困擾。</para>
+
+  <sect1 xml:id="examples-docbook-book">
+    <title>DocBook <tag>book</tag></title>
+
+    <example>
+      <title>DocBook <tag>book</tag></title>
+
+      <programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<book lang='zh_tw'>
+  <bookinfo>
+    <title>樣本書的例子</title>
+
+    <author>
+      <firstname>名(first name)</firstname>
+      <surname>姓(surname)</surname>
+      <affiliation>
+        <address><email>foo@example.com</email></address>
+      </affiliation>
+    </author>
+
+    <copyright>
+      <year>2000</year>
+      <holder>相關版權字樣</holder>
+    </copyright>
+
+    <abstract>
+      <para>該書若有摘要，就寫在這邊。</para>
+    </abstract>
+  </bookinfo>
+
+  <preface>
+    <title>序言</title>
+
+    <para>該書若有序言，就放在這邊。</para>
+  </preface>
+
+  <chapter>
+    <title>第一章</title>
+
+    <para>這是這本書的第一章。</para>
+
+    <sect1>
+      <title>第一節</title>
+
+      <para>這本書的第一節。</para>
+    </sect1>
+  </chapter>
+</book>]]></programlisting>
+    </example>
+  </sect1>
+
+  <sect1 xml:id="examples-docbook-article">
+    <title>DocBook <tag>article</tag></title>
+
+    <example>
+      <title>DocBook <tag>article</tag></title>
+
+      <programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<article lang='zh_tw'>
+  <articleinfo>
+    <title>文章樣本</title>
+
+    <author>
+      <firstname>名(first name)</firstname>
+      <surname>姓(surname)</surname>
+      <affiliation>
+        <address><email>foo@example.com</email></address>
+      </affiliation>
+    </author>
+
+    <copyright>
+      <year>2000</year>
+      <holder>相關版權字樣</holder>
+    </copyright>
+
+    <abstract>
+      <para>該文章若有摘要，就寫在這邊。</para>
+    </abstract>
+  </articleinfo>
+
+  <sect1>
+    <title>第一節</title>
+
+    <para>該文章的第一節。</para>
+
+    <sect2>
+      <title>第一小節(sub-section)</title>
+
+      <para>該文章的第一小節(sub-section)</para>
+    </sect2>
+  </sect1>
+</article>]]></programlisting>
+    </example>
+  </sect1>
+
+  <sect1 xml:id="examples-formatted">
+    <title>Producing formatted output</title>
+
+    <para>本節有些前提，假設：已經有裝 <package>textproc/docproj</package>
+      上面所安裝各軟體，無論它們是用 port 方式安裝或是手動安裝。
+      此外，假設所裝的軟體都放在 <filename>/usr/local/</filename> 下的子目錄，
+      並且所安裝的相關執行檔，都有裝在你的 <envar>PATH</envar> 環境變數內的目錄。
+      如有必要的話，請依你的系統環境而調整相關路徑。</para>
+
+    <sect2>
+      <title>使用 Jade</title>
+
+      <example>
+	<title>轉換 DocBook 為 HTML (完整模式)</title>
+
+	<screen>&prompt.user; <userinput>jade -V nochunks \  <co xml:id="examples-co-jade-1-nochunks"/>
+    -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-1-catalog"/>
+    -c /usr/local/share/xml/docbook/catalog \
+    -c /usr/local/share/xml/jade/catalog \
+    -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-1-dsssl"/>
+    -t sgml <co xml:id="examples-co-jade-1-transform"/> file.xml &gt; file.html <co xml:id="examples-co-jade-1-filename"/></userinput></screen>
+
+	<calloutlist>
+	  <callout arearefs="examples-co-jade-1-nochunks">
+	    <para>Specifies the <literal>nochunks</literal> parameter to the
+	      stylesheets, forcing all output to be written to
+	      <abbrev>STDOUT</abbrev> (using Norm Walsh's stylesheets).</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-1-catalog">
+	    <para>Specifies the catalogs that Jade will need to process.
+	      Three catalogs are required.  The first is a catalog that
+	      contains information about the DSSSL stylesheets.  The second
+	      contains information about the DocBook DTD.  The third contains
+	      information specific to Jade.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-1-dsssl">
+	    <para>Specifies the full path to the DSSSL stylesheet that Jade
+	      will use when processing the document.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-1-transform">
+	    <para>Instructs Jade to perform a
+	      <emphasis>transformation</emphasis> from one DTD to another.  In
+	      this case, the input is being transformed from the DocBook DTD
+	      to the HTML DTD.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-1-filename">
+	    <para>Specifies the file that Jade should process, and redirects
+	      output to the specified <filename>.html</filename> file.</para>
+	  </callout>
+	</calloutlist>
+      </example>
+
+      <example>
+	<title>轉換 DocBook 為 HTML (章節模式)</title>
+
+	<screen>&prompt.user; <userinput>jade \
+    -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-2-catalog"/>
+    -c /usr/local/share/xml/docbook/catalog \
+    -c /usr/local/share/xml/jade/catalog \
+    -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-2-dsssl"/>
+    -t sgml <co xml:id="examples-co-jade-2-transform"/> file.xml <co xml:id="examples-co-jade-2-filename"/></userinput></screen>
+
+	<calloutlist>
+	  <callout arearefs="examples-co-jade-2-catalog">
+	    <para>Specifies the catalogs that Jade will need to process.
+	      Three catalogs are required.  The first is a catalog that
+	      contains information about the DSSSL stylesheets.  The second
+	      contains information about the DocBook DTD.  The third contains
+	      information specific to Jade.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-2-dsssl">
+	    <para>Specifies the full path to the DSSSL stylesheet that Jade
+	      will use when processing the document.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-2-transform">
+	    <para>Instructs Jade to perform a
+	      <emphasis>transformation</emphasis> from one DTD to another.  In
+	      this case, the input is being transformed from the DocBook DTD
+	      to the HTML DTD.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-2-filename">
+	    <para>Specifies the file that Jade should process.  The
+	      stylesheets determine how the individual HTML files will be
+	      named, and the name of the <quote>root</quote> file (i.e., the
+	      one that contains the start of the document.</para>
+	  </callout>
+	</calloutlist>
+
+	<para>This example may still only generate one HTML file, depending on
+	  the structure of the document you are processing, and the
+	  stylesheet's rules for splitting output.</para>
+      </example>
+
+      <example xml:id="examples-docbook-postscript">
+	<title>轉換 DocBook 為 Postscript(PS) 格式</title>
+
+	<para>The source SGML file must be converted to a &tex; file.</para>
+
+	<screen>&prompt.user; <userinput>jade -Vtex-backend \ <co xml:id="examples-co-jade-3-tex-backend"/>
+    -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-3-catalog"/>
+    -c /usr/local/share/xml/docbook/catalog \
+    -c /usr/local/share/xml/jade/catalog \
+    -d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \<co xml:id="examples-co-jade-3-dsssl"/>
+    -t tex <co xml:id="examples-co-jade-3-tex"/> file.xml</userinput></screen>
+
+	<calloutlist>
+	  <callout arearefs="examples-co-jade-3-tex-backend">
+	    <para>Customizes the stylesheets to use various options
+	      specific to producing output for &tex;.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-3-catalog">
+	    <para>Specifies the catalogs that Jade will need to process. Three
+	      catalogs are required.  The first is a catalog that contains
+	      information about the DSSSL stylesheets.  The second contains
+	      information about the DocBook DTD.  The third contains
+	      information specific to Jade.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-3-dsssl">
+	    <para>Specifies the full path to the DSSSL stylesheet that
+	      Jade will use when processing the document.</para>
+	  </callout>
+
+	  <callout arearefs="examples-co-jade-3-tex">
+	    <para>Instructs Jade to convert the output to &tex;.</para>
+	  </callout>
+	</calloutlist>
+
+	<para>The generated <filename>.tex</filename> file must now be run
+	  through <command>tex</command>, specifying the
+	  <literal>&amp;jadetex</literal> macro package.</para>
+
+	<screen>&prompt.user; <userinput>tex "&amp;jadetex" file.tex</userinput></screen>
+
+	<para>You have to run <command>tex</command> <emphasis>at
+	  least</emphasis> three times.  The first run processes the
+	  document, and determines areas of the document which are referenced
+	  from other parts of the document, for use in indexing, and so
+	  on.</para>
+
+	<para>Do not be alarmed if you see warning messages such as
+	  <literal>LaTeX Warning: Reference `136' on page 5 undefined on input
+	  line 728.</literal> at this point.</para>
+
+	<para>The second run reprocesses the document now that certain pieces
+	  of information are known (such as the document's page length).  This
+	  allows index entries and other cross-references to be fixed
+	  up.</para>
+
+	<para>The third pass performs any final cleanup necessary.</para>
+
+	<para>The output from this stage will be
+	  <filename>file.dvi</filename>.</para>
+
+	<para>Finally, run <command>dvips</command> to convert the
+	  <filename>.dvi</filename> file to Postscript.</para>
+
+	<screen>&prompt.user; <userinput>dvips -o file.ps file.dvi</userinput></screen>
+      </example>
+
+      <example>
+	<title>轉換 DocBook 為 PDF 格式</title>
+
+	<para>The first part of this process is identical to that when
+	  converting DocBook to Postscript, using the same
+	  <command>jade</command> command line (<xref linkend="examples-docbook-postscript"/>).</para>
+
+	<para>When the <filename>.tex</filename> file has been generated you
+	  run pdfTeX.  However, use the &amp;pdfjadetex macro package
+	  instead.</para>
+
+	<screen>&prompt.user; <userinput>pdftex "&amp;pdfjadetex" file.tex</userinput></screen>
+
+	<para>Again, run this command three times.</para>
+
+	<para>This will generate
+	  <filename>file.pdf</filename>, which does
+	  not need to be processed any further.</para>
+      </example>
+    </sect2>
+  </sect1>
+</appendix>
diff --git a/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml
new file mode 100644
index 0000000000..d3f24e60ef
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml
@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.23
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">
+  <title>概論</title>
+
+  <para>歡迎參與 FreeBSD 文件計劃。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，
+	而 FreeBSD 文件計劃(以下皆以 FDP 來代表 FreeBSD Documentation Project
+	的縮寫) 則與這些文件撰寫、更新息息相關，因此您的點滴貢獻都是十分寶貴的。</para>
+
+  <para>本文件最主要的目的，就是清楚告訴您：『FDP 的架構有哪些』、『如何撰寫並提交文件給 FDP』、
+	『如何有效運用工具來協助撰稿』。</para>
+
+  <para><indexterm>
+      <primary>Membership</primary>
+    </indexterm>
+    我們歡迎每個熱心的志士來加入 FDP 行列。FDP 並不限定每月必須交出多少稿量，才能加入。
+    您唯一須要作的就是訂閱 &a.doc; 。</para>
+
+  <para>讀完本份文件，您將會：</para>
+
+  <itemizedlist>
+    <listitem>
+      <para>瞭解有哪些文件是由 FDP 所維護的。</para>
+    </listitem>
+
+    <listitem>
+      <para>可以看懂 FDP 所維護的 SGML 原始文件。</para>
+    </listitem>
+
+    <listitem>
+      <para>知道如何來對文件作修改。</para>
+    </listitem>
+
+    <listitem>
+      <para>知道如何投稿自己的修改部份，並最後正式進入 FreeBSD 文件內。</para>
+    </listitem>
+  </itemizedlist>
+
+  <sect1 xml:id="overview-doc">
+    <title>FreeBSD 文件的組成部分</title>
+
+    <para>FDP 總共負責 FreeBSD 的 4 種類別的文件：</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>線上手冊(manual)</term>
+
+        <listitem>
+          <para>英文版的系統 manual 並不是由 FDP 所撰寫的，因為它們是屬於 base system 的部份。
+		然而，FDP 可以(也曾這麼做過)修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。</para>
+
+          <para>翻譯團隊負責將系統的線上手冊翻譯為不同的語言。 這些譯本都由 FDP 維護。</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>FAQ</term>
+
+        <listitem>
+          <para>FAQ 主要是收集在各論壇或 newsgroup 會常問到或有可能會問到的 FreeBSD 相關問題與答案 。
+		(簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>使用手冊(Handbook)</term>
+
+        <listitem>
+          <para>使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+         <term>Web site</term>
+
+         <listitem>
+           <para>FreeBSD 主要各項介紹方面的 WWW 部份，歡迎逛逛 <link xlink:href="&url.base;/index.html">http://www.FreeBSD.org/</link>
+	    以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方。</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>這四個文件組成部分都可透過 FreeBSD CVS tree 來取得。也就是說，這些文件的修改記錄對於任何人都是公開的，
+      而且無論是誰都可以用像是 <application>CSup</application>, <application>CVSup</application> 或
+      <application>CTM</application> 將文件取出來(checkout)並放在自己機器上做備份或副本參考等用途。</para>
+
+    <para>此外，許多人會寫些教學文件或維護有關 FreeBSD 內容的網站。(若作者同意的話)其中有些資料會保存在 FreeBSD 正式
+      CVS repository 內。而其他的文件，可能作者不希望被放在 FreeBSD repository 內而另存他處。
+      總之，FDP 會盡力提供這些文件的連結。</para>
+  </sect1>
+
+  <sect1 xml:id="overview-before">
+    <title>在開工之前...</title>
+
+    <para>本文假設您已經瞭解：</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>如何從 FreeBSD CVS repository 更新自己電腦上的 FreeBSD 文件部份(以 <application>CVS</application>
+	  或 <application>CSup</application> 或 <application>CVSup</application> 或是
+	  <application>CTM</application>) 或是用
+	  <application>CVSup</application> 來下載 <emphasis>checked-out</emphasis> 的副本</para>
+      </listitem>
+
+      <listitem>
+	<para>如何用 FreeBSD Ports 套件管理機制或 &man.pkg.add.1; 來下載、安裝軟體。</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 xml:id="overview-quick-start">
+    <title>快速上手篇</title>
+
+    <para>若想先自行試試看，並有信心可以作得到，那麼就照下面步驟吧。</para>
+
+    <procedure>
+      <step>
+	<para>安裝 <package>textproc/docproj</package> 這個組合型 port(meta-port)。</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
+&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
+      </step>
+
+      <step>
+	<para>下載 FreeBSD <filename>doc</filename> tree 到本機上：
+	  無論是用 CSup 或 CVSup 的 <literal>checkout</literal> 模式，
+	  或是複製完整的 CVS repository 到本機上都可以。</para>
+
+	<para>若想在本機上只跑最低限度的 CVS repository 就好，那麼必須要
+	  checkout 出 <filename>doc/share</filename> 以及 <filename>doc/en_US.ISO8859-1/share</filename>
+	  這兩個目錄才行。</para>
+
+	<screen>&prompt.user; <userinput>cvs checkout doc/share</userinput>
+&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/share</userinput></screen>
+
+	<para>若硬碟空間還算可以的話，那可以把所有語系的 doc 都 check out 出來：</para>
+
+	<screen>&prompt.user; <userinput>cvs checkout doc</userinput></screen>
+      </step>
+
+      <step>
+	<para>可依需要從 repository 中 checkout 出來你想修改某份現有的書籍或文章內容。
+	  若打算撰寫新書或新文章的話，可以參考現有的部分作為實例來做。</para>
+
+	<para>舉例來說，若想寫篇新文章，內容是有關在 FreeBSD 與 Windows 2000 之間建立 VPN 連線，
+	那麼可以照類似下面這樣的作法：</para>
+
+	<procedure>
+	  <step>
+	    <para>Check out <filename>articles</filename> 目錄：</para>
+
+	    <screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/articles</userinput></screen>
+	  </step>
+
+	  <step>
+	    <para>複製現有的文章作為範本。在這個例子中，您打算決定把新文章放在
+		<filename>vpn-w2k</filename> 的目錄下。</para>
+
+	    <screen>&prompt.user; <userinput>cd doc/en_US.ISO8859-1/articles</userinput>
+&prompt.user; <userinput>cp -R committers-guide vpn-w2k</userinput></screen>
+	  </step>
+	</procedure>
+
+	<para>若是要修改現有文章，像是 FAQ(擺在 <filename>doc/en_US.ISO8859-1/books/faq</filename>)
+	，那麼要從 repository 中取出來(check out)：</para>
+
+	<screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/books/faq</userinput></screen>
+      </step>
+
+      <step>
+	<para>以編輯器來編寫 <filename>.xml</filename> 檔。</para>
+      </step>
+
+      <step>
+	<para>以 <buildtarget>lint</buildtarget> 當輔助參數，來快速檢測文件結構及連結有無錯誤，
+	以下這個指令，實際上不會進行耗時的編書過程，只是先測試文件有無錯誤。</para>
+
+	<screen>&prompt.user; <userinput>make lint</userinput></screen>
+
+	<para>當編書的一切都就緒時，這時你可以用 <varname>FORMATS</varname>
+	  變數來指定產生的格式為哪一種。  目前支援的格式共有：
+  	  <literal>html</literal>, <literal>html-split</literal>,
+  	  <literal>txt</literal>, <literal>ps</literal>,
+  	  <literal>pdf</literal>, <literal>rtf</literal> 。
+	 所支援的格式列表最新版，可參考
+  	  <filename>doc/share/mk/doc.docbook.mk</filename> 檔。 請記得：
+  	  在單一指令中，若要同時產生多種格式的話，應使用引號(quotes)來將這些格式括起來。</para>
+
+        <para>舉例來說，若只要產生
+          <literal>html</literal> 格式就好，那麼就打：</para>
+
+	<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
+
+        <para>但若希望有 <literal>html</literal> 及 <literal>txt</literal> 格式的話，
+          你可能要打兩次 &man.make.1; 指令才能完成：</para>
+
+	<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
+&prompt.user; <userinput>make FORMATS=txt</userinput></screen>
+
+        <para>其實，也可以用單一指令來完成：</para>
+
+	<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
+      </step>
+
+      <step>
+	<para>最後，以 &man.send-pr.1; 來提交修改的部份。</para>
+      </step>
+    </procedure>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml
new file mode 100644
index 0000000000..6edba25352
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.10
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="psgml-mode">
+  <title>Using <literal>sgml-mode</literal> with
+    <application>Emacs</application></title>
+
+  <para>Recent versions of <application>Emacs</application> or <application>XEmacs</application> (available from the ports
+    collection) contain a very useful package called PSGML. Automatically
+    invoked when a file with the <filename>.xml</filename> extension is loaded,
+    or by typing <command>M-x sgml-mode</command>, it is a major mode for
+    dealing with SGML files, elements and attributes.</para>
+
+  <para>An understanding of some of the commands provided by this mode can
+    make working with SGML documents such as the Handbook much easier.</para>
+
+  <variablelist>
+    <varlistentry>
+      <term><command>C-c C-e</command></term>
+
+      <listitem>
+	<para>Runs <literal>sgml-insert-element</literal>. You will be
+	  prompted for the name of the element to insert at the current point.
+	  You can use the TAB key to complete the element. Elements that are
+	  not valid at the current point will be disallowed.</para>
+
+	<para>The start and end tags for the element will be inserted. If the
+	  element contains other, mandatory, elements then these will be
+	  inserted as well.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>C-c =</command></term>
+
+      <listitem>
+	<para>Runs <literal>sgml-change-element-name</literal>. Place the
+	  point within an element and run this command. You will be prompted
+	  for the name of the element to change to. Both the start and end
+	  tags of the current element will be changed to the new
+	  element.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>C-c C-r</command></term>
+
+      <listitem>
+	<para>Runs <literal>sgml-tag-region</literal>. Select some text (move
+	  to start of text, C-space, move to end of text, C-space) and then
+	  run this command. You will be prompted for the element to use. This
+	  element will then be inserted immediately before and after your
+	  marked region.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>C-c -</command></term>
+
+      <listitem>
+	<para>Runs <literal>sgml-untag-element</literal>. Place the point
+	  within the start or end tag of an element you want to remove, and
+	  run this command. The element's start and end tags will be
+	  removed.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>C-c C-q</command></term>
+
+      <listitem>
+	<para>Runs <literal>sgml-fill-element</literal>. Will recursively fill
+	  (i.e., reformat) content from the current element in. The filling
+	  <emphasis>will</emphasis> affect content in which whitespace is
+	  significant, such as within <tag>programlisting</tag>
+	  elements, so run this command with care.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>C-c C-a</command></term>
+
+      <listitem>
+	<para>Runs <literal>sgml-edit-attributes</literal>. Opens a second
+	  buffer containing a list of all the attributes for the closest
+	  enclosing element, and their current values. Use TAB to navigate
+	  between attributes, <command>C-k</command> to remove an existing
+	  value and replace it with a new one, <command>C-c C-c</command>
+	  to close this buffer and return to the main document.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>C-c C-v</command></term>
+
+      <listitem>
+	<para>Runs <literal>sgml-validate</literal>. Prompts you to save the
+	  current document (if necessary) and then runs an SGML validator. The
+	  output from the validator is captured into a new buffer, and you can
+	  then navigate from one troublespot to the next, fixing markup errors
+	  as you go.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>C-c /</command></term>
+
+      <listitem>
+        <para>Runs <literal>sgml-insert-end-tag</literal>. Inserts the
+	  end tag for the current open element.</para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+  <para>Doubtless there are other useful functions of this mode, but those are
+    the ones I use most often.</para>
+
+  <para>You can also use the following entries in
+    <filename>.emacs</filename> to set proper spacing, indentation,
+    and column width for working with the Documentation Project.</para>
+
+  <programlisting>
+    (defun local-sgml-mode-hook
+      (setq fill-column 70
+            indent-tabs-mode nil
+            next-line-add-newlines nil
+            standard-indent 4
+            sgml-indent-data t)
+      (auto-fill-mode t)
+      (setq sgml-catalog-files '("/usr/local/share/xml/catalog")))
+    (add-hook 'psgml-mode-hook
+      '(lambda () (local-psgml-mode-hook)))
+  </programlisting>
+
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml
new file mode 100644
index 0000000000..89f409164e
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.13
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="see-also">
+  <title>他山之石</title>
+
+  <para>This document is deliberately not an exhaustive discussion of SGML,
+    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>The FreeBSD Documentation Project</title>
+
+    <itemizedlist>
+      <listitem>
+	<para><link xlink:href="&url.base;/docproj/index.html">The FreeBSD
+	    Documentation Project web pages</link></para>
+      </listitem>
+
+      <listitem>
+	<para><link xlink:href="&url.books.handbook;/index.html">The FreeBSD Handbook</link></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 xml:id="see-also-sgml">
+    <title>SGML</title>
+
+    <itemizedlist>
+      <listitem>
+	<para><link xlink:href="http://www.oasis-open.org/cover/">The SGML/XML web
+	    page</link>, a comprehensive SGML resource</para>
+      </listitem>
+
+      <listitem>
+	<para><link xlink:href="http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;id=SG">Gentle introduction to SGML</link></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 xml:id="see-also-html">
+    <title>HTML</title>
+
+    <itemizedlist>
+      <listitem>
+	<para><link xlink:href="http://www.w3.org/">The World Wide Web
+	    Consortium</link></para>
+      </listitem>
+
+      <listitem>
+	<para><link xlink:href="http://www.w3.org/TR/REC-html40/">The HTML 4.0
+	    specification</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
+	    Technical Committee</link>, maintainers of the DocBook DTD</para>
+      </listitem>
+
+      <listitem>
+	<para><link xlink:href="http://www.docbook.org/">DocBook: The Definitive
+	    Guide</link>, the online documentation for the DocBook
+	  DTD.</para>
+
+      </listitem>
+
+      <listitem>
+	<para><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>
+
+  <sect1 xml:id="see-also-linuxdoc">
+    <title>The Linux Documentation Project</title>
+
+    <itemizedlist>
+      <listitem>
+	<para><link xlink:href="http://www.linuxdoc.org/">The Linux Documentation
+	  Project web pages</link></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml
new file mode 100644
index 0000000000..6b0907ff57
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml
@@ -0,0 +1,2682 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.73
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sgml-markup">
+  <title>SGML Markup</title>
+
+  <para>This chapter describes the two markup languages you will encounter
+    when you contribute to the FreeBSD documentation project.  Each section
+    describes the markup language, and details the markup that you are likely
+    to want to use, or that is already in use.</para>
+
+  <para>These markup languages contain a large number of elements, and it can
+    be confusing sometimes to know which element to use for a particular
+    situation.  This section goes through the elements you are most likely to
+    need, and gives examples of how you would use them.</para>
+
+  <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
+    that would just reiterate the documentation for each language.  The aim of
+    this section is to list those elements more likely to be useful to you.
+    If you have a question about how best to markup a particular piece of
+    content, please post it to the &a.doc;.</para>
+
+  <note>
+    <title>Inline vs. block</title>
+
+    <para>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 xml:id="sgml-markup-html">
+    <title>HTML</title>
+
+    <para>HTML, the HyperText Markup Language, is the markup language of
+      choice on the World Wide Web.  More information can be found at
+      &lt;URL:<uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>&gt;.</para>
+
+    <para>HTML is used to markup pages on the FreeBSD web site.  It should not
+      (generally) be used to mark up other documentation,
+      since DocBook offers a
+      far richer set of elements to choose from.  Consequently, you will
+      normally only encounter HTML pages if you are writing for the web
+      site.</para>
+
+    <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
+      latest, 4.0 (available in both <emphasis>strict</emphasis> and
+      <emphasis>loose</emphasis> variants).</para>
+
+    <para>The HTML DTDs are available from the ports collection in the
+      <package>textproc/html</package> port.  They are automatically
+      installed as part of the <package>textproc/docproj</package>
+      port.</para>
+
+    <sect2>
+      <title>Formal Public Identifier (FPI)</title>
+
+      <para>There are a number of HTML FPIs, depending upon the version (also
+	known as the level) of HTML that you want to declare your document to
+	be compliant with.</para>
+
+      <para>The majority of HTML documents on the FreeBSD web site comply with
+	the loose version of HTML 4.0.</para>
+
+      <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Sectional elements</title>
+
+      <para>An HTML 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 the content that will be displayed
+	to the user.</para>
+
+      <para>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>Normal HTML document structure</title>
+
+	<programlisting>&lt;html&gt;
+  &lt;head&gt;
+	  &lt;title&gt;<replaceable>The document's title</replaceable>&lt;/title&gt;
+  &lt;/head&gt;
+
+  &lt;body&gt;
+
+    &hellip;
+
+  &lt;/body&gt;
+&lt;/html&gt;</programlisting>
+      </example>
+    </sect2>
+
+    <sect2>
+      <title>Block elements</title>
+
+      <sect3>
+	<title>Headings</title>
+
+	<para>HTML allows you to denote headings in your document, at up to
+	  six different levels.</para>
+
+	<para>The largest and most prominent heading is <tag>h1</tag>,
+	  then <tag>h2</tag>, continuing down to
+	  <tag>h6</tag>.</para>
+
+	<para>The element's content is the text of the heading.</para>
+
+	<example>
+	  <title><tag>h1</tag>, <tag>h2</tag>, etc.</title>
+
+	  <para>Use:</para>
+
+	  <programlisting>&lt;h1&gt;First section&lt;/h1&gt;
+
+&lt;!&hyphen;- Document introduction goes here -&hyphen;&gt;
+
+&lt;h2&gt;This is the heading for the first section&lt;/h2&gt;
+
+&lt;!&hyphen;- Content for the first section goes here -&hyphen;&gt;
+
+&lt;h3&gt;This is the heading for the first sub-section&lt;/h3&gt;
+
+&lt;!&hyphen;- Content for the first sub-section goes here -&hyphen;&gt;
+
+&lt;h2&gt;This is the heading for the second section&lt;/h2&gt;
+
+&lt;!&hyphen;- Content for the second section goes here -&hyphen;&gt;</programlisting>
+	</example>
+
+	<para>Generally, an HTML 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.  Each
+	  <tag>h<replaceable>n</replaceable></tag> element should have
+	  the same element, but one further up the hierarchy, preceding it.
+	  Leaving gaps in the numbering is to be avoided.</para>
+
+	<example>
+	  <title>Bad ordering of
+	    <tag>h<replaceable>n</replaceable></tag> elements</title>
+
+	  <para>Use:</para>
+
+	  <programlisting>&lt;h1&gt;First section&lt;/h1&gt;
+
+&lt;!&hyphen;- Document introduction -&hyphen;&gt;
+
+&lt;h3&gt;Sub-section&lt;/h3&gt;
+
+&lt;!&hyphen;- This is bad, &lt;h2&gt; has been left out -&hyphen;&gt;</programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Paragraphs</title>
+
+	<para>HTML supports a single paragraph element,
+	  <tag>p</tag>.</para>
+
+	<example>
+	  <title><tag>p</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>This is a paragraph.  It can contain just about any
+  other element.</p>]]></programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Block quotations</title>
+
+	<para>A block quotation is an extended quotation from another document
+	  that should not appear within the current paragraph.</para>
+
+	<example>
+	  <title><tag>blockquote</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>A small excerpt from the US Constitution:</p>
+
+<blockquote>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.</blockquote>]]></programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Lists</title>
+
+	<para>You can present the user with three types of lists, ordered,
+	  unordered, and definition.</para>
+
+	<para>Typically, each entry in an ordered list will be numbered, while
+	  each entry in an unordered list will be preceded by a bullet point.
+	  Definition lists are composed of two sections for each entry.  The
+	  first section is the term being defined, and the second section is
+	  the definition of the term.</para>
+
+	<para>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>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>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><tag>ul</tag> and <tag>ol</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>An unordered list.  Listitems will probably be
+  preceded by bullets.</p>
+
+<ul>
+  <li>First item</li>
+
+  <li>Second item</li>
+
+  <li>Third item</li>
+</ul>
+
+<p>An ordered list, with list items consisting of multiple
+  paragraphs.  Each item (note: not each paragraph) will be
+  numbered.</p>
+
+<ol>
+  <li><p>This is the first item.  It only has one paragraph.</p></li>
+
+  <li><p>This is the first paragraph of the second item.</p>
+
+    <p>This is the second paragraph of the second item.</p></li>
+
+  <li><p>This is the first and only paragraph of the third
+    item.</p></li>
+</ol>]]></programlisting>
+	</example>
+
+	<example>
+	  <title>Definition lists with <tag>dl</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<dl>
+  <dt>Term 1</dt>
+
+  <dd><p>Paragraph 1 of definition 1.</p>
+
+    <p>Paragraph 2 of definition 1.</p></dd>
+
+  <dt>Term 2</dt>
+
+  <dd><p>Paragraph 1 of definition 2.</p></dd>
+
+  <dt>Term 3</dt>
+
+  <dd><p>Paragraph 1 of definition 3.</p></dd>
+</dl>]]></programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Pre-formatted text</title>
+
+	<para>You can indicate that text should be shown to the user exactly
+	  as it is in the file.  Typically, this means that the text is shown
+	  in a fixed font, multiple spaces are not merged into one, and line
+	  breaks in the text are significant.</para>
+
+	<para>In order to do this, wrap the content in the
+	  <tag>pre</tag> element.</para>
+
+	<example>
+	  <title><tag>pre</tag></title>
+
+	  <para>You could use <tag>pre</tag> to mark up an email
+	    message:</para>
+
+	  <programlisting><![CDATA[<pre>  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</pre>]]></programlisting>
+
+	  <para>Keep in mind that <literal>&lt;</literal> and
+	    <literal>&amp;</literal> still are recognized as special
+	    characters in pre-formatted text.  This is why the example
+	    shown had to use <literal>&amp;lt;</literal> instead of
+	    <literal>&lt;</literal>.  For consistency,
+	    <literal>&amp;gt;</literal> was used in place of
+	    <literal>&gt;</literal>, too.  Watch out for the special characters
+	    that may appear in text copied from a plain-text source,
+	    e.g., an email message or program code.</para>
+
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Tables</title>
+
+	<note>
+	  <para>Most text-mode browsers (such as Lynx) do not render tables
+	    particularly effectively.  If you are relying on the tabular
+	    display of your content, you should consider using alternative
+	    markup to prevent confusion.</para>
+	</note>
+
+	<para>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 you do not need to include the
+	  <tag>p</tag> element.</para>
+
+	<example>
+	  <title>Simple use of <tag>table</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>This is a simple 2x2 table.</p>
+
+<table>
+  <tr>
+    <td>Top left cell</td>
+
+    <td>Top right cell</td>
+  </tr>
+
+  <tr>
+    <td>Bottom left cell</td>
+
+    <td>Bottom right cell</td>
+  </tr>
+</table>]]></programlisting></example>
+
+	<para>A cell can span multiple rows and columns.  To indicate this,
+	  add the <literal>rowspan</literal> and/or <literal>colspan</literal>
+	  attributes, with values indicating the number of rows of columns
+	  that should be spanned.</para>
+
+	<example>
+	  <title>Using <literal>rowspan</literal></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>One tall thin cell on the left, two short cells next to
+  it on the right.</p>
+
+<table>
+  <tr>
+    <td rowspan="2">Long and thin</td>
+  </tr>
+
+  <tr>
+    <td>Top cell</td>
+
+    <td>Bottom cell</td>
+  </tr>
+</table>]]></programlisting>
+	</example>
+
+	<example>
+	  <title>Using <literal>colspan</literal></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>One long cell on top, two short cells below it.</p>
+
+<table>
+  <tr>
+    <td colspan="2">Top cell</td>
+  </tr>
+
+  <tr>
+    <td>Bottom left cell</td>
+
+    <td>Bottom right cell</td>
+  </tr>
+</table>]]></programlisting>
+	</example>
+
+	<example>
+	  <title>Using <literal>rowspan</literal> and
+	    <literal>colspan</literal> together</title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>On a 3x3 grid, the top left block is a 2x2 set of
+  cells merged into one.  The other cells are normal.</p>
+
+<table>
+  <tr>
+    <td colspan="2" rowspan="2">Top left large cell</td>
+
+    <td>Top right cell</td>
+  </tr>
+
+  <tr>
+    <td>Middle right cell</td>
+  </tr>
+
+  <tr>
+    <td>Bottom left cell</td>
+
+    <td>Bottom middle cell</td>
+
+    <td>Bottom right cell</td>
+  </tr>
+</table>]]></programlisting>
+	</example>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>In-line elements</title>
+
+      <sect3>
+	<title>Emphasizing information</title>
+
+	<para>You have two levels of emphasis available in HTML,
+	  <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>Typically, <tag>em</tag> is rendered in italic and
+	  <tag>strong</tag> is rendered in bold.  This is not always
+	  the case, however, and you should not rely on it.</para>
+
+	<example>
+	  <title><tag>em</tag> and <tag>strong</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p><em>This</em> has been emphasized, while
+  <strong>this</strong> has been strongly emphasized.</p>]]></programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Bold and italics</title>
+
+	<para>Because HTML includes presentational markup, you can also
+	  indicate that particular content should be rendered in bold or
+	  italic.  The elements are <tag>b</tag> and
+	  <tag>i</tag> respectively.</para>
+
+	<example>
+	  <title><tag>b</tag> and <tag>i</tag></title>
+
+	  <programlisting><![CDATA[<p><b>This</b> is in bold, while <i>this</i> is
+  in italics.</p>]]></programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Indicating fixed pitch text</title>
+
+	<para>If you have content that should be rendered in a fixed pitch
+	  (typewriter) typeface, use <tag>tt</tag> (for
+	  <quote>teletype</quote>).</para>
+
+	<example>
+	  <title><tag>tt</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>This document was originally written by
+  Nik Clayton, who can be reached by email as
+  <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Content size</title>
+
+	<para>You can indicate that content should be shown in a larger or
+	  smaller font.  There are three ways of doing this.</para>
+
+	<orderedlist>
+	  <listitem>
+	    <para>Use <tag>big</tag> and <tag>small</tag>
+	      around the content you wish to change size.  These tags can be
+	      nested, so <literal>&lt;big&gt;&lt;big&gt;This is much
+		bigger&lt;/big&gt;&lt;/big&gt;</literal> is possible.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Use <tag>font</tag> with the <literal>size</literal>
+	      attribute set to <literal>+1</literal> or <literal>-1</literal>
+	      respectively.  This has the same effect as using
+	      <tag>big</tag> or <tag>small</tag>.  However,
+	      the use of this approach is deprecated.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Use <tag>font</tag> with the <literal>size</literal>
+	      attribute set to a number between 1 and 7.  The default font size
+	      is <literal>3</literal>.  This approach is deprecated.</para>
+	  </listitem>
+	</orderedlist>
+
+	<example>
+	  <title><tag>big</tag>, <tag>small</tag>, and
+	    <tag>font</tag></title>
+
+	  <para>The following fragments all do the same thing.</para>
+
+	  <programlisting><![CDATA[<p>This text is <small>slightly smaller</small>.  But
+  this text is <big>slightly bigger</big>.</p>
+
+<p>This text is <font size="-1">slightly smaller</font>.  But
+  this text is <font size="+1">slightly bigger</font.</p>
+
+<p>This text is <font size="2">slightly smaller</font>.  But
+  this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
+	</example>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Links</title>
+
+      <note>
+	<para>Links are also in-line elements.</para>
+      </note>
+
+      <sect3>
+	<title>Linking to other documents on the WWW</title>
+
+	<para>In order to include a link to another document on the WWW you
+	  must know the URL of the document you want to link to.</para>
+
+	<para>The link is indicated with <tag>a</tag>, and the
+	  <literal>href</literal> attribute contains the URL of the target
+	  document.  The content of the element becomes the link, and is
+	  normally indicated to the user in some way (underlining, change of
+	  color, different mouse cursor when over the link, and so
+	  on).</para>
+
+	<example>
+	  <title>Using <literal>&lt;a href="..."&gt;</literal></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p>More information is available at the
+  <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting>
+	</example>
+
+	<para>These links will take the user to the top of the chosen
+	  document.</para>
+      </sect3>
+
+      <sect3>
+	<title>Linking to other parts of documents</title>
+
+	<para>Linking to a point within another document (or within the same
+	  document) requires that the document author include anchors that you
+	  can link to.</para>
+
+	<para>Anchors are indicated with <tag>a</tag> and the
+	  <literal>name</literal> attribute instead of
+	  <literal>href</literal>.</para>
+
+	<example>
+	  <title>Using <literal>&lt;a name="..."&gt;</literal></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<p><a name="para1">This</a> paragraph can be referenced
+  in other links with the name <tt>para1</tt>.</p>]]></programlisting>
+	</example>
+
+	<para>To link to a named part of a document, write a normal link to
+	  that document, but include the name of the anchor after a
+	  <literal>#</literal> symbol.</para>
+
+	<example>
+	  <title>Linking to a named part of another document</title>
+
+	  <para>Assume that the <literal>para1</literal> example resides in a
+	    document called <filename>foo.html</filename>.</para>
+
+	  <programlisting><![CDATA[<p>More information can be found in the
+  <a href="foo.html#para1">first paragraph</a> of
+  <tt>foo.html</tt>.</p>]]></programlisting>
+	</example>
+
+	<para>If you are linking to a named anchor within the same document
+	  then you can omit the document's URL, and just include the name of
+	  the anchor (with the preceding <literal>#</literal>).</para>
+
+	<example>
+	  <title>Linking to a named part of the same document</title>
+
+	  <para>Assume that the <literal>para1</literal> example resides in
+	    this document:</para>
+
+	  <programlisting><![CDATA[<p>More information can be found in the
+  <a href="#para1">first paragraph</a> of this
+  document.</p>]]></programlisting>
+	</example>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="sgml-markup-docbook">
+    <title>DocBook</title>
+
+    <para>DocBook was originally developed by HaL Computer Systems and O'Reilly
+      &amp; Associates to be a DTD for writing technical documentation
+      <footnote><para>A short history can be found under <link xlink:href="http://www.oasis-open.org/committees/docbook/intro.shtml">
+      http://www.oasis-open.org/committees/docbook/intro.shtml</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 HTML, 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>
+
+    <note>
+      <title><literal>formal</literal> vs. <literal>informal</literal></title>
+
+      <para>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>
+
+    <para>The DocBook DTD is available from the ports collection in the
+      <package>textproc/docbook</package> port.  It is automatically
+      installed as part of the <package>textproc/docproj</package>
+      port.</para>
+
+    <sect2>
+      <title>FreeBSD extensions</title>
+
+      <para>The FreeBSD Documentation Project has extended the DocBook DTD by
+	adding some new elements.  These elements serve to make some of the
+	markup more precise.</para>
+
+      <para>Where a FreeBSD specific element is listed below it is clearly
+	marked.</para>
+
+      <para>Throughout the rest of this document, the term
+	<quote>DocBook</quote> is used to mean the FreeBSD extended DocBook
+	DTD.</para>
+
+      <note>
+	<para>There is nothing about these extensions that is FreeBSD
+	  specific, 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, &hellip;) be interested in
+	  collaborating on a standard DocBook extension set, please get in
+	  touch with &a.doceng;.</para>
+      </note>
+
+      <para>The FreeBSD extensions are not (currently) in the ports
+	collection.  They are stored in the FreeBSD CVS tree, as <link xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/xml/freebsd.dtd">doc/share/xml/freebsd.dtd</link>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Formal Public Identifier (FPI)</title>
+
+      <para>In compliance with the DocBook guidelines for writing FPIs for
+	  DocBook customizations, the FPI for the FreeBSD extended DocBook DTD
+	  is:</para>
+
+	<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Document structure</title>
+
+      <para>DocBook allows you to structure your documentation in several
+	ways.  In the FreeBSD Documentation Project we are using two primary
+	types of DocBook document: the book and the article.</para>
+
+      <para>A book is 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.
+	The Handbook is arranged in this way.</para>
+
+      <para>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>Chapters and sections contain the remainder of the content.</para>
+
+      <para>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>Obviously, you should consider the nature of the documentation you
+	are writing in order to decide 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>The <link xlink:href="&url.base;/docs.html">FreeBSD
+	  tutorials</link> are all marked up as articles, while this
+	document, the <link xlink:href="&url.books.faq;/index.html">FreeBSD
+	  FAQ</link>, and the <link xlink:href="&url.books.handbook;/index.html">FreeBSD Handbook</link> are
+	all marked up as books.</para>
+
+      <sect3>
+	<title>Starting a book</title>
+
+	<para>The content of the 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>This additional information should be contained within
+	  <tag>bookinfo</tag>.</para>
+
+	<example>
+	  <title>Boilerplate <tag>book</tag> with
+	    <tag>bookinfo</tag></title>
+
+	  <!-- Can't put this in a marked section because of the
+               replaceable elements -->
+	  <programlisting>&lt;book&gt;
+  &lt;bookinfo&gt;
+    &lt;title&gt;<replaceable>Your title here</replaceable>&lt;/title&gt;
+
+    &lt;author&gt;
+      &lt;firstname&gt;<replaceable>Your first name</replaceable>&lt;/firstname&gt;
+      &lt;surname&gt;<replaceable>Your surname</replaceable>&lt;/surname&gt;
+      &lt;affiliation&gt;
+        &lt;address&gt;&lt;email&gt;<replaceable>Your email address</replaceable>&lt;/email&gt;&lt;/address&gt;
+      &lt;/affiliation&gt;
+    &lt;/author&gt;
+
+    &lt;copyright&gt;
+      &lt;year&gt;<replaceable>1998</replaceable>&lt;/year&gt;
+      &lt;holder role="mailto:<replaceable>your email address</replaceable>"&gt;<replaceable>Your name</replaceable>&lt;/holder&gt;
+    &lt;/copyright&gt;
+
+    &lt;releaseinfo&gt;&#36;FreeBSD&#36;&lt;/releaseinfo&gt;
+
+    &lt;abstract&gt;
+      &lt;para&gt;<replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para&gt;
+    &lt;/abstract&gt;
+  &lt;/bookinfo&gt;
+
+  &hellip;
+
+&lt;/book&gt;</programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Starting an article</title>
+
+	<para>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>This additional information should be contained within
+	  <tag>articleinfo</tag>.</para>
+
+	<example>
+	  <title>Boilerplate <tag>article</tag> with
+	    <tag>articleinfo</tag></title>
+
+	  <!-- Can't put this in a marked section because of the
+               replaceable elements -->
+	  <programlisting>&lt;article&gt;
+  &lt;articleinfo&gt;
+    &lt;title&gt;<replaceable>Your title here</replaceable>&lt;/title&gt;
+
+    &lt;author&gt;
+      &lt;firstname&gt;<replaceable>Your first name</replaceable>&lt;/firstname&gt;
+      &lt;surname&gt;<replaceable>Your surname</replaceable>&lt;/surname&gt;
+      &lt;affiliation&gt;
+        &lt;address&gt;&lt;email&gt;<replaceable>Your email address</replaceable>&lt;/email&gt;&lt;/address&gt;
+      &lt;/affiliation&gt;
+    &lt;/author&gt;
+
+    &lt;copyright&gt;
+      &lt;year&gt;<replaceable>1998</replaceable>&lt;/year&gt;
+      &lt;holder role="mailto:<replaceable>your email address</replaceable>"&gt;<replaceable>Your name</replaceable>&lt;/holder&gt;
+    &lt;/copyright&gt;
+
+    &lt;releaseinfo&gt;&#36;FreeBSD&#36;&lt;/releaseinfo&gt;
+
+    &lt;abstract&gt;
+      &lt;para&gt;<replaceable>Include an abstract of the article's contents here.</replaceable>&lt;/para&gt;
+    &lt;/abstract&gt;
+  &lt;/articleinfo&gt;
+
+  &hellip;
+
+&lt;/article&gt;</programlisting>
+	</example>
+      </sect3>
+      <sect3>
+	<title>Indicating chapters</title>
+
+	<para>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>A simple chapter</title>
+
+	  <programlisting><![CDATA[<chapter>
+  <title>The chapter's title</title>
+
+  ...
+</chapter>]]></programlisting>
+	</example>
+
+	<para>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>Empty chapters</title>
+
+	  <programlisting><![CDATA[<chapter>
+  <title>This is an empty chapter</title>
+
+  <para></para>
+</chapter>]]></programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Sections below chapters</title>
+
+	<para>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>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>Sections in chapters</title>
+
+	  <programlisting><![CDATA[<chapter>
+  <title>A sample chapter</title>
+
+  <para>Some text in the chapter.</para>
+
+  <sect1>
+    <title>First section (1.1)</title>
+
+    &hellip;
+  </sect1>
+
+  <sect1>
+    <title>Second section (1.2)</title>
+
+    <sect2>
+      <title>First sub-section (1.2.1)</title>
+
+      <sect3>
+        <title>First sub-sub-section (1.2.1.1)</title>
+
+        &hellip;
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Second sub-section (1.2.2)</title>
+
+      &hellip;
+    </sect2>
+  </sect1>
+</chapter>]]></programlisting>
+	</example>
+
+	<note>
+	  <para>This example includes section numbers in the section titles.
+	    You should not do this in your documents.  Adding the section
+	    numbers is carried out by the stylesheets (of which more
+	    later), and you do not need to manage them yourself.</para>
+	</note>
+      </sect3>
+
+      <sect3>
+	<title>Subdividing using <tag>part</tag>s</title>
+
+	<para>You can introduce another layer 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><![CDATA[<part>
+  <title>Introduction</title>
+
+  <chapter>
+    <title>Overview</title>
+
+    ...
+  </chapter>
+
+  <chapter>
+    <title>What is FreeBSD?</title>
+
+    ...
+  </chapter>
+
+  <chapter>
+    <title>History</title>
+
+    ...
+  </chapter>
+</part>]]></programlisting>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Block elements</title>
+
+      <sect3>
+	<title>Paragraphs</title>
+
+	<para>DocBook supports three types of paragraphs:
+	  <tag>formalpara</tag>, <tag>para</tag>, and
+	  <tag>simpara</tag>.</para>
+
+	<para>Most of the time you will only need to 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><tag>para</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>This is a paragraph.  It can contain just about any
+  other element.</para> ]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>This is a paragraph.  It can contain just about any other
+	    element.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Block quotations</title>
+
+	<para>A block quotation is an extended quotation from another document
+	  that should not appear within the current paragraph.  You will
+	  probably only need it infrequently.</para>
+
+	<para>Blockquotes can optionally contain a title and an attribution
+	  (or they can be left untitled and unattributed).</para>
+
+	<example>
+	  <title><tag>blockquote</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>A small excerpt from the US Constitution:</para>
+
+<blockquote>
+  <title>Preamble to the Constitution of the United States</title>
+
+  <attribution>Copied from a web site somewhere</attribution>
+
+  <para>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>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <blockquote>
+	    <title>Preamble to the Constitution of the United States</title>
+
+	    <attribution>Copied from a web site somewhere</attribution>
+
+	    <para>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>
+      </sect3>
+
+      <sect3>
+	<title>Tips, notes, warnings, cautions, important information and
+	  sidebars.</title>
+
+	<para>You may need to include extra information separate from the
+	  main body of the text.  Typically this is <quote>meta</quote>
+	  information that the user should be aware of.</para>
+
+	<para>Depending on the nature of the information, one of
+	  <tag>tip</tag>, <tag>note</tag>,
+	  <tag>warning</tag>, <tag>caution</tag>, and
+	  <tag>important</tag> should be used.  Alternatively, if the
+	  information is related to the main text but is not one of the above,
+	  use <tag>sidebar</tag>.</para>
+
+	<para>The circumstances in which to choose one of these elements over
+	  another is unclear.  The DocBook documentation suggests:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>A Note is for information that should be heeded by all
+	      readers.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>An Important element is a variation on Note.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>A Caution is for information regarding possible data loss
+	      or software damage.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>A Warning is for information regarding possible hardware
+	      damage or injury to life or limb.</para>
+	  </listitem>
+	</itemizedlist>
+
+	<example>
+	  <title><tag>warning</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<warning>
+  <para>Installing FreeBSD may make you want to delete Windows from your
+    hard disk.</para>
+</warning>]]></programlisting>
+	  </example>
+
+	<!-- Need to do this outside of the example -->
+	<warning>
+	  <para>Installing FreeBSD may make you want to delete Windows from
+	    your hard disk.</para>
+	</warning>
+      </sect3>
+
+      <sect3>
+	<title>Lists and procedures</title>
+
+	<para>You will often need to list pieces of information to the user,
+	  or present them with a number of steps that must be carried out in
+	  order to accomplish a particular goal.</para>
+
+	<para>In order to do this, use <tag>itemizedlist</tag>,
+	  <tag>orderedlist</tag>, or
+	  <tag>procedure</tag><footnote><para>There are other types of
+	      list element in DocBook, but we are not concerned with those at
+	      the moment.</para>
+	  </footnote>
+	</para>
+
+	<para><tag>itemizedlist</tag> and
+	  <tag>orderedlist</tag> are similar to their counterparts in
+	  HTML, <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
+	  HTML's <tag>li</tag> tags.  However, unlike HTML, they are
+	  required.</para>
+
+	<para><tag>procedure</tag> is slightly different.  It consists
+	  of <tag>step</tag>s, which may in turn consists of more
+	  <tag>step</tag>s or <tag>substep</tag>s.  Each
+	  <tag>step</tag> contains block elements.</para>
+
+	<example>
+	  <title><tag>itemizedlist</tag>,
+	    <tag>orderedlist</tag>, and
+	    <tag>procedure</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<itemizedlist>
+  <listitem>
+    <para>This is the first itemized item.</para>
+  </listitem>
+
+  <listitem>
+    <para>This is the second itemized item.</para>
+  </listitem>
+</itemizedlist>
+
+<orderedlist>
+  <listitem>
+    <para>This is the first ordered item.</para>
+  </listitem>
+
+  <listitem>
+    <para>This is the second ordered item.</para>
+  </listitem>
+</orderedlist>
+
+<procedure>
+  <step>
+    <para>Do this.</para>
+  </step>
+
+  <step>
+    <para>Then do this.</para>
+  </step>
+
+  <step>
+    <para>And now do this.</para>
+  </step>
+</procedure>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para>This is the first itemized item.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>This is the second itemized item.</para>
+	    </listitem>
+	  </itemizedlist>
+
+	  <orderedlist>
+	    <listitem>
+	      <para>This is the first ordered item.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>This is the second ordered item.</para>
+	    </listitem>
+	  </orderedlist>
+	</example>
+
+	<!-- Can't have <procedure> inside <example>, so this is a cheat -->
+
+	<procedure>
+	  <step>
+	    <para>Do this.</para>
+	  </step>
+
+	  <step>
+	    <para>Then do this.</para>
+	  </step>
+
+	  <step>
+	    <para>And now do this.</para>
+	  </step>
+	</procedure>
+      </sect3>
+
+      <sect3>
+	<title>Showing file samples</title>
+
+	<para>If you want to show a fragment of a file (or perhaps a complete
+	  file) to the user, wrap it in the <tag>programlisting</tag>
+	  element.</para>
+
+	<para>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><tag>programlisting</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>When you have finished, your program should look like
+  this:</para>
+
+<programlisting>#include &lt;stdio.h&gt;
+
+int
+main(void)
+{
+    printf("hello, world\n");
+}</programlisting>]]></programlisting>
+
+	  <para>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>Appearance:</para>
+
+	  <para>When you have finished, your program should look like
+	    this:</para>
+
+	  <programlisting>#include &lt;stdio.h&gt;
+
+int
+main(void)
+{
+    printf("hello, world\n");
+}</programlisting>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Callouts</title>
+
+	<para>A callout is a mechanism for referring back to an earlier piece
+	  of text or specific position within an earlier example without
+	  linking to it within the text.</para>
+
+	<para>To do this, mark areas of interest in your example
+	  (<tag>programlisting</tag>,
+	  <tag>literallayout</tag>, or whatever) 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 refers back to the example and
+	  provides additional commentary.</para>
+
+	<example>
+	  <title><tag>co</tag> and
+	    <tag>calloutlist</tag></title>
+
+	  <programlisting><![CDATA[<para>When you have finished, your program should look like
+  this:</para>
+
+<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/>
+
+int <co id="co-ex-return"/>
+main(void)
+{
+    printf("hello, world\n"); <co id="co-ex-printf"/>
+}</programlisting>
+
+<calloutlist>
+  <callout arearefs="co-ex-include">
+    <para>Includes the standard IO header file.</para>
+  </callout>
+
+  <callout arearefs="co-ex-return">
+    <para>Specifies that <function>main()</function> returns an
+      int.</para>
+  </callout>
+
+  <callout arearefs="co-ex-printf">
+    <para>The <function>printf()</function> call that writes
+      <literal>hello, world</literal> to standard output.</para>
+  </callout>
+</calloutlist>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>When you have finished, your program should look like
+	    this:</para>
+
+	  <programlisting>#include &lt;stdio.h&gt; <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>Includes the standard IO header file.</para>
+	    </callout>
+
+	    <callout arearefs="co-ex-return">
+	      <para>Specifies that <function>main()</function> returns an
+		int.</para>
+	    </callout>
+
+	    <callout arearefs="co-ex-printf">
+	      <para>The <function>printf()</function> call that writes
+		<literal>hello, world</literal> to standard output.</para>
+	    </callout>
+	  </calloutlist>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Tables</title>
+
+	<para>Unlike HTML, you do not need to use tables for layout purposes,
+	  as the stylesheet handles those issues for you.  Instead, just use
+	  tables for marking up tabular data.</para>
+
+	<para>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
+	  you can then have 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>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><tag>informaltable</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<informaltable frame="none" pgwide="1">
+  <tgroup cols="2">
+    <thead>
+      <row>
+        <entry>This is column head 1</entry>
+        <entry>This is column head 2</entry>
+      </row>
+    </thead>
+
+    <tbody>
+      <row>
+        <entry>Row 1, column 1</entry>
+        <entry>Row 1, column 2</entry>
+      </row>
+
+      <row>
+        <entry>Row 2, column 1</entry>
+        <entry>Row 2, column 2</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <informaltable frame="none" pgwide="1">
+	    <tgroup cols="2">
+	      <thead>
+		<row>
+		  <entry>This is column head 1</entry>
+		  <entry>This is column head 2</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry>Row 1, column 1</entry>
+		  <entry>Row 1, column 2</entry>
+		</row>
+
+		<row>
+		  <entry>Row 2, column 1</entry>
+		  <entry>Row 2, column 2</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+	</example>
+
+	<para>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>If you do not want a border around the table the
+	  <literal>frame</literal> attribute can be added to the
+	  <tag>informaltable</tag> element with a value of
+	  <literal>none</literal> (i.e., <literal>&lt;informaltable
+	    frame="none"&gt;</literal>).</para>
+
+	<example>
+	  <title>Tables where <literal>frame="none"</literal></title>
+
+	  <para>Appearance:</para>
+
+	  <informaltable frame="none" pgwide="1">
+	    <tgroup cols="2">
+	      <thead>
+		<row>
+		  <entry>This is column head 1</entry>
+		  <entry>This is column head 2</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry>Row 1, column 1</entry>
+		  <entry>Row 1, column 2</entry>
+		</row>
+
+		<row>
+		  <entry>Row 2, column 1</entry>
+		  <entry>Row 2, column 2</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Examples for the user to follow</title>
+
+	<para>A lot of the time you need to show examples for the user to
+	  follow.  Typically, these will consist of dialogs with the computer;
+	  the user types in a command, the user gets a response back, they
+	  type in another command, and so on.</para>
+
+	<para>A number of distinct elements and entities come into play
+	  here.</para>
+
+	<variablelist>
+	  <varlistentry>
+	    <term><tag>screen</tag></term>
+
+	    <listitem>
+	      <para>Everything the user sees in this example will be on the
+		computer screen, so the next element is
+		<tag>screen</tag>.</para>
+
+	      <para>Within <tag>screen</tag>, white space is
+		significant.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><tag>prompt</tag>,
+	      <literal>&amp;prompt.root;</literal> and
+	      <literal>&amp;prompt.user;</literal></term>
+
+	    <listitem>
+	      <para>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>As a special case, the two shell prompts for the normal
+		user and the root user have been provided as entities.  Every
+		time you want to indicate the user is at a shell prompt, use
+		one of <literal>&amp;prompt.root;</literal> and
+		<literal>&amp;prompt.user;</literal> as necessary.  They do
+		not need to be inside <tag>prompt</tag>.</para>
+
+	      <note>
+		<para><literal>&amp;prompt.root;</literal> and
+		  <literal>&amp;prompt.user;</literal> are FreeBSD
+		  extensions to DocBook, and are not part of the original
+		  DTD.</para>
+	      </note>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><tag>userinput</tag></term>
+
+	    <listitem>
+	      <para>When displaying text that the user should type in, wrap it
+		in <tag>userinput</tag> tags.  It will probably be
+		displayed differently to the user.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+
+	<example>
+	  <title><tag>screen</tag>, <tag>prompt</tag>, and
+	    <tag>userinput</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<screen>&prompt.user; <userinput>ls -1</userinput>
+foo1
+foo2
+foo3
+&prompt.user; <userinput>ls -1 | grep foo2</userinput>
+foo2
+&prompt.user; <userinput>su</userinput>
+<prompt>Password: </prompt>
+&prompt.root; <userinput>cat foo2</userinput>
+This is the file called 'foo2'</screen>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <screen>&prompt.user; <userinput>ls -1</userinput>
+foo1
+foo2
+foo3
+&prompt.user; <userinput>ls -1 | grep foo2</userinput>
+foo2
+&prompt.user; <userinput>su</userinput>
+<prompt>Password: </prompt>
+&prompt.root; <userinput>cat foo2</userinput>
+This is the file called 'foo2'</screen>
+	</example>
+
+	<note>
+	  <para>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>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>In-line elements</title>
+
+      <sect3>
+	<title>Emphasizing information</title>
+
+	<para>When you want 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>There is no way to change the presentation of the emphasis
+	  within your document, no equivalent of HTML's <tag>b</tag>
+	  and <tag>i</tag>.  If the information you are presenting is
+	  important then consider presenting it in
+	  <tag>important</tag> rather than
+	  <tag>emphasis</tag>.</para>
+
+	<example>
+	  <title><tag>emphasis</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>FreeBSD is without doubt <emphasis>the</emphasis>
+  premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix
+	    like operating system for the Intel architecture.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Quotations</title>
+
+	<para>To quote text from another document or source, or to denote
+	  a phrase that is used figuratively, use <tag>quote</tag>.
+	  Within a <tag>quote</tag> tag, you may use most of the
+	  markup tags available for normal text.</para>
+
+	<example>
+	  <title>Quotations</title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the
+  <quote>boundary between local and public administration</quote>,
+  as RFC 1535 calls it.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>However, make sure that the search does not go beyond the
+	    <quote>boundary between local and public administration</quote>,
+	    as RFC 1535 calls it.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Keys, mouse buttons, and combinations</title>
+
+	<para>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><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>The stylesheets automatically add any connecting symbols, such
+	  as <literal>+</literal>, between the key names, when wrapped in
+	  <tag>keycombo</tag>.</para>
+
+	<example>
+	  <title>Keys, mouse buttons, and combinations</title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>To switch to the second virtual terminal, press
+  <keycombo action="simul"><keycap>Alt</keycap>
+    <keycap>F1</keycap></keycombo>.</para>
+
+<para>To exit <command>vi</command> without saving your work, type
+  <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
+    <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
+
+<para>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>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>To switch to the second virtual terminal, press
+	    <keycombo action="simul"><keycap>Alt</keycap>
+	      <keycap>F1</keycap></keycombo>.</para>
+
+	  <para>To exit <command>vi</command> without saving your work, type
+	    <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
+	      <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
+
+	  <para>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>
+      </sect3>
+
+      <sect3>
+	<title>Applications, commands, options, and cites</title>
+
+	<para>You will frequently want to refer to both applications and
+	  commands when writing for the Handbook.  The distinction between
+	  them is simple: an application is the name for a suite (or possibly
+	  just 1) of programs that fulfil a particular task.  A command is the
+	  name of a program that the user can run.</para>
+
+	<para>In addition, you will occasionally need to list one or more of
+	  the options that a command might take.</para>
+
+	<para>Finally, you will often want to list a command with its manual
+	  section number, in the <quote>command(number)</quote> format so
+	  common in Unix manuals.</para>
+
+	<para>Mark up application names with
+	  <tag>application</tag>.</para>
+
+	<para>When you want 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>This can be cumbersome to write, and so a series of <link linkend="sgml-primer-general-entities">general entities</link>
+	  have been created to make this easier.  Each entity takes the form
+	  <literal>&amp;man.manual-page.manual-section;</literal>.</para>
+
+	<para>The file that contains these entities is in
+	  <filename>doc/share/xml/man-refs.ent</filename>, and can be
+	  referred to using this FPI:</para>
+
+	<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
+
+	<para>Therefore, the introduction to your documentation will probably
+	  look like this:</para>
+
+	<programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
+
+&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
+%man;
+
+&hellip;
+
+]&gt;</programlisting>
+
+	<para>Use <tag>command</tag> when you want to include a
+	  command name <quote>in-line</quote> but present it as something the
+	  user should type in.</para>
+
+	<para>Use <tag>option</tag> to mark up the options
+	  which will be passed to a command.</para>
+
+	<para>When referring to the same command multiple times in
+	  close proximity it is preferred to use the
+	  <literal>&amp;man.command.section;</literal>
+	  notation to markup the first reference and use
+	  <tag>command</tag> to markup subsequent references.
+	  This makes the generated output, especially HTML, appear
+	  visually better.</para>
+
+	<para>This can be confusing, and sometimes the choice is not always
+	  clear.  Hopefully this example makes it clearer.</para>
+
+	<example>
+	  <title>Applications, commands, and options.</title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para><application>Sendmail</application> is the most
+  widely used Unix mail application.</para>
+
+<para><application>Sendmail</application> includes the
+  <citerefentry>
+    <refentrytitle>sendmail</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>, &man.mailq.8;, and &man.newaliases.8;
+  programs.</para>
+
+<para>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>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para><application>Sendmail</application> is the most widely used
+	    Unix mail application.</para>
+
+	  <para><application>Sendmail</application> includes the
+	    <citerefentry>
+	      <refentrytitle>sendmail</refentrytitle>
+	      <manvolnum>8</manvolnum>
+	    </citerefentry>, <citerefentry>
+	      <refentrytitle>mailq</refentrytitle>
+	      <manvolnum>8</manvolnum>
+	    </citerefentry>, and <citerefentry>
+	      <refentrytitle>newaliases</refentrytitle>
+	      <manvolnum>8</manvolnum>
+	    </citerefentry> programs.</para>
+
+	  <para>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>Notice how the
+	    <literal>&amp;man.command.section;</literal> notation is easier to follow.</para>
+	</note>
+      </sect3>
+
+      <sect3>
+	<title>Files, directories, extensions</title>
+
+	<para>Whenever you wish to refer to the name of a file, a directory,
+	  or a file extension, use <tag>filename</tag>.</para>
+
+	<example>
+	  <title><tag>filename</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>The SGML source for the Handbook in English can be
+  found in <filename>/usr/doc/en/handbook/</filename>.  The first
+  file is called <filename>handbook.xml</filename> in that
+  directory.  You should also see a <filename>Makefile</filename>
+  and a number of files with a <filename>.ent</filename>
+  extension.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>The SGML source for the Handbook in English can be found in
+	    <filename>/usr/doc/en/handbook/</filename>.  The first file is
+	    called <filename>handbook.xml</filename> in that directory.  You
+	    should also see a <filename>Makefile</filename> and a number of
+	    files with a <filename>.ent</filename> extension.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+        <title>The name of ports</title>
+
+	<note>
+	  <title>FreeBSD extension</title>
+
+	  <para>These elements are part of the FreeBSD extension to DocBook,
+	    and do not exist in the original DocBook DTD.</para>
+	</note>
+
+        <para>You might need to include the name of a program from the
+          FreeBSD Ports Collection in the documentation.  Use the
+          <tag>filename</tag> tag with the <literal>role</literal>
+          attribute set to <literal>package</literal> to identify these.
+          Since ports
+          can be installed in any number of locations, only include
+          the category and the port name; do not include
+          <filename>/usr/ports</filename>.</para>
+
+        <example>
+          <title><tag>filename</tag> tag with
+            <literal>package</literal> role</title>
+
+          <para>Use:</para>
+
+          <programlisting><![CDATA[<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>]]></programlisting>
+
+          <para>Appearance:</para>
+
+          <para>Install the <package>net/ethereal</package>
+            port to view network traffic.</para>
+        </example>
+      </sect3>
+
+      <sect3>
+	<title>Devices</title>
+
+	<note>
+	  <title>FreeBSD extension</title>
+
+	  <para>These elements are part of the FreeBSD extension to DocBook,
+	    and do not exist in the original DocBook DTD.</para>
+	</note>
+
+	<para>When referring to devices you have two choices.  You can either
+	  refer to the device as it appears in <filename>/dev</filename>, or
+	  you can use the name of the device as it appears in the kernel.  For
+	  this latter course, use <tag>devicename</tag>.</para>
+
+	<para>Sometimes you will not have a choice.  Some devices, such as
+	  networking cards, do not have entries in <filename>/dev</filename>,
+	  or the entries are markedly different from those entries.</para>
+
+	<example>
+	  <title><tag>devicename</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para><devicename>sio</devicename> is used for serial
+  communication in FreeBSD.  <devicename>sio</devicename> manifests
+  through a number of entries in <filename>/dev</filename>, including
+  <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>
+
+<para>By contrast, the networking devices, such as
+  <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para>
+
+<para>In MS-DOS, the first floppy drive is referred to as
+  <devicename>a:</devicename>.  In FreeBSD it is
+  <filename>/dev/fd0</filename>.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para><filename>sio</filename> is used for serial communication
+	    in FreeBSD.  <filename>sio</filename> manifests through a
+	    number of entries in <filename>/dev</filename>, including
+	    <filename>/dev/ttyd0</filename> and
+	    <filename>/dev/cuaa0</filename>.</para>
+
+	  <para>By contrast, the networking devices, such as
+	    <filename>ed0</filename> do not appear in
+	    <filename>/dev</filename>.</para>
+
+	  <para>In MS-DOS, the first floppy drive is referred to as
+	    <filename>a:</filename>.  In FreeBSD it is
+	    <filename>/dev/fd0</filename>.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Hosts, domains, IP addresses, and so forth</title>
+
+	<note>
+	  <title>FreeBSD extension</title>
+
+	  <para>These elements are part of the FreeBSD extension to DocBook,
+	    and do not exist in the original DocBook DTD.</para>
+	</note>
+
+	<para>You can markup identification information for networked
+	  computers (hosts) in several ways, depending on the nature of the
+	  information.  All of them use <tag>hostid</tag> as the
+	  element, with the <literal>role</literal> attribute selecting the
+	  type of the marked up information.</para>
+
+	<variablelist>
+	  <varlistentry>
+	    <term>No role attribute, or
+	      <literal>role="hostname"</literal></term>
+
+	    <listitem>
+	      <para>With no role attribute (i.e.,
+		<tag>hostid</tag>...<tag>/hostid</tag>) the
+		marked up information is the simple hostname, such as
+		<literal>freefall</literal> or <literal>wcarchive</literal>.
+		You can explicitly specify this with
+		<literal>role="hostname"</literal>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>role="domainname"</literal></term>
+
+	    <listitem>
+	      <para>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><literal>role="fqdn"</literal></term>
+
+	    <listitem>
+	      <para>The text is a Fully Qualified Domain Name, with both
+		hostname and domain name parts.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>role="ipaddr"</literal></term>
+
+	    <listitem>
+	      <para>The text is an IP address, probably expressed as a dotted
+		quad.</para>
+	    </listitem>
+	  </varlistentry>
+
+          <varlistentry>
+            <term><literal>role="ip6addr"</literal></term>
+
+            <listitem>
+              <para>The text is an IPv6 address.</para>
+            </listitem>
+          </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>role="netmask"</literal></term>
+
+	    <listitem>
+	      <para>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.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>role="mac"</literal></term>
+
+	    <listitem>
+	      <para>The text is an Ethernet MAC address, expressed as a series
+		of 2 digit hexadecimal numbers separated by colons.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+
+	<example>
+	  <title><tag>hostid</tag> and roles</title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>The local machine can always be referred to by the
+  name <hostid>localhost</hostid>, which will have the IP address
+  <hostid role="ipaddr">127.0.0.1</hostid>.</para>
+
+<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
+  contains a number of different hosts, including
+  <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
+  <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
+
+<para>When adding an IP alias to an interface (using
+  <command>ifconfig</command>) <emphasis>always</emphasis> use a
+  netmask of <hostid role="netmask">255.255.255.255</hostid>
+  (which can also be expressed as <hostid
+    role="netmask">0xffffffff</hostid>.</para>
+
+<para>The MAC address uniquely identifies every network card
+  in existence.  A typical MAC address looks like <hostid
+    role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>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>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>When adding an IP 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>The MAC address uniquely identifies every network card in
+	    existence.  A typical MAC address looks like <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Usernames</title>
+
+	<note>
+	  <title>FreeBSD extension</title>
+
+	  <para>These elements are part of the FreeBSD extension to DocBook,
+	    and do not exist in the original DocBook DTD.</para>
+	</note>
+
+	<para>When you need to refer to a specific username, such as
+	  <literal>root</literal> or <literal>bin</literal>, use
+	  <tag>username</tag>.</para>
+
+	<example>
+	  <title><tag>username</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>To carry out most system administration functions you
+  will need to be <username>root</username>.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>To carry out most system administration functions you will
+	    need to be <systemitem class="username">root</systemitem>.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Describing <filename>Makefile</filename>s</title>
+
+	<note>
+	  <title>FreeBSD extension</title>
+
+	  <para>These elements are part of the FreeBSD extension to DocBook,
+	    and do not exist in the original DocBook DTD.</para>
+	</note>
+
+	<para>Two elements exist to describe parts of
+	  <filename>Makefile</filename>s, <tag>maketarget</tag> and
+	  <tag>makevar</tag>.</para>
+
+	<para><tag>maketarget</tag> identifies a build target exported
+	  by a <filename>Makefile</filename> that can be given as a parameter
+	  to <command>make</command>.  <tag>makevar</tag> identifies a
+	  variable that can be set (in the environment, on the
+	  <command>make</command> command line, or within the
+	  <filename>Makefile</filename>) to influence the process.</para>
+
+	<example>
+	  <title><tag>maketarget</tag> and
+	    <tag>makevar</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>Two common targets in a <filename>Makefile</filename>
+  are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>
+
+<para>Typically, invoking <maketarget>all</maketarget> will rebuild the
+  application, and invoking <maketarget>clean</maketarget> will remove
+  the temporary files (<filename>.o</filename> for example) created by
+  the build process.</para>
+
+<para><maketarget>clean</maketarget> may be controlled by a number of
+  variables, including <makevar>CLOBBER</makevar> and
+  <makevar>RECURSE</makevar>.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>Two common targets in a <filename>Makefile</filename> are
+	    <buildtarget>all</buildtarget> and
+	    <buildtarget>clean</buildtarget>.</para>
+
+	  <para>Typically, invoking <buildtarget>all</buildtarget> will rebuild
+	    the application, and invoking <buildtarget>clean</buildtarget> will
+	    remove the temporary files (<filename>.o</filename> for example)
+	    created by the build process.</para>
+
+	  <para><buildtarget>clean</buildtarget> may be controlled by a number
+	    of variables, including <varname>CLOBBER</varname> and
+	    <varname>RECURSE</varname>.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Literal text</title>
+
+	<para>You will often need to include <quote>literal</quote> text in the
+	  Handbook.  This is text that is excerpted from another file, or
+	  which should be copied from the Handbook into another file
+	  verbatim.</para>
+
+	<para>Some of the time, <tag>programlisting</tag> will be
+	  sufficient to denote this text.  <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>On these occasions, use <tag>literal</tag>.</para>
+
+	<example>
+	  <title><tag>literal</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>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>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>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>
+      </sect3>
+
+      <sect3>
+	<title>Showing items that the user <emphasis>must</emphasis> fill
+	  in</title>
+
+	<para>There will often be times when you want to show the user what to
+	  do, or refer to a file, or command line, or similar, where the user
+	  cannot simply copy the examples that you provide, but must instead
+	  include some information themselves.</para>
+
+	<para><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><tag>replaceable</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<informalexample>
+  <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
+</informalexample>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <informalexample>
+	    <screen>&prompt.user; <userinput>man command</userinput></screen>
+	  </informalexample>
+
+	  <para><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>Use:</para>
+
+	  <programlisting><![CDATA[<para>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>For a desktop workstation, <literal>32</literal> is a good value
+  for <replaceable>n</replaceable>.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>The <literal>maxusers n</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>For a desktop workstation, <literal>32</literal> is a good
+	    value for <replaceable>n</replaceable>.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+        <title>Quoting system errors</title>
+
+        <para>You might want to show errors generated by FreeBSD.
+          Mark these with <tag>errorname</tag>.  This
+          indicates the exact error that appears.</para>
+
+        <example>
+          <title><tag>errorname</tag></title>
+
+          <para>Use:</para>
+
+	  <programlisting><![CDATA[
+<screen><errorname>Panic: cannot mount root</errorname></screen> ]]>
+</programlisting>
+
+
+          <para>Appearance:</para>
+
+          <informalexample>
+            <screen><errorname>Panic: cannot mount root</errorname></screen>
+          </informalexample>
+        </example>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Images</title>
+
+      <important>
+	<para>Image support in the documentation is currently extremely
+	  experimental.  I think the mechanisms described here are unlikely to
+	  change, but that is not guaranteed.</para>
+
+	<para>You will also need to install the
+	  <package>graphics/ImageMagick</package> port, which is used to
+	  convert between the different image formats.  This is a big port,
+	  and most of it is not required.  However, while we are working on the
+	  <filename>Makefile</filename>s and other infrastructure it makes
+	  things easier.  This port is <emphasis>not</emphasis> in the
+	  <package>textproc/docproj</package> meta port, you must install it
+	  by hand.</para>
+
+	<para>The best example of what follows in practice is the
+	  <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> document.
+	  If you are unsure of the description that follows, take a look at the
+	  files in that directory to see how everything hangs together.
+	  Experiment with creating different formatted versions of the
+	  document to see how the image markup appears in the formatted
+	  output.</para>
+      </important>
+
+      <sect3>
+	<title>Image formats</title>
+
+	<para>We currently support two formats for images.  The format you
+	  should use will depend on the nature of your image.</para>
+
+	<para>For images that are primarily vector based, such as network
+	  diagrams, time lines, and similar, use Encapsulated Postscript, and
+	  make sure that your images have the <filename>.eps</filename>
+	  extension.</para>
+
+	<para>For bitmaps, such as screen captures, use the Portable Network
+	  Graphic format, and make sure that your images have the
+	  <filename>.png</filename> extension.</para>
+
+	<para>These are the <emphasis>only</emphasis> formats in which images
+	  should be committed to the CVS repository.</para>
+
+	<para>Use the right format for the right image.  It is to be expected
+	  that your documentation will have a mix of EPS and PNG images.  The
+	  <filename>Makefile</filename>s ensure that the correct format image
+	  is chosen depending on the output format that you use for your
+	  documentation.  <emphasis>Do not commit the same image to the
+	    repository in two different formats</emphasis>.</para>
+
+	<important>
+	  <para>It is anticipated that the Documentation Project will switch to
+	    using the Scalable Vector Graphic (SVG) format for vector images.
+	    However, the current state of SVG capable editing tools makes this
+	    impractical.</para>
+	</important>
+      </sect3>
+
+      <sect3>
+	<title>Markup</title>
+
+	<para>The markup for an image is relatively simple.  First, markup 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>You should include one <tag>imageobject</tag>, and two
+	  <tag>textobject</tag> elements.  The
+	  <tag>imageobject</tag> will point to the name of the image
+	  file that will be used (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.</para>
+
+	<para>There are two circumstances where this can happen.</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>When the reader is viewing the documentation in HTML.  In
+	      this case, each image will need to have associated alternate
+	      text to show the user, typically whilst the image is loading, or
+	      if they hover the mouse pointer over the image.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>When the reader is viewing the documentation in plain text.
+	      In this case, each image should have an ASCII art equivalent to
+	      show the user.</para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>An example will probably make things easier to understand.
+	  Suppose you have an image, called <filename>fig1.png</filename>, that
+	  you want to include in the document.  This image is of a rectangle
+	  with an A inside it.  The markup for this would be as
+	  follows.</para>
+
+	<programlisting>&lt;mediaobject&gt;
+  &lt;imageobject&gt;
+    &lt;imagedata fileref="fig1"&gt; <co xml:id="co-image-ext"/>
+  &lt;/imageobject&gt;
+
+  &lt;textobject&gt;
+    &lt;literallayout class="monospaced"&gt;+---------------+ <co xml:id="co-image-literal"/>
+|       A       |
++---------------+&lt;/literallayout&gt;
+  &lt;/textobject&gt;
+
+  &lt;textobject&gt;
+    &lt;phrase&gt;A picture&lt;/phrase&gt; <co xml:id="co-image-phrase"/>
+  &lt;/textobject&gt;
+&lt;/mediaobject&gt;</programlisting>
+
+	<calloutlist>
+	  <callout arearefs="co-image-ext">
+	    <para>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>The first <tag>textobject</tag> should contain a
+	      <tag>literallayout</tag> element, where the
+	      <literal>class</literal> attribute is set to
+	      <literal>monospaced</literal>.  This is your opportunity to
+	      demonstrate your ASCII art skills.  This content will be used if
+	      the document is converted to plain text.</para>
+
+	    <para>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>The second <tag>textobject</tag> should contain a
+	      single <tag>phrase</tag> element.  The contents of this
+	      will become the <literal>alt</literal> attribute for the image
+	      when this document is converted to HTML.</para>
+	  </callout>
+	</calloutlist>
+      </sect3>
+
+      <sect3>
+	<title><filename>Makefile</filename> entries</title>
+
+	<para>Your images must be listed in the
+	  <filename>Makefile</filename> in the <varname>IMAGES</varname>
+	  variable.  This variable should contain the name of all your
+	  <emphasis>source</emphasis> images.  For example, if you have
+	  created three figures, <filename>fig1.eps</filename>,
+	  <filename>fig2.png</filename>, <filename>fig3.png</filename>, then
+	  your <filename>Makefile</filename> should have lines like this in
+	  it.</para>
+
+	<programlisting>&hellip;
+IMAGES= fig1.eps fig2.png fig3.png
+&hellip;</programlisting>
+
+	<para>or</para>
+
+	<programlisting>&hellip;
+IMAGES=  fig1.eps
+IMAGES+= fig2.png
+IMAGES+= fig3.png
+&hellip;</programlisting>
+
+	<para>Again, the <filename>Makefile</filename> will work out the
+	  complete list of images it needs to build your source document, you
+	  only need to list the image files <emphasis>you</emphasis>
+	  provided.</para>
+      </sect3>
+
+      <sect3>
+	<title>Images and chapters in subdirectories</title>
+
+	<para>You must be careful when you separate your documentation into
+	  smaller files (see <xref linkend="sgml-primer-include-using-gen-entities"/>) in
+	  different directories.</para>
+
+	<para>Suppose you have 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, I suggest you place those images in each
+	  chapter's subdirectory (<filename>chapter1/</filename>,
+	  <filename>chapter2/</filename>, and
+	  <filename>chapter3/</filename>).</para>
+
+	<para>However, if you do this you must include the directory names in
+	  the <varname>IMAGES</varname> variable in the
+	  <filename>Makefile</filename>, <emphasis>and</emphasis> you must
+	  include the directory name in the <tag>imagedata</tag>
+	  element in your document.</para>
+
+	<para>For example, if you have <filename>chapter1/fig1.png</filename>,
+	  then <filename>chapter1/chapter.xml</filename> should
+	  contain:</para>
+
+	<programlisting>&lt;mediaobject&gt;
+  &lt;imageobject&gt;
+    &lt;imagedata fileref="chapter1/fig1"&gt; <co xml:id="co-image-dir"/>
+  &lt;/imageobject&gt;
+
+  &hellip;
+
+&lt;/mediaobject&gt;</programlisting>
+
+	<calloutlist>
+	  <callout arearefs="co-image-dir">
+	    <para>The directory name must be included in the
+	      <literal>fileref</literal> attribute.</para>
+	  </callout>
+	</calloutlist>
+
+	<para>The <filename>Makefile</filename> must contain:</para>
+
+	<programlisting>&hellip;
+IMAGES=  chapter1/fig1.png
+&hellip;</programlisting>
+
+	<para>Then everything should just work.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Links</title>
+
+      <note>
+	<para>Links are also in-line elements.</para>
+      </note>
+
+      <sect3>
+	<title>Linking to other parts of the same document</title>
+
+	<para>Linking within the same document requires you to specify
+	  where you are linking from (i.e., the text the user will click, or
+	  otherwise indicate, as the source of the link) and where you are
+	  linking to (the link's destination).</para>
+
+	<para>Each element within DocBook has an attribute called
+	  <literal>id</literal>.  You can place text in this attribute to
+	  uniquely name the element it is attached to.</para>
+
+	  <para>This value will be used when you specify the link
+	  source.</para>
+
+	<para>Normally, you will only be linking to chapters or sections, so
+	  you would add the <literal>id</literal> attribute to these
+	  elements.</para>
+
+	<example>
+	  <title><literal>id on chapters and sections</literal></title>
+
+	  <programlisting><![CDATA[<chapter id="chapter1">
+  <title>Introduction</title>
+
+  <para>This is the introduction.  It contains a subsection,
+    which is identified as well.</para>
+
+  <sect1 id="chapter1-sect1">
+    <title>Sub-sect 1</title>
+
+    <para>This is the subsection.</para>
+  </sect1>
+</chapter>]]></programlisting>
+	</example>
+
+	<para>Obviously, you should use more descriptive values.  The values
+	  must be unique within the document (i.e., not just the file, but the
+	  document the file might be included in as well).  Notice how the
+	  <literal>id</literal> for the subsection is constructed by appending
+	  text to the <literal>id</literal> of the chapter.  This helps to
+	  ensure that they are unique.</para>
+
+	<para>If you want to allow the user to jump into a specific portion of
+	  the document (possibly in the middle of a paragraph or an example),
+	  use <tag>anchor</tag>.  This element has no content, but
+	  takes an <literal>id</literal> attribute.</para>
+
+	<example>
+	  <title><tag>anchor</tag></title>
+
+	  <programlisting><![CDATA[<para>This paragraph has an embedded
+  <anchor id="para1">link target in it.  It will not show up in
+  the document.</para>]]></programlisting>
+	</example>
+
+	<para>When you want to provide the user with a link they can activate
+	  (probably by clicking) to go to a section of the document that has
+	  an <literal>id</literal> attribute, you can use either
+	  <tag>xref</tag> or <tag>link</tag>.</para>
+
+	<para>Both of these elements have a <literal>linkend</literal>
+	  attribute.  The value of this attribute should be the value that you
+	  have used in a <literal>id</literal> attribute (it does not matter
+	  if that value has not yet occurred in your document; this will work
+	  for forward links as well as backward links).</para>
+
+	<para>If you use <tag>xref</tag> then you have no control over
+	  the text of the link.  It will be generated for you.</para>
+
+	<example>
+	  <title>Using <tag>xref</tag></title>
+
+	  <para>Assume that this fragment appears somewhere in a document that
+	    includes the <literal>id</literal> example:</para>
+
+	  <programlisting><![CDATA[<para>More information can be found
+  in <xref linkend="chapter1">.</para>
+
+<para>More specific information can be found
+  in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
+
+	  <para>The text of the link will be generated automatically, and will
+	    look like (<emphasis>emphasized</emphasis> text indicates the text
+	    that will be the link):</para>
+
+	  <blockquote>
+	    <para>More information can be found in <emphasis>Chapter
+		One</emphasis>.</para>
+
+	    <para>More specific information can be found in <emphasis>the
+		section called Sub-sect 1</emphasis>.</para>
+	  </blockquote>
+	</example>
+
+	<para>Notice how the text from the link is derived from the section
+	  title or the chapter number.</para>
+
+	<note>
+	  <para>This means that you <emphasis>cannot</emphasis> use
+	    <tag>xref</tag> to link to an <literal>id</literal>
+	    attribute on an <tag>anchor</tag> element.  The
+	    <tag>anchor</tag> has no content, so the
+	    <tag>xref</tag> cannot generate the text for the
+	    link.</para>
+	</note>
+
+	<para>If you want to control the text of the link then use
+	  <tag>link</tag>.  This element wraps content, and the
+	  content will be used for the link.</para>
+
+	<example>
+	  <title>Using <tag>link</tag></title>
+
+	  <para>Assume that this fragment appears somewhere in a document that
+	    includes the <literal>id</literal> example.</para>
+
+	  <programlisting><![CDATA[<para>More information can be found in
+  <link linkend="chapter1">the first chapter</link>.</para>
+
+<para>More specific information can be found in
+  <link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting>
+
+	  <para>This will generate the following
+	    (<emphasis>emphasized</emphasis> text indicates the text that will
+	    be the link):</para>
+
+	  <blockquote>
+	    <para>More information can be found in <emphasis>the first
+		chapter</emphasis>.</para>
+
+	    <para>More specific information can be found in
+	      <emphasis>this</emphasis> section.</para>
+	  </blockquote>
+	</example>
+
+	<note>
+	  <para>That last one is a bad example.  Never use words like
+	    <quote>this</quote> or <quote>here</quote> as the source for the
+	    link.  The reader will need to hunt around the surrounding context
+	    to see where the link is actually taking them.</para>
+	</note>
+
+	<note>
+	  <para>You <emphasis>can</emphasis> use <tag>link</tag> to
+	    include a link to an <literal>id</literal> on an
+	    <tag>anchor</tag> element, since the
+	    <tag>link</tag> content defines the text that will be used
+	    for the link.</para>
+	</note>
+      </sect3>
+
+      <sect3>
+	<title>Linking to documents on the WWW</title>
+
+	<para>Linking to external documents is much simpler, as long as you
+	  know the URL of the document you want to link to.  Use
+	  <tag>ulink</tag>.  The <literal>url</literal> attribute is
+	  the URL of the page that the link points to, and the content of the
+	  element is the text that will be displayed for the user to
+	  activate.</para>
+
+	<example>
+	  <title><tag>ulink</tag></title>
+
+	  <para>Use:</para>
+
+	  <programlisting><![CDATA[<para>Of course, you could stop reading this document and
+  go to the <ulink url="&url.base;/index.html">FreeBSD
+  home page</ulink> instead.</para>]]></programlisting>
+
+	  <para>Appearance:</para>
+
+	  <para>Of course, you could stop reading this document and go to the
+	    <link xlink:href="&url.base;/index.html">FreeBSD home page</link>
+	    instead.</para>
+	</example>
+      </sect3>
+    </sect2>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml
new file mode 100644
index 0000000000..eb17a7cd91
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml
@@ -0,0 +1,1543 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.45
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sgml-primer">
+  <title>SGML Primer</title>
+
+  <para>FDP 文件幾乎都是以 SGML 相關程式寫的。本章會介紹 SGML 是什麼、
+    如何閱讀、理解這些 SGML 原稿，以及本文件中所運用的各項 SGML 技巧。</para>
+
+  <para>本節部分靈感啟發來自 Mark Galassi 的這篇 <link xlink:href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</link>。</para>
+
+  <sect1 xml:id="sgml-primer-overview">
+    <title>簡介</title>
+
+    <para>Way back when, electronic text was simple to deal with.  Admittedly,
+      you had to know which character set your document was written in (ASCII,
+      EBCDIC, or one of a number of others) 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>Inevitably, this was not enough.  Once you have text in a
+      machine-usable format, you expect machines to be able to use it and
+      manipulate it intelligently.  You would like to indicate that certain
+      phrases should be emphasized, or added to a glossary, or be hyperlinks.
+      You might want filenames to 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>It was once hoped that Artificial Intelligence (AI) would make this
+      easy.  Your computer would read in 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 our computers require some assistance before they can
+      meaningfully process our text.</para>
+
+    <para>More precisely, they need help identifying what is what.  You or I
+      can look at
+
+      <blockquote>
+	<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
+
+	<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
+      </blockquote>
+
+      and easily 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><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>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&mdash;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> (i.e., the effort required) to create the
+      document.</para>
+
+    <para>The previous example is actually represented in this document like
+      this:</para>
+
+    <programlisting><![CDATA[
+<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
+
+<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>
+
+    <para>As you can see, the markup is clearly separate from the
+      content.</para>
+
+    <para>Obviously, if you are going to use markup you need to define what
+      your markup means, and how it should be interpreted.  You will need a
+      markup language that you can follow when marking up your
+      documents.</para>
+
+   <para>Of course, one markup language might not be enough.  A markup
+      language for technical documentation has very different requirements
+      than a markup language that was to be used for cookery recipes.  This,
+      in turn, would be very different from a markup language used to describe
+      poetry.  What you really need is a first language that you use to write
+      these other markup languages.  A <emphasis>meta markup
+      language</emphasis>.</para>
+
+    <para>This is exactly what the Standard Generalized Markup Language (SGML)
+      is.  Many markup languages have been written in SGML, including the two
+      most used by the FDP, HTML and DocBook.</para>
+
+    <para>Each language definition is more properly called a Document Type
+      Definition (DTD).  The DTD specifies the name of the elements that can
+      be used, what order they appear in (and whether some markup can be used
+      inside other markup) and related information.  A DTD is sometimes
+      referred to as an <emphasis>application</emphasis> of SGML.</para>
+
+    <para xml:id="sgml-primer-validating">A DTD 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 SGML
+      <emphasis>parser</emphasis> which reads in both the DTD and a document
+      which claims to conform to the DTD.  The parser can then confirm whether
+      or not all the elements required by the DTD 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>This processing simply confirms that the choice of elements, their
+	ordering, and so on, conforms to that listed in the DTD.  It does
+	<emphasis>not</emphasis> check that you have used
+	<emphasis>appropriate</emphasis> markup for the content.  If you
+	tried to mark up all the filenames in your document as function
+	names, the parser would not flag this as an error (assuming, of
+	course, that your DTD defines elements for filenames and functions,
+	and that they are allowed to appear in the same place).</para>
+    </note>
+
+    <para>It is likely that most of your contributions to the Documentation
+      Project will consist of content marked up in either HTML or DocBook,
+      rather than alterations to the DTDs.  For this reason this book will
+      not touch on how to write a DTD.</para>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-elements">
+    <title>Elements, tags, and attributes</title>
+
+    <para>All the DTDs written in SGML share certain characteristics.  This is
+      hardly surprising, as the philosophy behind SGML 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>Your 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>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>You might like to think of this as <quote>chunking</quote> content.
+      At the very top level you have one chunk, the book.  Look a little
+      deeper, and you have more chunks, the individual chapters.  These are
+      chunked further into paragraphs, footnotes, character names, and so
+      on.</para>
+
+    <para>Notice how you can make this differentiation between different
+      elements of the content without resorting to any SGML terms.  It really
+      is surprisingly straightforward.  You could do this with a highlighter
+      pen and a printout of the book, using different colors to indicate
+      different chunks of content.</para>
+
+    <para>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 SGML (HTML, DocBook, et al) this is done by
+      means of <emphasis>tags</emphasis>.</para>
+
+    <para>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 DTD 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>For an element called <replaceable>element-name</replaceable> the
+      start tag will normally look like
+      <literal>&lt;element-name&gt;</literal>.  The
+      corresponding closing tag for this element is
+      <literal>&lt;/element-name&gt;</literal>.</para>
+
+    <example>
+      <title>Using an element (start and end tags)</title>
+
+      <para>HTML has an element for indicating that the content enclosed by
+	the element is a paragraph, called <literal>p</literal>.  This
+	element has both start and end tags.</para>
+
+      <programlisting><![CDATA[<p>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.</p>
+
+<p>This is another paragraph.  But this one is much shorter.</p>]]></programlisting>
+    </example>
+
+    <para>Not all elements require an end tag.  Some elements have no content.
+      For example, in HTML you can indicate that you want a horizontal line to
+      appear in the document.  Obviously, this line has no content, so just
+      the start tag is required for this element.</para>
+
+    <example>
+      <title>Using an element (start tag only)</title>
+
+      <para>HTML has an element for indicating a horizontal rule, called
+	<literal>hr</literal>.  This element does not wrap content, so only
+	has a start tag.</para>
+
+      <programlisting><![CDATA[<p>This is a paragraph.</p>
+
+<hr>
+
+<p>This is another paragraph.  A horizontal rule separates this
+  from the previous paragraph.</p>]]></programlisting>
+    </example>
+
+    <para>If it is not obvious by now, 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>Elements within elements; <tag>em</tag></title>
+
+      <programlisting><![CDATA[<p>This is a simple <em>paragraph</em> where some
+  of the <em>words</em> have been <em>emphasized</em>.</p>]]></programlisting>
+    </example>
+
+    <para>The DTD will specify the rules detailing which elements can contain
+      other elements, and exactly what they can contain.</para>
+
+    <important>
+      <para>People often confuse the terms tags and elements, and use the
+	terms as if they were interchangeable.  They are not.</para>
+
+      <para>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
+	end.</para>
+
+      <para>When this document (or anyone else knowledgeable about SGML) refers
+	to <quote>the &lt;p&gt; tag</quote> they mean the literal text
+	consisting of the three characters <literal>&lt;</literal>,
+	<literal>p</literal>, and <literal>&gt;</literal>.  But the phrase
+	<quote>the &lt;p&gt; element</quote> refers to the whole
+	element.</para>
+
+      <para>This distinction <emphasis>is</emphasis> very subtle.  But keep it
+	in mind.</para>
+    </important>
+
+    <para>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>An element's attributes are written <emphasis>inside</emphasis> the
+      start tag for that element, and take the form
+      <literal>attribute-name="attribute-value"</literal>.</para>
+
+    <para>In sufficiently recent versions of HTML, the <tag>p</tag>
+      element has an attribute called <literal>align</literal>, which suggests
+      an alignment (justification) for the paragraph to the program displaying
+      the HTML.</para>
+
+    <para>The <literal>align</literal> 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>Using an element with an attribute</title>
+
+      <programlisting><![CDATA[<p align="left">The inclusion of the align attribute
+  on this paragraph was superfluous, since the default is left.</p>
+
+<p align="center">This may appear in the center.</p>]]></programlisting>
+    </example>
+
+    <para>Some attributes will only take specific values, such as
+      <literal>left</literal> or <literal>justify</literal>.  Others will
+      allow you to enter anything you want.  If you need to include quotes
+      (<literal>"</literal>) within an attribute then use single quotes around
+      the attribute value.</para>
+
+    <example>
+      <title>Single quotes around attributes</title>
+
+      <programlisting><![CDATA[<p align='right'>I am on the right!</p>]]></programlisting>
+    </example>
+
+    <para>Sometimes you do not need to use quotes around attribute values at
+      all.  However, the rules for doing this are subtle, and it is far
+      simpler just to <emphasis>always</emphasis> quote your attribute
+      values.</para>
+
+    <para>The information on attributes, elements, and tags is stored
+      in SGML catalogs.  The various Documentation Project tools use
+      these catalog files to validate your work.  The tools in
+      <package>textproc/docproj</package> include a variety of SGML catalog
+      files.  The FreeBSD Documentation Project includes its own set
+      of catalog files.  Your tools need to know about both sorts of
+      catalog files.</para>
+
+    <sect2>
+      <title>For you to do&hellip;</title>
+
+      <para>In order to run the examples in this document you will need to
+        install some software on your system and ensure that an environment
+        variable is set correctly.</para>
+
+      <procedure>
+	<step>
+	  <para>Download and install <package>textproc/docproj</package>
+	    from the FreeBSD ports system.  This is a
+            <emphasis>meta-port</emphasis> that should download and install
+            all of the programs and supporting files that are used by the
+            Documentation Project.</para>
+	</step>
+
+        <step>
+          <para>Add lines to your shell startup files to set
+            <envar>SGML_CATALOG_FILES</envar>. (If you are not working
+            on the English version of the documentation, you will want
+            to substitute the correct directory for your
+            language.)</para>
+
+	  <example xml:id="sgml-primer-envars">
+	    <title><filename>.profile</filename>, for &man.sh.1; and
+	      &man.bash.1; users</title>
+
+	    <programlisting>SGML_ROOT=/usr/local/share/xml
+SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
+SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
+SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
+SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
+SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
+SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES
+export SGML_CATALOG_FILES</programlisting>
+	  </example>
+
+	  <example>
+	    <title><filename>.cshrc</filename>, for &man.csh.1; and
+	      &man.tcsh.1; users</title>
+
+	    <programlisting>setenv SGML_ROOT /usr/local/share/xml
+setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
+setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
+setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
+setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
+setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
+setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES</programlisting>
+          </example>
+
+          <para>Then either log out, and log back in again, or run those
+            commands from the command line to set the variable values.</para>
+	</step>
+      </procedure>
+
+      <procedure>
+	<step>
+	  <para>Create <filename>example.xml</filename>, and enter the
+            following text:</para>
+
+	  <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<html>
+  <head>
+    <title>An example HTML file</title>
+  </head>
+
+  <body>
+    <p>This is a paragraph containing some text.</p>
+
+    <p>This paragraph contains some more text.</p>
+
+    <p align="right">This paragraph might be right-justified.</p>
+  </body>
+</html>]]></programlisting>
+	</step>
+
+	<step>
+	  <para>Try to validate this file using an SGML parser.</para>
+
+	  <para>Part of <package>textproc/docproj</package> is the
+	    <command>nsgmls</command> <link linkend="sgml-primer-validating">validating
+	    parser</link>.  Normally, <command>nsgmls</command> reads in a document
+	    marked up according to an SGML DTD and returns a copy of the
+	    document's Element Structure Information Set (ESIS, but that is
+	    not important right now).</para>
+
+	  <para>However, when <command>nsgmls</command> is given the <option>-s</option>
+	    parameter, <command>nsgmls</command> will suppress its normal output, and
+	    just print error messages.  This makes it a useful way to check to
+	    see if your document is valid or not.</para>
+
+	  <para>Use <command>nsgmls</command> to check that your document is
+	    valid:</para>
+
+          <screen>&prompt.user; <userinput>nsgmls -s example.xml</userinput></screen>
+
+	  <para>As you will see, <command>nsgmls</command> returns without displaying any
+	    output.  This means that your document validated
+	    successfully.</para>
+	</step>
+
+	<step>
+	  <para>See what happens when required elements are omitted.  Try
+	    removing the <tag>title</tag> and
+	    <tag>/title</tag> tags, and re-run the validation.</para>
+
+          <screen>&prompt.user; <userinput>nsgmls -s example.xml</userinput>
+nsgmls:example.xml:5:4:E: character data is not allowed here
+nsgmls:example.xml:6:8:E: end tag for "HEAD" which is not finished</screen>
+
+	  <para>The error output from <command>nsgmls</command> is organized into
+	    colon-separated groups, or columns.</para>
+
+	  <informaltable frame="none" pgwide="1">
+	    <tgroup cols="2">
+	      <thead>
+		<row>
+		  <entry>Column</entry>
+		  <entry>Meaning</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry>1</entry>
+		  <entry>The name of the program generating the error.  This
+		    will always be <literal>nsgmls</literal>.</entry>
+		</row>
+
+		<row>
+		  <entry>2</entry>
+		  <entry>The name of the file that contains the error.</entry>
+		</row>
+
+		<row>
+		  <entry>3</entry>
+		  <entry>Line number where the error appears.</entry>
+		</row>
+
+		<row>
+		  <entry>4</entry>
+		  <entry>Column number where the error appears.</entry>
+		</row>
+
+		<row>
+		  <entry>5</entry>
+		  <entry>A one letter code indicating the nature of the
+		    message.  <literal>I</literal> indicates an informational
+		    message, <literal>W</literal> is for warnings, and
+		    <literal>E</literal> is for errors<footnote>
+		      <para>It is not always the fifth column either.
+			<command>nsgmls -sv</command> displays
+			<literal>nsgmls:I: SP version "1.3"</literal>
+			(depending on the installed version).  As you can see,
+			this is an informational message.</para>
+		    </footnote>, and <literal>X</literal> is for
+		    cross-references.  As you can see, these messages are
+		    errors.</entry>
+		</row>
+
+		<row>
+		  <entry>6</entry>
+		  <entry>The text of the error message.</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+
+	  <para>Simply omitting the <tag>title</tag> tags has
+	    generated 2 different errors.</para>
+
+	  <para>The first error indicates that content (in this case,
+	    characters, rather than the start tag for an element) has occurred
+	    where the SGML parser was expecting something else.  In this case,
+	    the parser was expecting to see one of the start tags for elements
+	    that are valid inside <tag>head</tag> (such as
+	    <tag>title</tag>).</para>
+
+	  <para>The second error is because <tag>head</tag> elements
+	    <emphasis>must</emphasis> contain a <tag>title</tag>
+	    element.  Because it does not <command>nsgmls</command> considers that the
+	    element has not been properly finished.  However, the closing tag
+	    indicates that the element has been closed before it has been
+	    finished.</para>
+	</step>
+
+	<step>
+	  <para>Put the <literal>title</literal> element back in.</para>
+	</step>
+      </procedure>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-doctype-declaration">
+    <title>The DOCTYPE declaration</title>
+
+    <para>The beginning of each document that you write must specify the name
+      of the DTD that the document conforms to.  This is so that SGML parsers
+      can determine the DTD and ensure that the document does conform to
+      it.</para>
+
+    <para>This information is generally expressed on one line, in the DOCTYPE
+      declaration.</para>
+
+    <para>A typical declaration for a document written to conform with version
+      4.0 of the HTML DTD looks like this:</para>
+
+    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>
+
+    <para>That line contains a number of different components.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term><literal>&lt;!</literal></term>
+
+	<listitem>
+	  <para>Is the <emphasis>indicator</emphasis> that indicates that this
+	    is an SGML declaration.  This line is declaring the document type.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><literal>DOCTYPE</literal></term>
+
+	<listitem>
+	  <para>Shows that this is an SGML declaration for the document
+	    type.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><literal>html</literal></term>
+
+	<listitem>
+	  <para>Names the first <link linkend="sgml-primer-elements">element</link> that
+	    will appear in the document.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term>
+
+	<listitem>
+	  <para>Lists the Formal Public Identifier (FPI)<indexterm>
+	      <primary>Formal Public Identifier</primary>
+	    </indexterm>
+	    for the DTD that this
+	    document conforms to.  Your SGML parser will use this to find the
+	    correct DTD when processing this document.</para>
+
+	  <para><literal>PUBLIC</literal> is not a part of the FPI, but
+	    indicates to the SGML processor how to find the DTD referenced in
+	    the FPI.  Other ways of telling the SGML parser how to find the
+	    DTD are shown <link linkend="sgml-primer-fpi-alternatives">later</link>.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><literal>&gt;</literal></term>
+
+	<listitem>
+	  <para>Returns to the document.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <sect2>
+      <title>Formal Public Identifiers (FPIs)<indexterm significance="preferred">
+	  <primary>Formal Public Identifier</primary>
+	</indexterm>
+</title>
+
+      <note>
+	<para>You do not need to know this, but it is useful background, and
+	  might help you debug problems when your SGML processor can not locate
+	  the DTD you are using.</para>
+      </note>
+
+      <para>FPIs must follow a specific syntax.  This syntax is as
+	follows:</para>
+
+      <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
+
+      <variablelist>
+	<varlistentry>
+	  <term><replaceable>Owner</replaceable></term>
+
+	  <listitem>
+	    <para>This indicates the owner of the FPI.</para>
+
+	    <para>If this string starts with <quote>ISO</quote> then this is an
+	      ISO owned FPI.  For example, the FPI <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.  ISO 8879:1986 is the ISO number
+	      for the SGML standard.</para>
+
+	    <para>Otherwise, this string will either look like
+	      <literal>-//Owner</literal> or
+	      <literal>+//Owner</literal> (notice
+	      the only difference is the leading <literal>+</literal> or
+	      <literal>-</literal>).</para>
+
+	    <para>If the string starts with <literal>-</literal> then the
+	      owner information is unregistered, with a <literal>+</literal>
+	      it identifies it as being registered.</para>
+
+	    <para>ISO 9070:1991 defines how registered names are generated; it
+	      might be derived from the number of an ISO publication, an ISBN
+	      code, or an organization code assigned according to ISO 6523.
+	      In addition, a registration authority could be created in order
+	      to assign registered names.  The ISO council delegated this to
+	      the American National Standards Institute (ANSI).</para>
+
+	    <para>Because the FreeBSD Project has not been registered the
+	      owner string is <literal>-//FreeBSD</literal>.  And as you can
+	      see, the W3C are not a registered owner either.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><replaceable>Keyword</replaceable></term>
+
+	  <listitem>
+	    <para>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 DTD files,
+	      <literal>ELEMENT</literal> is usually used for DTD fragments
+	      that contain only entity or element declarations.
+	      <literal>TEXT</literal> is used for SGML content (text and
+	      tags).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><replaceable>Description</replaceable></term>
+
+	  <listitem>
+	    <para>Any description you want to supply for the contents of this
+	      file.  This may include version numbers or any short text that
+	      is meaningful to you and unique for the SGML system.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><replaceable>Language</replaceable></term>
+
+	  <listitem>
+	    <para>This is an ISO two-character code that identifies the native
+	      language for the file.  <literal>EN</literal> is used for
+	      English.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <sect3>
+	<title><filename>catalog</filename> files</title>
+
+	<para>If you use the syntax above and process this document
+	  using an SGML processor, the processor will need to have some way of
+	  turning the FPI into the name of the file on your computer that
+	  contains the DTD.</para>
+
+	<para>In order to do this it can use a catalog file.  A catalog file
+	  (typically called <filename>catalog</filename>) contains lines that
+	  map FPIs to filenames.  For example, if the catalog file contained
+	  the line:</para>
+
+	<programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"</programlisting>
+
+	<para>The SGML processor would know to look up the DTD from
+	  <filename>strict.dtd</filename> in the <filename>4.0</filename>
+	  subdirectory of whichever directory held the
+	  <filename>catalog</filename> file that contained that line.</para>
+
+	<para>Look at the contents of
+	  <filename>/usr/local/share/xml/html/catalog</filename>.  This is
+	  the catalog file for the HTML DTDs that will have been installed as
+	  part of the <package>textproc/docproj</package> port.</para>
+      </sect3>
+
+      <sect3>
+	<title><envar>SGML_CATALOG_FILES</envar></title>
+
+	<para>In order to locate a <filename>catalog</filename> file, your
+	  SGML processor will need to know where to look.  Many of them
+	  feature command line parameters for specifying the path to one or
+	  more catalogs.</para>
+
+	<para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to
+	  point to the files.  This environment variable should consist of a
+	  colon-separated list of catalog files (including their full
+	  path).</para>
+
+	<para>Typically, you will want to include the following files:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para><filename>/usr/local/share/xml/docbook/4.1/catalog</filename></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><filename>/usr/local/share/xml/html/catalog</filename></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><filename>/usr/local/share/xml/iso8879/catalog</filename></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><filename>/usr/local/share/xml/jade/catalog</filename></para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>You should <link linkend="sgml-primer-envars">already have done
+	    this</link>.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 xml:id="sgml-primer-fpi-alternatives">
+      <title>Alternatives to FPIs</title>
+
+      <para>Instead of using an FPI to indicate the DTD that the document
+	conforms to (and therefore, which file on the system contains the DTD)
+	you can explicitly specify the name of the file.</para>
+
+      <para>The syntax for this is slightly different:</para>
+
+      <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>
+
+      <para>The <literal>SYSTEM</literal> keyword indicates that the SGML
+	processor should locate the DTD in a system specific fashion.  This
+	typically (but not always) means the DTD will be provided as a
+	filename.</para>
+
+      <para>Using FPIs is preferred for reasons of portability.  You do not
+	want to have to ship a copy of the DTD around with your document, and
+	if you used the <literal>SYSTEM</literal> identifier then everyone
+	would need to keep their DTDs in the same place.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-sgml-escape">
+    <title>Escaping back to SGML</title>
+
+    <para>Earlier in this primer I said that SGML is only used when writing a
+      DTD.  This is not strictly true.  There is certain SGML syntax that you
+      will want to be able to use within your documents.  For example,
+      comments can be included in your document, and will be ignored by the
+      parser.  Comments are entered using SGML syntax.  Other uses for SGML
+      syntax in your document will be shown later too.</para>
+
+    <para>Obviously, you need some way of indicating to the SGML processor
+      that the following content is not elements within the document, but is
+      SGML that the parser should act upon.</para>
+
+    <para>These sections are marked by <literal>&lt;! ...  &gt;</literal> in
+      your document.  Everything between these delimiters is SGML syntax as
+      you might find within a DTD.</para>
+
+    <para>As you may just have realized, the <link linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
+      is an example of SGML syntax that you need to include in your
+      document&hellip;</para>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-comments">
+    <title>註解</title>
+
+    <para>Comments are an SGML construction, and are normally only valid
+      inside a DTD.  However, as <xref linkend="sgml-primer-sgml-escape"/>
+      shows, it is possible to use SGML syntax within your document.</para>
+
+    <para>The delimiter for SGML 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>SGML generic comment</title>
+
+      <programlisting>&lt;!-- 測試註解 --&gt;</programlisting>
+
+      <programlisting>
+&lt;!&hyphen;- 這是註解 -&hyphen;&gt;
+
+&lt;!&hyphen;- 這也是註解    -&hyphen;&gt;
+
+&lt;!&hyphen;- 要寫多行註解的話，
+     這是其中之一的方式 -&hyphen;&gt;
+
+&lt;!&hyphen;- 要寫多行註解，   -&hyphen;
+  &hyphen;- 也可以這樣子用 -&hyphen;&gt;</programlisting>
+    </example>
+
+    <para>If you have used HTML before you may have been shown different rules
+      for comments.  In particular, you may think that the string
+      <literal>&lt;!--</literal> opens a comment, and it is only closed by
+      <literal>--&gt;</literal>.</para>
+
+    <para>This is <emphasis>not</emphasis> the case.  A lot of web browsers
+      have broken HTML parsers, and will accept that as valid.  However, the
+      SGML parsers used by the Documentation Project are much stricter, and
+      will reject documents that make that error.</para>
+
+    <example>
+      <title>Erroneous SGML comments</title>
+
+      <programlisting>
+&lt;!&hyphen;- This is in the comment -&hyphen;
+
+     THIS IS OUTSIDE THE COMMENT!
+
+  &hyphen;- back inside the comment -&hyphen;&gt;</programlisting>
+
+      <para>The SGML parser will treat this as though it were actually:</para>
+
+      <programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
+
+      <para>This is not valid SGML, and may give confusing error
+	messages.</para>
+
+      <programlisting>&lt;!&hyphen;&hyphen;&hyphen;&hyphen;&hyphen; This is a very bad idea &hyphen;&hyphen;&hyphen;&hyphen;&hyphen;&gt;</programlisting>
+
+      <para>As the example suggests, <emphasis>do not</emphasis> write
+	comments like that.</para>
+
+      <programlisting>&lt;!&hyphen;-===================================================-&hyphen;&gt;</programlisting>
+
+      <para>That is a (slightly) better approach, but it still potentially
+	confusing to people new to SGML.</para>
+    </example>
+
+    <sect2>
+      <title>For you to do&hellip;</title>
+
+      <procedure>
+	<step>
+	  <para>Add some comments to <filename>example.xml</filename>, and
+	    check that the file still validates using <command>nsgmls</command>.</para>
+	</step>
+
+	<step>
+	  <para>Add some invalid comments to
+	    <filename>example.xml</filename>, and see the error messages that
+	    <command>nsgmls</command> gives when it encounters an invalid comment.</para>
+	</step>
+      </procedure>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-entities">
+    <title>Entities</title>
+
+    <para>Entities are a mechanism for assigning names to chunks of content.
+      As an SGML parser processes your document, any entities it finds are
+      replaced by the content of the entity.</para>
+
+    <para>This is a good way to have re-usable, easily changeable chunks of
+      content in your SGML documents.  It is also the only way to include one
+      marked up file inside another using SGML.</para>
+
+    <para>There are two types of entities which can be used in two different
+      situations; <emphasis>general entities</emphasis> and
+      <emphasis>parameter entities</emphasis>.</para>
+
+    <sect2 xml:id="sgml-primer-general-entities">
+      <title>General Entities</title>
+
+      <para>You cannot use general entities in an SGML context (although you
+	define them in one).  They can only be used in your document.
+	Contrast this with <link linkend="sgml-primer-parameter-entities">parameter
+	  entities</link>.</para>
+
+      <para>Each general entity has a name.  When you want to reference a
+	general entity (and therefore include whatever text it represents in
+	your document), you write
+	<literal>&amp;entity-name;</literal>.  For
+	example, suppose you had an entity called
+	<literal>current.version</literal> which expanded to the current
+	version number of your product.  You could write:</para>
+
+      <programlisting><![CDATA[<para>The current version of our product is
+  &current.version;.</para>]]></programlisting>
+
+      <para>When the version number changes you can simply change the
+	definition of the value of the general entity and reprocess your
+	document.</para>
+
+      <para>You can also use general entities to enter characters that you
+	could not otherwise include in an SGML document.  For example,
+	<literal>&lt;</literal> and <literal>&amp;</literal> cannot
+	normally appear in an SGML document.  When the SGML
+	parser sees the <literal>&lt;</literal>
+	symbol it assumes that a tag (either a start tag
+	or an end tag) is about to appear, and when it sees the
+	<literal>&amp;</literal> symbol
+	it assumes the next text will be the name of an entity.</para>
+
+      <para>Fortunately, you can use the two general entities
+	<literal>&amp;lt;</literal> and <literal>&amp;amp;</literal>
+	whenever you need to include one or other of these.</para>
+
+      <para>A general entity can only be defined within an SGML context.
+	Typically, this is done immediately after the DOCTYPE
+	declaration.</para>
+
+      <example>
+	<title>Defining general entities</title>
+
+	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+<!ENTITY current.version    "3.0-RELEASE">
+<!ENTITY last.version       "2.2.7-RELEASE">
+]>]]></programlisting>
+
+	<para>Notice how 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, before the square bracket is
+	  closed, and then the DOCTYPE declaration is closed.</para>
+
+	<para>The square brackets are necessary to indicate that we are
+	  extending the DTD indicated by the DOCTYPE declaration.</para>
+      </example>
+    </sect2>
+
+    <sect2 xml:id="sgml-primer-parameter-entities">
+      <title>Parameter entities</title>
+
+      <para>Like <link linkend="sgml-primer-general-entities">general
+	  entities</link>, parameter entities are used to assign names to
+	reusable chunks of text.  However, where as general entities can only
+	be used within your document, parameter entities can only be used
+	within an <link linkend="sgml-primer-sgml-escape">SGML
+	  context</link>.</para>
+
+      <para>Parameter entities are defined in a similar way to general
+	entities.  However, instead of using
+	<literal>&amp;entity-name;</literal> to
+	refer to them, use
+	<literal>%entity-name;</literal><footnote>
+	  <para><emphasis>P</emphasis>arameter entities use the
+	    <emphasis>P</emphasis>ercent symbol.</para>
+	</footnote>.  The definition also includes the <literal>%</literal>
+	between the <literal>ENTITY</literal> keyword and the name of the
+	entity.</para>
+
+      <example>
+	<title>Defining parameter entities</title>
+
+	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+<!ENTITY % param.some "some">
+<!ENTITY % param.text "text">
+<!ENTITY % param.new  "%param.some more %param.text">
+]>]]></programlisting>
+      </example>
+
+      <para>This may not seem particularly useful.  It will be.</para>
+    </sect2>
+
+    <sect2>
+      <title>For you to do&hellip;</title>
+
+      <procedure>
+	<step>
+	  <para>Add a general entity to
+	    <filename>example.xml</filename>.</para>
+
+	  <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
+<!ENTITY version "1.1">
+]>
+
+<html>
+  <head>
+    <title>An example HTML file</title>
+  </head>
+
+  <body>
+    <p>This is a paragraph containing some text.</p>
+
+    <p>This paragraph contains some more text.</p>
+
+    <p align="right">This paragraph might be right-justified.</p>
+
+    <p>The current version of this document is: &version;</p>
+  </body>
+</html>]]></programlisting>
+	</step>
+
+	<step>
+	  <para>Validate the document using <command>nsgmls</command>.</para>
+	</step>
+
+	<step>
+	  <para>Load <filename>example.xml</filename> into your web browser
+	    (you may need to copy it to <filename>example.html</filename>
+	    before your browser recognizes it as an HTML document).</para>
+
+	  <para>Unless your browser is very advanced, you will not see the entity
+	    reference <literal>&amp;version;</literal> replaced with the
+	    version number.  Most web browsers have very simplistic parsers
+	    which do not handle proper SGML<footnote>
+	      <para>This is a shame.  Imagine all the problems and hacks (such
+		as Server Side Includes) that could be avoided if they
+		did.</para>
+	    </footnote>.</para>
+	</step>
+
+	<step>
+	  <para>The solution is to <emphasis>normalize</emphasis> your
+	    document using an SGML normalizer.  The normalizer reads in valid
+	    SGML and outputs equally valid SGML which has been transformed in
+	    some way.  One of the ways in which the normalizer transforms the
+	    SGML is to expand all the entity references in the document,
+	    replacing the entities with the text that they represent.</para>
+
+	  <para>You can use <command>sgmlnorm</command> to do this.</para>
+
+          <screen>&prompt.user; <userinput>sgmlnorm example.xml &gt; example.html</userinput></screen>
+
+	  <para>You should find a normalized (i.e., entity references
+	    expanded) copy of your document in
+	    <filename>example.html</filename>, ready to load into your web
+	    browser.</para>
+	</step>
+
+	<step>
+	  <para>If you look at the output from <command>sgmlnorm</command>
+	    you will see that it does not include a DOCTYPE declaration at
+	    the start.  To include this you need to use the <option>-d</option>
+	    option:</para>
+
+          <screen>&prompt.user; <userinput>sgmlnorm -d example.xml &gt; example.html</userinput></screen>
+	</step>
+      </procedure>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-include">
+    <title>Using entities to include files</title>
+
+    <para>Entities (both <link linkend="sgml-primer-general-entities">general</link> and <link linkend="sgml-primer-parameter-entities">parameter</link>) are
+      particularly useful when used to include one file inside another.</para>
+
+    <sect2 xml:id="sgml-primer-include-using-gen-entities">
+      <title>Using general entities to include files</title>
+
+      <para>Suppose you have some content for an SGML 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> file that will contain these
+	chapters.</para>
+
+      <para>In order to use the contents of these files as the values for your
+	entities, you declare them with the <literal>SYSTEM</literal> keyword.
+	This directs the SGML parser to use the contents of the named file as
+	the value of the entity.</para>
+
+      <example>
+	<title>Using general entities to include files</title>
+
+	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+<!ENTITY chapter.1 SYSTEM "chapter1.xml">
+<!ENTITY chapter.2 SYSTEM "chapter2.xml">
+<!ENTITY chapter.3 SYSTEM "chapter3.xml">
+]>
+
+<html>
+
+  &chapter.1;
+  &chapter.2;
+  &chapter.3;
+</html>]]></programlisting>
+      </example>
+
+      <warning>
+	<para>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.</para>
+      </warning>
+    </sect2>
+
+    <sect2>
+      <title>Using parameter entities to include files</title>
+
+      <para>Recall that parameter entities can only be used inside an SGML
+	context.  Why then would you want to include a file within an SGML
+	context?</para>
+
+      <para>You can use this to ensure that you can reuse your general
+	entities.</para>
+
+      <para>Suppose that you had many chapters in your document, and you
+	reused these chapters in two different books, each book organizing the
+	chapters in a different fashion.</para>
+
+      <para>You could list the entities at the top of each book, but this
+	quickly becomes cumbersome to manage.</para>
+
+      <para>Instead, place the general entity definitions inside one file,
+	and use a parameter entity to include that file within your
+	document.</para>
+
+      <example>
+	<title>Using parameter entities to include files</title>
+
+	<para>First, place your entity definitions in a separate file, called
+	  <filename>chapters.ent</filename>.  This file contains the
+	  following:</para>
+
+	<programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml">
+<!ENTITY chapter.2 SYSTEM "chapter2.xml">
+<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting>
+
+	<para>Now 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><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+<!ENTITY % chapters SYSTEM "chapters.ent">
+%chapters;
+]>
+
+<html>
+  &chapter.1;
+  &chapter.2;
+  &chapter.3;
+</html>]]></programlisting>
+      </example>
+    </sect2>
+
+    <sect2>
+      <title>For you to do&hellip;</title>
+
+      <sect3>
+	<title>Use general entities to include files</title>
+
+	<procedure>
+	  <step>
+	    <para>Create three files, <filename>para1.xml</filename>,
+	      <filename>para2.xml</filename>, and
+	      <filename>para3.xml</filename>.</para>
+
+	    <para>Put content similar to the following in each file:</para>
+
+	    <programlisting><![CDATA[<p>This is the first paragraph.</p>]]></programlisting>
+	  </step>
+
+	  <step>
+	    <para>Edit <filename>example.xml</filename> so that it looks like
+	      this:</para>
+
+	    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+<!ENTITY version "1.1">
+<!ENTITY para1 SYSTEM "para1.xml">
+<!ENTITY para2 SYSTEM "para2.xml">
+<!ENTITY para3 SYSTEM "para3.xml">
+]>
+
+<html>
+  <head>
+    <title>An example HTML file</title>
+  </head>
+
+  <body>
+    <p>The current version of this document is: &version;</p>
+
+    &para1;
+    &para2;
+    &para3;
+  </body>
+</html>]]></programlisting>
+	  </step>
+
+	  <step>
+	    <para>Produce <filename>example.html</filename> by normalizing
+	      <filename>example.xml</filename>.</para>
+
+            <screen>&prompt.user; <userinput>sgmlnorm -d example.xml &gt; example.html</userinput></screen>
+	  </step>
+
+	  <step>
+	    <para>Load <filename>example.html</filename> into your web
+	      browser, and confirm that the
+	      <filename>paran.xml</filename> files
+	      have been included in <filename>example.html</filename>.</para>
+	  </step>
+	</procedure>
+      </sect3>
+
+      <sect3>
+	<title>Use parameter entities to include files</title>
+
+	<note>
+	  <para>You must have taken the previous steps first.</para>
+	</note>
+
+	<procedure>
+	  <step>
+	    <para>Edit <filename>example.xml</filename> so that it looks like
+	      this:</para>
+
+	    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+<!ENTITY % entities SYSTEM "entities.xml"> %entities;
+]>
+
+<html>
+  <head>
+    <title>An example HTML file</title>
+  </head>
+
+  <body>
+    <p>The current version of this document is: &version;</p>
+
+    &para1;
+    &para2;
+    &para3;
+  </body>
+</html>]]></programlisting>
+	  </step>
+
+	  <step>
+	    <para>Create a new file, <filename>entities.xml</filename>, with
+	      this content:</para>
+
+	    <programlisting><![CDATA[<!ENTITY version "1.1">
+<!ENTITY para1 SYSTEM "para1.xml">
+<!ENTITY para2 SYSTEM "para2.xml">
+<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting>
+	  </step>
+
+	  <step>
+	    <para>Produce <filename>example.html</filename> by normalizing
+	      <filename>example.xml</filename>.</para>
+
+            <screen>&prompt.user; <userinput>sgmlnorm -d example.xml &gt; example.html</userinput></screen>
+	  </step>
+
+	  <step>
+	    <para>Load <filename>example.html</filename> into your web
+	      browser, and confirm that the
+	      <filename>paran.xml</filename> files
+	      have been included in <filename>example.html</filename>.</para>
+	  </step>
+	</procedure>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-marked-sections">
+    <title>Marked sections</title>
+
+    <para>SGML provides a mechanism to indicate that particular pieces of the
+      document should be processed in a special way.  These are termed
+      <quote>marked sections</quote>.</para>
+
+    <example>
+      <title>Structure of a marked section</title>
+
+      <programlisting>&lt;![ <replaceable>KEYWORD</replaceable> [
+  Contents of marked section
+]]&gt;</programlisting>
+    </example>
+
+    <para>As you would expect, being an SGML construct, a marked section
+      starts with <literal>&lt;!</literal>.</para>
+
+    <para>The first square bracket begins to delimit the marked
+      section.</para>
+
+    <para><replaceable>KEYWORD</replaceable> describes how this marked
+      section should be processed by the parser.</para>
+
+    <para>The second square bracket indicates that the content of the marked
+      section starts here.</para>
+
+    <para>The marked section is finished by closing the two square brackets,
+      and then returning to the document context from the SGML context with
+      <literal>&gt;</literal>.</para>
+
+    <sect2>
+      <title>Marked section keywords</title>
+
+      <sect3>
+	<title><literal>CDATA</literal>, <literal>RCDATA</literal></title>
+
+	<para>These keywords denote the marked sections <emphasis>content
+	    model</emphasis>, and allow you to change it from the
+	  default.</para>
+
+	<para>When an SGML parser is processing a document it keeps track
+	  of what is called the <quote>content model</quote>.</para>
+
+	<para>Briefly, the content model describes what sort of content the
+	  parser is expecting to see, and what it will do with it when it
+	  finds it.</para>
+
+	<para>The two content models you will probably find most useful are
+	  <literal>CDATA</literal> and <literal>RCDATA</literal>.</para>
+
+	<para><literal>CDATA</literal> is for <quote>Character Data</quote>.
+	  If the parser is in this content model then it is expecting to see
+	  characters, and characters only.  In this model the
+	  <literal>&lt;</literal> and <literal>&amp;</literal>
+	  symbols lose their special status, and will be treated as ordinary
+	  characters.</para>
+
+	<para><literal>RCDATA</literal> is for <quote>Entity references and
+	  character data</quote> If the parser is in this content model then it
+	  is expecting to see characters <emphasis>and</emphasis> entities.
+	  <literal>&lt;</literal> loses its special status, but
+	  <literal>&amp;</literal> will still be treated as
+	  starting the beginning of a general entity.</para>
+
+	<para>This is particularly useful if you are including some verbatim
+	  text that contains lots of <literal>&lt;</literal> and
+	  <literal>&amp;</literal> characters.  While you
+	  could go through the text ensuring that every
+	  <literal>&lt;</literal> is converted to a
+	  <literal>&amp;lt;</literal> and every <literal>&amp;</literal>
+	  is converted to a <literal>&amp;amp;</literal>, it can be
+	  easier to mark the section as only containing CDATA.  When the SGML
+	  parser encounters this it will ignore the
+	  <literal>&lt;</literal> and <literal>&amp;</literal> symbols
+	  embedded in the content.</para>
+
+        <note>
+          <para>When you use <literal>CDATA</literal> or
+            <literal>RCDATA</literal> in examples of text marked up in SGML,
+            keep in mind that the content of <literal>CDATA</literal> is not
+            validated.  You have to check the included SGML text using other
+            means.  You could, for example, write the example in another
+            document, validate the example code, and then paste it to your
+            <literal>CDATA</literal> content.</para>
+        </note>
+	<!-- The nesting of CDATA within the next example is disgusting -->
+
+	<example>
+	  <title>Using a CDATA marked section</title>
+
+	  <programlisting>&lt;para&gt;Here is an example of how you would include some text
+  that contained many &lt;literal&gt;&amp;lt;&lt;/literal&gt;
+  and &lt;literal&gt;&amp;amp;&lt;/literal&gt; symbols.  The sample
+  text is a fragment of HTML.  The surrounding text (&lt;para&gt; and
+  &lt;programlisting&gt;) are from DocBook.&lt;/para&gt;
+
+&lt;programlisting&gt;
+  &lt;![CDATA[<![CDATA[
+    <p>This is a sample that shows you some of the elements within
+      HTML.  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.</p>
+
+    <ul>
+      <li>This is a listitem</li>
+      <li>This is a second listitem</li>
+      <li>This is a third listitem</li>
+    </ul>
+
+    <p>This is the end of the example.</p>]]>
+  ]]&gt;
+&lt;/programlisting&gt;</programlisting>
+
+	  <para>If you look at the source for this document you will see this
+	    technique used throughout.</para>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title><literal>INCLUDE</literal> and
+	  <literal>IGNORE</literal></title>
+
+	<para>If the keyword is <literal>INCLUDE</literal> then the contents
+	  of the marked section will be processed.  If the keyword is
+	  <literal>IGNORE</literal> then the marked section is ignored and
+	  will not be processed.  It will not appear in the output.</para>
+
+	<example>
+	  <title>Using <literal>INCLUDE</literal> and
+	    <literal>IGNORE</literal> in marked sections</title>
+
+	  <programlisting>&lt;![ INCLUDE [
+  This text will be processed and included.
+]]&gt;
+
+&lt;![ IGNORE [
+  This text will not be processed or included.
+]]&gt;</programlisting>
+	</example>
+
+	<para>By itself, this is not too useful.  If you wanted to remove text
+	  from your document you could cut it out, or wrap it in
+	  comments.</para>
+
+	<para>It becomes more useful when you realize you can use <link linkend="sgml-primer-parameter-entities">parameter entities</link>
+	  to control this.  Remember that parameter entities can only be used
+	  in SGML contexts, and the keyword of a marked section
+	  <emphasis>is</emphasis> an SGML context.</para>
+
+	<para>For example, suppose that you produced a hard-copy version of
+	  some documentation and an electronic version.  In the electronic
+	  version you wanted to include some extra content that was not to
+	  appear in the hard-copy.</para>
+
+	<para>Create a parameter entity, and set its value to
+	  <literal>INCLUDE</literal>.  Write your document, using marked
+	  sections to delimit content that should only appear in the
+	  electronic version.  In these marked sections use the parameter
+	  entity in place of the keyword.</para>
+
+	<para>When you want to produce the hard-copy version of the document,
+	  change the parameter entity's value to <literal>IGNORE</literal> and
+	  reprocess the document.</para>
+
+	<example>
+	  <title>Using a parameter entity to control a marked
+	    section</title>
+
+	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+&lt;!ENTITY % electronic.copy "INCLUDE"&gt;
+]]&gt;
+
+...
+
+&lt;![ %electronic.copy [
+  This content should only appear in the electronic
+  version of the document.
+]]&gt;</programlisting>
+
+	  <para>When producing the hard-copy version, change the entity's
+	    definition to:</para>
+
+	  <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"&gt;</programlisting>
+
+	  <para>On reprocessing the document, the marked sections that use
+	    <literal>%electronic.copy</literal> as their keyword will be
+	    ignored.</para>
+	</example>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>For you to do&hellip;</title>
+
+      <procedure>
+	<step>
+	  <para>Create a new file, <filename>section.xml</filename>, that
+	    contains the following:</para>
+
+	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+&lt;!ENTITY % text.output "INCLUDE"&gt;
+]&gt;
+
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;title&gt;An example using marked sections&lt;/title&gt;
+  &lt;/head&gt;
+
+  &lt;body&gt;
+    &lt;p&gt;This paragraph &lt;![CDATA[contains many &lt;
+      characters (&lt; &lt; &lt; &lt; &lt;) so it is easier
+      to wrap it in a CDATA marked section ]]&gt;&lt;/p&gt;
+
+    &lt;![IGNORE[
+    &lt;p&gt;This paragraph will definitely not be included in the
+      output.&lt;/p&gt;
+    ]]&gt;
+
+    &lt;![<![CDATA[%text.output]]> [
+    &lt;p&gt;This paragraph might appear in the output, or it
+      might not.&lt;/p&gt;
+
+    &lt;p&gt;Its appearance is controlled by the <![CDATA[%text.output]]>
+      parameter entity.&lt;/p&gt;
+    ]]&gt;
+  &lt;/body&gt;
+&lt;/html&gt;</programlisting>
+	</step>
+
+	<step>
+	  <para>Normalize this file using &man.xmlnorm.1; and examine the
+	    output.  Notice which paragraphs have appeared, which have
+	    disappeared, and what has happened to the content of the CDATA
+	    marked section.</para>
+	</step>
+
+	<step>
+	  <para>Change the definition of the <literal>text.output</literal>
+	    entity from <literal>INCLUDE</literal> to
+	    <literal>IGNORE</literal>.  Re-normalize the file, and examine the
+	    output to see what has changed.</para>
+	</step>
+      </procedure>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="sgml-primer-conclusion">
+    <title>Conclusion</title>
+
+    <para>That is the conclusion of this SGML primer.  For reasons of space
+      and complexity several things have not been covered in depth (or at
+      all).  However, the previous sections cover enough SGML for you to be
+      able to follow the organization of the FDP documentation.</para>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml
new file mode 100644
index 0000000000..c4feee84cb
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml
@@ -0,0 +1,281 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.17
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">
+  <title>Structuring documents under <filename>doc/</filename></title>
+
+  <para>The <filename>doc/</filename> tree is organized in a particular
+    fashion, and the documents that are part of the FDP are in turn organized
+    in a particular fashion.  The aim is to make it simple to add new
+    documentation into the tree and:</para>
+
+  <orderedlist>
+    <listitem>
+      <para>make it easy to automate converting the document to other formats;</para>
+    </listitem>
+
+    <listitem>
+      <para>promote consistency between the different documentation
+	organizations, to make it easier to switch between working on
+	different documents;</para>
+    </listitem>
+
+    <listitem>
+      <para>make it easy to decide where in the tree new documentation should
+	be placed.</para>
+    </listitem>
+  </orderedlist>
+
+  <para>In addition, the documentation tree has to accommodate documentation
+    that could be in many different languages and in many different
+    encodings.  It is important that the structure of the documentation tree
+    does not enforce any particular defaults or cultural preferences.</para>
+
+  <sect1 xml:id="structure-top">
+    <title>The top level, <filename>doc/</filename></title>
+
+    <para>There are two types of directory under <filename>doc/</filename>,
+      each with very specific directory names and meanings.</para>
+
+    <segmentedlist>
+      <segtitle>Directory</segtitle>
+
+      <segtitle>Meaning</segtitle>
+
+      <seglistitem>
+	<seg><filename>share/</filename></seg>
+
+	<seg>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 &man.make.1; infrastructure are in
+	  <filename>share/mk</filename>, while the additional SGML support
+	  files (such as the FreeBSD extended DocBook DTD) are in
+	  <filename>share/xml</filename>.</seg>
+      </seglistitem>
+
+      <seglistitem>
+	<seg><filename>lang.encoding/</filename></seg>
+
+	<seg>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
+	  should a translation team want to provide the documentation in the
+	  same language but in more than one encoding.  This also completely
+	  isolates us from any problems that might be caused by a switch to
+	  Unicode.</seg>
+      </seglistitem>
+    </segmentedlist>
+  </sect1>
+
+  <sect1 xml:id="structure-locale">
+    <title>The
+      <filename>lang.encoding/</filename> directories</title>
+
+    <para>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>
+
+    <segmentedlist>
+      <segtitle>Directory</segtitle>
+
+      <segtitle>Contents</segtitle>
+
+      <seglistitem>
+	<seg><filename>articles</filename></seg>
+
+	<seg>Documentation marked up as a DocBook <tag>article</tag>
+	  (or equivalent).  Reasonably short, and broken up into sections.
+	  Normally only available as one HTML file.</seg>
+      </seglistitem>
+
+      <seglistitem>
+	<seg><filename>books</filename></seg>
+
+	<seg>Documentation marked up as a DocBook <tag>book</tag> (or
+	  equivalent).  Book length, and broken up into chapters.  Normally
+	  available as both one large HTML file (for people with fast
+	  connections, or who want to print it easily from a browser) and
+	  as a collection of linked, smaller files.</seg>
+      </seglistitem>
+
+      <seglistitem>
+	<seg><filename>man</filename></seg>
+
+	<seg>For translations of the system manual pages.  This directory will
+	  contain one or more
+	  <filename>mann</filename> directories,
+	  corresponding to the sections that have been translated.</seg>
+      </seglistitem>
+    </segmentedlist>
+
+    <para>Not every
+      <filename>lang.encoding</filename> directory will contain all of these directories.  It depends
+      on how much translation has been accomplished by that translation
+      team.</para>
+  </sect1>
+
+  <sect1 xml:id="structure-document">
+    <title>Document specific information</title>
+
+    <para>This section contains specific notes about particular documents
+      managed by the FDP.</para>
+
+    <sect2>
+      <title>The Handbook</title>
+
+      <subtitle><filename>books/handbook/</filename></subtitle>
+
+      <para>The Handbook is written to comply with the FreeBSD DocBook
+	extended DTD.</para>
+
+      <para>The Handbook is organized as a DocBook <tag>book</tag>.
+	It is then divided into <tag>part</tag>s, each of which may
+	contain 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>Physical organization</title>
+
+	<para>There are a number of files and directories within the
+	  <filename>handbook</filename> directory.</para>
+
+	<note>
+	  <para>The Handbook's organization may change over time, and this
+	    document may lag in detailing the organizational changes.  If you
+	    have any questions about how the Handbook is organized, please
+	    contact the &a.doc;.</para>
+	</note>
+
+	<sect4>
+	  <title><filename>Makefile</filename></title>
+
+	  <para>The <filename>Makefile</filename> defines some variables that
+	    affect how the SGML 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> file, to
+	    bring in the rest of the code that handles converting documents
+	    from one format to another.</para>
+	</sect4>
+
+	<sect4>
+	  <title><filename>book.xml</filename></title>
+
+	  <para>This is the top level document in the Handbook.  It contains
+	    the Handbook's <link linkend="sgml-primer-doctype-declaration">DOCTYPE
+	      declaration</link>, as well as the elements that describe the
+	    Handbook's structure.</para>
+
+	  <para><filename>book.xml</filename> uses <link linkend="sgml-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="sgml-primer-general-entities">general
+	      entities</link> that are used throughout the rest of the
+	    Handbook.</para>
+	</sect4>
+
+	<sect4>
+	  <title><filename>directory/chapter.xml</filename></title>
+
+	  <para>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>For example, if one of the chapter files contains:</para>
+
+	  <programlisting><![CDATA[
+<chapter id="kernelconfiguration">
+...
+</chapter>]]></programlisting>
+
+	  <para>then it will be called <filename>chapter.xml</filename> in
+	    the <filename>kernelconfiguration</filename> directory.  In
+	    general, the entire contents of the chapter will be held in this
+	    file.</para>
+
+	  <para>When the HTML version of the Handbook is produced, this will
+	    yield <filename>kernelconfiguration.html</filename>.  This is
+	    because of the <literal>id</literal> value, and is not related to
+	    the name of the directory.</para>
+
+	  <para>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.  Moving them into
+	    separate directories prepares for future plans for the Handbook.
+	    Specifically, it will soon be possible to include images in each
+	    chapter.  It makes more sense for each image to be stored in a
+	    directory with the text for the chapter than to try to keep the
+	    text for all the chapters, and all the images, in one large
+	    directory.  Namespace collisions would be 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>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>Chapters and/or directories should not be named in a fashion
+	      that reflects their ordering within the Handbook.  This ordering
+	      might change as the content within the Handbook is reorganized;
+	      this sort of reorganization should not (generally) include the
+	      need to rename files (unless entire chapters are being promoted
+	      or demoted within the hierarchy).</para>
+	  </important>
+
+	  <para>Each <filename>chapter.xml</filename> file will not be a
+	    complete SGML document.  In particular, they will not have their
+	    own DOCTYPE lines at the start of the files.</para>
+
+	  <para>This is unfortunate as
+	    it makes it impossible to treat these as generic SGML
+	    files and simply convert them to HTML, RTF, PS, and other
+	    formats in the same way the main Handbook is generated.  This
+	    <emphasis>would</emphasis> force you to rebuild the Handbook
+	    every time you want to see the effect a change has had on just
+	    one chapter.</para>
+	</sect4>
+      </sect3>
+    </sect2>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml
new file mode 100644
index 0000000000..b1ef0c7460
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.12
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="stylesheets">
+  <title>* Stylesheets</title>
+
+  <para>SGML says nothing about how a document should be displayed to the
+    user, or rendered on paper.  To do that, various languages have been
+    developed to describe stylesheets, including DynaText, Panorama, SPICE,
+    JSSS, FOSI, CSS, and DSSSL.</para>
+
+  <para>For DocBook, we are using stylesheets written in DSSSL.  For HTML we
+    are using CSS.</para>
+
+  <sect1 xml:id="stylesheets-dsssl">
+    <title>* DSSSL</title>
+
+    <para>The Documentation Project uses a slightly customized version of
+      Norm Walsh's modular DocBook stylesheets.</para>
+
+    <para>These can be found in
+      <package>textproc/dsssl-docbook-modular</package>.</para>
+
+    <para>The modified stylesheets are not in the ports system.  Instead they
+      are part of the Documentation Project source repository, and can be
+      found in <filename>doc/share/xml/freebsd.dsl</filename>.  It is well
+      commented, and pending completion of this section you are encouraged to
+      examine that file to see how some of the available options in the
+      standard stylesheets have been configured in order to customize the
+      output for the FreeBSD Documentation Project.  That file also contains
+      examples showing how to extend the elements that the stylesheet
+      understands, which is how the FreeBSD specific elements have been
+      formatted.</para>
+  </sect1>
+
+  <sect1 xml:id="stylesheets-css">
+    <title>CSS</title>
+
+    <para>Cascading Stylesheets (CSS) are a mechanism for attaching style
+      information (font, weight, size, color, and so forth) to elements in an
+      HTML document without abusing HTML to do so.</para>
+
+    <sect2>
+      <title>The Web site (HTML documents)</title>
+
+      <para>The FreeBSD web site does not currently use CSS.  Unfortunately,
+	the look and feel is constructed using abuses of HTML of varying
+	degrees.  This should be fixed, and would be a good project for
+	someone looking to contribute to the documentation project.</para>
+    </sect2>
+
+    <sect2>
+      <title>The DocBook documents</title>
+
+      <para>The FreeBSD DSSSL stylesheets include a reference to a stylesheet,
+	<filename>docbook.css</filename>, which is expected to appear in the
+	same directory as the HTML files.  The project-wide CSS file is copied
+	from <filename>doc/share/misc/docbook.css</filename> when documents
+	are converted to HTML, and is installed automatically.</para>
+    </sect2>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml
new file mode 100644
index 0000000000..8e2a94ad94
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml
@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.22
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
+  <title>建構 Website</title>
+
+  <sect1 xml:id="the-website-prep">
+    <title>事前準備</title>
+
+    <para>請先準備約 200MB 空間，這些是要用來放 SGML 工具程式、CVS tree、
+      臨時編譯用的空間，以及編譯好的網頁存放空間。若事先已有裝 SGML 工具程式、
+      CVS tree 的話，那麼只需頂多約 100MB 空間即可。</para>
+
+    <note>
+      <para>請確認一下你的相關文件製作所會用到的 ports 都是最新版！
+	若不清楚所裝的版本為何，那麼就先以 &man.pkg.delete.1; 指令來移除舊版，
+	接著才去裝 port。  舉例來說，若已裝的是 jade-1.1，
+	但是我們目前需要的卻是 jade-1.2，那麼先用下列方式來移除舊版：</para>
+
+      <screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen>
+    </note>
+
+    <para>接著，就是設定 CVS repository。需要至少 www, doc, ports 這三樣
+      CVS tree(當然還要加上 CVSROOT)。  請參閱
+      <link xlink:href="&url.books.handbook;/synching.html#CVSUP">CVSup 簡介</link>
+      以瞭解如何來 mirror a CVS tree 或部分 CVS tree。</para>
+
+    <para>最低需求的 cvsup collections 為：<literal>www</literal>,
+      <literal>doc-all</literal>, <literal>cvs-base</literal> 以及
+      <literal>ports-base</literal>。</para>
+
+    <para>剛講的這些需要約 105MB 空間。</para>
+
+    <para>而完整的 CVS tree - 包括 <literal>src</literal>,
+      <literal>doc</literal>, <literal>www</literal> 以及
+      <literal>ports</literal> - 目前約為 940MB。</para>
+  </sect1>
+
+  <sect1 xml:id="the-website-build">
+    <title>Build the web pages from scratch</title>
+
+    <procedure>
+      <step>
+	<para>先建立要編譯的目錄(至少要有 60MB 空間)，並切換到該目錄。</para>
+
+	<screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput>
+&prompt.root; <userinput>cd /var/tmp/webbuild</userinput></screen>
+      </step>
+
+      <step>
+	<para>從 CVS tree 內 checkout 相關的 SGML 檔。</para>
+
+	<screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen>
+      </step>
+
+      <step>
+	<para>切到 <filename>www/en</filename> 目錄，然後打
+	  &man.make.1; <buildtarget>all</buildtarget> 來產生網頁。</para>
+
+	<screen>&prompt.root; <userinput>cd en</userinput>
+&prompt.root; <userinput>make all</userinput></screen>
+      </step>
+    </procedure>
+  </sect1>
+
+  <sect1 xml:id="the-website-install">
+    <title>在你的網頁伺服器上安裝網頁</title>
+
+    <procedure>
+      <step>
+	<para>如果你已經離開 <filename>en</filename>
+	  這個目錄，請切換回這個目錄中。</para>
+
+	  <screen>&prompt.root; <userinput>cd path/www/en</userinput></screen>
+      </step>
+
+      <step>
+	<para>執行 &man.make.1; <buildtarget>install</buildtarget> ，
+	  並將 <varname>DESTDIR</varname> 設定為你想安裝檔案的目錄名稱。</para>
+
+	<screen>&prompt.root; <userinput>make DESTDIR=/usr/local/www install</userinput></screen>
+      </step>
+
+      <step>
+	<para>如果你之前已經在相同的目錄中安裝了這些網頁，
+	  安裝過程並不會刪除任何既有或過期的網頁。
+	  舉例來說，如果你每日建構和安裝新的網頁副本，
+	  這個指令將會搜尋並刪除在三天內沒有更新的檔案。</para>
+
+	<screen>&prompt.root; <userinput>find /usr/local/www -ctime 3 -print0 | xargs -0 rm</userinput></screen>
+      </step>
+    </procedure>
+  </sect1>
+
+  <sect1 xml:id="the-website-env">
+    <title>環境變數</title>
+
+    <variablelist>
+      <varlistentry>
+	<term><envar>CVSROOT</envar></term>
+
+	<listitem>
+	  <para>設定 CVS tree 的位置，此為必備條件。</para>
+
+	  <screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>ENGLISH_ONLY</varname></term>
+
+	<listitem>
+	  <para>如果設定這個環境變數，而且值不為空白，
+	    makefiles 將只會建構和安裝英文文件。
+	    所以將會略過其他的各國翻譯。例如：</para>
+
+	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen>
+
+	  <para>如果你想要取消變數 <varname>ENGLISH_ONLY</varname>
+	    以及建構所有的頁面並包括翻譯，只要將變數 <varname>ENGLISH_ONLY</varname>
+	    的值設定成空白即可。</para>
+
+	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>WEB_ONLY</varname></term>
+
+	<listitem>
+	  <para>如果有設定這個變數的話，
+	    makefiles 將只會從 www 目錄建構及安裝 HTML 頁面。
+	    所有從 doc 目錄下的文件全部都會被忽略 (Handbook, FAQ, Tutorials)。
+	    例如：</para>
+
+	  <screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>NOPORTSCVS</varname></term>
+
+	<listitem>
+	  <para>如果設了這個變數，makefiles 就不會從 ports cvs repository
+	    取出檔案。 取而代之會從
+	    <filename>/usr/ports</filename> (或是 <envar>PORTSBASE</envar>
+	    所設定的值) 內複製檔案。</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para><envar>CVSROOT</envar> 是環境變數。
+      你必須直接使用指令或是在 dot files (如： ~/.profile) 中
+      設定這個環境變數。</para>
+
+    <para><varname>WEB_ONLY</varname>、<varname>ENGLISH_ONLY</varname> 及
+      <varname>NOPORTSCVS</varname> 都是 makefile 變數。
+      你可以在 <filename>/etc/make.conf</filename>、<filename>Makefile.inc</filename>
+      中設定這些變數，作法就像是用命令列或使用 dot files 來設定環境變數一般。</para>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml
new file mode 100644
index 0000000000..622e98e164
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml
@@ -0,0 +1,235 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.32
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools">
+  <title>工具</title>
+
+  <para>FDP 使用一堆工具來協助管理 FreeBSD 文件、轉換文件格式等等。
+	因此，若要進行 FDP 工作的話，必須要學會這些工具才行。</para>
+
+  <para>這些工具都可以用 Ports 或 Packages 來安裝，以節省許多安裝的工夫。</para>
+
+  <para>您必須安裝這些工具，才能使用接下來各章節會介紹到的例子。 這些工具的用法，會在後續相關章節談到。 </para>
+
+  <tip>
+    <title>建議安裝 <package>textproc/docproj</package></title>
+
+    <para>裝了
+      <package>textproc/docproj</package> 可以更省時省力，它是個
+      組合型的 port(meta-port)，本身並非軟體，只是將一些常用工具組合起來而已。
+      裝了這個 port 之後，『應該』就會自動下載、安裝本章所會介紹到的工具了。
+      若要處理中文的話，建議再裝 <package>chinese/docproj</package> 會比較好。</para>
+
+    <para>在這些 packages 當中，你可能會需要使用 JadeTeX 這個 macro 設定，
+      一旦選擇使用該 macro 的話，它會接著去裝 &tex;。由於 &tex; 算是個蠻大的套件，
+      除非你需要輸出 Postscript 或 PDF 格式，否則就不必裝了。</para>
+
+    <para>所以請考慮是否要節省編譯時間、硬碟空間，以判定要不要裝 JadeTeX (以及 &tex;)
+      了。若要一併裝起來的話：</para>
+
+      <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
+
+    <para>或是，不裝的話：</para>
+
+      <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
+
+    <para>或者，也可以選擇 <package>textproc/docproj-jadetex</package> 或是 <package>textproc/docproj-nojadetex</package> 這兩個之一來裝，
+      它們都是已事先設定  <varname>JADETEX</varname> 變數的 slave ports，
+      都一樣會裝 docproj 差別僅在於有沒有 JadeTeX 而已。
+      請注意：若只要輸出 HTML 或 ASCII 格式文件，那就不用裝 <application>JadeTeX</application>，
+      而若要輸出 PostScript、PDF 格式，就需要裝 &tex; 才行。</para>
+  </tip>
+
+  <sect1 xml:id="tools-mandatory">
+    <title>必備工具</title>
+
+    <sect2>
+      <title>軟體</title>
+
+      <para>這些都是在進行 FreeeBSD 文件計劃時所會需要用上的工具程式，
+	而且可以用來轉換文件為 HTML、plain text以及 RTF 格式。這些相關套件在
+	<package>textproc/docproj</package> 都已經全部收錄了。</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><application>Jade</application>
+	    (<package>textproc/jade</package>)</term>
+
+	  <listitem>
+	    <para>DSSSL 規格的實作程式，可用來把標記語言的文件(marked up)轉換為其他格式，像是：HTML 及 &tex;。</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><application>Tidy</application>
+	    (<package>www/tidy</package>)</term>
+
+	  <listitem>
+	    <para>HTML <quote>pretty printer</quote>，可用來把自動產生的 HTML 內容整理得更易閱讀、以便日後維護。</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><application>Links</application>
+	    (<package>www/links</package>)</term>
+
+	  <listitem>
+	    <para>文字操作模式的 WWW 瀏覽器(browser)可以把 HTML 檔轉為 plain text 格式。</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><application>peps</application>
+	    (<package>graphics/peps</package>)</term>
+
+	  <listitem>
+	    <para>文件中有些圖是存成 EPS 格式的，這些必須要轉為 PNG 格式，
+	      才能讓一般瀏覽器可以正常觀看。</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>DTD 及 Entity</title>
+
+      <para>由於 FDP 有用到許多 DTD 跟 Entity，因此在開工前，要裝上這些才行。</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>HTML DTD (<package>textproc/html</package>)</term>
+
+	  <listitem>
+	    <para>HTML 是用於 WWW 的標記語言，且也是 FreeBSD 網頁所使用的格式。</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>DocBook DTD (<package>textproc/docbook</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 之中有 19 個 entity 被許多 DTD 所大量使用，
+	      包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>樣式表(Stylesheets)</title>
+
+      <para>這些樣式表都是用來轉換、重排文件的螢幕顯示、列印等效果處理</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>Modular DocBook 樣式表
+	    (<package>textproc/dsssl-docbook-modular</package>)</term>
+
+	  <listitem>
+	    <para>Modular DocBook 樣式表，是用來把 DocBook 的標記語言文件轉換為其他格式，像是：
+	      HTML 或 RTF。</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="tools-optional">
+    <title>輔助工具</title>
+
+    <para>不一定得裝下列的工具才行，但是，裝了之後會更容易進行各項工作，
+      而且可輸出的格式也更具彈性。</para>
+
+    <sect2>
+      <title>軟體</title>
+
+      <variablelist>
+	<varlistentry>
+	  <term><application>JadeTeX</application> 及
+	    <application>teTeX</application>
+	    (<package>print/jadetex</package> 及
+	    <package>print/teTeX</package>)</term>
+
+	  <listitem>
+	    <para><application>Jade</application> 與
+	      <application>teTeX</application> 可用來把 DocBook 格式文件轉為
+	      DVI, Postscript 及 PDF 格式。安裝時請記得加上
+	      <application>JadeTeX</application> 這個 macro，這樣才會順便裝上這兩個套件。</para>
+
+	    <para>若無意把文件轉換更多格式的話(舉例：只要 HTML, plain text, RTF 這些格式就夠的話)
+	      ，那麼就不用裝
+	      <application>JadeTeX</application> 與
+	      <application>teTeX</application>。  如此一來可省下一些的編譯時間、安裝空間，
+	      因為 <application>teTeX</application> 大約要至少 30MB 空間。</para>
+
+	    <important>
+	      <para>若決定要裝
+		<application>JadeTeX</application> 以及
+		<application>teTeX</application> 的話，那麼在裝完 <application>JadeTeX</application> 之後，
+		要記得設定 <application>teTeX</application> 才行。
+		<filename>print/jadetex/pkg-message</filename> 內有詳細介紹相關步驟。</para>
+	    </important>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><application>Emacs</application> 或
+	    <application>XEmacs</application>
+	    (<package>editors/emacs</package> 或
+	    <package>editors/xemacs</package>)</term>
+
+	  <listitem>
+	    <para>這兩者編輯器都具有處理 SGML DTD 標記文件的特殊模式。
+	      該模式提供一些指令，來簡化所需的打字次數，而且可以減少可能發生的錯誤。</para>
+
+	    <para>不過，這些編輯器並不是必備的；任何文字編輯器都可以用來編輯標記語言文件。
+	      不過，你可以透過類似上述這樣的編輯器，來讓這些繁瑣作業更輕鬆有效率些。</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>若有推薦其他好用的處理 SGML 文件程式，請來信讓 &a.doceng; 知道，
+        如此一來，該軟體就會列入這裡介紹了。</para>
+    </sect2>
+  </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml
new file mode 100644
index 0000000000..93e331fbe8
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml
@@ -0,0 +1,383 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.29
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="translations">
+  <title>翻譯時的常見問題</title>
+
+  <para>本章是翻譯 FreeBSD 文件(包含：FAQ, Handbook, tutorials, manual pages等)的常見問題(FAQ)。</para>
+
+  <para>本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文翻譯計劃的翻譯 FAQ 為母本而來的，
+    原始撰稿者為 Frank Gr&uuml;nder <email>elwood@mc5sys.in-berlin.de</email> ，並由
+    Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。</para>
+
+  <para>The FAQ is maintained by the &a.doceng;.</para>
+
+  <qandaset>
+    <qandaentry>
+      <question>
+	<para>FAQ 的目的是?</para>
+      </question>
+
+      <answer>
+	<para>隨著越來越多人參與 freebsd-doc 郵遞論壇，而且希望將 FreeBSD 文件翻譯為各種語言版本。
+    我們希望這份 FAQ 能儘可能為這些參與翻譯者提供快速的解惑。</para>
+      </answer>
+    </qandaentry>
+
+    <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 及相關網站。</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 CVS repository 的備份(至少文件部分)，可以用
+	  <application>CTM</application> 或
+	  <application>CVSup</application> 都可以。Handbook 中的 "更新、升級 FreeBSD"
+	  一章內有提到如何使用這些程式。</para>
+
+	<para>此外，需要熟悉 <application>CVS</application> 用法。
+	  如此一來，你可以查閱不同版本之間的差異處。</para>
+
+	<para>[XXX To Do(尚未撰稿，仍待補充) -- 寫份上手說明(tutorial)來介紹如何以 CVSup
+	  取得文件部分，以及察看不同版本之間的差異。]</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>要怎麼找出來還有誰要跟我一起翻譯的呢？</para>
+      </question>
+
+      <answer>
+	<para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">文件計劃的翻譯</link> 這列了目前已知的各翻譯者成果
+	    ，如果已經有其他人也在做跟你一樣的翻譯工作，那麼請不要重複浪費人力，
+	    請與他們聯繫看看還有哪些地方可以幫上忙的。</para>
+
+	<para>若上面並未列出你母語的翻譯，或是也有人要翻譯但還未公開宣布的話，那麼就寄信到 &a.doc; 吧。
+	  </para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>都沒人翻譯為我所使用的語言，該怎麼辦？</para>
+      </question>
+
+      <answer>
+	<para>恭喜啊，你剛好踏上 <quote>FreeBSD
+	  <replaceable>你的母語</replaceable> 文件翻譯計劃</quote> 的啟程之路，歡迎上船。</para>
+
+	<para>首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已，
+	  因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para>
+
+	<para>寫信到 &a.doc; 向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料</para>
+
+	<para>若你的國家已經有人提供 FreeBSD 的 mirror(映設) 服務的話，那麼就先跟他們聯繫，
+	  並詢問你是否在上面可以有網頁空間來放相關計劃資料，
+	  以及是否可以有提供 email 帳號或 mailing list 服務。</para>
+
+	<para>然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些
+	  &mdash; 像是 FAQ 啦，或是如何上手之類的說明文章。</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>已經翻好一些文件了，該寄到哪呢？</para>
+      </question>
+
+      <answer>
+	<para>這要看情況而定。 若你是在翻譯團隊內做的話(像是日本、德國)，
+	  他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。</para>
+
+	<para>若你是某語系的唯一翻譯者(或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃)
+	  ，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？</para>
+
+	<para>或者</para>
+
+	<para>我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？</para>
+      </question>
+
+      <answer>
+	<para>首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說：
+	  把它擺到現有文件架構內是可以正確編譯成功的。</para>
+
+	<para>目前，FreeBSD 文件都是放在最上層的 <filename>doc/</filename> 目錄內。
+	  而該目錄下的則依其語系來做分類命名的，依照 ISO639 定義(<filename>/usr/share/misc/iso639</filename>
+	  的這個 FreeBSD 版本比 1999/01/20 還新)。</para>
+
+	<para>若你這個語系可能會有不同編碼方式(像是：中文)
+	  那麼就應該會像下面這樣，來依你所使用的編碼方式細分。</para>
+
+	<para>最後，你應該建立好各文件的目錄了。</para>
+
+	<para>舉例來說，假設有瑞典文(Swedish)版的翻譯，那麼應該會長像：</para>
+
+	<programlisting>doc/
+    sv_SE.ISO8859-1/
+                     Makefile
+                     books/
+                           faq/
+                               Makefile
+                               book.xml</programlisting>
+
+	<para><literal>sv_SE.ISO8859-1</literal> 是依照
+	  <filename>語系(lang).編碼(encoding)</filename>
+	  的規則來建立的譯名。
+	  請注意：其中有兩個 <filename>Makefiles</filename> 檔，它們是用來編書的。</para>
+
+	<para>然後請用 &man.tar.1; 與 &man.gzip.1; 來把你的翻譯文件壓縮起來，並寄到本計劃來。</para>
+
+	<screen>&prompt.user; <userinput>cd doc</userinput>
+&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
+&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen>
+
+	<para>接著，把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上，若你沒有自己網頁空間的話(ISP不提供)
+	  ，那麼可以該檔寄到 &a.doceng; 來。</para>
+
+	<para>還有，記得用 &man.send-pr.1; 以正式通知大家；你已經寄出翻譯文件了，
+	  還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好，
+	  因為這也有助於提升翻譯品質的流暢度。</para>
+
+	<para>最後，會有人(可能是文件計劃總管，或是 &a.doceng; 成員)
+	  會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點：</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>我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 &hellip;)
+	  因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。
+	  此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。</para>
+
+	<para>若你有某國才有的資料，請(用 &man.send-pr.1; )提供給英文版 Handbook 以作為修訂
+	  ，然後再把英文版的修訂部分，翻為你要翻譯的 Handbook 吧。</para>
+
+	<para>感恩，謝謝。</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>要怎麼把該語系特有的字元寫進去翻譯內容呢？</para>
+      </question>
+
+      <answer>
+	<para>文件內所有的非 ASCII(Non-ASCII) 字元，都要使用 SGML entities 才能寫進去。</para>
+
+	<para>簡單來說，長相一開頭會是 &amp; 符號(&amp;)，然後是該 entity 名稱，最後接上分號(;)。</para>
+
+	<para>這些 entity 名稱都是 ISO8879 所制訂的，而 port tree 內則在
+	  <package>textproc/iso8879</package>。</para>
+
+	<para>以下舉一些例子：</para>
+
+	<segmentedlist>
+          <segtitle>Entity名稱</segtitle>
+
+          <segtitle>實際樣子</segtitle>
+
+          <segtitle>介紹</segtitle>
+
+	  <seglistitem>
+	    <seg>&amp;eacute;</seg>
+	    <seg>&eacute;</seg>
+	    <seg>小 <quote>e</quote>，並帶尖、重音(acute accent)</seg>
+	  </seglistitem>
+
+	  <seglistitem>
+	    <seg>&amp;Eacute;</seg>
+	    <seg>&Eacute;</seg>
+	    <seg>大 <quote>E</quote>，並帶尖、重音(acute accent)</seg>
+	  </seglistitem>
+
+	  <seglistitem>
+	    <seg>&amp;uuml;</seg>
+	    <seg>&uuml;</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>
+
+	<!--
+	  摘自 http://fatpipi.cirx.org/~vanilla/rules.txt
+	  如非必要，翻譯文章內盡量少用直接稱呼你我他的用字。
+	  如果真的得用，就採用第三人稱(用【他】而非【你】)，還有就是用複數(用【你們】而非【你】)，
+	  當然這還是得配合原文的上下語意。如果他是寫 "I" 而翻譯成 "我"，則無可厚非。
+
+	  但是對於文內絕大多數的"You..... you ...etc"
+	  其實都可以把【你】簡化或是避免掉，這對閱讀時候的順暢感應該有幫助。
+	-->
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>翻譯成果內要不要附上一些其他訊息呢？</para>
+      </question>
+
+      <answer>
+	<para>當然要。</para>
+
+	<para>每份英文版原稿的開頭，通常會有像下面的內容：</para>
+
+	<programlisting>&lt;!--
+     The FreeBSD Documentation Project
+
+     &dollar;FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.5 2000/07/07 18:38:38 dannyboy Exp &dollar;
+--&gt;</programlisting>
+
+	<para>實際上的內容可能稍有不同，但每份原稿都會附上 &dollar;FreeBSD&dollar; 這一行以及
+	  <literal>The FreeBSD Documentation Project</literal> 宣告。
+	  請注意：&dollar;FreeBSD 開頭的這行是會由 CVS 隨著每次異動而自動更改的，
+	  所以，新檔案的話請保持原狀(也就是只要寫  <literal>&dollar;FreeBSD&dollar;</literal> 就好了)。</para>
+
+	<para>翻譯文件中，必須都要有 &dollar;FreeBSD&dollar; 這行，並且把
+	  <literal>FreeBSD Documentation Project</literal> 這行改為
+	  <literal>The FreeBSD 你的語系
+	    Documentation Project</literal>。</para>
+
+	<para>此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。</para>
+
+	<para>因此呢，西班牙文版(Spanish)的檔案開頭應該是長像這樣：</para>
+
+	<programlisting>&lt;!--
+     The FreeBSD Spanish Documentation Project
+
+     &dollar;FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.3 1999/06/24 19:12:32 jesusr Exp &dollar;
+     Original revision: 1.11
+--&gt;</programlisting>
+      </answer>
+    </qandaentry>
+  </qandaset>
+</chapter>
diff --git a/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml
new file mode 100644
index 0000000000..158d232029
--- /dev/null
+++ b/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml
@@ -0,0 +1,440 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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$
+     Original revision: 1.48
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style">
+  <title>文件的撰寫風格</title>
+
+  <para>由於 FreeBSD 文件是由眾多作者所維護的，為了保持寫作風格的一貫性，
+    於是就產生較有共識的寫作規則，請各位記得要遵守。</para>
+
+  <variablelist>
+    <varlistentry>
+      <term>使用美式英語</term>
+
+      <listitem>
+	<para>同一個字在不同種類的英語會有著不同的拼法。
+	  遇到拼字不同的情況，請採用美式英語拼法。 像是：
+	  請改用 <quote>color</quote>，而非 <quote>colour</quote>。
+	  請改用 <quote>rationalize</quote>，而非 <quote>rationalise</quote>
+	  等等類似字彙。</para>
+
+	<note>
+	  <para>若文章採用英式英語也可以接受，但必須全篇文章都採用同一拼法才行
+	    。  而文件的其他部份，像是書、網頁、 manual
+	    說明等則必須採用美式英語。</para>
+	</note>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>不要用簡寫</term>
+
+      <listitem>
+	<para>請不要簡寫(contraction)。  請務必將完整的字寫出來。 比如：
+	  <quote>Don't use contractions</quote> 這句有用到簡寫，就要避免。</para>
+
+	<para>正式書面寫法避免簡寫的原因，乃是因為如此一來字句意思較精準，
+	  且對譯者會比較輕鬆些。</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>正確使用 serial comma 以及頓號</term>
+
+      <listitem>
+	<para>英文段落通常會逗號(,)作為該句所提到的各項目的語氣區隔。
+	  並且會在最後一個提到的項目時，先加上逗號再接上 <quote>and</quote>，
+	  最後才是最後的項目。</para>
+
+	<para>舉個例子，看看下面這句：</para>
+
+	<blockquote>
+	  <para>This is a list of one, two and three items.</para>
+	</blockquote>
+
+	<para>那麼這一句到底是有三個項目(<quote>one</quote>、<quote>two</quote>
+	  、<quote>three</quote>)呢？或者是只有兩個項目(<quote>one</quote>、
+	  <quote>two and three</quote>)呢？</para>
+
+	<para>因此較妥的方式是以 serial comma 的方式，才能正確表達語意：</para>
+
+	<blockquote>
+	  <para>This is a list of one, two, and three items.</para>
+	</blockquote>
+
+	<para>然而，在翻譯過程中，建議把逗號(,)部份改為頓號(、)，並且
+	  <quote>and</quote> 的部份可略而不翻，以免語意頓塞。</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>避免使用贅詞</term>
+
+      <listitem>
+	<para>請試著避免使用贅詞(redundant phrase)。  尤其是
+	  <quote>這個指令</quote>、<quote>這個檔案</quote>、<quote>man
+	  指令</quote> 這幾個通常都是不必要的贅詞。</para>
+
+	<para>以指令(command)方面舉例，比較妥當的用法是第二句的例子：</para>
+
+	<informalexample>
+	  <para>使用 <command>cvsup</command> 指令來更新原始碼。</para>
+	</informalexample>
+
+	<informalexample>
+	  <para>使用 <command>cvsup</command> 來更新原始碼。</para>
+	</informalexample>
+
+	<para>以檔案(filename)方面舉例，比較妥當的用法是第二句的例子：</para>
+
+	<informalexample>
+	  <para>&hellip; 在這個
+	    <filename>/etc/rc.local</filename> 檔案 &hellip;</para>
+	</informalexample>
+
+	<informalexample>
+	  <para>&hellip; 在
+	    <filename>/etc/rc.local</filename> 檔 &hellip;</para>
+	</informalexample>
+
+	<para>以 man(manual)方面舉例，比較妥當的用法是第二句(有用到 SGML
+	  <tag>citerefentry</tag> 標籤)：</para>
+
+	<informalexample>
+	  <para>請打 <command>man csh</command> 指令以參閱詳情說明。</para>
+	</informalexample>
+
+	<informalexample>
+	  <para>詳情請參閱 &man.csh.1;。</para>
+	</informalexample>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>每句後面加上兩個空白</term>
+
+      <listitem>
+	<para>為了使文章更易閱讀，以及讓 <application>Emacs</application>
+	  之類的工具容易運用，請在每一完整句子後面加上兩個空白。</para>
+
+	<para>不過，句號(.)後面有接大寫字母，
+	  並不一定表示前一個句點所在處就是完整句子，
+	  尤其是名字部份常常會有這現象。  像是 <quote>Jordan K. Hubbard</quote>
+	  這人名就是很好的例證：句號後面接空白，然後是大寫的
+	  <literal>H</literal>，然而這肯定並不是兩段句子。</para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+  <para>撰寫風格的相關細節，可參閱 William Strunk 所寫的 <link xlink:href="http://www.bartleby.com/141/">Elements of Style</link>。</para>
+
+  <sect1 xml:id="writing-style-guide">
+    <title>Style guide</title>
+
+    <para>由於 Handbook 是由眾多作者所維護，為了保持寫作風格的一貫性，
+      請遵守下列撰寫風格。</para>
+
+    <sect2>
+      <title>大小寫</title>
+
+      <para>Tag 的部份都是用小寫字母，譬如是用 <literal>&lt;para&gt;</literal>
+	，<emphasis>而非</emphasis> <literal>&lt;PARA&gt;</literal>。</para>
+
+      <para>而 SGML 內文則是用大寫字母表示，像是：
+	<literal>&lt;!ENTITY&hellip;&gt;</literal> 及
+	<literal>&lt;!DOCTYPE&hellip;&gt;</literal>，
+	<emphasis>而不是</emphasis>
+	<literal>&lt;!entity&hellip;&gt;</literal> 及
+	<literal>&lt;!doctype&hellip;&gt;</literal>。</para>
+    </sect2>
+
+    <sect2>
+      <title>縮寫字</title>
+
+      <para>縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法，
+	比如："Network Time Protocol (<acronym role="Network Time Protocol">NTP</acronym>)"。
+	定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙，
+	除非使用完整詞彙可以更能表達語意)來表達即可。
+	通常每本書只會第一次提到時，才會列出完整詞彙，
+	但若您高興也可以在每章第一次提到時又列出完整詞彙。</para>
+
+      <para>此外，同一縮寫字在前三次使用時，須使用 &lt;acronym&gt; 標籤，
+	並把完整詞彙附在 <literal>role</literal> 屬性內做說明。
+	如此一來就會建立詞彙表，並且當滑鼠移至該縮寫字上方時，
+	就會顯示完整詞彙。</para>
+    </sect2>
+
+    <sect2>
+      <title>縮排</title>
+
+      <para><emphasis>無論</emphasis> 檔案縮排設定為何，
+	每個檔案一開始的縮排(indentation)都是從 0 縱列開始</para>
+
+      <para>未完的標籤會以多兩個空白來增加縮排，
+	結尾的標籤則少兩個空白來縮減縮排。  若已達 8 個空白，則以 tab 取代之。
+	此外，在 tab 前面不要再用空白，也不要在每行後面加上空白。
+	每個 tag 的內文若超過一行的話，則接下來的就多兩個空白以做縮排。</para>
+
+      <para>舉個例子，這節所用的寫法大致是下面這樣：</para>
+
+      <programlisting><![CDATA[+--- 這是 0 縱列
+V
+<chapter>
+  <title>...</title>
+
+  <sect1>
+    <title>...</title>
+
+    <sect2>
+      <title>縮排</title>
+
+      <para><emphasis>無論</emphasis> 檔案縮排設定為何，
+        每個檔案一開始的縮排(indentation)都是從 0 縱列開始。</para>
+
+      ...
+    </sect2>
+  </sect1>
+</chapter>]]></programlisting>
+
+      <para>若用 <application>Emacs</application> 或
+	<application>XEmacs</application> 來編輯這檔，那麼會自動進入
+	<literal>sgml-mode</literal> 模式，
+	然後就會強制使用每個檔案最下方的環境設定。</para>
+
+      <para><application>Vim</application> 愛用者也可以用下列設定來調整：</para>
+
+      <programlisting>augroup sgmledit
+  autocmd FileType sgml set formatoptions=cq2l " 特殊格式選項
+  autocmd FileType sgml set textwidth=70       " 在 70 縱列處即自動換行
+  autocmd FileType sgml set shiftwidth=2       " 自動縮排 2 個空白
+  autocmd FileType sgml set softtabstop=2      " 按 Tab 會自動轉為兩個空白縮排
+  autocmd FileType sgml set tabstop=8          " 把 8 個空白轉為 tab
+  autocmd FileType sgml set autoindent         " 自動縮排
+augroup END</programlisting>
+
+    </sect2>
+
+    <sect2>
+      <title>Tag 風格</title>
+
+      <sect3>
+	<title>Tag 空行</title>
+
+	<para>同一縮排等級的標籤要以空一行來做區隔，而不同縮排等級的則不必。
+	  比如：</para>
+
+	<informalexample>
+	  <programlisting><![CDATA[<article lang='zh_tw'>
+  <articleinfo>
+    <title>NIS</title>
+
+    <pubdate>October 1999</pubdate>
+
+    <abstract>
+      <para>...
+	...
+	...</para>
+    </abstract>
+  </articleinfo>
+
+  <sect1>
+    <title>...</title>
+
+    <para>...</para>
+  </sect1>
+
+  <sect1>
+    <title>...</title>
+
+    <para>...</para>
+  </sect1>
+</article>]]></programlisting>
+	</informalexample>
+      </sect3>
+
+      <sect3>
+	<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>
+      <title>空白的更改</title>
+
+      <para>在 commit 修改時，<emphasis>請別在修改內容的同時，
+	也一起更改編排格式</emphasis>。</para>
+
+      <para>如此一來，像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容，
+	而不用費心思去判斷該行的改變，是由於格式重排或者內容異動。</para>
+
+      <para>舉例說明，若要在某段加上兩個句子，如此一來該段落的某行勢必會超出 80
+	縱列，這時請先 commmit 修改。  接著，再修飾過長行落的換行，然後再次
+	commit 之。  而第二次的 commit 紀錄，請明確說明這只是 whitespace-only
+	(修改空白而已) 的更改，如此一來，翻譯團隊就可以忽略第二次 commit 了
+	。</para>
+    </sect2>
+
+    <sect2>
+      <title>Nonbreaking space</title>
+
+      <para>請避免一些情況下的斷行：造成版面醜醜的、或是須連貫表達的同一句子。
+	斷行的情況會隨所閱讀的工具不同而有所不同。  尤其是透過純文字瀏覽器來看
+	HTML 時會更明顯看到類似下面這樣不好的編排段落：</para>
+
+      <literallayout class="monospaced">Data capacity ranges from 40 MB to 15
+GB.  Hardware compression &hellip;</literallayout>
+
+      <para>請使用 <literal>&amp;nbsp;</literal> 以避免同句子之間的斷行，
+	以下示範如何使用 nonbreaking spaces：</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>在數字與單位之間：</para>
+	  <programlisting><![CDATA[57600&nbsp;bps]]></programlisting>
+	</listitem>
+
+	<listitem>
+	  <para>在程式名稱與版號之間：</para>
+	  <programlisting><![CDATA[FreeBSD&nbsp;4.7]]></programlisting>
+	</listitem>
+
+	<listitem>
+	  <para>multiword 之間 (使用時請小心，像是 <quote>The FreeBSD Brazilian
+	    Portuguese Documentation Project</quote> 這類由三到四個字所組成的，
+	    則不用加。)：</para>
+	  <programlisting><![CDATA[Sun&nbsp;Microsystems]]></programlisting>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="writing-style-word-list">
+    <title>詞彙表</title>
+
+    <para>以下為 FreeBSD 文件計劃編排時所採用的小型詞彙表。
+      若找不到要找的詞彙，請參閱 <link xlink:href="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly
+      word list</link>。</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>2.2.X</para>
+      </listitem>
+
+      <listitem>
+	<para>4.X-STABLE</para>
+      </listitem>
+
+      <listitem>
+	<para>CD-ROM</para>
+      </listitem>
+
+      <listitem>
+	<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
+      </listitem>
+
+      <listitem>
+	<para>Ports Collection</para>
+      </listitem>
+
+      <listitem>
+	<para>IPsec</para>
+      </listitem>
+
+      <listitem>
+	<para>Internet</para>
+      </listitem>
+
+      <listitem>
+	<para>MHz</para>
+      </listitem>
+
+      <listitem>
+	<para>Soft Updates</para>
+      </listitem>
+
+      <listitem>
+	<para>Unix</para>
+      </listitem>
+
+      <listitem>
+	<para>disk label</para>
+      </listitem>
+
+      <listitem>
+	<para>email</para>
+      </listitem>
+
+      <listitem>
+	<para>file system</para>
+      </listitem>
+
+      <listitem>
+	<para>manual page</para>
+      </listitem>
+
+      <listitem>
+	<para>mail server</para>
+      </listitem>
+
+      <listitem>
+	<para>name server</para>
+      </listitem>
+
+      <listitem>
+	<para>null-modem</para>
+      </listitem>
+
+      <listitem>
+	<para>web server</para>
+      </listitem>
+    </itemizedlist>
+
+  </sect1>
+</chapter>