aboutsummaryrefslogtreecommitdiff
path: root/zh_TW.UTF-8/books/fdp-primer
diff options
context:
space:
mode:
authorLi-Wen Hsu <lwhsu@FreeBSD.org>2014-05-29 16:48:07 +0000
committerLi-Wen Hsu <lwhsu@FreeBSD.org>2014-05-29 16:48:07 +0000
commit163ba6b752e2d1b900f88ba29324ed5998b14551 (patch)
tree3010592efec60252103b5e76eab918b0491bb533 /zh_TW.UTF-8/books/fdp-primer
parent536050cea8f16998f8fbddf6b4aff8469e149ec0 (diff)
downloaddoc-163ba6b752e2d1b900f88ba29324ed5998b14551.tar.gz
doc-163ba6b752e2d1b900f88ba29324ed5998b14551.zip
Convert zh_TW from Big5 to UTF-8.
Approved by: bcr
Notes
Notes: svn path=/head/; revision=44974
Diffstat (limited to 'zh_TW.UTF-8/books/fdp-primer')
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/Makefile51
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/book.xml234
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/chapters.ent27
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml486
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml336
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml241
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml165
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml122
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml2682
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml1543
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml281
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml92
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml191
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml235
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml383
-rw-r--r--zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml440
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>