<?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">
<!--
Creates entities for each chapter in the Documentation Project Primer.
Each entity is named chap.foo, where foo is the value of the id
attribute on that chapter, and corresponds to the name of the
directory in which that chapter's .xml file is stored.
Chapters should be listed in the order in which they are referenced.
$FreeBSD$
--><!ENTITY chap.overview SYSTEM "overview/chapter.xml">
<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml">
<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml">
<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml">
<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.translations SYSTEM "translations/chapter.xml">
<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml">
<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml">
<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml">
<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml">
<!ENTITY app.examples SYSTEM "examples/appendix.xml">
<!-- ENTITY index SYSTEM "index.xml" -->]>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(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$
-->
<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> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <holder role="mailto:doceng@FreeBSD.org">DocEng</holder></copyright>
<pubdate role="rcs" xml:lang="en">$FreeBSD$</pubdate>
<releaseinfo xml:lang="en">$FreeBSD$</releaseinfo>
<legalnotice xml:id="legalnotice">
<title>版權</title>
<para xml:lang="en">Redistribution and use in source (XML DocBook) and 'compiled'
forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions are
met:</para>
<orderedlist>
<listitem>
<para xml:lang="en">Redistributions of source code (XML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.</para>
</listitem>
<listitem>
<para xml:lang="en">Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.</para>
</listitem>
</orderedlist>
<important>
<para xml:lang="en">THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION
PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.</para>
</important>
</legalnotice>
<abstract>
<para>感謝您參與 FreeBSD 文件計劃,您的點滴貢獻,都相當寶貴。</para>
<para>本入手書內容包括:如何開始著手貢獻FreeBSD 文件計劃 (簡稱: <acronym>FDP</acronym> )的各項細節,以及會用到的一些工具、軟體 ,以及文件計畫的宗旨。</para>
<para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</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>提示符號</entry>
</row>
</thead>
<tbody>
<row>
<entry>一般使用者</entry>
<entry><prompt>%</prompt></entry>
</row>
<row>
<entry><systemitem class="username">root</systemitem></entry>
<entry><prompt>#</prompt></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 -l</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>%</prompt> <userinput>date +"The time is %H:%M"</userinput>
The time is 09:18</screen></entry>
</row>
<row>
<entry>要參考的線上手冊</entry>
<entry>使用 <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來切換帳號。</entry>
</row>
<row>
<entry>使用者名稱和群組名稱</entry>
<entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry>
</row>
<row>
<entry>語氣的強調。</entry>
<entry>使用者<emphasis>必須</emphasis>這樣做</entry>
</row>
<row>
<entry>打指令時,可替換的部份</entry>
<entry>要搜尋線上手冊的關鍵字,請輸入 <command>man -k <replaceable>關鍵字</replaceable></command></entry>
</row>
<row>
<entry>環境變數。</entry>
<entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 xml:id="preface-notes">
<title>注意、技巧、重要訊息、警告、與範例的運用。</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>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="overview">
<title>概論</title>
<para>歡迎參與 FreeBSD 文件計劃( 簡稱 <acronym>FDP</acronym> ) 。維持優秀質量的文件對 FreeBSD 的成功來說十分重要,您的點滴貢獻都是十分寶貴的。</para>
<para>本文件描述:『 <acronym>FDP</acronym> 的架構有哪些』、『如何撰寫並提交文件』、 『如何有效運用工具來協助撰稿』。</para>
<para>歡迎大家對 <acronym>FDP</acronym> 做出貢獻。唯一的成員要求就有貢獻的意願。</para>
<para>本入門書指出如何:</para>
<itemizedlist>
<listitem>
<para>瞭解有哪些文件是由 <acronym>FDP</acronym> 所維護的。</para>
</listitem>
<listitem>
<para>安裝所需的文件工具和檔案</para>
</listitem>
<listitem>
<para>修改文件</para>
</listitem>
<listitem>
<para>提交修改以供審核並納入 FreeBSD 文件</para>
</listitem>
</itemizedlist>
<sect1 xml:id="overview-quick-start">
<title>快速上手</title>
<para>在編輯 FreeBSD 文件之前,有一些準備工作要做。 首先,請訂閱 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 文件計劃郵件論壇</link>。 有些團隊成員也會出現在<link xlink:href="http://www.efnet.org/">EFnet</link>的<literal>#bsddocs</literal> <acronym>IRC</acronym> 頻道。這些人可以幫忙解決文件相關的問題。</para>
<procedure>
<step>
<para>安裝 <package>textproc/docproj</package> 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。</para>
</step>
<step>
<para>在<filename>~/doc</filename>安裝 FreeBSD 文件庫的本地端工作副本 ( 請見 <xref linkend="working-copy"/> )。</para>
<screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
</step>
<step>
<para>設定文字編輯器:</para>
<itemizedlist>
<listitem>
<para>Word wrap 設為70個字元。</para>
</listitem>
<listitem>
<para>Tab stops 設成 。</para>
</listitem>
<listitem>
<para>將句首每八個空白以一個 tab 替換。</para>
</listitem>
</itemizedlist>
<para>特定編輯器的設定方式列於 <xref linkend="editor-config"/>。</para>
</step>
<step>
<para>更新本地端工作副本</para>
<screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
</step>
<step>
<para>編輯需要修改的文件檔案。如果檔案需要大幅度的編修,請先諮詢郵件論壇。</para>
<para>標籤 ( tag ) 和 entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>. 。</para>
</step>
<step>
<para>編輯完後,執行以下指令來檢查是否有問題:</para>
<screen><prompt>%</prompt> <userinput>igor -R filename.xml | less -RS</userinput></screen>
<para>檢查輸出並重新編輯檔案來修正顯示的錯誤,然後重新執行指令來找出剩下的問題。重複執行直到所有錯誤都解決完。</para>
</step>
<step>
<para>修正送出前請先建構測試 (build-test ) 。在編輯的文件目錄最頂層執行 <userinput>make</userinput>,將會產生 split HTML 格式的文件。例如要建構 <acronym>HTML</acronym> 格式的英文版使用手冊,請在 <filename>en_US.ISO8859-1/books/handbook/</filename> 目錄執行 <command>make</command> 。</para>
</step>
<step>
<para>修改並測試完後,產生<quote>diff 檔</quote>:</para>
<screen><prompt>%</prompt> <userinput>cd ~/doc</userinput>
<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
<para>設一個可辨識的檔名。如上例中,是使用手冊的<filename>bsdinstall</filename> 部份的修改。</para>
</step>
<step>
<para>使用網頁版 <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">Problem Report</link> 系統提交 diff 檔。 如果使用網頁版,請輸入<emphasis>[修正檔] <replaceable>問題簡短描述</replaceable></emphasis>的概要 。選擇 <literal>docs</literal> 分類和 <literal>doc-bug</literal>類別。在訊息的主體中,輸入修正的簡短描述和其他相關的重要的細節。使用<guibutton>[ Browse... ]</guibutton> 按鈕來附加 diff 檔。</para>
</step>
</procedure>
</sect1>
<sect1 xml:id="overview-doc">
<title>FreeBSD 文件組</title>
<para><acronym>FDP</acronym> 負責四類 FreeBSD 文件</para>
<itemizedlist>
<listitem>
<para><emphasis>使用手冊</emphasis>: 使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para>
</listitem>
<listitem>
<para><emphasis>FAQ</emphasis> 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講,就是『問答集』格式) 通常會擺在這裡面的問答格式,不會放太長的詳細內容。</para>
</listitem>
<listitem>
<para><emphasis>線上手冊 ( manual pages )</emphasis>:英文版的系統 manual 並不是由 <acronym>FDP</acronym> 所撰寫的,因為它們是屬於 base system 的部份。 然而,<acronym>FDP</acronym> 可以修改這些文件,來讓這些文件寫得更清楚,甚至是勘正錯誤的地方。</para>
</listitem>
<listitem>
<para><emphasis>網站</emphasis>: 這是 FreeBSD 在網路上的主要部份,位於 <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link> 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方</para>
</listitem>
</itemizedlist>
<para>翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯</para>
<para>FreeBSD 網站、使用手冊、和 <acronym>FAQ</acronym> 的文件原始碼可以在 <literal>https://svn.FreeBSD.org/doc/</literal> 的文件庫取得。</para>
<para>線上手冊的原始碼則是在 <literal>https://svn.FreeBSD.org/base/</literal> 的原始碼庫可以取得。</para>
<para>文件提交訊息可以用 <command>svn log</command> 察看。 提交訊息也會保存在<uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>。</para>
<para>這些儲存庫的網頁版位於<link xlink:href="https://svnweb.FreeBSD.org/doc/"/> 和 <link xlink:href="https://svnweb.FreeBSD.org/base/"/>。</para>
<para>許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 <acronym>FDP</acronym> 的檔案中。其他一些文件則是作者希望放在他處。<acronym>FDP</acronym> 會盡力提供這些文件的連結。</para>
</sect1>
</chapter>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="tools">
<title>工具</title>
<para>有些工具軟體用來管理 FreeBSD 文件,並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的,但是裝了之後會更容易進行文件製作工作。</para>
<sect1 xml:id="tools-required">
<title>必備工具</title>
<para>從 Ports Collection 安裝 <package>textproc/docproj</package>。這個 <emphasis>組合型 port (meta-port)</emphasis> 會安裝處理 FreeBSD 文件需要的所有應用程式。以下列出特定元件的進一步說明。</para>
<sect2>
<title><acronym>DTD</acronym>s 與 <acronym>Entities</acronym></title>
<para>FreeBSD 文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 組。這些都會經由 <package>textproc/docproj</package> port 來安裝。</para>
<variablelist>
<varlistentry>
<term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)</term>
<listitem>
<para><acronym>XHTML</acronym> 是全球資訊網的一種標記語言,也是整個 FreeBSD 網站所使用的格式。</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en">DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml</package>)</term>
<listitem>
<para>DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ISO 8879 entities (<package>textproc/iso8879</package>)</term>
<listitem>
<para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用, 包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 xml:id="tools-optional">
<title>輔助工具</title>
<para>不一定得裝下列的應用程式才行,但是,出的格式也更具彈性。</para>
<sect2>
<title>軟體</title>
<variablelist>
<varlistentry>
<term><application>Vim</application> (<package>editors/vim</package>)</term>
<listitem>
<para>一個很受歡迎的編輯器,可以處理 <acronym>XML</acronym> 和他的衍生相關文件,例如 DocBook <acronym>XML</acronym>。</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Emacs</application> 或 <application>XEmacs</application> (<package>editors/emacs</package> 或 <package>editors/xemacs</package>)</term>
<listitem>
<para>這兩個編輯器都包含特別模式來編輯用 <acronym>XML</acronym> <acronym>DTD</acronym> 標記的文件。這個模式包含指令來減少打字量,並可以幫忙減少錯誤的發生。</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
</chapter>
<!-- Copyright (c) 2013 Warren Block
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="working-copy">
<title>工作副本</title>
<para xml:lang="en">The <emphasis>working copy</emphasis> is a copy of the FreeBSD
repository documentation tree downloaded onto the local computer.
Changes are made to the local working copy, tested, and then
submitted as patches to be committed to the main
repository.</para>
<para xml:lang="en">A full copy of the documentation tree can occupy 700 megabytes
of disk space. Allow for a full gigabyte of space to have room
for temporary files and test versions of various output
formats.</para>
<para xml:lang="en"><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link>
is used to manage the FreeBSD documentation files. It is installed
by <package>textproc/docproj</package> as one of
the required applications.</para>
<sect1 xml:id="working-copy-doc-and-src">
<title xml:lang="en">Documentation and Manual Pages</title>
<para xml:lang="en">FreeBSD documentation is not just books and articles. Manual
pages for all the commands and configuration files are also part
of the documentation, and part of the <acronym>FDP</acronym>'s
territory. Two repositories are involved:
<literal>doc</literal> for the books and articles, and
<literal>base</literal> for the operating system and manual
pages. To edit manual pages, the <literal>base</literal>
repository must be checked out separately.</para>
<para xml:lang="en">Repositories may contain multiple versions of documentation
and source code. New modifications are almost always made only
to the latest version, called <literal>head</literal>.</para>
</sect1>
<sect1 xml:id="working-copy-choosing-directory">
<title xml:lang="en">Choosing a Directory</title>
<para xml:lang="en">FreeBSD documentation is traditionally stored in
<filename>/usr/doc/</filename>, and system
source code with manual pages in
<filename>/usr/src/</filename>. These
directory trees are relocatable, and users may want to put the
working copies in other locations to avoid interfering with
existing information in the main directories. The examples
that follow use <filename>~/doc</filename>
and <filename>~/src</filename>, both
subdirectories of the user's home directory.</para>
</sect1>
<sect1 xml:id="working-copy-checking-out">
<title xml:lang="en">Checking Out a Copy</title>
<para xml:lang="en">A download of a working copy from the repository is called
a <emphasis>checkout</emphasis>, and done with
<command>svn checkout</command>. This example checks out a
copy of the latest version (<literal>head</literal>) of
the main documentation tree:</para>
<screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
<para xml:lang="en">A checkout of the source code to work on manual pages is
very similar:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
</sect1>
<sect1 xml:id="working-copy-updating">
<title xml:lang="en">Updating a Working Copy</title>
<para xml:lang="en">The documents and files in the FreeBSD repository change daily.
People modify files and commit changes frequently. Even a short
time after an initial checkout, there will already be
differences between the local working copy and the main FreeBSD
repository. To update the local version with the changes that
have been made to the main repository, use
<command>svn update</command> on the directory containing the
local working copy:</para>
<screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>
<para xml:lang="en">Get in the protective habit of using
<command>svn update</command> before editing document files.
Someone else may have edited that file very recently, and the
local working copy will not include the latest changes until it
has been updated. Editing the newest version of a file is much
easier than trying to combine an older, edited local file with
the newer version from the repository.</para>
</sect1>
<sect1 xml:id="working-copy-revert">
<title xml:lang="en">Reverting Changes</title>
<para xml:lang="en">Sometimes it turns out that changes were
not necessary after all, or the writer just wants to start over.
Files can be <quote>reset</quote> to their unchanged form with
<command>svn revert</command>. For example, to erase the edits
made to <filename>chapter.xml</filename> and reset it to
unmodified form:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen>
</sect1>
<sect1 xml:id="working-copy-making-diff">
<title xml:lang="en">Making a Diff</title>
<para xml:lang="en">After edits to a file or group of files are completed, the
differences between the local working copy and the version on
the FreeBSD repository must be collected into a single file for
submission. These <emphasis>diff</emphasis> files are produced
by redirecting the output of <command>svn diff</command> into a
file:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>
<prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen>
<para xml:lang="en">Give the file a meaningful name that identifies the
contents. The example above is for spelling fixes to the whole
documentation tree.</para>
<para xml:lang="en">If the diff file is to be submitted with the web
<quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a FreeBSD
problem report</link></quote> interface, add a
<filename>.txt</filename> extension to give the earnest and
simple-minded web form a clue that the contents are plain
text.</para>
<para xml:lang="en">Be careful: <command>svn diff</command> includes all changes
made in the current directory and any subdirectories. If there
are files in the working copy with edits that are not ready to
be submitted yet, provide a list of only the files that are to
be included:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>
<prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen>
</sect1>
<sect1 xml:id="working-copy-subversion-references">
<title xml:lang="en"><application>Subversion</application> References</title>
<para xml:lang="en">These examples show very basic usage of
<application>Subversion</application>. More detail is available
in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link>
and the <link xlink:href="http://subversion.apache.org/docs/">Subversion
documentation</link>.</para>
</sect1>
</chapter>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="structure">
<title xml:lang="en">Documentation Directory Structure</title>
<para xml:lang="en">Files and directories in the
<filename>doc/</filename> tree follow a
structure meant to:</para>
<orderedlist>
<listitem>
<para xml:lang="en">Make it easy to automate converting the document to other
formats.</para>
</listitem>
<listitem>
<para xml:lang="en">Promote consistency between the different documentation
organizations, to make it easier to switch between working on
different documents.</para>
</listitem>
<listitem>
<para xml:lang="en">Make it easy to decide where in the tree new documentation
should be placed.</para>
</listitem>
</orderedlist>
<para xml:lang="en">In addition, the documentation tree must accommodate
documents in many different languages and encodings. It is
important that the documentation tree structure does not enforce
any particular defaults or cultural preferences.</para>
<sect1 xml:id="structure-top">
<title xml:lang="en">The Top Level,
<filename>doc/</filename></title>
<para xml:lang="en">There are two types of directory under
<filename>doc/</filename>, each with very
specific directory names and meanings.</para>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry xml:lang="en">Directory</entry>
<entry xml:lang="en">Usage</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top" xml:lang="en">
<filename>share</filename></entry>
<entry xml:lang="en">Contains files that are not specific to the various
translations and encodings of the documentation.
Contains subdirectories to further categorize the
information. For example, the files that comprise the
<citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> infrastructure are in
<filename>share/mk</filename>, while
the additional <acronym>XML</acronym> support files
(such as the FreeBSD extended DocBook
<acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry>
</row>
<row>
<entry valign="top" xml:lang="en">
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
<entry xml:lang="en">One directory exists for each available translation
and encoding of the documentation, for example
<filename>en_US.ISO8859-1/</filename>
and <filename>zh_TW.UTF-8/</filename>.
The names are long, but by fully specifying the language
and encoding we prevent any future headaches when a
translation team wants to provide documentation in the
same language but in more than one encoding. This also
avoids problems that might be caused by a future switch
to Unicode.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 xml:id="structure-locale">
<title xml:lang="en">The
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename>
Directories</title>
<para xml:lang="en">These directories contain the documents themselves. The
documentation is split into up to three more categories at
this level, indicated by the different directory names.</para>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry xml:lang="en">Directory</entry>
<entry xml:lang="en">Usage</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top" xml:lang="en">
<filename>articles</filename></entry>
<entry xml:lang="en">Documentation marked up as a DocBook
<tag>article</tag> (or equivalent). Reasonably
short, and broken up into sections. Normally only
available as one <acronym>XHTML</acronym> file.</entry>
</row>
<row>
<entry valign="top" xml:lang="en"><filename>books</filename></entry>
<entry xml:lang="en">Documentation marked up as a DocBook
<tag>book</tag> (or equivalent). Book length,
and broken up into chapters. Normally available as both
one large <acronym>XHTML</acronym> file (for people with
fast connections, or who want to print it easily from a
browser) and as a collection of linked, smaller
files.</entry>
</row>
<row>
<entry valign="top" xml:lang="en">
<filename>man</filename></entry>
<entry xml:lang="en">For translations of the system manual pages. This
directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename>
directories, corresponding to the sections that have
been translated.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para xml:lang="en">Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
directory will have all of these subdirectories. It depends
on how much translation has been accomplished by that
translation team.</para>
</sect1>
<sect1 xml:id="structure-document">
<title xml:lang="en">Document-Specific Information</title>
<para xml:lang="en">This section contains specific notes about particular
documents managed by the FDP.</para>
<sect2>
<title xml:lang="en">The Handbook</title>
<subtitle xml:lang="en"><filename>books/handbook/</filename></subtitle>
<para xml:lang="en">The Handbook is written in DocBook <acronym>XML</acronym>
using the FreeBSD DocBook extended <acronym>DTD</acronym>.</para>
<para xml:lang="en">The Handbook is organized as a DocBook
<tag>book</tag>. The book is divided into
<tag>part</tag>s, each of which contains several
<tag>chapter</tag>s. <tag>chapter</tag>s are
further subdivided into sections (<tag>sect1</tag>)
and subsections (<tag>sect2</tag>,
<tag>sect3</tag>) and so on.</para>
<sect3>
<title xml:lang="en">Physical Organization</title>
<para xml:lang="en">There are a number of files and directories within the
<filename>handbook</filename> directory.</para>
<note>
<para xml:lang="en">The Handbook's organization may change over time, and
this document may lag in detailing the organizational
changes. Post questions about Handbook organization to the
<link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
</note>
<sect4>
<title xml:lang="en"><filename>Makefile</filename></title>
<para xml:lang="en">The <filename>Makefile</filename> defines some
variables that affect how the <acronym>XML</acronym>
source is converted to other formats, and lists the
various source files that make up the Handbook. It then
includes the standard <filename>doc.project.mk</filename>,
to bring in the rest of the code that handles converting
documents from one format to another.</para>
</sect4>
<sect4>
<title xml:lang="en"><filename>book.xml</filename></title>
<para xml:lang="en">This is the top level document in the Handbook. It
contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that
describe the Handbook's structure.</para>
<para xml:lang="en"><filename>book.xml</filename> uses <link linkend="xml-primer-parameter-entities">parameter
entities</link> to load in the files with the
<filename>.ent</filename> extension. These files
(described later) then define <link linkend="xml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
</sect4>
<sect4>
<title xml:lang="en"><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
<para xml:lang="en">Each chapter in the Handbook is stored in a file
called <filename>chapter.xml</filename> in a separate
directory from the other chapters. Each directory is
named after the value of the <literal>id</literal>
attribute on the <tag>chapter</tag>
element.</para>
<para xml:lang="en">For example, if one of the chapter files
contains:</para>
<programlisting xml:lang="en"><tag class="starttag">chapter id="kernelconfig"</tag>
...
<tag class="endtag">chapter</tag></programlisting>
<para xml:lang="en">Then it will be called
<filename>chapter.xml</filename> in the
<filename>kernelconfig</filename> directory. In general,
the entire contents of the chapter are in this one
file.</para>
<para xml:lang="en">When the <acronym>XHTML</acronym> version of the
Handbook is produced, this will yield
<filename>kernelconfig.html</filename>. This is because
of the <literal>id</literal> value, and is not related to
the name of the directory.</para>
<para xml:lang="en">In earlier versions of the Handbook, the files were
stored in the same directory as
<filename>book.xml</filename>, and named after the value
of the <literal>id</literal> attribute on the file's
<tag>chapter</tag> element. Now, it is possible
to include images in each chapter. Images for each
Handbook chapter are stored within <filename>share/images/books/handbook</filename>.
The localized version of these images should be
placed in the same directory as the <acronym>XML</acronym>
sources for each chapter. Namespace collisions are
inevitable, and it is easier to work with several
directories with a few files in them than it is to work
with one directory that has many files in it.</para>
<para xml:lang="en">A brief look will show that there are many directories
with individual <filename>chapter.xml</filename> files,
including <filename>basics/chapter.xml</filename>,
<filename>introduction/chapter.xml</filename>, and
<filename>printing/chapter.xml</filename>.</para>
<important>
<para xml:lang="en">Do not name chapters or directories after
their ordering within the Handbook. This ordering can
change as the content within the Handbook is
reorganized. Reorganization should be possible without
renaming files, unless entire chapters are being
promoted or demoted within the hierarchy.</para>
</important>
<para xml:lang="en">The <filename>chapter.xml</filename> files are not
complete <acronym>XML</acronym> documents that can be
built individually. They can only be built
as parts of the whole Handbook.</para>
</sect4>
</sect3>
</sect2>
</sect1>
</chapter>
<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="doc-build">
<title xml:lang="en">The Documentation Build Process</title>
<para xml:lang="en">This chapter covers organization of the documentation build
process and how <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to control it.</para>
<sect1 xml:id="doc-build-rendering">
<title xml:lang="en">Rendering DocBook into Output</title>
<para xml:lang="en">Different types of output can be produced from a single
DocBook source file. The type of output desired is set with the
<varname>FORMATS</varname> variable. A list of known formats is
stored in <varname>KNOWN_FORMATS</varname>:</para>
<screen xml:id="doc-build-rendering-known-formats" xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
<prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput></screen>
<table xml:id="doc-build-rendering-common-formats" frame="none">
<title xml:lang="en">Common Output Formats</title>
<tgroup cols="3">
<thead>
<row>
<entry xml:lang="en"><varname>FORMATS</varname> Value</entry>
<entry xml:lang="en">File Type</entry>
<entry xml:lang="en">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry xml:lang="en"><literal>html</literal></entry>
<entry xml:lang="en"><acronym>HTML</acronym>, one file</entry>
<entry xml:lang="en">A single <filename>book.html</filename> or
<filename>article.html</filename>.</entry>
</row>
<row>
<entry xml:lang="en"><literal>html-split</literal></entry>
<entry xml:lang="en"><acronym>HTML</acronym>, multiple files</entry>
<entry xml:lang="en">Multiple <acronym>HTML</acronym> files, one for
each chapter or section, for use on a typical web
site.</entry>
</row>
<row>
<entry xml:lang="en"><literal>pdf</literal></entry>
<entry xml:lang="en"><acronym>PDF</acronym></entry>
<entry xml:lang="en">Portable Document Format</entry>
</row>
</tbody>
</tgroup>
</table>
<para xml:lang="en">The default output format can vary by document, but is
usually <literal>html-split</literal>. Other formats are chosen
by setting <varname>FORMATS</varname> to a specific value.
Multiple output formats can be created at a single time by
setting <varname>FORMATS</varname> to a list of formats.</para>
<example xml:id="doc-build-formats-example-html">
<title xml:lang="en">Build a Single HTML Output File</title>
<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
<prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen>
</example>
<example xml:id="doc-build-formats-example-html-split-pdf">
<title xml:lang="en">Build HTML-Split and <acronym>PDF</acronym> Output
Files</title>
<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
<prompt>%</prompt> <userinput>make FORMATS="html-split pdf"</userinput></screen>
</example>
</sect1>
<sect1 xml:id="doc-build-toolset">
<title xml:lang="en">The FreeBSD Documentation Build Toolset</title>
<para xml:lang="en">These are the tools used to build and install the
<acronym>FDP</acronym> documentation.</para>
<itemizedlist>
<listitem>
<para xml:lang="en">The primary build tool is <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, specifically
<application>Berkeley Make</application>.</para>
</listitem>
<listitem>
<para xml:lang="en">Package building is handled by FreeBSD's
<citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
</listitem>
<listitem>
<para xml:lang="en"><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to create compressed versions of
the document. <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> archives are also supported.
<citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used for package building.</para>
</listitem>
<listitem>
<para xml:lang="en"><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to install the
documentation.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="doc-build-makefiles">
<title xml:lang="en">Understanding <filename>Makefile</filename>s in the
Documentation Tree</title>
<para xml:lang="en">There are three main types of <filename>Makefile</filename>s
in the FreeBSD Documentation Project tree.</para>
<itemizedlist>
<listitem>
<para xml:lang="en"><link linkend="sub-make">Subdirectory
<filename>Makefile</filename>s</link> simply pass
commands to those directories below them.</para>
</listitem>
<listitem>
<para xml:lang="en"><link linkend="doc-make">Documentation
<filename>Makefile</filename>s</link> describe the
documents that are produced from this
directory.</para>
</listitem>
<listitem>
<para xml:lang="en"><link linkend="make-includes"><application>Make</application>
includes</link> are the glue that perform the document
production, and are usually of the form
<filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
</listitem>
</itemizedlist>
<sect2 xml:id="sub-make">
<title xml:lang="en">Subdirectory <filename>Makefile</filename>s</title>
<para xml:lang="en">These <filename>Makefile</filename>s usually take the form
of:</para>
<programlisting xml:lang="en">SUBDIR =articles
SUBDIR+=books
COMPAT_SYMLINK = en
DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
<para xml:lang="en">The first four non-empty lines define the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
variables <varname>SUBDIR</varname>,
<varname>COMPAT_SYMLINK</varname>, and
<varname>DOC_PREFIX</varname>.</para>
<para xml:lang="en">The <varname>SUBDIR</varname> statement and
<varname>COMPAT_SYMLINK</varname> statement show how to
assign a value to a variable, overriding any previous
value.</para>
<para xml:lang="en">The second <varname>SUBDIR</varname> statement shows how a
value is appended to the current value of a variable. The
<varname>SUBDIR</varname> variable is now <literal>articles
books</literal>.</para>
<para xml:lang="en">The <varname>DOC_PREFIX</varname> assignment shows how a
value is assigned to the variable, but only if it is not
already defined. This is useful if
<varname>DOC_PREFIX</varname> is not where this
<filename>Makefile</filename> thinks it is - the user can
override this and provide the correct value.</para>
<para xml:lang="en">What does it all mean? <varname>SUBDIR</varname>
mentions which subdirectories below this one the build process
should pass any work on to.</para>
<para xml:lang="en"><varname>COMPAT_SYMLINK</varname> is specific to
compatibility symlinks (amazingly enough) for languages to
their official encoding (<filename>doc/en</filename> would
point to <filename>en_US.ISO-8859-1</filename>).</para>
<para xml:lang="en"><varname>DOC_PREFIX</varname> is the path to the root of
the FreeBSD Document Project tree. This is not always that easy
to find, and is also easily overridden, to allow for
flexibility. <varname>.CURDIR</varname> is a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
builtin variable with the path to the current
directory.</para>
<para xml:lang="en">The final line includes the FreeBSD Documentation Project's
project-wide <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> system file
<filename>doc.project.mk</filename> which is the glue which
converts these variables into build instructions.</para>
</sect2>
<sect2 xml:id="doc-make">
<title xml:lang="en">Documentation <filename>Makefile</filename>s</title>
<para xml:lang="en">These <filename>Makefile</filename>s set <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
variables that describe how to build the documentation
contained in that directory.</para>
<para xml:lang="en">Here is an example:</para>
<programlisting xml:lang="en">MAINTAINER=nik@FreeBSD.org
DOC?= book
FORMATS?= html-split html
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
# SGML content
SRCS= book.xml
DOC_PREFIX?= ${.CURDIR}/../../..
.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
<para xml:lang="en">The <varname>MAINTAINER</varname> variable allows
committers to claim ownership of a document in the FreeBSD
Documentation Project, and take responsibility for maintaining
it.</para>
<para xml:lang="en"><varname>DOC</varname> is the name (sans the
<filename>.xml</filename> extension) of the main document
created by this directory. <varname>SRCS</varname> lists all
the individual files that make up the document. This should
also include important files in which a change should result
in a rebuild.</para>
<para xml:lang="en"><varname>FORMATS</varname> indicates the default formats
that should be built for this document.
<varname>INSTALL_COMPRESSED</varname> is the default list of
compression techniques that should be used in the document
build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by
default, should be non-empty if only compressed documents are
desired in the build.</para>
<para xml:lang="en">The <varname>DOC_PREFIX</varname> and include statements
should be familiar already.</para>
</sect2>
</sect1>
<sect1 xml:id="make-includes">
<title xml:lang="en">FreeBSD Documentation Project
<application>Make</application> Includes</title>
<para xml:lang="en"><citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes are best explained by inspection of
the code. Here are the system include files:</para>
<itemizedlist>
<listitem>
<para xml:lang="en"><filename>doc.project.mk</filename> is the main project
include file, which includes all the following include
files, as necessary.</para>
</listitem>
<listitem>
<para xml:lang="en"><filename>doc.subdir.mk</filename> handles traversing of
the document tree during the build and install
processes.</para>
</listitem>
<listitem>
<para xml:lang="en"><filename>doc.install.mk</filename> provides variables
that affect ownership and installation of documents.</para>
</listitem>
<listitem>
<para xml:lang="en"><filename>doc.docbook.mk</filename> is included if
<varname>DOCFORMAT</varname> is <literal>docbook</literal>
and <varname>DOC</varname> is set.</para>
</listitem>
</itemizedlist>
<sect2>
<title xml:lang="en"><filename>doc.project.mk</filename></title>
<para xml:lang="en">By inspection:</para>
<programlisting xml:lang="en">DOCFORMAT?= docbook
MAINTAINER?= doc@FreeBSD.org
PREFIX?= /usr/local
PRI_LANG?= en_US.ISO8859-1
.if defined(DOC)
.if ${DOCFORMAT} == "docbook"
.include "doc.docbook.mk"
.endif
.endif
.include "doc.subdir.mk"
.include "doc.install.mk"</programlisting>
<sect3>
<title xml:lang="en">Variables</title>
<para xml:lang="en"><varname>DOCFORMAT</varname> and
<varname>MAINTAINER</varname> are assigned default values,
if these are not set by the document make file.</para>
<para xml:lang="en"><varname>PREFIX</varname> is the prefix under which the
<link linkend="tools">documentation building tools</link>
are installed. For normal package and port installation,
this is <filename>/usr/local</filename>.</para>
<para xml:lang="en"><varname>PRI_LANG</varname> should be set to whatever
language and encoding is natural amongst users these
documents are being built for. US English is the
default.</para>
<note>
<para xml:lang="en"><varname>PRI_LANG</varname> does not affect which
documents can, or even will, be built. Its main use is
creating links to commonly referenced documents into the
FreeBSD documentation install root.</para>
</note>
</sect3>
<sect3>
<title xml:lang="en">Conditionals</title>
<para xml:lang="en">The <literal>.if defined(DOC)</literal> line is an
example of a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> conditional which, like in other
programs, defines behavior if some condition is true or if
it is false. <literal>defined</literal> is a function which
returns whether the variable given is defined or not.</para>
<para xml:lang="en"><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
tests whether the <varname>DOCFORMAT</varname> variable is
<literal>"docbook"</literal>, and in this case, includes
<filename>doc.docbook.mk</filename>.</para>
<para xml:lang="en">The two <literal>.endif</literal>s close the two above
conditionals, marking the end of their application.</para>
</sect3>
</sect2>
<sect2>
<title xml:lang="en"><filename>doc.subdir.mk</filename></title>
<para xml:lang="en">This file is too long to explain in detail. These notes
describe the most important features.</para>
<sect3>
<title xml:lang="en">Variables</title>
<itemizedlist>
<listitem>
<para xml:lang="en"><varname>SUBDIR</varname> is a list of
subdirectories that the build process should go further
down into.</para>
</listitem>
<listitem>
<para xml:lang="en"><varname>ROOT_SYMLINKS</varname> is the name of
directories that should be linked to the document
install root from their actual locations, if the current
language is the primary language (specified by
<varname>PRI_LANG</varname>).</para>
</listitem>
<listitem>
<para xml:lang="en"><varname>COMPAT_SYMLINK</varname> is described in
the
<link linkend="sub-make">Subdirectory Makefile</link>
section.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title xml:lang="en">Targets and Macros</title>
<para xml:lang="en">Dependencies are described by
<literal><replaceable>target</replaceable>:
<replaceable>dependency1 dependency2
...</replaceable></literal> tuples, where to build
<literal>target</literal>, the given
dependencies must be built first.</para>
<para xml:lang="en">After that descriptive tuple, instructions on how to
build the target may be given, if the conversion process
between the target and its dependencies are not previously
defined, or if this particular conversion is not the same as
the default conversion method.</para>
<para xml:lang="en">A special dependency <literal>.USE</literal> defines
the equivalent of a macro.</para>
<programlisting xml:lang="en">_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===> ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} && \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>
<para xml:lang="en">In the above, <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> is now
a macro which will execute the given commands when it is
listed as a dependency.</para>
<para xml:lang="en">What sets this macro apart from other targets?
Basically, it is executed <emphasis>after</emphasis> the
instructions given in the build procedure it is listed as a
dependency to, and it does not adjust
<varname>.TARGET</varname>, which is the variable which
contains the name of the target currently being
built.</para>
<programlisting xml:lang="en">clean: _SUBDIRUSE
rm -f ${CLEANFILES}</programlisting>
<para xml:lang="en">In the above, <buildtarget xml:lang="en">clean</buildtarget> will use
the <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> macro after it has
executed the instruction
<command>rm -f ${CLEANFILES}</command>. In effect, this
causes <buildtarget xml:lang="en">clean</buildtarget> to go further and
further down the directory tree, deleting built files as it
goes <emphasis>down</emphasis>, not on the way back
up.</para>
<sect4>
<title xml:lang="en">Provided Targets</title>
<itemizedlist>
<listitem>
<para xml:lang="en"><buildtarget xml:lang="en">install</buildtarget> and
<buildtarget xml:lang="en">package</buildtarget> both go down the
directory tree calling the real versions of themselves
in the subdirectories
(<buildtarget xml:lang="en">realinstall</buildtarget> and
<buildtarget xml:lang="en">realpackage</buildtarget>
respectively).</para>
</listitem>
<listitem>
<para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> removes files
created by the build process (and goes down the
directory tree too).
<buildtarget xml:lang="en">cleandir</buildtarget> does the same, and
also removes the object directory, if any.</para>
</listitem>
</itemizedlist>
</sect4>
</sect3>
<sect3>
<title xml:lang="en">More on Conditionals</title>
<itemizedlist>
<listitem>
<para xml:lang="en"><literal>exists</literal> is another condition
function which returns true if the given file
exists.</para>
</listitem>
<listitem>
<para xml:lang="en"><literal>empty</literal> returns true if the given
variable is empty.</para>
</listitem>
<listitem>
<para xml:lang="en"><literal>target</literal> returns true if the given
target does not already exist.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title xml:lang="en">Looping Constructs in <command>make
(.for)</command></title>
<para xml:lang="en"><literal>.for</literal> provides a way to repeat a set
of instructions for each space-separated element in a
variable. It does this by assigning a variable to contain
the current element in the list being examined.</para>
<programlisting xml:lang="en">_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===> ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} && \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>
<para xml:lang="en">In the above, if <varname>SUBDIR</varname> is empty, no
action is taken; if it has one or more elements, the
instructions between <literal>.for</literal> and
<literal>.endfor</literal> would repeat for every element,
with <varname>entry</varname> being replaced with the value
of the current element.</para>
</sect3>
</sect2>
</sect1>
</chapter>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="the-website">
<title>網站</title>
<para>FreeBSD 網站是 FreeBSD 文件的一部份。網站的檔案儲存在文件樹目錄,此例中是 <filename>~/doc</filename>,的 <filename>en_US.ISO8859-1/htdocs</filename> 子目錄。</para>
<sect1 xml:id="the-website-env">
<title>環境變數</title>
<para>有些環境變數控制網站的建構或安裝,和裝到哪個目錄</para>
<tip>
<para xml:lang="en">The web build system uses <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and considers
variables to be set when they have been defined, even if they
are empty. The examples here show the recommended ways of
defining and using these variables. Setting or defining these
variables with other values or methods might lead to
unexpected surprises.</para>
</tip>
<variablelist>
<varlistentry xml:id="the-website-env-destdir">
<term xml:lang="en"><varname>DESTDIR</varname></term>
<listitem>
<para xml:lang="en">DESTDIR specifies the path where the web site files
are to be installed.</para>
<para xml:lang="en">This variable is best set with <citerefentry><refentrytitle>env</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the user
shell's method of setting environment variables,
<command>setenv</command> for <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
<command>export</command> for <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry xml:id="the-website-env-englishonly">
<term xml:lang="en"><varname>ENGLISH_ONLY</varname></term>
<listitem>
<para xml:lang="en">Default: undefined. Build and include all
translations.</para>
<para xml:lang="en"><userinput>ENGLISH_ONLY=yes</userinput>: use only
the English documents and ignore all translations.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="the-website-env-webonly">
<term xml:lang="en"><varname>WEB_ONLY</varname></term>
<listitem>
<para xml:lang="en">Default: undefined. Build both the web site
and all the books and articles.</para>
<para xml:lang="en"><userinput>WEB_ONLY=yes</userinput>: build or install
only <acronym>HTML</acronym> pages from the
<filename>en_US.ISO8859-1/htdocs</filename> directory.
Other directories and documents, including books and
articles, will be ignored.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="the-website-env-weblang">
<term xml:lang="en"><varname>WEB_LANG</varname></term>
<listitem>
<para xml:lang="en">Default: undefined. Build and include all the
available languages on the web site.</para>
<para xml:lang="en">Set to a space-separated list of languages to be
included in the build
or install. The formats are the same as the directory
names in the document root directory. For example, to
include the German and French documents:</para>
<screen xml:lang="en"><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen>
</listitem>
</varlistentry>
</variablelist>
<para xml:lang="en"><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
and <varname>ENGLISH_ONLY</varname> are <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables
and can be set in <filename>/etc/make.conf</filename>,
<filename>Makefile.inc</filename>, as environment variables on
the command line, or in dot files.</para>
</sect1>
<sect1 xml:id="the-website-build">
<title xml:lang="en">Building and Installing the Web Pages</title>
<para xml:lang="en">Having obtained the documentation and web site source files,
the web site can be built.</para>
<para xml:lang="en">An actual installation of the web site is run as the <systemitem class="username">root</systemitem>
user because the permissions on the web server directory will
not allow files to be installed by an unprivileged user.
For testing, it can be useful to install the files as a normal
user to a temporary directory.</para>
<para xml:lang="en">In these examples, the web site files are built by user
<systemitem class="username">jru</systemitem> in their home
directory, <filename>~/doc</filename>, with a full path of
<filename>/usr/home/jru/doc</filename>.</para>
<tip>
<para xml:lang="en">The web site build uses the <filename>INDEX</filename>
from the Ports Collection and might fail if that file or
<filename>/usr/ports</filename> is not
present. The simplest approach is to install the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/ports.html#ports-tree">Ports
Collection</link>.</para>
</tip>
<example xml:id="the-website-examples-build">
<title xml:lang="en">Build the Full Web Site and All Documents</title>
<para xml:lang="en">Build the web site and all documents. The resulting files
are left in the document tree:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
<prompt>%</prompt> <userinput>make all</userinput></screen>
</example>
<example xml:id="the-website-examples-buildinstall-englishonly">
<title xml:lang="en">Build Only the Web Site in English</title>
<para xml:lang="en">Build the web site only, in English, as user
<systemitem class="username">jru</systemitem>, and install
the resulting files into <filename>/tmp/www</filename> for
testing:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
<prompt>%</prompt> <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen>
<para xml:lang="en">Changes to static files can usually be tested by viewing
the modified files directly with a web browser. If the site
has been built as shown above, a modified main page can be
viewed with:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>firefox /tmp/www/data/index.html</userinput></screen>
<para xml:lang="en">Modifications to dynamic files can be tested with a web
server running on the local system. After building the site
as shown above, this
<filename>/usr/local/etc/apache24/httpd.conf</filename> can be
used with <package>www/apache24</package>:</para>
<programlisting xml:lang="en"># httpd.conf for testing the FreeBSD website
Define TestRoot "/tmp/www/data"
# directory for configuration files
ServerRoot "/usr/local"
Listen 80
# minimum required modules
LoadModule authz_core_module libexec/apache24/mod_authz_core.so
LoadModule mime_module libexec/apache24/mod_mime.so
LoadModule unixd_module libexec/apache24/mod_unixd.so
LoadModule cgi_module libexec/apache24/mod_cgi.so
LoadModule dir_module libexec/apache24/mod_dir.so
# run the webserver as user and group
User www
Group www
ServerAdmin you@example.com
ServerName fbsdtest
# deny access to all files
<Directory />
AllowOverride none
Require all denied
</Directory>
# allow access to the website directory
DocumentRoot "${TestRoot}"
<Directory "${TestRoot}">
Options Indexes FollowSymLinks
AllowOverride None
Require all granted
</Directory>
# prevent access to .htaccess and .htpasswd files
<Files ".ht*">
Require all denied
</Files>
ErrorLog "/var/log/httpd-error.log"
LogLevel warn
# set up the CGI script directory
<Directory "${TestRoot}/cgi">
AllowOverride None
Options None
Require all granted
Options +ExecCGI
AddHandler cgi-script .cgi
</Directory>
Include etc/apache24/Includes/*.conf</programlisting>
<para xml:lang="en">Start the web server with</para>
<screen xml:lang="en"><prompt>#</prompt> <userinput>service apache24 onestart</userinput></screen>
<para xml:lang="en">The web site can be viewed at
<link xlink:href="http://localhost"/>. Be aware that many
links refer to the real FreeBSD site by name, and those links
will still go to the external site instead of the local test
version. Fully testing the local site will require
temporarily setting <acronym>DNS</acronym> so
<literal>www.FreeBSD.org</literal> resolves to
<literal>localhost</literal> or the local
<acronym>IP</acronym> address.</para>
</example>
<example xml:id="the-website-examples-buildinstall">
<title xml:lang="en">Build and Install the Web Site</title>
<para xml:lang="en">Build the web site and all documents as user
<systemitem class="username">jru</systemitem>. Install the
resulting files as
<systemitem class="username">root</systemitem> into the
default directory,
<filename>/root/public_html</filename>:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
<prompt>%</prompt> <userinput>make all</userinput>
<prompt>%</prompt> <userinput>su -</userinput>
Password:
<prompt>#</prompt> <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
<prompt>#</prompt> <userinput>make install</userinput></screen>
</example>
<para xml:lang="en">The install process does not delete any old or outdated
files that existed previously in the same directory. If a new
copy of the site is built and installed every day, this command
will find and delete all files that have not been updated in
three days:</para>
<screen xml:lang="en"><prompt>#</prompt> <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
</sect1>
</chapter>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="xml-primer">
<title xml:lang="en">XML Primer</title>
<para xml:lang="en">Most <acronym>FDP</acronym> documentation is written with
markup languages based on <acronym>XML</acronym>. This chapter
explains what that means, how to read and understand the
documentation source, and the <acronym>XML</acronym> techniques
used.</para>
<para xml:lang="en">Portions of this section were inspired by Mark Galassi's
<link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
Going With DocBook</link>.</para>
<sect1 xml:id="xml-primer-overview">
<title>概論</title>
<para xml:lang="en">In the original days of computers, electronic text was
simple. There were a few character sets like
<acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, but that
was about it. Text was text, and what you saw really was what
you got. No frills, no formatting, no intelligence.</para>
<para xml:lang="en">Inevitably, this was not enough. When text is in a
machine-usable format, machines are expected to be able to use
and manipulate it intelligently. Authors want to indicate that
certain phrases should be emphasized, or added to a glossary, or
made into hyperlinks. Filenames could be shown in a
<quote>typewriter</quote> style font for viewing on screen, but
as <quote>italics</quote> when printed, or any of a myriad of
other options for presentation.</para>
<para xml:lang="en">It was once hoped that Artificial Intelligence (AI) would
make this easy. The computer would read the document and
automatically identify key phrases, filenames, text that the
reader should type in, examples, and more. Unfortunately, real
life has not happened quite like that, and computers still
require assistance before they can meaningfully process
text.</para>
<para xml:lang="en">More precisely, they need help identifying what is what.
Consider this text:</para>
<blockquote>
<para xml:lang="en">To remove <filename>/tmp/foo</filename>, use
<citerefentry><refentrytitle>rm</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>rm /tmp/foo</userinput></screen>
</blockquote>
<para xml:lang="en">It is easy to see which parts are filenames, which are
commands to be typed in, which parts are references to manual
pages, and so on. But the computer processing the document
cannot. For this we need markup.</para>
<para xml:lang="en"><quote>Markup</quote> is commonly used to describe
<quote>adding value</quote> or <quote>increasing cost</quote>.
The term takes on both these meanings when applied to text.
Markup is additional text included in the document,
distinguished from the document's content in some way, so that
programs that process the document can read the markup and use
it when making decisions about the document. Editors can hide
the markup from the user, so the user is not distracted by
it.</para>
<para xml:lang="en">The extra information stored in the markup
<emphasis>adds value</emphasis> to the document. Adding the
markup to the document must typically be done by a
person—after all, if computers could recognize the text
sufficiently well to add the markup then there would be no need
to add it in the first place. This
<emphasis>increases the cost</emphasis> (the effort required) to
create the document.</para>
<para xml:lang="en">The previous example is actually represented in this
document like this:</para>
<programlisting xml:lang="en"><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &man.rm.1;.<tag class="endtag">para</tag>
<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>
<para xml:lang="en">The markup is clearly separate from the content.</para>
<para xml:lang="en">Markup languages define what the markup means and how it
should be interpreted.</para>
<para xml:lang="en">Of course, one markup language might not be enough. A
markup language for technical documentation has very different
requirements than a markup language that is intended for cookery
recipes. This, in turn, would be very different from a markup
language used to describe poetry. What is really needed is a
first language used to write these other markup languages. A
<emphasis>meta markup language</emphasis>.</para>
<para xml:lang="en">This is exactly what the eXtensible Markup
Language (<acronym>XML</acronym>) is. Many markup languages
have been written in <acronym>XML</acronym>, including the two
most used by the <acronym>FDP</acronym>,
<acronym>XHTML</acronym> and DocBook.</para>
<para xml:lang="en">Each language definition is more properly called a grammar,
vocabulary, schema or Document Type Definition
(<acronym>DTD</acronym>). There are various languages to
specify an <acronym>XML</acronym> grammar, or
<emphasis>schema</emphasis>.</para>
<para xml:id="xml-primer-validating" xml:lang="en">A schema is a
<emphasis>complete</emphasis> specification of all the elements
that are allowed to appear, the order in which they should
appear, which elements are mandatory, which are optional, and so
forth. This makes it possible to write an
<acronym>XML</acronym> <emphasis>parser</emphasis> which reads
in both the schema and a document which claims to conform to the
schema. The parser can then confirm whether or not all the
elements required by the vocabulary are in the document in the
right order, and whether there are any errors in the markup.
This is normally referred to as
<quote>validating the document</quote>.</para>
<note>
<para xml:lang="en">Validation confirms that the choice of
elements, their ordering, and so on, conforms to that listed
in the grammar. It does <emphasis>not</emphasis> check
whether <emphasis>appropriate</emphasis> markup has been used
for the content. If all the filenames in a document were
marked up as function names, the parser would not flag this as
an error (assuming, of course, that the schema defines
elements for filenames and functions, and that they are
allowed to appear in the same place).</para>
</note>
<para xml:lang="en">Most contributions to the Documentation
Project will be content marked up in either
<acronym>XHTML</acronym> or DocBook, rather than alterations to
the schemas. For this reason, this book will not touch on how
to write a vocabulary.</para>
</sect1>
<sect1 xml:id="xml-primer-elements">
<title xml:lang="en">Elements, Tags, and Attributes</title>
<para xml:lang="en">All the vocabularies written in <acronym>XML</acronym> share
certain characteristics. This is hardly surprising, as the
philosophy behind <acronym>XML</acronym> will inevitably show
through. One of the most obvious manifestations of this
philosophy is that of <emphasis>content</emphasis> and
<emphasis>elements</emphasis>.</para>
<para xml:lang="en">Documentation, whether it is a single web page, or a lengthy
book, is considered to consist of content. This content is then
divided and further subdivided into elements. The purpose of
adding markup is to name and identify the boundaries of these
elements for further processing.</para>
<para xml:lang="en">For example, consider a typical book. At the very top
level, the book is itself an element. This <quote>book</quote>
element obviously contains chapters, which can be considered to
be elements in their own right. Each chapter will contain more
elements, such as paragraphs, quotations, and footnotes. Each
paragraph might contain further elements, identifying content
that was direct speech, or the name of a character in the
story.</para>
<para xml:lang="en">It may be helpful to think of this as
<quote>chunking</quote> content. At the very top level is one
chunk, the book. Look a little deeper, and there are more
chunks, the individual chapters. These are chunked further into
paragraphs, footnotes, character names, and so on.</para>
<para xml:lang="en">Notice how this differentiation between different elements
of the content can be made without resorting to any
<acronym>XML</acronym> terms. It really is surprisingly
straightforward. This could be done with a highlighter pen and
a printout of the book, using different colors to indicate
different chunks of content.</para>
<para xml:lang="en">Of course, we do not have an electronic highlighter pen, so
we need some other way of indicating which element each piece of
content belongs to. In languages written in
<acronym>XML</acronym> (<acronym>XHTML</acronym>, DocBook, et
al) this is done by means of <emphasis>tags</emphasis>.</para>
<para xml:lang="en">A tag is used to identify where a particular element starts,
and where the element ends. <emphasis>The tag is not part of
the element itself</emphasis>. Because each grammar was
normally written to mark up specific types of information, each
one will recognize different elements, and will therefore have
different names for the tags.</para>
<para xml:lang="en">For an element called
<replaceable>element-name</replaceable> the start tag will
normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>.
The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para>
<example>
<title xml:lang="en">Using an Element (Start and End Tags)</title>
<para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating
that the content enclosed by the element is a paragraph,
called <tag>p</tag>.</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for
the 'p' element, and it will end with the end tag for the 'p'
element.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting>
</example>
<para xml:lang="en">Some elements have no content. For example, in
<acronym>XHTML</acronym>, a horizontal line can be included in
the document. For these <quote>empty</quote> elements,
<acronym>XML</acronym> introduced a shorthand form that is
completely equivalent to the two-tag version:</para>
<example>
<title xml:lang="en">Using an Element Without Content</title>
<para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating a
horizontal rule, called <tag>hr</tag>. This element
does not wrap content, so it looks like this:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
<tag class="starttag">hr</tag><tag class="endtag">hr</tag>
<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
from the previous paragraph.<tag class="endtag">p</tag></programlisting>
<para xml:lang="en">The shorthand version consists of a single tag:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
<tag class="emptytag">hr</tag>
<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
from the previous paragraph.<tag class="endtag">p</tag></programlisting>
</example>
<para xml:lang="en">As shown above, elements can contain other elements. In the
book example earlier, the book element contained all the chapter
elements, which in turn contained all the paragraph elements,
and so on.</para>
<example>
<title xml:lang="en">Elements Within Elements; <tag>em</tag></title>
<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some
of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting>
</example>
<para xml:lang="en">The grammar consists of rules that describe which elements
can contain other elements, and exactly what they can
contain.</para>
<important>
<para xml:lang="en">People often confuse the terms tags and elements, and use
the terms as if they were interchangeable. They are
not.</para>
<para xml:lang="en">An element is a conceptual part of your document. An
element has a defined start and end. The tags mark where the
element starts and ends.</para>
<para xml:lang="en">When this document (or anyone else knowledgeable about
<acronym>XML</acronym>) refers to
<quote>the <tag class="starttag">p</tag> tag</quote>
they mean the literal text consisting of the three characters
<literal><</literal>, <literal>p</literal>, and
<literal>></literal>. But the phrase
<quote>the <tag>p</tag> element</quote> refers to the
whole element.</para>
<para xml:lang="en">This distinction <emphasis>is</emphasis> very subtle. But
keep it in mind.</para>
</important>
<para xml:lang="en">Elements can have attributes. An attribute has a name and a
value, and is used for adding extra information to the element.
This might be information that indicates how the content should
be rendered, or might be something that uniquely identifies that
occurrence of the element, or it might be something else.</para>
<para xml:lang="en">An element's attributes are written
<emphasis>inside</emphasis> the start tag for that element, and
take the form
<literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
<para xml:lang="en">In <acronym>XHTML</acronym>, the <tag>p</tag>
element has an attribute called
<tag class="attribute">align</tag>, which suggests an
alignment (justification) for the paragraph to the program
displaying the <acronym>XHTML</acronym>.</para>
<para xml:lang="en">The <tag class="attribute">align</tag> attribute can
take one of four defined values, <literal>left</literal>,
<literal>center</literal>, <literal>right</literal> and
<literal>justify</literal>. If the attribute is not specified
then the default is <literal>left</literal>.</para>
<example>
<title xml:lang="en">Using an Element with an Attribute</title>
<programlisting xml:lang="en"><tag class="starttag">p align="left"</tag>The inclusion of the align attribute
on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag>
<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting>
</example>
<para xml:lang="en">Some attributes only take specific values, such as
<literal>left</literal> or <literal>justify</literal>. Others
allow any value.</para>
<example>
<title xml:lang="en">Single Quotes Around Attributes</title>
<programlisting xml:lang="en"><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting>
</example>
<para xml:lang="en">Attribute values in <acronym>XML</acronym> must be enclosed
in either single or double quotes. Double quotes are
traditional. Single quotes are useful when the attribute value
contains double quotes.</para>
<para xml:lang="en">Information about attributes, elements, and tags is stored
in catalog files. The Documentation Project uses standard
DocBook catalogs and includes additional catalogs for
FreeBSD-specific features. Paths to the catalog files are defined
in an environment variable so they can be found by the document
build tools.</para>
<sect2>
<title xml:lang="en">To Do…</title>
<para xml:lang="en">Before running the examples in this document, install
<package>textproc/docproj</package> from
the FreeBSD Ports Collection. This is a
<emphasis>meta-port</emphasis> that downloads and installs
the standard programs and supporting files needed by the
Documentation Project. <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> users must use
<command>rehash</command> for the shell to recognize new
programs after they have been installed, or log out
and then log back in again.</para>
<procedure>
<step>
<para xml:lang="en">Create <filename>example.xml</filename>, and enter
this text:</para>
<programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag>
<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<tag class="starttag">head</tag>
<tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
<tag class="endtag">head</tag>
<tag class="starttag">body</tag>
<tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
<tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
<tag class="endtag">body</tag>
<tag class="endtag">html</tag></programlisting>
</step>
<step>
<para xml:lang="en">Try to validate this file using an
<acronym>XML</acronym> parser.</para>
<para xml:lang="en"><package>textproc/docproj</package>
includes the <command>xmllint</command>
<link linkend="xml-primer-validating">validating
parser</link>.</para>
<para xml:lang="en">Use <command>xmllint</command> to validate the
document:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput></screen>
<para xml:lang="en"><command>xmllint</command> returns without displaying
any output, showing that the document validated
successfully.</para>
</step>
<step>
<para xml:lang="en">See what happens when required elements are omitted.
Delete the line with the
<tag class="starttag">title</tag> and
<tag class="endtag">title</tag> tags, and re-run
the validation.</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput>
example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen>
<para xml:lang="en">This shows that the validation error comes from the
<replaceable>fifth</replaceable> line of the
<replaceable>example.xml</replaceable> file and that the
content of the <tag class="starttag">head</tag> is
the part which does not follow the rules of the
<acronym>XHTML</acronym> grammar.</para>
<para xml:lang="en">Then <command>xmllint</command> shows the line where
the error was found and marks the exact character position
with a <literal>^</literal> sign.</para>
</step>
<step>
<para xml:lang="en">Replace the <tag>title</tag> element.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 xml:id="xml-primer-doctype-declaration">
<title xml:lang="en">The DOCTYPE Declaration</title>
<para xml:lang="en">The beginning of each document can specify the name of the
<acronym>DTD</acronym> to which the document conforms. This
DOCTYPE declaration is used by <acronym>XML</acronym> parsers to
identify the <acronym>DTD</acronym> and ensure that the document
does conform to it.</para>
<para xml:lang="en">A typical declaration for a document written to conform with
version 1.0 of the <acronym>XHTML</acronym>
<acronym>DTD</acronym> looks like this:</para>
<programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting>
<para xml:lang="en">That line contains a number of different components.</para>
<variablelist>
<varlistentry>
<term xml:lang="en"><literal><!</literal></term>
<listitem>
<para xml:lang="en">The <emphasis>indicator</emphasis> shows
this is an <acronym>XML</acronym> declaration.</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><literal>DOCTYPE</literal></term>
<listitem>
<para xml:lang="en">Shows that this is an <acronym>XML</acronym>
declaration of the document type.</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><literal>html</literal></term>
<listitem>
<para xml:lang="en">Names the first
<link linkend="xml-primer-elements">element</link> that
will appear in the document.</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</literal></term>
<listitem>
<para xml:lang="en">Lists the Formal Public Identifier
(<acronym>FPI</acronym>)
<indexterm xml:lang="en">
<primary>Formal Public Identifier</primary>
</indexterm>
for the <acronym>DTD</acronym> to which this document
conforms. The <acronym>XML</acronym> parser uses this to
find the correct <acronym>DTD</acronym> when processing
this document.</para>
<para xml:lang="en"><literal>PUBLIC</literal> is not a part of the
<acronym>FPI</acronym>, but indicates to the
<acronym>XML</acronym> processor how to find the
<acronym>DTD</acronym> referenced in the
<acronym>FPI</acronym>. Other ways of telling the
<acronym>XML</acronym> parser how to find the
<acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
<listitem>
<para xml:lang="en">A local filename or a <acronym>URL</acronym> to find
the <acronym>DTD</acronym>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><literal>></literal></term>
<listitem>
<para xml:lang="en">Ends the declaration and returns to the
document.</para>
</listitem>
</varlistentry>
</variablelist>
<sect2>
<title xml:lang="en">Formal Public Identifiers
(<acronym>FPI</acronym>s)</title>
<indexterm significance="preferred" xml:lang="en">
<primary>Formal Public Identifier</primary>
</indexterm>
<note>
<para xml:lang="en">It is not necessary to know this, but it is useful
background, and might help debug problems when the
<acronym>XML</acronym> processor can not locate the
<acronym>DTD</acronym>.</para>
</note>
<para xml:lang="en"><acronym>FPI</acronym>s must follow a specific
syntax:</para>
<programlisting xml:lang="en">"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
<variablelist>
<varlistentry>
<term xml:lang="en"><replaceable>Owner</replaceable></term>
<listitem>
<para xml:lang="en">The owner of the <acronym>FPI</acronym>.</para>
<para xml:lang="en">The beginning of the string identifies the owner of
the <acronym>FPI</acronym>. For example, the
<acronym>FPI</acronym>
<literal>"ISO 8879:1986//ENTITIES Greek
Symbols//EN"</literal> lists
<literal>ISO 8879:1986</literal> as being the owner for
the set of entities for Greek symbols.
<acronym>ISO</acronym> 8879:1986 is the International
Organization for Standardization
(<acronym>ISO</acronym>) number for the
<acronym>SGML</acronym> standard, the predecessor (and a
superset) of <acronym>XML</acronym>.</para>
<para xml:lang="en">Otherwise, this string will either look like
<literal>-//<replaceable>Owner</replaceable></literal>
or
<literal>+//<replaceable>Owner</replaceable></literal>
(notice the only difference is the leading
<literal>+</literal> or <literal>-</literal>).</para>
<para xml:lang="en">If the string starts with <literal>-</literal> then
the owner information is unregistered, with a
<literal>+</literal> identifying it as
registered.</para>
<para xml:lang="en"><acronym>ISO</acronym> 9070:1991 defines how
registered names are generated. It might be derived
from the number of an <acronym>ISO</acronym>
publication, an <acronym>ISBN</acronym> code, or an
organization code assigned according to
<acronym>ISO</acronym> 6523. Additionally, a
registration authority could be created in order to
assign registered names. The <acronym>ISO</acronym>
council delegated this to the American National
Standards Institute (<acronym>ANSI</acronym>).</para>
<para xml:lang="en">Because the FreeBSD Project has not been registered,
the owner string is <literal>-//FreeBSD</literal>. As seen
in the example, the <acronym>W3C</acronym> are not a
registered owner either.</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><replaceable>Keyword</replaceable></term>
<listitem>
<para xml:lang="en">There are several keywords that indicate the type of
information in the file. Some of the most common
keywords are <literal>DTD</literal>,
<literal>ELEMENT</literal>, <literal>ENTITIES</literal>,
and <literal>TEXT</literal>. <literal>DTD</literal> is
used only for <acronym>DTD</acronym> files,
<literal>ELEMENT</literal> is usually used for
<acronym>DTD</acronym> fragments that contain only
entity or element declarations. <literal>TEXT</literal>
is used for <acronym>XML</acronym> content (text and
tags).</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><replaceable>Description</replaceable></term>
<listitem>
<para xml:lang="en">Any description can be given for the contents
of this file. This may include version numbers or any
short text that is meaningful and unique for the
<acronym>XML</acronym> system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term xml:lang="en"><replaceable>Language</replaceable></term>
<listitem>
<para xml:lang="en">An <acronym>ISO</acronym> two-character code that
identifies the native language for the file.
<literal>EN</literal> is used for English.</para>
</listitem>
</varlistentry>
</variablelist>
<sect3>
<title xml:lang="en"><filename>catalog</filename> Files</title>
<para xml:lang="en">With the syntax above, an <acronym>XML</acronym>
processor needs to have some way of turning the
<acronym>FPI</acronym> into the name of the file containing
the <acronym>DTD</acronym>. A catalog file (typically
called <filename>catalog</filename>) contains lines that map
<acronym>FPI</acronym>s to filenames. For example, if the
catalog file contained the line:</para>
<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog -->
<programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting>
<para xml:lang="en">The <acronym>XML</acronym> processor knows that the
<acronym>DTD</acronym> is called
<filename>transitional.dtd</filename> in the
<filename>1.0</filename> subdirectory of the directory that
held <filename>catalog</filename>.</para>
<para xml:lang="en">Examine the contents of
<filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
This is the catalog file for the <acronym>XHTML</acronym>
<acronym>DTD</acronym>s that were installed as part of the
<package>textproc/docproj</package> port.</para>
</sect3>
</sect2>
<sect2 xml:id="xml-primer-fpi-alternatives">
<title xml:lang="en">Alternatives to <acronym>FPI</acronym>s</title>
<para xml:lang="en">Instead of using an <acronym>FPI</acronym> to indicate the
<acronym>DTD</acronym> to which the document conforms (and
therefore, which file on the system contains the
<acronym>DTD</acronym>), the filename can be explicitly
specified.</para>
<para xml:lang="en">The syntax is slightly different:</para>
<programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting>
<para xml:lang="en">The <literal>SYSTEM</literal> keyword indicates that the
<acronym>XML</acronym> processor should locate the
<acronym>DTD</acronym> in a system specific fashion. This
typically (but not always) means the <acronym>DTD</acronym>
will be provided as a filename.</para>
<para xml:lang="en">Using <acronym>FPI</acronym>s is preferred for reasons of
portability. If the <literal>SYSTEM</literal> identifier is
used, then the <acronym>DTD</acronym> must be provided and
kept in the same location for everyone.</para>
</sect2>
</sect1>
<sect1 xml:id="xml-primer-xml-escape">
<title xml:lang="en">Escaping Back to <acronym>XML</acronym></title>
<para xml:lang="en">Some of the underlying <acronym>XML</acronym> syntax can be
useful within documents. For example, comments can be included
in the document, and will be ignored by the parser. Comments
are entered using <acronym>XML</acronym> syntax. Other uses for
<acronym>XML</acronym> syntax will be shown later.</para>
<para xml:lang="en"><acronym>XML</acronym> sections begin with a
<literal><!</literal> tag and end with a
<literal>></literal>. These sections contain instructions
for the parser rather than elements of the document. Everything
between these tags is <acronym>XML</acronym> syntax. The
<link linkend="xml-primer-doctype-declaration">DOCTYPE
declaration</link> shown earlier is an example of
<acronym>XML</acronym> syntax included in the document.</para>
</sect1>
<sect1 xml:id="xml-primer-comments">
<title xml:lang="en">Comments</title>
<para xml:lang="en">An <acronym>XML</acronym> document may contain comments.
They may appear anywhere as long as they are not inside tags.
They are even allowed in some locations inside the
<acronym>DTD</acronym> (e.g., between <link linkend="xml-primer-entities">entity
declarations</link>).</para>
<para xml:lang="en"><acronym>XML</acronym> comments start with the string
<quote><literal><!--</literal></quote> and end with the
string <quote><literal>--></literal></quote>.</para>
<para xml:lang="en">Here are some examples of valid <acronym>XML</acronym>
comments:</para>
<example>
<title xml:lang="en"><acronym>XML</acronym> Generic Comments</title>
<programlisting xml:lang="en"><!-- This is inside the comment -->
<!--This is another comment-->
<!-- This is how you
write multiline comments -->
<p>A simple <!-- Comment inside an element's content --> paragraph.</p></programlisting>
</example>
<para xml:lang="en"><acronym>XML</acronym> comments may contain any strings
except <quote><literal>--</literal></quote>:</para>
<example>
<title xml:lang="en">Erroneous <acronym>XML</acronym> Comment</title>
<programlisting xml:lang="en"><!-- This comment--is wrong --></programlisting>
</example>
<sect2>
<title xml:lang="en">To Do…</title>
<procedure>
<step>
<para xml:lang="en">Add some comments to
<filename>example.xml</filename>, and check that the file
still validates using <command>xmllint</command>.</para>
</step>
<step>
<para xml:lang="en">Add some invalid comments to
<filename>example.xml</filename>, and see the error
messages that <command>xmllint</command> gives when it
encounters an invalid comment.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 xml:id="xml-primer-entities">
<title xml:lang="en">Entities</title>
<para xml:lang="en">Entities are a mechanism for assigning names to chunks of
content. As an <acronym>XML</acronym> parser processes a
document, any entities it finds are replaced by the content of
the entity.</para>
<para xml:lang="en">This is a good way to have re-usable, easily changeable
chunks of content in <acronym>XML</acronym> documents. It is
also the only way to include one marked up file inside another
using <acronym>XML</acronym>.</para>
<para xml:lang="en">There are two types of entities for two different
situations: <emphasis>general entities</emphasis> and
<emphasis>parameter entities</emphasis>.</para>
<sect2 xml:id="xml-primer-general-entities">
<title xml:lang="en">General Entities</title>
<para xml:lang="en">General entities are used to assign names to reusable
chunks of text. These entities can only be used in the
document. They cannot be used in an
<acronym>XML</acronym> context.</para>
<para xml:lang="en">To include the text of a general entity in the document,
include
<literal>&<replaceable>entity-name</replaceable>;</literal>
in the text. For example, consider a general entity called
<literal>current.version</literal> which expands to the
current version number of a product. To use it in the
document, write:</para>
<programlisting xml:lang="en"><tag class="starttag">para</tag>The current version of our product is
&current.version;.<tag class="endtag">para</tag></programlisting>
<para xml:lang="en">When the version number changes, edit the definition of
the general entity, replacing the value. Then reprocess the
document.</para>
<para xml:lang="en">General entities can also be used to enter characters that
could not otherwise be included in an <acronym>XML</acronym>
document. For example, <literal><</literal> and
<literal>&</literal> cannot normally appear in an
<acronym>XML</acronym> document. The <acronym>XML</acronym>
parser sees the <literal><</literal> symbol as the start of
a tag. Likewise, when the <literal>&</literal> symbol is
seen, the next text is expected to be an entity name.</para>
<para xml:lang="en">These symbols can be included by using two predefined
general entities: <literal>&lt;</literal> and
<literal>&amp;</literal>.</para>
<para xml:lang="en">General entities can only be defined within an
<acronym>XML</acronym> context. Such definitions are usually
done immediately after the DOCTYPE declaration.</para>
<example>
<title xml:lang="en">Defining General Entities</title>
<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY current.version "3.0-RELEASE">
<!ENTITY last.version "2.2.7-RELEASE">
]></programlisting>
<para xml:lang="en">The DOCTYPE declaration has been extended by adding a
square bracket at the end of the first line. The two
entities are then defined over the next two lines, the
square bracket is closed, and then the DOCTYPE declaration
is closed.</para>
<para xml:lang="en">The square brackets are necessary to indicate that the
DTD indicated by the DOCTYPE declaration is being
extended.</para>
</example>
</sect2>
<sect2 xml:id="xml-primer-parameter-entities">
<title xml:lang="en">Parameter Entities</title>
<para xml:lang="en">Parameter entities, like
<link linkend="xml-primer-general-entities">general
entities</link>, are used to assign names to reusable chunks
of text. But parameter entities can only be used within an
<link linkend="xml-primer-xml-escape">XML
context</link>.</para>
<para xml:lang="en">Parameter entity definitions are similar to those for
general entities. However, parameter entries are included
with
<literal>%<replaceable>entity-name</replaceable>;</literal>.
The definition also includes the <literal>%</literal> between
the <literal>ENTITY</literal> keyword and the name of the
entity.</para>
<para xml:lang="en">For a mnemonic, think
<quote><emphasis>P</emphasis>arameter entities use the
<emphasis>P</emphasis>ercent symbol</quote>.</para>
<example>
<title xml:lang="en">Defining Parameter Entities</title>
<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % param.some "some">
<!ENTITY % param.text "text">
<!ENTITY % param.new "%param.some more %param.text">
<!-- %param.new now contains "some more text" -->
]></programlisting>
</example>
</sect2>
<sect2>
<title xml:lang="en">To Do…</title>
<procedure>
<step>
<para xml:lang="en">Add a general entity to
<filename>example.xml</filename>.</para>
<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
]>
<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<tag class="starttag">head</tag>
<tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
<tag class="endtag">head</tag>
<!-- There may be some comments in here as well -->
<tag class="starttag">body</tag>
<tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
<tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag>
<tag class="endtag">body</tag>
<tag class="endtag">html</tag></programlisting>
</step>
<step>
<para xml:lang="en">Validate the document using
<command>xmllint</command>.</para>
</step>
<step>
<para xml:lang="en">Load <filename>example.xml</filename> into a web
browser. It may have to be copied to
<filename>example.html</filename> before the browser
recognizes it as an <acronym>XHTML</acronym>
document.</para>
<para xml:lang="en">Older browsers with simple parsers may not render this
file as expected. The entity reference
<literal>&version;</literal> may not be replaced by
the version number, or the <acronym>XML</acronym> context
closing <literal>]></literal> may not be recognized and
instead shown in the output.</para>
</step>
<step>
<para xml:lang="en">The solution is to <emphasis>normalize</emphasis> the
document with an <acronym>XML</acronym> normalizer. The
normalizer reads valid <acronym>XML</acronym> and writes
equally valid <acronym>XML</acronym> which has been
transformed in some way. One way the normalizer
transforms the input is by expanding all the entity
references in the document, replacing the entities with
the text that they represent.</para>
<para xml:lang="en"><command>xmllint</command> can be used for this. It
also has an option to drop the initial
<acronym>DTD</acronym> section so that the closing
<literal>]></literal> does not confuse browsers:</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput></screen>
<para xml:lang="en">A normalized copy of the document with entities
expanded is produced in <filename>example.html</filename>,
ready to load into a web browser.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 xml:id="xml-primer-include">
<title xml:lang="en">Using Entities to Include Files</title>
<para xml:lang="en">Both
<link linkend="xml-primer-general-entities">general</link> and
<link linkend="xml-primer-parameter-entities">parameter</link>
entities are particularly useful for including one file inside
another.</para>
<sect2 xml:id="xml-primer-include-using-gen-entities">
<title xml:lang="en">Using General Entities to Include Files</title>
<para xml:lang="en">Consider some content for an <acronym>XML</acronym> book
organized into files, one file per chapter, called
<filename>chapter1.xml</filename>,
<filename>chapter2.xml</filename>, and so forth, with a
<filename>book.xml</filename> that will contain these
chapters.</para>
<para xml:lang="en">In order to use the contents of these files as the values
for entities, they are declared with the
<literal>SYSTEM</literal> keyword. This directs the
<acronym>XML</acronym> parser to include the contents of the
named file as the value of the entity.</para>
<example>
<title xml:lang="en">Using General Entities to Include Files</title>
<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!-- And so forth -->
]>
<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<!-- Use the entities to load in the chapters -->
&chapter.1;
&chapter.2;
&chapter.3;
<tag class="endtag">html</tag></programlisting>
</example>
<warning>
<para xml:lang="en">When using general entities to include other files
within a document, the files being included
(<filename>chapter1.xml</filename>,
<filename>chapter2.xml</filename>, and so on)
<emphasis>must not</emphasis> start with a DOCTYPE
declaration. This is a syntax error because entities are
low-level constructs and they are resolved before any
parsing happens.</para>
</warning>
</sect2>
<sect2>
<title xml:lang="en">Using Parameter Entities to Include Files</title>
<para xml:lang="en">Parameter entities can only be used inside an
<acronym>XML</acronym> context. Including a file in an
<acronym>XML</acronym> context can be used
to ensure that general entities are reusable.</para>
<para xml:lang="en">Suppose that there are many chapters in the document, and
these chapters were reused in two different books, each book
organizing the chapters in a different fashion.</para>
<para xml:lang="en">The entities could be listed at the top of each book, but
that quickly becomes cumbersome to manage.</para>
<para xml:lang="en">Instead, place the general entity definitions inside one
file, and use a parameter entity to include that file within
the document.</para>
<example>
<title xml:lang="en">Using Parameter Entities to Include Files</title>
<para xml:lang="en">Place the entity definitions in a separate file
called <filename>chapters.ent</filename> and
containing this text:</para>
<programlisting xml:lang="en"><!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml"></programlisting>
<para xml:lang="en">Create a parameter entity to refer to the contents
of the file. Then use the parameter entity to load the file
into the document, which will then make all the general
entities available for use. Then use the general entities
as before:</para>
<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!-- Define a parameter entity to load in the chapter general entities -->
<!ENTITY % chapters SYSTEM "chapters.ent">
<!-- Now use the parameter entity to load in this file -->
%chapters;
]>
<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
&chapter.1;
&chapter.2;
&chapter.3;
<tag class="endtag">html</tag></programlisting>
</example>
</sect2>
<sect2>
<title xml:lang="en">To Do…</title>
<sect3>
<title xml:lang="en">Use General Entities to Include Files</title>
<procedure>
<step>
<para xml:lang="en">Create three files, <filename>para1.xml</filename>,
<filename>para2.xml</filename>, and
<filename>para3.xml</filename>.</para>
<para xml:lang="en">Put content like this in each file:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting>
</step>
<step>
<para xml:lang="en">Edit <filename>example.xml</filename> so that it
looks like this:</para>
<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
]>
<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<tag class="starttag">head</tag>
<tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
<tag class="endtag">head</tag>
<tag class="starttag">body</tag>
<tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag>
&para1;
&para2;
&para3;
<tag class="endtag">body</tag>
<tag class="endtag">html</tag></programlisting>
</step>
<step>
<para xml:lang="en">Produce <filename>example.html</filename> by
normalizing <filename>example.xml</filename>.</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen>
</step>
<step>
<para xml:lang="en">Load <filename>example.html</filename> into the web
browser and confirm that the
<filename>para<replaceable>n</replaceable>.xml</filename>
files have been included in
<filename>example.html</filename>.</para>
</step>
</procedure>
</sect3>
<sect3>
<title xml:lang="en">Use Parameter Entities to Include Files</title>
<note>
<para xml:lang="en">The previous steps must have completed before this
step.</para>
</note>
<procedure>
<step>
<para xml:lang="en">Edit <filename>example.xml</filename> so that it
looks like this:</para>
<programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % entities SYSTEM "entities.ent"> %entities;
]>
<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<tag class="starttag">head</tag>
<tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
<tag class="endtag">head</tag>
<tag class="starttag">body</tag>
<tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag>
&para1;
&para2;
&para3;
<tag class="endtag">body</tag>
<tag class="endtag">html</tag></programlisting>
</step>
<step>
<para xml:lang="en">Create a new file called
<filename>entities.ent</filename> with this
content:</para>
<programlisting xml:lang="en"><!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml"></programlisting>
</step>
<step>
<para xml:lang="en">Produce <filename>example.html</filename> by
normalizing <filename>example.xml</filename>.</para>
<screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen>
</step>
<step>
<para xml:lang="en">Load <filename>example.html</filename> into the web
browser and confirm that the
<filename>para<replaceable>n</replaceable>.xml</filename>
files have been included in
<filename>example.html</filename>.</para>
</step>
</procedure>
</sect3>
</sect2>
</sect1>
<sect1 xml:id="xml-primer-marked-sections">
<title xml:lang="en">Marked Sections</title>
<para xml:lang="en"><acronym>XML</acronym> provides a mechanism to indicate that
particular pieces of the document should be processed in a
special way. These are called
<quote>marked sections</quote>.</para>
<example>
<title xml:lang="en">Structure of a Marked Section</title>
<programlisting xml:lang="en"><![<replaceable>KEYWORD</replaceable>[
Contents of marked section
]]></programlisting>
</example>
<para xml:lang="en">As expected of an <acronym>XML</acronym> construct, a marked
section starts with <literal><!</literal>.</para>
<para xml:lang="en">The first square bracket begins the marked section.</para>
<para xml:lang="en"><replaceable>KEYWORD</replaceable> describes how this marked
section is to be processed by the parser.</para>
<para xml:lang="en">The second square bracket indicates the start of the
marked section's content.</para>
<para xml:lang="en">The marked section is finished by closing the two square
brackets, and then returning to the document context from the
<acronym>XML</acronym> context with
<literal>></literal>.</para>
<sect2 xml:id="xml-primer-marked-section-keywords">
<title xml:lang="en">Marked Section Keywords</title>
<sect3 xml:id="xml-primer-cdata">
<title xml:lang="en"><literal>CDATA</literal></title>
<para xml:lang="en">These keywords denote the marked sections
<emphasis>content model</emphasis>, and allow you to change
it from the default.</para>
<para xml:lang="en">When an <acronym>XML</acronym> parser is processing a
document, it keeps track of the
<quote>content model</quote>.</para>
<para xml:lang="en">The content model describes the
content the parser is expecting to see and what it will do
with that content.</para>
<para xml:lang="en">The <literal>CDATA</literal> content model is one of the
most useful.</para>
<para xml:lang="en"><literal>CDATA</literal> is for
<quote>Character Data</quote>. When the parser is in this
content model, it expects to see only characters. In this
model the <literal><</literal> and
<literal>&</literal> symbols lose their special status,
and will be treated as ordinary characters.</para>
<note>
<para xml:lang="en">When using <literal>CDATA</literal> in examples of
text marked up in <acronym>XML</acronym>, remember that
the content of <literal>CDATA</literal> is not validated.
The included text must be check with other means. For
example, the content could be written in another document,
validated, and then pasted into the
<literal>CDATA</literal> section.</para>
</note>
<example>
<title xml:lang="en">Using a <literal>CDATA</literal> Marked
Section</title>
<programlisting xml:lang="en"><tag class="starttag">para</tag>Here is an example of how to include some text that contains
many <tag class="starttag">literal</tag>&lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;<tag class="endtag">literal</tag>
symbols. The sample text is a fragment of
<tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and
<tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag>
<tag class="starttag">programlisting</tag><![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the
elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle
brackets are used so many times, it is simpler to say the whole
example is a CDATA marked section than to use the entity names for
the left and right angle brackets throughout.<tag class="endtag">p</tag>
<tag class="starttag">ul</tag>
<tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag>
<tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag>
<tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag>
<tag class="endtag">ul</tag>
<tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting>
</example>
</sect3>
<sect3 xml:id="xml-primer-include-ignore">
<title xml:lang="en"><literal>INCLUDE</literal> and
<literal>IGNORE</literal></title>
<para xml:lang="en">When the keyword is <literal>INCLUDE</literal>, then the
contents of the marked section will be processed. When the
keyword is <literal>IGNORE</literal>, the marked section
is ignored and will not be processed. It will not appear in
the output.</para>
<example>
<title xml:lang="en">Using <literal>INCLUDE</literal> and
<literal>IGNORE</literal> in Marked Sections</title>
<programlisting xml:lang="en"><![INCLUDE[
This text will be processed and included.
]]>
<![IGNORE[
This text will not be processed or included.
]]></programlisting>
</example>
<para xml:lang="en">By itself, this is not too useful. Text to be
removed from the document could be cut out, or wrapped
in comments.</para>
<para xml:lang="en">It becomes more useful when controlled by
<link linkend="xml-primer-parameter-entities">parameter
entities</link>, yet this usage is limited
to entity files.</para>
<para xml:lang="en">For example, suppose that documentation was produced in
a hard-copy version and an electronic version. Some extra
text is desired in the electronic version content that was
not to appear in the hard-copy.</para>
<para xml:lang="en">Create an entity file that defines general entities to
include each chapter and guard these definitions with a
parameter entity that can be set to either
<literal>INCLUDE</literal> or <literal>IGNORE</literal> to
control whether the entity is defined. After these
conditional general entity definitions, place one more
definition for each general entity to set them to an empty
value. This technique makes use of the fact that entity
definitions cannot be overridden but the first definition
always takes effect. So the inclusion of the chapter is
controlled with the corresponding parameter entity. Set to
<literal>INCLUDE</literal>, the first general entity
definition will be read and the second one will be ignored.
Set to <literal>IGNORE</literal>, the first definition will
be ignored and the second one will take effect.</para>
<example>
<title xml:lang="en">Using a Parameter Entity to Control a Marked
Section</title>
<programlisting xml:lang="en"><!ENTITY % electronic.copy "INCLUDE">
<![%electronic.copy;[
<!ENTITY chap.preface SYSTEM "preface.xml">
]]>
<!ENTITY chap.preface ""></programlisting>
<para xml:lang="en">When producing the hard-copy version, change the
parameter entity's definition to:</para>
<programlisting xml:lang="en"><!ENTITY % electronic.copy "IGNORE"></programlisting>
</example>
</sect3>
</sect2>
<sect2>
<title xml:lang="en">To Do…</title>
<procedure>
<step>
<para xml:lang="en">Modify <filename>entities.ent</filename> to
contain the following:</para>
<programlisting xml:lang="en"><!ENTITY version "1.1">
<!ENTITY % conditional.text "IGNORE">
<![%conditional.text;[
<!ENTITY para1 SYSTEM "para1.xml">
]]>
<!ENTITY para1 "">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml"></programlisting>
</step>
<step>
<para xml:lang="en">Normalize <filename>example.xml</filename>
and notice that the conditional text is not present in the
output document. Set the parameter entity
guard to <literal>INCLUDE</literal> and regenerate the
normalized document and the text will appear again.
This method makes sense if there are more
conditional chunks depending on the same condition. For
example, to control generating printed or online
text.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 xml:id="xml-primer-conclusion">
<title xml:lang="en">Conclusion</title>
<para xml:lang="en">That is the conclusion of this <acronym>XML</acronym>
primer. For reasons of space and complexity, several things
have not been covered in depth (or at all). However, the
previous sections cover enough <acronym>XML</acronym> to
introduce the organization of the <acronym>FDP</acronym>
documentation.</para>
</sect1>
</chapter>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter version="5.0" xml:id="xhtml-markup">
<title xml:lang="en"><acronym>XHTML</acronym> Markup</title>
<sect1 xml:id="xhtml-markup-introduction">
<title xml:lang="en">Introduction</title>
<para xml:lang="en">This chapter describes usage of the <acronym>XHTML</acronym>
markup language used for the FreeBSD web site.</para>
<para xml:lang="en"><acronym>XHTML</acronym> is the <acronym>XML</acronym>
version of the HyperText Markup Language, the markup language of
choice on the World Wide Web. More information can be found at
<uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>
<para xml:lang="en"><acronym>XHTML</acronym> is used to mark up pages on the
FreeBSD web site. It is usually not used to mark up other
documentation, since DocBook offers a far richer set of elements
from which to choose. Consequently, <acronym>XHTML</acronym>
pages will normally only be encountered when writing for the web
site.</para>
<para xml:lang="en"><acronym>HTML</acronym> has gone through a number of
versions. The <acronym>XML</acronym>-compliant version
described here is called <acronym>XHTML</acronym>. The latest
widespread version is <acronym>XHTML</acronym> 1.0, available in
both <emphasis>strict</emphasis> and
<emphasis>transitional</emphasis> variants.</para>
<para xml:lang="en">The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
available from the Ports Collection in
<package>textproc/xhtml</package>. They are
automatically installed by the <package>textproc/docproj</package> port.</para>
<note>
<para xml:lang="en">This is <emphasis>not</emphasis> an exhaustive list of
elements, since that would just repeat the documentation for
<acronym>XHTML</acronym>. The aim is to list those elements
most commonly used. Please post questions about elements or
uses not covered here to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
</note>
<note>
<title xml:lang="en">Inline Versus Block</title>
<para xml:lang="en">In the remainder of this document, when describing
elements, <emphasis>inline</emphasis> means that the element
can occur within a block element, and does not cause a line
break. A <emphasis>block</emphasis> element, by comparison,
will cause a line break (and other processing) when it is
encountered.</para>
</note>
</sect1>
<sect1 xml:id="xhtml-markup-fpi">
<title xml:lang="en">Formal Public Identifier (<acronym>FPI</acronym>)</title>
<para xml:lang="en">There are a number of <acronym>XHTML</acronym>
<acronym>FPI</acronym>s, depending upon the version, or
<emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
a document conforms. Most <acronym>XHTML</acronym> documents on
the FreeBSD web site comply with the transitional version of
<acronym>XHTML</acronym> 1.0.</para>
<programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
</sect1>
<sect1 xml:id="xhtml-markup-sectional-elements">
<title xml:lang="en">Sectional Elements</title>
<para xml:lang="en">An <acronym>XHTML</acronym> document is normally split into
two sections. The first section, called the
<emphasis>head</emphasis>, contains meta-information about the
document, such as its title, the name of the author, the parent
document, and so on. The second section, the
<emphasis>body</emphasis>, contains content that will be
displayed to the user.</para>
<para xml:lang="en">These sections are indicated with <tag>head</tag>
and <tag>body</tag> elements respectively. These
elements are contained within the top-level
<tag>html</tag> element.</para>
<example>
<title xml:lang="en">Normal <acronym>XHTML</acronym> Document
Structure</title>
<programlisting xml:lang="en"><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<tag class="starttag">head</tag>
<tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag>
<tag class="endtag">head</tag>
<tag class="starttag">body</tag>
…
<tag class="endtag">body</tag>
<tag class="endtag">html</tag></programlisting>
</example>
</sect1>
<sect1 xml:id="xhtml-markup-block-elements">
<title xml:lang="en">Block Elements</title>
<sect2 xml:id="xhtml-markup-block-elements-headings">
<title xml:lang="en">Headings</title>
<para xml:lang="en"><acronym>XHTML</acronym> has tags to denote headings in
the document at up to six different levels.</para>
<para xml:lang="en">The largest and most prominent heading is
<tag>h1</tag>, then <tag>h2</tag>,
continuing down to <tag>h6</tag>.</para>
<para xml:lang="en">The element's content is the text of the heading.</para>
<example>
<title xml:lang="en"><tag>h1</tag>, <tag>h2</tag>,
and Other Header Tags</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag>
<!-- Document introduction goes here -->
<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag>
<!-- Content for the first section goes here -->
<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag>
<!-- Content for the first sub-section goes here -->
<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag>
<!-- Content for the second section goes here --></programlisting>
</example>
<para xml:lang="en">Generally, an <acronym>XHTML</acronym> page should have
one first level heading (<tag>h1</tag>). This can
contain many second level headings (<tag>h2</tag>),
which can in turn contain many third level headings. Do not
leave gaps in the numbering.</para>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-paragraphs">
<title xml:lang="en">Paragraphs</title>
<para xml:lang="en"><acronym>XHTML</acronym> supports a single paragraph
element, <tag>p</tag>.</para>
<example>
<title xml:lang="en"><tag>p</tag> Example</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It can contain just about any
other element.<tag class="endtag">p</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-block-quotations">
<title xml:lang="en">Block Quotations</title>
<para xml:lang="en">A block quotation is an extended quotation from another
document that will appear in a separate paragraph.</para>
<example>
<title xml:lang="en"><tag>blockquote</tag> Example</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag>
<tag class="starttag">blockquote</tag>We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic
Tranquility, provide for the common defence, promote the general
Welfare, and secure the Blessings of Liberty to ourselves and our
Posterity, do ordain and establish this Constitution for the
United States of America.<tag class="endtag">blockquote</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-lists">
<title xml:lang="en">Lists</title>
<para xml:lang="en"><acronym>XHTML</acronym> can present the user with three
types of lists: ordered, unordered, and definition.</para>
<para xml:lang="en">Entries in an ordered list will be numbered, while entries
in an unordered list will be preceded by bullet points.
Definition lists have two sections for each entry. The first
section is the term being defined, and the second section is
the definition.</para>
<para xml:lang="en">Ordered lists are indicated by the <tag>ol</tag>
element, unordered lists by the <tag>ul</tag>
element, and definition lists by the <tag>dl</tag>
element.</para>
<para xml:lang="en">Ordered and unordered lists contain listitems, indicated
by the <tag>li</tag> element. A listitem can
contain textual content, or it may be further wrapped in one
or more <tag>p</tag> elements.</para>
<para xml:lang="en">Definition lists contain definition terms
(<tag>dt</tag>) and definition descriptions
(<tag>dd</tag>). A definition term can only contain
inline elements. A definition description can contain other
block elements.</para>
<example>
<title xml:lang="en"><tag>ul</tag> and
<tag>ol</tag> Example</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>An unordered list. Listitems will probably be
preceded by bullets.<tag class="endtag">p</tag>
<tag class="starttag">ul</tag>
<tag class="starttag">li</tag>First item<tag class="endtag">li</tag>
<tag class="starttag">li</tag>Second item<tag class="endtag">li</tag>
<tag class="starttag">li</tag>Third item<tag class="endtag">li</tag>
<tag class="endtag">ul</tag>
<tag class="starttag">p</tag>An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be
numbered.<tag class="endtag">p</tag>
<tag class="starttag">ol</tag>
<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item. It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag>
<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third
item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
<tag class="endtag">ol</tag></programlisting>
</example>
<example>
<title xml:lang="en">Definition Lists with <tag>dl</tag></title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">dl</tag>
<tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag>
<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
<tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag>
<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
<tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag>
<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
<tag class="endtag">dl</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-preformatted-text">
<title xml:lang="en">Pre-formatted Text</title>
<para xml:lang="en">Pre-formatted text is shown to the user exactly as it is
in the file. Text is shown in a fixed font. Multiple spaces
and line breaks are shown exactly as they are in the
file.</para>
<para xml:lang="en">Wrap pre-formatted text in the <tag>pre</tag>
element.</para>
<example>
<title xml:lang="en"><tag>pre</tag> Example</title>
<para xml:lang="en">For example, the <tag>pre</tag> tags could be
used to mark up an email message:</para>
<programlisting xml:lang="en"><tag class="starttag">pre</tag> From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org
Subject: New documentation available
There is a new copy of my primer for contributors to the FreeBSD
Documentation Project available at
&lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;
Comments appreciated.
N<tag class="endtag">pre</tag></programlisting>
<para xml:lang="en">Keep in mind that <literal><</literal> and
<literal>&</literal> still are recognized as special
characters in pre-formatted text. This is why the example
shown had to use <literal>&lt;</literal> instead of
<literal><</literal>. For consistency,
<literal>&gt;</literal> was used in place of
<literal>></literal>, too. Watch out for the special
characters that may appear in text copied from a plain-text
source, like an email message or program code.</para>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-tables">
<title xml:lang="en">Tables</title>
<para xml:lang="en">Mark up tabular information using the
<tag>table</tag> element. A table consists of one or
more table rows (<tag>tr</tag>), each containing one
or more cells of table data (<tag>td</tag>). Each
cell can contain other block elements, such as paragraphs or
lists. It can also contain another table (this nesting can
repeat indefinitely). If the cell only contains one paragraph
then the <tag>p</tag>element is not needed.</para>
<example>
<title xml:lang="en">Simple Use of <tag>table</tag></title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
<para xml:lang="en">A cell can span multiple rows and columns by adding the
<tag class="attribute">rowspan</tag> or
<tag class="attribute">colspan</tag> attributes with
values for the number of rows or columns to be spanned.</para>
<example>
<title xml:lang="en">Using
<tag class="attribute">rowspan</tag></title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to
it on the right.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
<example>
<title xml:lang="en">Using
<tag class="attribute">colspan</tag></title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
<example>
<title xml:lang="en">Using <tag class="attribute">rowspan</tag> and
<tag class="attribute">colspan</tag>
Together</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of
cells merged into one. The other cells are normal.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<!-- Because the large cell on the left merges into
this row, the first <td> will occur on its
right -->
<tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom middle cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
</sect2>
</sect1>
<sect1 xml:id="xhtml-markup-inline-elements">
<title xml:lang="en">In-line Elements</title>
<sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">
<title xml:lang="en">Emphasizing Information</title>
<para xml:lang="en">Two levels of emphasis are available in
<acronym>XHTML</acronym>, <tag>em</tag> and
<tag>strong</tag>. <tag>em</tag> is for a
normal level of emphasis and <tag>strong</tag>
indicates stronger emphasis.</para>
<para xml:lang="en"><tag>em</tag> is typically rendered in italic
and <tag>strong</tag> is rendered in bold. This is
not always the case, and should not be relied upon. According
to best practices, web pages only hold structural and
semantical information, and stylesheets are later applied to
them. Think of semantics, not formatting, when using these
tags.</para>
<example>
<title xml:lang="en"><tag>em</tag> and
<tag>strong</tag> Example</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while
<tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text">
<title xml:lang="en">Indicating Fixed-Pitch Text</title>
<para xml:lang="en">Content that should be rendered in a fixed pitch
(typewriter) typeface is tagged with <tag>tt</tag>
(for <quote>teletype</quote>).</para>
<example>
<title xml:lang="en"><tag>tt</tag> Example</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>Many system settings are stored in
<tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-inline-elements-links">
<title xml:lang="en">Links</title>
<note>
<para xml:lang="en">Links are also inline elements.</para>
</note>
<sect3 xml:id="xhtml-markup-inline-elements-linking">
<title xml:lang="en">Linking to Other Documents on the Web</title>
<para xml:lang="en">A link points to the <acronym>URL</acronym> of a
document on the web. The link is indicated with
<tag>a</tag>, and the
<tag class="attribute">href</tag> attribute contains
the <acronym>URL</acronym> of the target document. The
content of the element becomes the link, indicated to the
user by showing it in a different color or with an
underline.</para>
<example>
<title xml:lang="en">Using
<tag class="starttag">a href="..."</tag></title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p</tag>More information is available at the
<tag class="starttag">a href="http://www.&os;.org/"</tag>&os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting>
</example>
<para xml:lang="en">This link always takes the user to the top of the linked
document.</para>
</sect3>
<sect3 xml:id="xhtml-markup-inline-elements-specific-parts">
<title xml:lang="en">Linking to Specific Parts of Documents</title>
<para xml:lang="en">To link to a specific point within a document, that
document must include an <emphasis>anchor</emphasis> at the
desired point. Anchors are included by setting the
<tag class="attribute">id</tag> attribute of an
element to a name. This example creates an anchor by
setting the <tag class="attribute">id</tag>
attribute of a <tag class="element">p</tag>
element.</para>
<example>
<title xml:lang="en">Creating an Anchor</title>
<para xml:lang="en">Usage:</para>
<programlisting xml:lang="en"><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced
in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>
<para xml:lang="en">Links to anchors are similar to plain links, but include
a <literal>#</literal> symbol and the anchor's
<acronym>ID</acronym> at the end of the
<acronym>URL</acronym>.</para>
<example>