diff options
| author | Kevin Lo <kevlo@FreeBSD.org> | 2016-06-21 01:19:43 +0000 |
|---|---|---|
| committer | Kevin Lo <kevlo@FreeBSD.org> | 2016-06-21 01:19:43 +0000 |
| commit | e920a09b0e01b29663e506f99e9f743b2bde2610 (patch) | |
| tree | 70cabc3a3de14ac91d5c144b8d06a92ae14b3d02 /zh_TW.UTF-8/books/fdp-primer/book.xml | |
| parent | e14d1d2172ccd8f466d1ca944fbf37deca817298 (diff) | |
| download | doc-e920a09b0e01b29663e506f99e9f743b2bde2610.tar.gz doc-e920a09b0e01b29663e506f99e9f743b2bde2610.zip | |
- Move all usable previous translation to the po translation of
zh_TW fdp-primer.
- New translation of Chapter 12 PO translation
Submitted by: RayCherng Yu <raycherng at gmail dot com>
Reviewed by: wblock
Differential Revision: https://reviews.freebsd.org/D6869
Notes
Notes:
svn path=/head/; revision=48972
Diffstat (limited to 'zh_TW.UTF-8/books/fdp-primer/book.xml')
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/book.xml | 8638 |
1 files changed, 8563 insertions, 75 deletions
diff --git a/zh_TW.UTF-8/books/fdp-primer/book.xml b/zh_TW.UTF-8/books/fdp-primer/book.xml index 0863eb87ba..cb0dbad186 100644 --- a/zh_TW.UTF-8/books/fdp-primer/book.xml +++ b/zh_TW.UTF-8/books/fdp-primer/book.xml @@ -1,8 +1,32 @@ <?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -]> +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ +<!ENTITY % chapters SYSTEM "chapters.ent"> +<!-- + Creates entities for each chapter in the Documentation Project Primer. + Each entity is named chap.foo, where foo is the value of the id + attribute on that chapter, and corresponds to the name of the + directory in which that chapter's .xml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ +--><!ENTITY chap.overview SYSTEM "overview/chapter.xml"> +<!ENTITY chap.tools SYSTEM "tools/chapter.xml"> +<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml"> +<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> +<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> +<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> +<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> +<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> +<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> +<!ENTITY chap.translations SYSTEM "translations/chapter.xml"> +<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml"> +<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml"> +<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml"> +<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml"> +<!ENTITY app.examples SYSTEM "examples/appendix.xml"> +<!-- ENTITY index SYSTEM "index.xml" -->]> <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. Redistribution and use in source (SGML DocBook) and 'compiled' forms @@ -33,71 +57,96 @@ POSSIBILITY OF SUCH DAMAGE. $FreeBSD$ - Original revision: 1.27 --> -<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw"> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW"> <info><title>FreeBSD 文件計畫入門書</title> <author><orgname>FreeBSD 文件計劃</orgname></author> - <copyright> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <holder role="mailto:doceng@FreeBSD.org">DocEng</holder> - </copyright> + <copyright><year>1998</year> <year>1999</year> <year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <holder role="mailto:doceng@FreeBSD.org">DocEng</holder></copyright> <pubdate role="rcs">$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - &legalnotice; + +<legalnotice xml:id="legalnotice"> + <title>版權</title> + + <para xml:lang="en">Redistribution and use in source (XML DocBook) and 'compiled' + forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions are + met:</para> + + <orderedlist> + <listitem> + <para xml:lang="en">Redistributions of source code (XML DocBook) must retain the + above copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified.</para> + </listitem> + + <listitem> + <para xml:lang="en">Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must + reproduce the above copyright notice, this list of conditions and + the following disclaimer in the documentation and/or other + materials provided with the distribution.</para> + </listitem> + </orderedlist> + + <important> + <para xml:lang="en">THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION + PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, + BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL + THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, + BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR + TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE + USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + DAMAGE.</para> + </important> +</legalnotice> + <abstract> - <para>感謝您參與 FreeBSD 文件計劃(簡稱：FDP, FreeBSD Documentation Project)，您的點滴貢獻，都相當寶貴。</para> + <para>感謝您參與 FreeBSD 文件計劃，您的點滴貢獻，都相當寶貴。</para> - <para>本入手書內容包括：如何開始著手翻譯的各項細節，以及會用到的一些好用工具(包括：必備工具、輔助工具) - ，以及文件計畫的宗旨。</para> + <para>本入手書內容包括：如何開始著手貢獻FreeBSD 文件計劃 (簡稱： <acronym>FDP</acronym> )的各項細節，以及會用到的一些工具、軟體 ，以及文件計畫的宗旨。</para> - <para>本文件還在草稿，尚未完稿。未完成的章節，我們會在章節名稱旁邊加註『<literal>*</literal> 』以作識別。</para> + <para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para> </abstract> </info> <preface xml:id="preface"> - <title>序言</title> + <title>序</title> <sect1 xml:id="preface-prompts"> <title>Shell 提示符號(Prompts)</title> - <para>下表顯示出一般帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt) - ，來提醒您該用哪種帳號才對。</para> + <para>下表顯示出一般使用者帳號與 root 的提示符號，在所有的文件例子中會用提示符號(prompt) ，來提醒您該用哪種帳號才對。</para> <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> <entry>帳號</entry> - <entry>提示符號(Prompt)</entry> + <entry>提示符號</entry> </row> </thead> <tbody> <row> - <entry>普通帳號</entry> - <entry>&prompt.user;</entry> + <entry>一般使用者</entry> + <entry><prompt>%</prompt></entry> </row> <row> <entry><systemitem class="username">root</systemitem></entry> - <entry>&prompt.root;</entry> + <entry><prompt>#</prompt></entry> </row> </tbody> </tgroup> @@ -107,7 +156,7 @@ <sect1 xml:id="preface-conventions"> <title>書中所用的編排風格</title> - <para>下表為本書中所使用編排風格方式：</para> + <para>下表為本書中所使用編排風格方式</para> <informaltable frame="none" pgwide="1"> <tgroup cols="2"> @@ -121,12 +170,12 @@ <tbody> <row> <entry>指令</entry> - <entry>使用 <command>ls -a</command> 來列出所有的檔案。</entry> + <entry>使用 <command>ls -l</command> 來列出所有的檔案。</entry> </row> <row> <entry>檔名</entry> - <entry>修改 <filename>.login</filename> 檔。</entry> + <entry>編輯 <filename>.login</filename> 。</entry> </row> <row> @@ -137,40 +186,33 @@ <row> <entry>輸入指令後，螢幕上會出現的對應內容。</entry> - <entry><screen>&prompt.user; <userinput>su</userinput> -Password:</screen></entry> + <entry><screen><prompt>%</prompt> <userinput>date +"The time is %H:%M"</userinput> +The time is 09:18</screen></entry> </row> <row> - <entry>要參考的線上手冊(manual)</entry> - - <entry>以 <citerefentry> - <refentrytitle>su</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> 來切換帳號。</entry> + <entry>要參考的線上手冊</entry> + <entry>使用 <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來切換帳號。</entry> </row> <row> - <entry>在講到帳號(user)、群組(group)的名稱的時候...</entry> - - <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry> + <entry>使用者名稱和群組名稱</entry> + <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry> </row> <row> - <entry>語氣的強調</entry> - - <entry>你『必須』這麼做才行。</entry> + <entry>語氣的強調。</entry> + <entry>使用者<emphasis>必須</emphasis>這樣做</entry> </row> <row> <entry>打指令時，可替換的部份</entry> - <entry>要刪除檔案的話，請打 <command>rm 要刪除的檔名</command></entry> + <entry>要搜尋線上手冊的關鍵字，請輸入 <command>man -k <replaceable>關鍵字</replaceable></command></entry> </row> <row> - <entry>環境變數設定</entry> - + <entry>環境變數。</entry> <entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry> </row> </tbody> @@ -179,29 +221,28 @@ Password:</screen></entry> </sect1> <sect1 xml:id="preface-notes"> - <title>『Note、Tip、Important、Warning、Example』的運用</title> + <title>注意、技巧、重要訊息、警告、與範例的運用。</title> - <para>以下文字是『注意』、『技巧』、『重要訊息』、『警告』、『範例』的運用。</para> + <para>出現在本文中的注意、警告、與範例。</para> <note> - <para>表示需要注意的事項，其中包括您需要注意的事情，因為這些事情可能會影響到操作結果。</para> + <para>注意：表示需要注意的事項，其中包括您需要注意的事情，因為這些事情可能會影響到操作結果。</para> </note> <tip> - <para>提供可能對您有用或簡化操作方式的技巧說明。</para> + <para>提示：提供可能對您有用的資訊，例如簡化操作方式的技巧說明。</para> </tip> <important> - <para>表示要特別注意的事情。一般來說，它們會包括操作指令時需要加的額外參數。</para> + <para>重要：表示要特別注意的事情。一般來說，它們會包括操作指令時需要加的額外參數。</para> </important> <warning> - <para>表示警告事項，比如如果您不注意則可能導致的損失。這些損失可能是對您或硬體造成實際傷害， - 也可能是無法估計的損害，例如一時疏忽而刪除重要檔案...。</para> + <para>警告：表示警告事項，比如如果您不則可能導致的損失。這些損失可能是對您或硬體造成實際傷害， 也可能是無法估計的損害，例如一時疏忽而刪除重要檔案...。</para> </warning> <example> - <title>這是舉例說明</title> + <title>一個範例</title> <para>這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。</para> </example> @@ -210,25 +251,8472 @@ Password:</screen></entry> <sect1 xml:id="preface-acknowledgements"> <title>感謝</title> - <para>在此要感謝 Sue Blake, Patrick Durusau, Jon Hamilton, Peter - Flynn, Christopher Maden 這些人的協助與閱讀初期草稿，並提供許多寶貴的潤稿意見與評論。</para> + <para>在此要感謝 Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, Christopher Maden 這些人的協助與閱讀初期草稿，並提供許多寶貴的潤稿意見與評論。</para> </sect1> </preface> - &chap.overview; - &chap.tools; - &chap.xml-primer; - &chap.xml-markup; - &chap.stylesheets; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.translations; - &chap.writing-style; - &chap.psgml-mode; - &chap.see-also; - - &app.examples; + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="overview"> + <title>概論</title> + + <para>歡迎參與 FreeBSD 文件計劃( 簡稱 <acronym>FDP</acronym> ) 。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，您的點滴貢獻都是十分寶貴的。</para> + + <para>本文件描述：『 <acronym>FDP</acronym> 的架構有哪些』、『如何撰寫並提交文件』、 『如何有效運用工具來協助撰稿』。</para> + + <para>歡迎大家對 <acronym>FDP</acronym> 做出貢獻。唯一的成員要求就有貢獻的意願。</para> + + <para>本入門書指出如何：</para> + + <itemizedlist> + <listitem> + <para>瞭解有哪些文件是由 <acronym>FDP</acronym> 所維護的。</para> + </listitem> + + <listitem> + <para>安裝所需的文件工具和檔案</para> + </listitem> + + <listitem> + <para>修改文件</para> + </listitem> + + <listitem> + <para>提交修改以供審核並納入 FreeBSD 文件</para> + </listitem> + </itemizedlist> + + <sect1 xml:id="overview-doc"> + <title>FreeBSD 文件組</title> + + <para><acronym>FDP</acronym> 負責四類 FreeBSD 文件</para> + + <itemizedlist> + <listitem> + <para><emphasis>使用手冊</emphasis>： 使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para> + </listitem> + + <listitem> + <para><emphasis>FAQ</emphasis> 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para> + </listitem> + + <listitem> + <para><emphasis>線上手冊 ( manual pages )</emphasis>:英文版的系統 manual 並不是由 <acronym>FDP</acronym> 所撰寫的，因為它們是屬於 base system 的部份。 然而，<acronym>FDP</acronym> 可以修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。</para> + </listitem> + + <listitem> + <para><emphasis>網站</emphasis>: 這是 FreeBSD 在網路上的主要部份，位於 <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link> 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方</para> + </listitem> + </itemizedlist> + + <para>翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯</para> + + <para>FreeBSD 網站、使用手冊、和 <acronym>FAQ</acronym> 的文件原始碼可以在 <literal>https://svn.FreeBSD.org/doc/</literal> 的文件庫取得。</para> + + <para>線上手冊的原始碼則是在 <literal>https://svn.FreeBSD.org/base/</literal> 的原始碼庫可以取得。</para> + + <para>文件提交訊息可以用 <command>svn log</command> 察看。 提交訊息也會保存在<uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>。</para> + + <para>這些儲存庫的網頁版位於<link xlink:href="https://svnweb.FreeBSD.org/doc/"/> 和 <link xlink:href="https://svnweb.FreeBSD.org/base/"/>。</para> + + <para>許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 <acronym>FDP</acronym> 的檔案中。其他一些文件則是作者希望放在他處。<acronym>FDP</acronym> 會盡力提供這些文件的連結。</para> + </sect1> + + <sect1 xml:id="overview-quick-start"> + <title>快速上手</title> + + <para>在編輯 FreeBSD 文件之前，有一些準備工作要做。 首先，請訂閱 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 文件計劃郵件論壇</link>。 有些團隊成員也會出現在<link xlink:href="http://www.efnet.org/">EFnet</link>的<literal>#bsddocs</literal> <acronym>IRC</acronym> 頻道。這些人可以幫忙解決文件相關的問題。</para> + + <procedure> + <step> + <para>安裝 <package>textproc/docproj</package> 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。</para> + </step> + + <step> + <para>在<filename>~/doc</filename>安裝 FreeBSD 文件庫的本地端工作副本 ( 請見 <xref linkend="working-copy"/> )。</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para>設定文字編輯器：</para> + + <itemizedlist> + <listitem> + <para>Word wrap 設為70個字元。</para> + </listitem> + + <listitem> + <para>Tab stops 設成 。</para> + </listitem> + + <listitem> + <para>將句首每八個空白以一個 tab 替換。</para> + </listitem> + </itemizedlist> + + <para>特定編輯器的設定方式列於 <xref linkend="editor-config"/>。</para> + </step> + + <step> + <para>更新本地端工作副本</para> + + <screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para>編輯需要修改的文件檔案。如果檔案需要大幅度的編修，請先諮詢郵件論壇。</para> + + <para>標籤 ( tag ) 和 entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>. 。</para> + </step> + + <step> + <para>編輯完後，執行以下指令來檢查是否有問題：</para> + + <screen><prompt>%</prompt> <userinput>igor -R filename.xml | less -RS</userinput></screen> + + <para>檢查輸出並重新編輯檔案來修正顯示的錯誤，然後重新執行指令來找出剩下的問題。重複執行直到所有錯誤都解決完。</para> + </step> + + <step> + <para>修正送出前請先建構測試 (build-test ) 。在編輯的文件目錄最頂層執行 <userinput>make</userinput>，將會產生 split HTML 格式的文件。例如要建構 <acronym>HTML</acronym> 格式的英文版使用手冊，請在 <filename>en_US.ISO8859-1/books/handbook/</filename> 目錄執行 <command>make</command> 。</para> + </step> + + <step> + <para>修改並測試完後，產生<quote>diff 檔</quote>：</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> + + <para>設一個可辨識的檔名。如上例中，是使用手冊的<filename>bsdinstall</filename> 部份的修改。</para> + </step> + + <step> + <para>使用網頁版 <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">Problem Report</link> 系統提交 diff 檔。 如果使用網頁版，請輸入<emphasis>[修正檔] <replaceable>問題簡短描述</replaceable></emphasis>的概要 。選擇 <literal>docs</literal> 分類和 <literal>doc-bug</literal>類別。在訊息的主體中，輸入修正的簡短描述和其他相關的重要的細節。使用<guibutton>[ Browse... ]</guibutton> 按鈕來附加 diff 檔。</para> + </step> + </procedure> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="tools"> + <title>工具</title> + + <para>有些工具軟體用來管理 FreeBSD 文件，並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的，但是裝了之後會更容易進行文件製作工作。</para> + + <sect1 xml:id="tools-required"> + <title>必備工具</title> + + <para>從 Ports Collection 安裝 <package>textproc/docproj</package>。這個 <emphasis>組合型 port (meta-port)</emphasis> 會安裝處理 FreeBSD 文件需要的所有應用程式。以下列出特定元件的進一步說明。</para> + + <sect2> + <title><acronym>DTD</acronym>s 與 <acronym>Entities</acronym></title> + + <para>FreeBSD 文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 組。這些都會經由 <package>textproc/docproj</package> port 來安裝。</para> + + <variablelist> + <varlistentry> + <term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)</term> + + <listitem> + <para><acronym>XHTML</acronym> 是全球資訊網的一種標記語言，也是整個 FreeBSD 網站所使用的格式。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term> + + <listitem> + <para>DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ISO 8879 entities (<package>textproc/iso8879</package>)</term> + + <listitem> + <para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用， 包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 xml:id="tools-optional"> + <title>輔助工具</title> + + <para>不一定得裝下列的應用程式才行，但是，出的格式也更具彈性。</para> + + <sect2> + <title>軟體</title> + + <variablelist> + + <varlistentry> + <term><application>Vim</application> (<package>editors/vim</package>)</term> + + <listitem> + <para>一個很受歡迎的編輯器，可以處理 <acronym>XML</acronym> 和他的衍生相關文件，例如 DocBook <acronym>XML</acronym>。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Emacs</application> 或 <application>XEmacs</application> (<package>editors/emacs</package> 或 <package>editors/xemacs</package>)</term> + + <listitem> + <para>這兩個編輯器都包含特別模式來編輯用 <acronym>XML</acronym> <acronym>DTD</acronym> 標記的文件。這個模式包含指令來減少打字量，並可以幫忙減少錯誤的發生。</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 2013 Warren Block + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS + IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="working-copy"> + <title>工作副本</title> + + <para xml:lang="en">The <emphasis>working copy</emphasis> is a copy of the FreeBSD + repository documentation tree downloaded onto the local computer. + Changes are made to the local working copy, tested, and then + submitted as patches to be committed to the main + repository.</para> + + <para xml:lang="en">A full copy of the documentation tree can occupy 700 megabytes + of disk space. Allow for a full gigabyte of space to have room + for temporary files and test versions of various output + formats.</para> + + <para xml:lang="en"><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link> + is used to manage the FreeBSD documentation files. It is installed + by <package>textproc/docproj</package> as one of + the required applications.</para> + + <sect1 xml:id="working-copy-doc-and-src"> + <title xml:lang="en">Documentation and Manual Pages</title> + + <para xml:lang="en">FreeBSD documentation is not just books and articles. Manual + pages for all the commands and configuration files are also part + of the documentation, and part of the <acronym>FDP</acronym>'s + territory. Two repositories are involved: + <literal>doc</literal> for the books and articles, and + <literal>base</literal> for the operating system and manual + pages. To edit manual pages, the <literal>base</literal> + repository must be checked out separately.</para> + + <para xml:lang="en">Repositories may contain multiple versions of documentation + and source code. New modifications are almost always made only + to the latest version, called <literal>head</literal>.</para> + </sect1> + + <sect1 xml:id="working-copy-choosing-directory"> + <title xml:lang="en">Choosing a Directory</title> + + <para xml:lang="en">FreeBSD documentation is traditionally stored in + <filename>/usr/doc/</filename>, and system + source code with manual pages in + <filename>/usr/src/</filename>. These + directory trees are relocatable, and users may want to put the + working copies in other locations to avoid interfering with + existing information in the main directories. The examples + that follow use <filename>~/doc</filename> + and <filename>~/src</filename>, both + subdirectories of the user's home directory.</para> + </sect1> + + <sect1 xml:id="working-copy-checking-out"> + <title xml:lang="en">Checking Out a Copy</title> + + <para xml:lang="en">A download of a working copy from the repository is called + a <emphasis>checkout</emphasis>, and done with + <command>svn checkout</command>. This example checks out a + copy of the latest version (<literal>head</literal>) of + the main documentation tree:</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + + <para xml:lang="en">A checkout of the source code to work on manual pages is + very similar:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-updating"> + <title xml:lang="en">Updating a Working Copy</title> + + <para xml:lang="en">The documents and files in the FreeBSD repository change daily. + People modify files and commit changes frequently. Even a short + time after an initial checkout, there will already be + differences between the local working copy and the main FreeBSD + repository. To update the local version with the changes that + have been made to the main repository, use + <command>svn update</command> on the directory containing the + local working copy:</para> + + <screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> + + <para xml:lang="en">Get in the protective habit of using + <command>svn update</command> before editing document files. + Someone else may have edited that file very recently, and the + local working copy will not include the latest changes until it + has been updated. Editing the newest version of a file is much + easier than trying to combine an older, edited local file with + the newer version from the repository.</para> + </sect1> + + <sect1 xml:id="working-copy-revert"> + <title xml:lang="en">Reverting Changes</title> + + <para xml:lang="en">Sometimes it turns out that changes were + not necessary after all, or the writer just wants to start over. + Files can be <quote>reset</quote> to their unchanged form with + <command>svn revert</command>. For example, to erase the edits + made to <filename>chapter.xml</filename> and reset it to + unmodified form:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-making-diff"> + <title xml:lang="en">Making a Diff</title> + + <para xml:lang="en">After edits to a file or group of files are completed, the + differences between the local working copy and the version on + the FreeBSD repository must be collected into a single file for + submission. These <emphasis>diff</emphasis> files are produced + by redirecting the output of <command>svn diff</command> into a + file:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> + + <para xml:lang="en">Give the file a meaningful name that identifies the + contents. The example above is for spelling fixes to the whole + documentation tree.</para> + + <para xml:lang="en">If the diff file is to be submitted with the web + <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a FreeBSD + problem report</link></quote> interface, add a + <filename>.txt</filename> extension to give the earnest and + simple-minded web form a clue that the contents are plain + text.</para> + + <para xml:lang="en">Be careful: <command>svn diff</command> includes all changes + made in the current directory and any subdirectories. If there + are files in the working copy with edits that are not ready to + be submitted yet, provide a list of only the files that are to + be included:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-subversion-references"> + <title xml:lang="en"><application>Subversion</application> References</title> + + <para xml:lang="en">These examples show very basic usage of + <application>Subversion</application>. More detail is available + in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link> + and the <link xlink:href="http://subversion.apache.org/docs/">Subversion + documentation</link>.</para> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="structure"> + <title xml:lang="en">Documentation Directory Structure</title> + + <para xml:lang="en">Files and directories in the + <filename>doc/</filename> tree follow a + structure meant to:</para> + + <orderedlist> + <listitem> + <para xml:lang="en">Make it easy to automate converting the document to other + formats.</para> + </listitem> + + <listitem> + <para xml:lang="en">Promote consistency between the different documentation + organizations, to make it easier to switch between working on + different documents.</para> + </listitem> + + <listitem> + <para xml:lang="en">Make it easy to decide where in the tree new documentation + should be placed.</para> + </listitem> + </orderedlist> + + <para xml:lang="en">In addition, the documentation tree must accommodate + documents in many different languages and encodings. It is + important that the documentation tree structure does not enforce + any particular defaults or cultural preferences.</para> + + <sect1 xml:id="structure-top"> + <title xml:lang="en">The Top Level, + <filename>doc/</filename></title> + + <para xml:lang="en">There are two types of directory under + <filename>doc/</filename>, each with very + specific directory names and meanings.</para> + + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry xml:lang="en">Directory</entry> + <entry xml:lang="en">Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top" xml:lang="en"> + <filename>share</filename></entry> + + <entry xml:lang="en">Contains files that are not specific to the various + translations and encodings of the documentation. + Contains subdirectories to further categorize the + information. For example, the files that comprise the + <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> infrastructure are in + <filename>share/mk</filename>, while + the additional <acronym>XML</acronym> support files + (such as the FreeBSD extended DocBook + <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry> + </row> + + <row> + <entry valign="top" xml:lang="en"> + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> + + <entry xml:lang="en">One directory exists for each available translation + and encoding of the documentation, for example + <filename>en_US.ISO8859-1/</filename> + and <filename>zh_TW.UTF-8/</filename>. + The names are long, but by fully specifying the language + and encoding we prevent any future headaches when a + translation team wants to provide documentation in the + same language but in more than one encoding. This also + avoids problems that might be caused by a future switch + to Unicode.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="structure-locale"> + <title xml:lang="en">The + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> + Directories</title> + + <para xml:lang="en">These directories contain the documents themselves. The + documentation is split into up to three more categories at + this level, indicated by the different directory names.</para> + + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry xml:lang="en">Directory</entry> + <entry xml:lang="en">Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top" xml:lang="en"> + <filename>articles</filename></entry> + + <entry xml:lang="en">Documentation marked up as a DocBook + <tag>article</tag> (or equivalent). Reasonably + short, and broken up into sections. Normally only + available as one <acronym>XHTML</acronym> file.</entry> + </row> + + <row> + <entry valign="top" xml:lang="en"><filename>books</filename></entry> + + <entry xml:lang="en">Documentation marked up as a DocBook + <tag>book</tag> (or equivalent). Book length, + and broken up into chapters. Normally available as both + one large <acronym>XHTML</acronym> file (for people with + fast connections, or who want to print it easily from a + browser) and as a collection of linked, smaller + files.</entry> + </row> + + <row> + <entry valign="top" xml:lang="en"> + <filename>man</filename></entry> + + <entry xml:lang="en">For translations of the system manual pages. This + directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename> + directories, corresponding to the sections that have + been translated.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para xml:lang="en">Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> + directory will have all of these subdirectories. It depends + on how much translation has been accomplished by that + translation team.</para> + </sect1> + + <sect1 xml:id="structure-document"> + <title xml:lang="en">Document-Specific Information</title> + + <para xml:lang="en">This section contains specific notes about particular + documents managed by the FDP.</para> + + <sect2> + <title xml:lang="en">The Handbook</title> + + <subtitle xml:lang="en"><filename>books/handbook/</filename></subtitle> + + <para xml:lang="en">The Handbook is written in DocBook <acronym>XML</acronym> + using the FreeBSD DocBook extended <acronym>DTD</acronym>.</para> + + <para xml:lang="en">The Handbook is organized as a DocBook + <tag>book</tag>. The book is divided into + <tag>part</tag>s, each of which contains several + <tag>chapter</tag>s. <tag>chapter</tag>s are + further subdivided into sections (<tag>sect1</tag>) + and subsections (<tag>sect2</tag>, + <tag>sect3</tag>) and so on.</para> + + <sect3> + <title xml:lang="en">Physical Organization</title> + + <para xml:lang="en">There are a number of files and directories within the + <filename>handbook</filename> directory.</para> + + <note> + <para xml:lang="en">The Handbook's organization may change over time, and + this document may lag in detailing the organizational + changes. Post questions about Handbook organization to the + <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para> + </note> + + <sect4> + <title xml:lang="en"><filename>Makefile</filename></title> + + <para xml:lang="en">The <filename>Makefile</filename> defines some + variables that affect how the <acronym>XML</acronym> + source is converted to other formats, and lists the + various source files that make up the Handbook. It then + includes the standard <filename>doc.project.mk</filename>, + to bring in the rest of the code that handles converting + documents from one format to another.</para> + </sect4> + + <sect4> + <title xml:lang="en"><filename>book.xml</filename></title> + + <para xml:lang="en">This is the top level document in the Handbook. It + contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE + declaration</link>, as well as the elements that + describe the Handbook's structure.</para> + + <para xml:lang="en"><filename>book.xml</filename> uses <link linkend="xml-primer-parameter-entities">parameter + entities</link> to load in the files with the + <filename>.ent</filename> extension. These files + (described later) then define <link linkend="xml-primer-general-entities">general + entities</link> that are used throughout the rest of the + Handbook.</para> + </sect4> + + <sect4> + <title xml:lang="en"><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title> + + <para xml:lang="en">Each chapter in the Handbook is stored in a file + called <filename>chapter.xml</filename> in a separate + directory from the other chapters. Each directory is + named after the value of the <literal>id</literal> + attribute on the <tag>chapter</tag> + element.</para> + + <para xml:lang="en">For example, if one of the chapter files + contains:</para> + + <programlisting xml:lang="en"><tag class="starttag">chapter id="kernelconfig"</tag> +... +<tag class="endtag">chapter</tag></programlisting> + + <para xml:lang="en">Then it will be called + <filename>chapter.xml</filename> in the + <filename>kernelconfig</filename> directory. In general, + the entire contents of the chapter are in this one + file.</para> + + <para xml:lang="en">When the <acronym>XHTML</acronym> version of the + Handbook is produced, this will yield + <filename>kernelconfig.html</filename>. This is because + of the <literal>id</literal> value, and is not related to + the name of the directory.</para> + + <para xml:lang="en">In earlier versions of the Handbook, the files were + stored in the same directory as + <filename>book.xml</filename>, and named after the value + of the <literal>id</literal> attribute on the file's + <tag>chapter</tag> element. Now, it is possible + to include images in each chapter. Images for each + Handbook chapter are stored within <filename>share/images/books/handbook</filename>. + The localized version of these images should be + placed in the same directory as the <acronym>XML</acronym> + sources for each chapter. Namespace collisions are + inevitable, and it is easier to work with several + directories with a few files in them than it is to work + with one directory that has many files in it.</para> + + <para xml:lang="en">A brief look will show that there are many directories + with individual <filename>chapter.xml</filename> files, + including <filename>basics/chapter.xml</filename>, + <filename>introduction/chapter.xml</filename>, and + <filename>printing/chapter.xml</filename>.</para> + + <important> + <para xml:lang="en">Do not name chapters or directories after + their ordering within the Handbook. This ordering can + change as the content within the Handbook is + reorganized. Reorganization should be possible without + renaming files, unless entire chapters are being + promoted or demoted within the hierarchy.</para> + </important> + + <para xml:lang="en">The <filename>chapter.xml</filename> files are not + complete <acronym>XML</acronym> documents that can be + built individually. They can only be built + as parts of the whole Handbook.</para> + </sect4> + </sect3> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="doc-build"> + <title xml:lang="en">The Documentation Build Process</title> + + <para xml:lang="en">This chapter covers organization of the documentation build + process and how <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to control it.</para> + + <sect1 xml:id="doc-build-rendering"> + <title xml:lang="en">Rendering DocBook into Output</title> + + <para xml:lang="en">Different types of output can be produced from a single + DocBook source file. The type of output desired is set with the + <varname>FORMATS</varname> variable. A list of known formats is + stored in <varname>KNOWN_FORMATS</varname>:</para> + + <screen xml:id="doc-build-rendering-known-formats" xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> +<prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput></screen> + + <table xml:id="doc-build-rendering-common-formats" frame="none"> + <title xml:lang="en">Common Output Formats</title> + + <tgroup cols="3"> + <thead> + <row> + <entry xml:lang="en"><varname>FORMATS</varname> Value</entry> + <entry xml:lang="en">File Type</entry> + <entry xml:lang="en">Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry xml:lang="en"><literal>html</literal></entry> + <entry xml:lang="en"><acronym>HTML</acronym>, one file</entry> + <entry xml:lang="en">A single <filename>book.html</filename> or + <filename>article.html</filename>.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>html-split</literal></entry> + <entry xml:lang="en"><acronym>HTML</acronym>, multiple files</entry> + <entry xml:lang="en">Multiple <acronym>HTML</acronym> files, one for + each chapter or section, for use on a typical web + site.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>pdf</literal></entry> + <entry xml:lang="en"><acronym>PDF</acronym></entry> + <entry xml:lang="en">Portable Document Format</entry> + </row> + </tbody> + </tgroup> + </table> + + <para xml:lang="en">The default output format can vary by document, but is + usually <literal>html-split</literal>. Other formats are chosen + by setting <varname>FORMATS</varname> to a specific value. + Multiple output formats can be created at a single time by + setting <varname>FORMATS</varname> to a list of formats.</para> + + <example xml:id="doc-build-formats-example-html"> + <title xml:lang="en">Build a Single HTML Output File</title> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> +<prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen> + </example> + + <example xml:id="doc-build-formats-example-html-split-pdf"> + <title xml:lang="en">Build HTML-Split and <acronym>PDF</acronym> Output + Files</title> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> +<prompt>%</prompt> <userinput>make FORMATS="html-split pdf"</userinput></screen> + </example> + </sect1> + + <sect1 xml:id="doc-build-toolset"> + <title xml:lang="en">The FreeBSD Documentation Build Toolset</title> + + <para xml:lang="en">These are the tools used to build and install the + <acronym>FDP</acronym> documentation.</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">The primary build tool is <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, specifically + <application>Berkeley Make</application>.</para> + </listitem> + + <listitem> + <para xml:lang="en">Package building is handled by FreeBSD's + <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + + <listitem> + <para xml:lang="en"><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to create compressed versions of + the document. <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> archives are also supported. + <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used for package building.</para> + </listitem> + + <listitem> + <para xml:lang="en"><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to install the + documentation.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="doc-build-makefiles"> + + <title xml:lang="en">Understanding <filename>Makefile</filename>s in the + Documentation Tree</title> + + <para xml:lang="en">There are three main types of <filename>Makefile</filename>s + in the FreeBSD Documentation Project tree.</para> + + <itemizedlist> + <listitem> + <para xml:lang="en"><link linkend="sub-make">Subdirectory + <filename>Makefile</filename>s</link> simply pass + commands to those directories below them.</para> + </listitem> + + <listitem> + <para xml:lang="en"><link linkend="doc-make">Documentation + <filename>Makefile</filename>s</link> describe the + documents that are produced from this + directory.</para> + </listitem> + + <listitem> + <para xml:lang="en"><link linkend="make-includes"><application>Make</application> + includes</link> are the glue that perform the document + production, and are usually of the form + <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para> + </listitem> + </itemizedlist> + + <sect2 xml:id="sub-make"> + <title xml:lang="en">Subdirectory <filename>Makefile</filename>s</title> + + <para xml:lang="en">These <filename>Makefile</filename>s usually take the form + of:</para> + + <programlisting xml:lang="en">SUBDIR =articles +SUBDIR+=books + +COMPAT_SYMLINK = en + +DOC_PREFIX?= ${.CURDIR}/.. +.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> + + <para xml:lang="en">The first four non-empty lines define the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> + variables <varname>SUBDIR</varname>, + <varname>COMPAT_SYMLINK</varname>, and + <varname>DOC_PREFIX</varname>.</para> + + <para xml:lang="en">The <varname>SUBDIR</varname> statement and + <varname>COMPAT_SYMLINK</varname> statement show how to + assign a value to a variable, overriding any previous + value.</para> + + <para xml:lang="en">The second <varname>SUBDIR</varname> statement shows how a + value is appended to the current value of a variable. The + <varname>SUBDIR</varname> variable is now <literal>articles + books</literal>.</para> + + <para xml:lang="en">The <varname>DOC_PREFIX</varname> assignment shows how a + value is assigned to the variable, but only if it is not + already defined. This is useful if + <varname>DOC_PREFIX</varname> is not where this + <filename>Makefile</filename> thinks it is - the user can + override this and provide the correct value.</para> + + <para xml:lang="en">What does it all mean? <varname>SUBDIR</varname> + mentions which subdirectories below this one the build process + should pass any work on to.</para> + + <para xml:lang="en"><varname>COMPAT_SYMLINK</varname> is specific to + compatibility symlinks (amazingly enough) for languages to + their official encoding (<filename>doc/en</filename> would + point to <filename>en_US.ISO-8859-1</filename>).</para> + + <para xml:lang="en"><varname>DOC_PREFIX</varname> is the path to the root of + the FreeBSD Document Project tree. This is not always that easy + to find, and is also easily overridden, to allow for + flexibility. <varname>.CURDIR</varname> is a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> + builtin variable with the path to the current + directory.</para> + + <para xml:lang="en">The final line includes the FreeBSD Documentation Project's + project-wide <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> system file + <filename>doc.project.mk</filename> which is the glue which + converts these variables into build instructions.</para> + </sect2> + + <sect2 xml:id="doc-make"> + <title xml:lang="en">Documentation <filename>Makefile</filename>s</title> + + <para xml:lang="en">These <filename>Makefile</filename>s set <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> + variables that describe how to build the documentation + contained in that directory.</para> + + <para xml:lang="en">Here is an example:</para> + + <programlisting xml:lang="en">MAINTAINER=nik@FreeBSD.org + +DOC?= book + +FORMATS?= html-split html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# SGML content +SRCS= book.xml + +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> + + <para xml:lang="en">The <varname>MAINTAINER</varname> variable allows + committers to claim ownership of a document in the FreeBSD + Documentation Project, and take responsibility for maintaining + it.</para> + + <para xml:lang="en"><varname>DOC</varname> is the name (sans the + <filename>.xml</filename> extension) of the main document + created by this directory. <varname>SRCS</varname> lists all + the individual files that make up the document. This should + also include important files in which a change should result + in a rebuild.</para> + + <para xml:lang="en"><varname>FORMATS</varname> indicates the default formats + that should be built for this document. + <varname>INSTALL_COMPRESSED</varname> is the default list of + compression techniques that should be used in the document + build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by + default, should be non-empty if only compressed documents are + desired in the build.</para> + + <para xml:lang="en">The <varname>DOC_PREFIX</varname> and include statements + should be familiar already.</para> + </sect2> + </sect1> + + <sect1 xml:id="make-includes"> + <title xml:lang="en">FreeBSD Documentation Project + <application>Make</application> Includes</title> + + <para xml:lang="en"><citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes are best explained by inspection of + the code. Here are the system include files:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en"><filename>doc.project.mk</filename> is the main project + include file, which includes all the following include + files, as necessary.</para> + </listitem> + + <listitem> + <para xml:lang="en"><filename>doc.subdir.mk</filename> handles traversing of + the document tree during the build and install + processes.</para> + </listitem> + + <listitem> + <para xml:lang="en"><filename>doc.install.mk</filename> provides variables + that affect ownership and installation of documents.</para> + </listitem> + + <listitem> + <para xml:lang="en"><filename>doc.docbook.mk</filename> is included if + <varname>DOCFORMAT</varname> is <literal>docbook</literal> + and <varname>DOC</varname> is set.</para> + </listitem> + </itemizedlist> + + <sect2> + <title xml:lang="en"><filename>doc.project.mk</filename></title> + + <para xml:lang="en">By inspection:</para> + + <programlisting xml:lang="en">DOCFORMAT?= docbook +MAINTAINER?= doc@FreeBSD.org + +PREFIX?= /usr/local +PRI_LANG?= en_US.ISO8859-1 + +.if defined(DOC) +.if ${DOCFORMAT} == "docbook" +.include "doc.docbook.mk" +.endif +.endif + +.include "doc.subdir.mk" +.include "doc.install.mk"</programlisting> + + <sect3> + + <title xml:lang="en">Variables</title> + + <para xml:lang="en"><varname>DOCFORMAT</varname> and + <varname>MAINTAINER</varname> are assigned default values, + if these are not set by the document make file.</para> + + <para xml:lang="en"><varname>PREFIX</varname> is the prefix under which the + <link linkend="tools">documentation building tools</link> + are installed. For normal package and port installation, + this is <filename>/usr/local</filename>.</para> + + <para xml:lang="en"><varname>PRI_LANG</varname> should be set to whatever + language and encoding is natural amongst users these + documents are being built for. US English is the + default.</para> + + <note> + <para xml:lang="en"><varname>PRI_LANG</varname> does not affect which + documents can, or even will, be built. Its main use is + creating links to commonly referenced documents into the + FreeBSD documentation install root.</para> + </note> + </sect3> + + <sect3> + <title xml:lang="en">Conditionals</title> + + <para xml:lang="en">The <literal>.if defined(DOC)</literal> line is an + example of a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> conditional which, like in other + programs, defines behavior if some condition is true or if + it is false. <literal>defined</literal> is a function which + returns whether the variable given is defined or not.</para> + + <para xml:lang="en"><literal>.if ${DOCFORMAT} == "docbook"</literal>, next, + tests whether the <varname>DOCFORMAT</varname> variable is + <literal>"docbook"</literal>, and in this case, includes + <filename>doc.docbook.mk</filename>.</para> + + <para xml:lang="en">The two <literal>.endif</literal>s close the two above + conditionals, marking the end of their application.</para> + </sect3> + </sect2> + + <sect2> + <title xml:lang="en"><filename>doc.subdir.mk</filename></title> + + <para xml:lang="en">This file is too long to explain in detail. These notes + describe the most important features.</para> + + <sect3> + <title xml:lang="en">Variables</title> + + <itemizedlist> + <listitem> + <para xml:lang="en"><varname>SUBDIR</varname> is a list of + subdirectories that the build process should go further + down into.</para> + </listitem> + + <listitem> + <para xml:lang="en"><varname>ROOT_SYMLINKS</varname> is the name of + directories that should be linked to the document + install root from their actual locations, if the current + language is the primary language (specified by + <varname>PRI_LANG</varname>).</para> + </listitem> + + <listitem> + <para xml:lang="en"><varname>COMPAT_SYMLINK</varname> is described in + the + <link linkend="sub-make">Subdirectory Makefile</link> + section.</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title xml:lang="en">Targets and Macros</title> + + <para xml:lang="en">Dependencies are described by + <literal><replaceable>target</replaceable>: + <replaceable>dependency1 dependency2 + ...</replaceable></literal> tuples, where to build + <literal>target</literal>, the given + dependencies must be built first.</para> + + <para xml:lang="en">After that descriptive tuple, instructions on how to + build the target may be given, if the conversion process + between the target and its dependencies are not previously + defined, or if this particular conversion is not the same as + the default conversion method.</para> + + <para xml:lang="en">A special dependency <literal>.USE</literal> defines + the equivalent of a macro.</para> + + <programlisting xml:lang="en">_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor</programlisting> + + <para xml:lang="en">In the above, <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> is now + a macro which will execute the given commands when it is + listed as a dependency.</para> + + <para xml:lang="en">What sets this macro apart from other targets? + Basically, it is executed <emphasis>after</emphasis> the + instructions given in the build procedure it is listed as a + dependency to, and it does not adjust + <varname>.TARGET</varname>, which is the variable which + contains the name of the target currently being + built.</para> + + <programlisting xml:lang="en">clean: _SUBDIRUSE + rm -f ${CLEANFILES}</programlisting> + + <para xml:lang="en">In the above, <buildtarget xml:lang="en">clean</buildtarget> will use + the <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> macro after it has + executed the instruction + <command>rm -f ${CLEANFILES}</command>. In effect, this + causes <buildtarget xml:lang="en">clean</buildtarget> to go further and + further down the directory tree, deleting built files as it + goes <emphasis>down</emphasis>, not on the way back + up.</para> + + <sect4> + <title xml:lang="en">Provided Targets</title> + + <itemizedlist> + <listitem> + <para xml:lang="en"><buildtarget xml:lang="en">install</buildtarget> and + <buildtarget xml:lang="en">package</buildtarget> both go down the + directory tree calling the real versions of themselves + in the subdirectories + (<buildtarget xml:lang="en">realinstall</buildtarget> and + <buildtarget xml:lang="en">realpackage</buildtarget> + respectively).</para> + </listitem> + + <listitem> + <para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> removes files + created by the build process (and goes down the + directory tree too). + <buildtarget xml:lang="en">cleandir</buildtarget> does the same, and + also removes the object directory, if any.</para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + + <sect3> + <title xml:lang="en">More on Conditionals</title> + + <itemizedlist> + <listitem> + <para xml:lang="en"><literal>exists</literal> is another condition + function which returns true if the given file + exists.</para> + </listitem> + + <listitem> + <para xml:lang="en"><literal>empty</literal> returns true if the given + variable is empty.</para> + </listitem> + + <listitem> + <para xml:lang="en"><literal>target</literal> returns true if the given + target does not already exist.</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title xml:lang="en">Looping Constructs in <command>make + (.for)</command></title> + + <para xml:lang="en"><literal>.for</literal> provides a way to repeat a set + of instructions for each space-separated element in a + variable. It does this by assigning a variable to contain + the current element in the list being examined.</para> + + <programlisting xml:lang="en">_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor</programlisting> + + <para xml:lang="en">In the above, if <varname>SUBDIR</varname> is empty, no + action is taken; if it has one or more elements, the + instructions between <literal>.for</literal> and + <literal>.endfor</literal> would repeat for every element, + with <varname>entry</varname> being replaced with the value + of the current element.</para> + </sect3> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="the-website"> + <title>網站</title> + + <para>FreeBSD 網站是 FreeBSD 文件的一部份。網站的檔案儲存在文件樹目錄，此例中是 <filename>~/doc</filename>，的 <filename>en_US.ISO8859-1/htdocs</filename> 子目錄。</para> + + <sect1 xml:id="the-website-env"> + <title>環境變數</title> + + <para>有些環境變數控制網站的建構或安裝，和裝到哪個目錄</para> + + <tip> + <para xml:lang="en">The web build system uses <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and considers + variables to be set when they have been defined, even if they + are empty. The examples here show the recommended ways of + defining and using these variables. Setting or defining these + variables with other values or methods might lead to + unexpected surprises.</para> + </tip> + + <variablelist> + <varlistentry xml:id="the-website-env-destdir"> + <term xml:lang="en"><varname>DESTDIR</varname></term> + + <listitem> + <para xml:lang="en">DESTDIR specifies the path where the web site files + are to be installed.</para> + + <para xml:lang="en">This variable is best set with <citerefentry><refentrytitle>env</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the user + shell's method of setting environment variables, + <command>setenv</command> for <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> or + <command>export</command> for <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry xml:id="the-website-env-englishonly"> + <term xml:lang="en"><varname>ENGLISH_ONLY</varname></term> + + <listitem> + <para xml:lang="en">Default: undefined. Build and include all + translations.</para> + + <para xml:lang="en"><userinput>ENGLISH_ONLY=yes</userinput>: use only + the English documents and ignore all translations.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="the-website-env-webonly"> + <term xml:lang="en"><varname>WEB_ONLY</varname></term> + + <listitem> + <para xml:lang="en">Default: undefined. Build both the web site + and all the books and articles.</para> + + <para xml:lang="en"><userinput>WEB_ONLY=yes</userinput>: build or install + only <acronym>HTML</acronym> pages from the + <filename>en_US.ISO8859-1/htdocs</filename> directory. + Other directories and documents, including books and + articles, will be ignored.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="the-website-env-weblang"> + <term xml:lang="en"><varname>WEB_LANG</varname></term> + + <listitem> + <para xml:lang="en">Default: undefined. Build and include all the + available languages on the web site.</para> + + <para xml:lang="en">Set to a space-separated list of languages to be + included in the build + or install. The formats are the same as the directory + names in the document root directory. For example, to + include the German and French documents:</para> + + <screen xml:lang="en"><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen> + </listitem> + </varlistentry> + </variablelist> + + <para xml:lang="en"><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>, + and <varname>ENGLISH_ONLY</varname> are <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables + and can be set in <filename>/etc/make.conf</filename>, + <filename>Makefile.inc</filename>, as environment variables on + the command line, or in dot files.</para> + </sect1> + + <sect1 xml:id="the-website-build"> + <title xml:lang="en">Building and Installing the Web Pages</title> + + <para xml:lang="en">Having obtained the documentation and web site source files, + the web site can be built.</para> + + <para xml:lang="en">An actual installation of the web site is run as the <systemitem class="username">root</systemitem> + user because the permissions on the web server directory will + not allow files to be installed by an unprivileged user. + For testing, it can be useful to install the files as a normal + user to a temporary directory.</para> + + <para xml:lang="en">In these examples, the web site files are built by user + <systemitem class="username">jru</systemitem> in their home + directory, <filename>~/doc</filename>, with a full path of + <filename>/usr/home/jru/doc</filename>.</para> + + <tip> + <para xml:lang="en">The web site build uses the <filename>INDEX</filename> + from the Ports Collection and might fail if that file or + <filename>/usr/ports</filename> is not + present. The simplest approach is to install the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/ports.html#ports-tree">Ports + Collection</link>.</para> + </tip> + + <example xml:id="the-website-examples-build"> + <title xml:lang="en">Build the Full Web Site and All Documents</title> + + <para xml:lang="en">Build the web site and all documents. The resulting files + are left in the document tree:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput> +<prompt>%</prompt> <userinput>make all</userinput></screen> + </example> + + <example xml:id="the-website-examples-buildinstall-englishonly"> + <title xml:lang="en">Build Only the Web Site in English</title> + + <para xml:lang="en">Build the web site only, in English, as user + <systemitem class="username">jru</systemitem>, and install + the resulting files into <filename>/tmp/www</filename> for + testing:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput> +<prompt>%</prompt> <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen> + + <para xml:lang="en">Changes to static files can usually be tested by viewing + the modified files directly with a web browser. If the site + has been built as shown above, a modified main page can be + viewed with:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>firefox /tmp/www/data/index.html</userinput></screen> + + <para xml:lang="en">Modifications to dynamic files can be tested with a web + server running on the local system. After building the site + as shown above, this + <filename>/usr/local/etc/apache24/httpd.conf</filename> can be + used with <package>www/apache24</package>:</para> + + <programlisting xml:lang="en"># httpd.conf for testing the FreeBSD website +Define TestRoot "/tmp/www/data" + +# directory for configuration files +ServerRoot "/usr/local" + +Listen 80 + +# minimum required modules +LoadModule authz_core_module libexec/apache24/mod_authz_core.so +LoadModule mime_module libexec/apache24/mod_mime.so +LoadModule unixd_module libexec/apache24/mod_unixd.so +LoadModule cgi_module libexec/apache24/mod_cgi.so +LoadModule dir_module libexec/apache24/mod_dir.so + +# run the webserver as user and group +User www +Group www + +ServerAdmin you@example.com +ServerName fbsdtest + +# deny access to all files +<Directory /> + AllowOverride none + Require all denied +</Directory> + +# allow access to the website directory +DocumentRoot "${TestRoot}" +<Directory "${TestRoot}"> + Options Indexes FollowSymLinks + AllowOverride None + Require all granted +</Directory> + +# prevent access to .htaccess and .htpasswd files +<Files ".ht*"> + Require all denied +</Files> + +ErrorLog "/var/log/httpd-error.log" +LogLevel warn + +# set up the CGI script directory +<Directory "${TestRoot}/cgi"> + AllowOverride None + Options None + Require all granted + Options +ExecCGI + AddHandler cgi-script .cgi +</Directory> + +Include etc/apache24/Includes/*.conf</programlisting> + + <para xml:lang="en">Start the web server with</para> + + <screen xml:lang="en"><prompt>#</prompt> <userinput>service apache24 onestart</userinput></screen> + + <para xml:lang="en">The web site can be viewed at + <link xlink:href="http://localhost"/>. Be aware that many + links refer to the real FreeBSD site by name, and those links + will still go to the external site instead of the local test + version. Fully testing the local site will require + temporarily setting <acronym>DNS</acronym> so + <literal>www.FreeBSD.org</literal> resolves to + <literal>localhost</literal> or the local + <acronym>IP</acronym> address.</para> + </example> + + <example xml:id="the-website-examples-buildinstall"> + <title xml:lang="en">Build and Install the Web Site</title> + + <para xml:lang="en">Build the web site and all documents as user + <systemitem class="username">jru</systemitem>. Install the + resulting files as + <systemitem class="username">root</systemitem> into the + default directory, + <filename>/root/public_html</filename>:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput> +<prompt>%</prompt> <userinput>make all</userinput> +<prompt>%</prompt> <userinput>su -</userinput> +Password: +<prompt>#</prompt> <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput> +<prompt>#</prompt> <userinput>make install</userinput></screen> + </example> + + <para xml:lang="en">The install process does not delete any old or outdated + files that existed previously in the same directory. If a new + copy of the site is built and installed every day, this command + will find and delete all files that have not been updated in + three days:</para> + + <screen xml:lang="en"><prompt>#</prompt> <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="xml-primer"> + <title xml:lang="en">XML Primer</title> + + <para xml:lang="en">Most <acronym>FDP</acronym> documentation is written with + markup languages based on <acronym>XML</acronym>. This chapter + explains what that means, how to read and understand the + documentation source, and the <acronym>XML</acronym> techniques + used.</para> + + <para xml:lang="en">Portions of this section were inspired by Mark Galassi's + <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get + Going With DocBook</link>.</para> + + <sect1 xml:id="xml-primer-overview"> + <title>概論</title> + + <para xml:lang="en">In the original days of computers, electronic text was + simple. There were a few character sets like + <acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, but that + was about it. Text was text, and what you saw really was what + you got. No frills, no formatting, no intelligence.</para> + + <para xml:lang="en">Inevitably, this was not enough. When text is in a + machine-usable format, machines are expected to be able to use + and manipulate it intelligently. Authors want to indicate that + certain phrases should be emphasized, or added to a glossary, or + made into hyperlinks. Filenames could be shown in a + <quote>typewriter</quote> style font for viewing on screen, but + as <quote>italics</quote> when printed, or any of a myriad of + other options for presentation.</para> + + <para xml:lang="en">It was once hoped that Artificial Intelligence (AI) would + make this easy. The computer would read the document and + automatically identify key phrases, filenames, text that the + reader should type in, examples, and more. Unfortunately, real + life has not happened quite like that, and computers still + require assistance before they can meaningfully process + text.</para> + + <para xml:lang="en">More precisely, they need help identifying what is what. + Consider this text:</para> + + <blockquote> + <para xml:lang="en">To remove <filename>/tmp/foo</filename>, use + <citerefentry><refentrytitle>rm</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>rm /tmp/foo</userinput></screen> + </blockquote> + + <para xml:lang="en">It is easy to see which parts are filenames, which are + commands to be typed in, which parts are references to manual + pages, and so on. But the computer processing the document + cannot. For this we need markup.</para> + + <para xml:lang="en"><quote>Markup</quote> is commonly used to describe + <quote>adding value</quote> or <quote>increasing cost</quote>. + The term takes on both these meanings when applied to text. + Markup is additional text included in the document, + distinguished from the document's content in some way, so that + programs that process the document can read the markup and use + it when making decisions about the document. Editors can hide + the markup from the user, so the user is not distracted by + it.</para> + + <para xml:lang="en">The extra information stored in the markup + <emphasis>adds value</emphasis> to the document. Adding the + markup to the document must typically be done by a + person—after all, if computers could recognize the text + sufficiently well to add the markup then there would be no need + to add it in the first place. This + <emphasis>increases the cost</emphasis> (the effort required) to + create the document.</para> + + <para xml:lang="en">The previous example is actually represented in this + document like this:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &man.rm.1;.<tag class="endtag">para</tag> + +<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> + + <para xml:lang="en">The markup is clearly separate from the content.</para> + + <para xml:lang="en">Markup languages define what the markup means and how it + should be interpreted.</para> + + <para xml:lang="en">Of course, one markup language might not be enough. A + markup language for technical documentation has very different + requirements than a markup language that is intended for cookery + recipes. This, in turn, would be very different from a markup + language used to describe poetry. What is really needed is a + first language used to write these other markup languages. A + <emphasis>meta markup language</emphasis>.</para> + + <para xml:lang="en">This is exactly what the eXtensible Markup + Language (<acronym>XML</acronym>) is. Many markup languages + have been written in <acronym>XML</acronym>, including the two + most used by the <acronym>FDP</acronym>, + <acronym>XHTML</acronym> and DocBook.</para> + + <para xml:lang="en">Each language definition is more properly called a grammar, + vocabulary, schema or Document Type Definition + (<acronym>DTD</acronym>). There are various languages to + specify an <acronym>XML</acronym> grammar, or + <emphasis>schema</emphasis>.</para> + + <para xml:id="xml-primer-validating" xml:lang="en">A schema is a + <emphasis>complete</emphasis> specification of all the elements + that are allowed to appear, the order in which they should + appear, which elements are mandatory, which are optional, and so + forth. This makes it possible to write an + <acronym>XML</acronym> <emphasis>parser</emphasis> which reads + in both the schema and a document which claims to conform to the + schema. The parser can then confirm whether or not all the + elements required by the vocabulary are in the document in the + right order, and whether there are any errors in the markup. + This is normally referred to as + <quote>validating the document</quote>.</para> + + <note> + <para xml:lang="en">Validation confirms that the choice of + elements, their ordering, and so on, conforms to that listed + in the grammar. It does <emphasis>not</emphasis> check + whether <emphasis>appropriate</emphasis> markup has been used + for the content. If all the filenames in a document were + marked up as function names, the parser would not flag this as + an error (assuming, of course, that the schema defines + elements for filenames and functions, and that they are + allowed to appear in the same place).</para> + </note> + + <para xml:lang="en">Most contributions to the Documentation + Project will be content marked up in either + <acronym>XHTML</acronym> or DocBook, rather than alterations to + the schemas. For this reason, this book will not touch on how + to write a vocabulary.</para> + </sect1> + + <sect1 xml:id="xml-primer-elements"> + <title xml:lang="en">Elements, Tags, and Attributes</title> + + <para xml:lang="en">All the vocabularies written in <acronym>XML</acronym> share + certain characteristics. This is hardly surprising, as the + philosophy behind <acronym>XML</acronym> will inevitably show + through. One of the most obvious manifestations of this + philosophy is that of <emphasis>content</emphasis> and + <emphasis>elements</emphasis>.</para> + + <para xml:lang="en">Documentation, whether it is a single web page, or a lengthy + book, is considered to consist of content. This content is then + divided and further subdivided into elements. The purpose of + adding markup is to name and identify the boundaries of these + elements for further processing.</para> + + <para xml:lang="en">For example, consider a typical book. At the very top + level, the book is itself an element. This <quote>book</quote> + element obviously contains chapters, which can be considered to + be elements in their own right. Each chapter will contain more + elements, such as paragraphs, quotations, and footnotes. Each + paragraph might contain further elements, identifying content + that was direct speech, or the name of a character in the + story.</para> + + <para xml:lang="en">It may be helpful to think of this as + <quote>chunking</quote> content. At the very top level is one + chunk, the book. Look a little deeper, and there are more + chunks, the individual chapters. These are chunked further into + paragraphs, footnotes, character names, and so on.</para> + + <para xml:lang="en">Notice how this differentiation between different elements + of the content can be made without resorting to any + <acronym>XML</acronym> terms. It really is surprisingly + straightforward. This could be done with a highlighter pen and + a printout of the book, using different colors to indicate + different chunks of content.</para> + + <para xml:lang="en">Of course, we do not have an electronic highlighter pen, so + we need some other way of indicating which element each piece of + content belongs to. In languages written in + <acronym>XML</acronym> (<acronym>XHTML</acronym>, DocBook, et + al) this is done by means of <emphasis>tags</emphasis>.</para> + + <para xml:lang="en">A tag is used to identify where a particular element starts, + and where the element ends. <emphasis>The tag is not part of + the element itself</emphasis>. Because each grammar was + normally written to mark up specific types of information, each + one will recognize different elements, and will therefore have + different names for the tags.</para> + + <para xml:lang="en">For an element called + <replaceable>element-name</replaceable> the start tag will + normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>. + The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para> + + <example> + <title xml:lang="en">Using an Element (Start and End Tags)</title> + + <para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating + that the content enclosed by the element is a paragraph, + called <tag>p</tag>.</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for + the 'p' element, and it will end with the end tag for the 'p' + element.<tag class="endtag">p</tag> + +<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">Some elements have no content. For example, in + <acronym>XHTML</acronym>, a horizontal line can be included in + the document. For these <quote>empty</quote> elements, + <acronym>XML</acronym> introduced a shorthand form that is + completely equivalent to the two-tag version:</para> + + <example> + <title xml:lang="en">Using an Element Without Content</title> + + <para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating a + horizontal rule, called <tag>hr</tag>. This element + does not wrap content, so it looks like this:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> +<tag class="starttag">hr</tag><tag class="endtag">hr</tag> + +<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<tag class="endtag">p</tag></programlisting> + + <para xml:lang="en">The shorthand version consists of a single tag:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> +<tag class="emptytag">hr</tag> + +<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">As shown above, elements can contain other elements. In the + book example earlier, the book element contained all the chapter + elements, which in turn contained all the paragraph elements, + and so on.</para> + + <example> + <title xml:lang="en">Elements Within Elements; <tag>em</tag></title> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some + of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">The grammar consists of rules that describe which elements + can contain other elements, and exactly what they can + contain.</para> + + <important> + <para xml:lang="en">People often confuse the terms tags and elements, and use + the terms as if they were interchangeable. They are + not.</para> + + <para xml:lang="en">An element is a conceptual part of your document. An + element has a defined start and end. The tags mark where the + element starts and ends.</para> + + <para xml:lang="en">When this document (or anyone else knowledgeable about + <acronym>XML</acronym>) refers to + <quote>the <tag class="starttag">p</tag> tag</quote> + they mean the literal text consisting of the three characters + <literal><</literal>, <literal>p</literal>, and + <literal>></literal>. But the phrase + <quote>the <tag>p</tag> element</quote> refers to the + whole element.</para> + + <para xml:lang="en">This distinction <emphasis>is</emphasis> very subtle. But + keep it in mind.</para> + </important> + + <para xml:lang="en">Elements can have attributes. An attribute has a name and a + value, and is used for adding extra information to the element. + This might be information that indicates how the content should + be rendered, or might be something that uniquely identifies that + occurrence of the element, or it might be something else.</para> + + <para xml:lang="en">An element's attributes are written + <emphasis>inside</emphasis> the start tag for that element, and + take the form + <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> + + <para xml:lang="en">In <acronym>XHTML</acronym>, the <tag>p</tag> + element has an attribute called + <tag class="attribute">align</tag>, which suggests an + alignment (justification) for the paragraph to the program + displaying the <acronym>XHTML</acronym>.</para> + + <para xml:lang="en">The <tag class="attribute">align</tag> attribute can + take one of four defined values, <literal>left</literal>, + <literal>center</literal>, <literal>right</literal> and + <literal>justify</literal>. If the attribute is not specified + then the default is <literal>left</literal>.</para> + + <example> + <title xml:lang="en">Using an Element with an Attribute</title> + + <programlisting xml:lang="en"><tag class="starttag">p align="left"</tag>The inclusion of the align attribute + on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag> + +<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">Some attributes only take specific values, such as + <literal>left</literal> or <literal>justify</literal>. Others + allow any value.</para> + + <example> + <title xml:lang="en">Single Quotes Around Attributes</title> + + <programlisting xml:lang="en"><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">Attribute values in <acronym>XML</acronym> must be enclosed + in either single or double quotes. Double quotes are + traditional. Single quotes are useful when the attribute value + contains double quotes.</para> + + <para xml:lang="en">Information about attributes, elements, and tags is stored + in catalog files. The Documentation Project uses standard + DocBook catalogs and includes additional catalogs for + FreeBSD-specific features. Paths to the catalog files are defined + in an environment variable so they can be found by the document + build tools.</para> + + <sect2> + <title xml:lang="en">To Do…</title> + + <para xml:lang="en">Before running the examples in this document, install + <package>textproc/docproj</package> from + the FreeBSD Ports Collection. This is a + <emphasis>meta-port</emphasis> that downloads and installs + the standard programs and supporting files needed by the + Documentation Project. <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> users must use + <command>rehash</command> for the shell to recognize new + programs after they have been installed, or log out + and then log back in again.</para> + + <procedure> + <step> + <para xml:lang="en">Create <filename>example.xml</filename>, and enter + this text:</para> + + <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> + + <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para xml:lang="en">Try to validate this file using an + <acronym>XML</acronym> parser.</para> + + <para xml:lang="en"><package>textproc/docproj</package> + includes the <command>xmllint</command> + <link linkend="xml-primer-validating">validating + parser</link>.</para> + + <para xml:lang="en">Use <command>xmllint</command> to validate the + document:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput></screen> + + <para xml:lang="en"><command>xmllint</command> returns without displaying + any output, showing that the document validated + successfully.</para> + </step> + + <step> + <para xml:lang="en">See what happens when required elements are omitted. + Delete the line with the + <tag class="starttag">title</tag> and + <tag class="endtag">title</tag> tags, and re-run + the validation.</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput> +example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen> + + <para xml:lang="en">This shows that the validation error comes from the + <replaceable>fifth</replaceable> line of the + <replaceable>example.xml</replaceable> file and that the + content of the <tag class="starttag">head</tag> is + the part which does not follow the rules of the + <acronym>XHTML</acronym> grammar.</para> + + <para xml:lang="en">Then <command>xmllint</command> shows the line where + the error was found and marks the exact character position + with a <literal>^</literal> sign.</para> + </step> + + <step> + <para xml:lang="en">Replace the <tag>title</tag> element.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-doctype-declaration"> + <title xml:lang="en">The DOCTYPE Declaration</title> + + <para xml:lang="en">The beginning of each document can specify the name of the + <acronym>DTD</acronym> to which the document conforms. This + DOCTYPE declaration is used by <acronym>XML</acronym> parsers to + identify the <acronym>DTD</acronym> and ensure that the document + does conform to it.</para> + + <para xml:lang="en">A typical declaration for a document written to conform with + version 1.0 of the <acronym>XHTML</acronym> + <acronym>DTD</acronym> looks like this:</para> + + <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting> + + <para xml:lang="en">That line contains a number of different components.</para> + + <variablelist> + <varlistentry> + <term xml:lang="en"><literal><!</literal></term> + + <listitem> + <para xml:lang="en">The <emphasis>indicator</emphasis> shows + this is an <acronym>XML</acronym> declaration.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>DOCTYPE</literal></term> + + <listitem> + <para xml:lang="en">Shows that this is an <acronym>XML</acronym> + declaration of the document type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>html</literal></term> + + <listitem> + <para xml:lang="en">Names the first + <link linkend="xml-primer-elements">element</link> that + will appear in the document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</literal></term> + + <listitem> + <para xml:lang="en">Lists the Formal Public Identifier + (<acronym>FPI</acronym>) + <indexterm xml:lang="en"> + <primary>Formal Public Identifier</primary> + </indexterm> + for the <acronym>DTD</acronym> to which this document + conforms. The <acronym>XML</acronym> parser uses this to + find the correct <acronym>DTD</acronym> when processing + this document.</para> + + <para xml:lang="en"><literal>PUBLIC</literal> is not a part of the + <acronym>FPI</acronym>, but indicates to the + <acronym>XML</acronym> processor how to find the + <acronym>DTD</acronym> referenced in the + <acronym>FPI</acronym>. Other ways of telling the + <acronym>XML</acronym> parser how to find the + <acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> + + <listitem> + <para xml:lang="en">A local filename or a <acronym>URL</acronym> to find + the <acronym>DTD</acronym>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>></literal></term> + + <listitem> + <para xml:lang="en">Ends the declaration and returns to the + document.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect2> + <title xml:lang="en">Formal Public Identifiers + (<acronym>FPI</acronym>s)</title> + + <indexterm significance="preferred" xml:lang="en"> + <primary>Formal Public Identifier</primary> + </indexterm> + + <note> + <para xml:lang="en">It is not necessary to know this, but it is useful + background, and might help debug problems when the + <acronym>XML</acronym> processor can not locate the + <acronym>DTD</acronym>.</para> + </note> + + <para xml:lang="en"><acronym>FPI</acronym>s must follow a specific + syntax:</para> + + <programlisting xml:lang="en">"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> + + <variablelist> + <varlistentry> + <term xml:lang="en"><replaceable>Owner</replaceable></term> + + <listitem> + <para xml:lang="en">The owner of the <acronym>FPI</acronym>.</para> + + <para xml:lang="en">The beginning of the string identifies the owner of + the <acronym>FPI</acronym>. For example, the + <acronym>FPI</acronym> + <literal>"ISO 8879:1986//ENTITIES Greek + Symbols//EN"</literal> lists + <literal>ISO 8879:1986</literal> as being the owner for + the set of entities for Greek symbols. + <acronym>ISO</acronym> 8879:1986 is the International + Organization for Standardization + (<acronym>ISO</acronym>) number for the + <acronym>SGML</acronym> standard, the predecessor (and a + superset) of <acronym>XML</acronym>.</para> + + <para xml:lang="en">Otherwise, this string will either look like + <literal>-//<replaceable>Owner</replaceable></literal> + or + <literal>+//<replaceable>Owner</replaceable></literal> + (notice the only difference is the leading + <literal>+</literal> or <literal>-</literal>).</para> + + <para xml:lang="en">If the string starts with <literal>-</literal> then + the owner information is unregistered, with a + <literal>+</literal> identifying it as + registered.</para> + + <para xml:lang="en"><acronym>ISO</acronym> 9070:1991 defines how + registered names are generated. It might be derived + from the number of an <acronym>ISO</acronym> + publication, an <acronym>ISBN</acronym> code, or an + organization code assigned according to + <acronym>ISO</acronym> 6523. Additionally, a + registration authority could be created in order to + assign registered names. The <acronym>ISO</acronym> + council delegated this to the American National + Standards Institute (<acronym>ANSI</acronym>).</para> + + <para xml:lang="en">Because the FreeBSD Project has not been registered, + the owner string is <literal>-//FreeBSD</literal>. As seen + in the example, the <acronym>W3C</acronym> are not a + registered owner either.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><replaceable>Keyword</replaceable></term> + + <listitem> + <para xml:lang="en">There are several keywords that indicate the type of + information in the file. Some of the most common + keywords are <literal>DTD</literal>, + <literal>ELEMENT</literal>, <literal>ENTITIES</literal>, + and <literal>TEXT</literal>. <literal>DTD</literal> is + used only for <acronym>DTD</acronym> files, + <literal>ELEMENT</literal> is usually used for + <acronym>DTD</acronym> fragments that contain only + entity or element declarations. <literal>TEXT</literal> + is used for <acronym>XML</acronym> content (text and + tags).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><replaceable>Description</replaceable></term> + + <listitem> + <para xml:lang="en">Any description can be given for the contents + of this file. This may include version numbers or any + short text that is meaningful and unique for the + <acronym>XML</acronym> system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><replaceable>Language</replaceable></term> + + <listitem> + <para xml:lang="en">An <acronym>ISO</acronym> two-character code that + identifies the native language for the file. + <literal>EN</literal> is used for English.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3> + <title xml:lang="en"><filename>catalog</filename> Files</title> + + <para xml:lang="en">With the syntax above, an <acronym>XML</acronym> + processor needs to have some way of turning the + <acronym>FPI</acronym> into the name of the file containing + the <acronym>DTD</acronym>. A catalog file (typically + called <filename>catalog</filename>) contains lines that map + <acronym>FPI</acronym>s to filenames. For example, if the + catalog file contained the line:</para> + +<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog --> + + <programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting> + + <para xml:lang="en">The <acronym>XML</acronym> processor knows that the + <acronym>DTD</acronym> is called + <filename>transitional.dtd</filename> in the + <filename>1.0</filename> subdirectory of the directory that + held <filename>catalog</filename>.</para> + + <para xml:lang="en">Examine the contents of + <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>. + This is the catalog file for the <acronym>XHTML</acronym> + <acronym>DTD</acronym>s that were installed as part of the + <package>textproc/docproj</package> port.</para> + </sect3> + </sect2> + + <sect2 xml:id="xml-primer-fpi-alternatives"> + <title xml:lang="en">Alternatives to <acronym>FPI</acronym>s</title> + + <para xml:lang="en">Instead of using an <acronym>FPI</acronym> to indicate the + <acronym>DTD</acronym> to which the document conforms (and + therefore, which file on the system contains the + <acronym>DTD</acronym>), the filename can be explicitly + specified.</para> + + <para xml:lang="en">The syntax is slightly different:</para> + + <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting> + + <para xml:lang="en">The <literal>SYSTEM</literal> keyword indicates that the + <acronym>XML</acronym> processor should locate the + <acronym>DTD</acronym> in a system specific fashion. This + typically (but not always) means the <acronym>DTD</acronym> + will be provided as a filename.</para> + + <para xml:lang="en">Using <acronym>FPI</acronym>s is preferred for reasons of + portability. If the <literal>SYSTEM</literal> identifier is + used, then the <acronym>DTD</acronym> must be provided and + kept in the same location for everyone.</para> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-xml-escape"> + <title xml:lang="en">Escaping Back to <acronym>XML</acronym></title> + + <para xml:lang="en">Some of the underlying <acronym>XML</acronym> syntax can be + useful within documents. For example, comments can be included + in the document, and will be ignored by the parser. Comments + are entered using <acronym>XML</acronym> syntax. Other uses for + <acronym>XML</acronym> syntax will be shown later.</para> + + <para xml:lang="en"><acronym>XML</acronym> sections begin with a + <literal><!</literal> tag and end with a + <literal>></literal>. These sections contain instructions + for the parser rather than elements of the document. Everything + between these tags is <acronym>XML</acronym> syntax. The + <link linkend="xml-primer-doctype-declaration">DOCTYPE + declaration</link> shown earlier is an example of + <acronym>XML</acronym> syntax included in the document.</para> + + </sect1> + + <sect1 xml:id="xml-primer-comments"> + <title xml:lang="en">Comments</title> + + <para xml:lang="en">Comments are an <acronym>XML</acronym> construct, and are + normally only valid inside a <acronym>DTD</acronym>. However, + as <xref linkend="xml-primer-xml-escape"/> shows, it is possible + to use <acronym>XML</acronym> syntax within the document.</para> + + <para xml:lang="en">The delimiter for XML comments is the string + <quote><literal>--</literal></quote>. The first occurrence of + this string opens a comment, and the second closes it.</para> + + <example> + <title xml:lang="en"><acronym>XML</acronym> Generic Comment</title> + + <programlisting xml:lang="en"><!-- This is inside the comment --> + +<!-- This is another comment --> + +<!-- This is one way + of doing multiline comments --> + +<!-- This is another way of -- + -- doing multiline comments --></programlisting> + </example> + + <para xml:lang="en"><acronym>XHTML</acronym> users may be familiar with different + rules for comments. In particular, it is often believed that + the string <literal><!--</literal> opens a comment, and it is + only closed by <literal>--></literal>.</para> + + <para xml:lang="en">This is <emphasis>not</emphasis> correct. Many web browsers + have broken <acronym>XHTML</acronym> parsers, and will accept + incorrect input as valid. However, the <acronym>XML</acronym> + parsers used by the Documentation Project are more strict, and + will reject documents with that error.</para> + + <example> + <title xml:lang="en">Erroneous <acronym>XML</acronym> Comments</title> + + <programlisting xml:lang="en"><!-- This is in the comment -- + + THIS IS OUTSIDE THE COMMENT! + + -- back inside the comment --></programlisting> + + <para xml:lang="en">The <acronym>XML</acronym> parser will treat this as + though it were actually:</para> + + <programlisting xml:lang="en"><!THIS IS OUTSIDE THE COMMENT></programlisting> + + <para xml:lang="en">That is not valid <acronym>XML</acronym>, and may give + confusing error messages.</para> + </example> + + <sect2> + <title xml:lang="en">To Do…</title> + + <procedure> + <step> + <para xml:lang="en">Add some comments to + <filename>example.xml</filename>, and check that the file + still validates using <command>xmllint</command>.</para> + </step> + + <step> + <para xml:lang="en">Add some invalid comments to + <filename>example.xml</filename>, and see the error + messages that <command>xmllint</command> gives when it + encounters an invalid comment.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-entities"> + <title xml:lang="en">Entities</title> + + <para xml:lang="en">Entities are a mechanism for assigning names to chunks of + content. As an <acronym>XML</acronym> parser processes a + document, any entities it finds are replaced by the content of + the entity.</para> + + <para xml:lang="en">This is a good way to have re-usable, easily changeable + chunks of content in <acronym>XML</acronym> documents. It is + also the only way to include one marked up file inside another + using <acronym>XML</acronym>.</para> + + <para xml:lang="en">There are two types of entities for two different + situations: <emphasis>general entities</emphasis> and + <emphasis>parameter entities</emphasis>.</para> + + <sect2 xml:id="xml-primer-general-entities"> + <title xml:lang="en">General Entities</title> + + <para xml:lang="en">General entities are used to assign names to reusable + chunks of text. These entities can only be used in the + document. They cannot be used in an + <acronym>XML</acronym> context.</para> + + <para xml:lang="en">To include the text of a general entity in the document, + include + <literal>&<replaceable>entity-name</replaceable>;</literal> + in the text. For example, consider a general entity called + <literal>current.version</literal> which expands to the + current version number of a product. To use it in the + document, write:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>The current version of our product is + &current.version;.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">When the version number changes, edit the definition of + the general entity, replacing the value. Then reprocess the + document.</para> + + <para xml:lang="en">General entities can also be used to enter characters that + could not otherwise be included in an <acronym>XML</acronym> + document. For example, <literal><</literal> and + <literal>&</literal> cannot normally appear in an + <acronym>XML</acronym> document. The <acronym>XML</acronym> + parser sees the <literal><</literal> symbol as the start of + a tag. Likewise, when the <literal>&</literal> symbol is + seen, the next text is expected to be an entity name.</para> + + <para xml:lang="en">These symbols can be included by using two predefined + general entities: <literal>&lt;</literal> and + <literal>&amp;</literal>.</para> + + <para xml:lang="en">General entities can only be defined within an + <acronym>XML</acronym> context. Such definitions are usually + done immediately after the DOCTYPE declaration.</para> + + <example> + <title xml:lang="en">Defining General Entities</title> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]></programlisting> + + <para xml:lang="en">The DOCTYPE declaration has been extended by adding a + square bracket at the end of the first line. The two + entities are then defined over the next two lines, the + square bracket is closed, and then the DOCTYPE declaration + is closed.</para> + + <para xml:lang="en">The square brackets are necessary to indicate that the + DTD indicated by the DOCTYPE declaration is being + extended.</para> + </example> + </sect2> + + <sect2 xml:id="xml-primer-parameter-entities"> + <title xml:lang="en">Parameter Entities</title> + + <para xml:lang="en">Parameter entities, like + <link linkend="xml-primer-general-entities">general + entities</link>, are used to assign names to reusable chunks + of text. But parameter entities can only be used within an + <link linkend="xml-primer-xml-escape">XML + context</link>.</para> + + <para xml:lang="en">Parameter entity definitions are similar to those for + general entities. However, parameter entries are included + with + <literal>%<replaceable>entity-name</replaceable>;</literal>. + The definition also includes the <literal>%</literal> between + the <literal>ENTITY</literal> keyword and the name of the + entity.</para> + + <para xml:lang="en">For a mnemonic, think + <quote><emphasis>P</emphasis>arameter entities use the + <emphasis>P</emphasis>ercent symbol</quote>.</para> + + <example> + <title xml:lang="en">Defining Parameter Entities</title> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % param.some "some"> +<!ENTITY % param.text "text"> +<!ENTITY % param.new "%param.some more %param.text"> + +<!-- %param.new now contains "some more text" --> +]></programlisting> + </example> + </sect2> + + <sect2> + <title xml:lang="en">To Do…</title> + + <procedure> + <step> + <para xml:lang="en">Add a general entity to + <filename>example.xml</filename>.</para> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY version "1.1"> +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <!-- There may be some comments in here as well --> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> + + <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para xml:lang="en">Validate the document using + <command>xmllint</command>.</para> + </step> + + <step> + <para xml:lang="en">Load <filename>example.xml</filename> into a web + browser. It may have to be copied to + <filename>example.html</filename> before the browser + recognizes it as an <acronym>XHTML</acronym> + document.</para> + + <para xml:lang="en">Older browsers with simple parsers may not render this + file as expected. The entity reference + <literal>&version;</literal> may not be replaced by + the version number, or the <acronym>XML</acronym> context + closing <literal>]></literal> may not be recognized and + instead shown in the output.</para> + </step> + + <step> + <para xml:lang="en">The solution is to <emphasis>normalize</emphasis> the + document with an <acronym>XML</acronym> normalizer. The + normalizer reads valid <acronym>XML</acronym> and writes + equally valid <acronym>XML</acronym> which has been + transformed in some way. One way the normalizer + transforms the input is by expanding all the entity + references in the document, replacing the entities with + the text that they represent.</para> + + <para xml:lang="en"><command>xmllint</command> can be used for this. It + also has an option to drop the initial + <acronym>DTD</acronym> section so that the closing + <literal>]></literal> does not confuse browsers:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput></screen> + + <para xml:lang="en">A normalized copy of the document with entities + expanded is produced in <filename>example.html</filename>, + ready to load into a web browser.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-include"> + <title xml:lang="en">Using Entities to Include Files</title> + + <para xml:lang="en">Both + <link linkend="xml-primer-general-entities">general</link> and + <link linkend="xml-primer-parameter-entities">parameter</link> + entities are particularly useful for including one file inside + another.</para> + + <sect2 xml:id="xml-primer-include-using-gen-entities"> + <title xml:lang="en">Using General Entities to Include Files</title> + + <para xml:lang="en">Consider some content for an <acronym>XML</acronym> book + organized into files, one file per chapter, called + <filename>chapter1.xml</filename>, + <filename>chapter2.xml</filename>, and so forth, with a + <filename>book.xml</filename> that will contain these + chapters.</para> + + <para xml:lang="en">In order to use the contents of these files as the values + for entities, they are declared with the + <literal>SYSTEM</literal> keyword. This directs the + <acronym>XML</acronym> parser to include the contents of the + named file as the value of the entity.</para> + + <example> + <title xml:lang="en">Using General Entities to Include Files</title> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml"> +<!-- And so forth --> +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <!-- Use the entities to load in the chapters --> + + &chapter.1; + &chapter.2; + &chapter.3; +<tag class="endtag">html</tag></programlisting> + </example> + + <warning> + <para xml:lang="en">When using general entities to include other files + within a document, the files being included + (<filename>chapter1.xml</filename>, + <filename>chapter2.xml</filename>, and so on) + <emphasis>must not</emphasis> start with a DOCTYPE + declaration. This is a syntax error because entities are + low-level constructs and they are resolved before any + parsing happens.</para> + </warning> + </sect2> + + <sect2> + <title xml:lang="en">Using Parameter Entities to Include Files</title> + + <para xml:lang="en">Parameter entities can only be used inside an + <acronym>XML</acronym> context. Including a file in an + <acronym>XML</acronym> context can be used + to ensure that general entities are reusable.</para> + + <para xml:lang="en">Suppose that there are many chapters in the document, and + these chapters were reused in two different books, each book + organizing the chapters in a different fashion.</para> + + <para xml:lang="en">The entities could be listed at the top of each book, but + that quickly becomes cumbersome to manage.</para> + + <para xml:lang="en">Instead, place the general entity definitions inside one + file, and use a parameter entity to include that file within + the document.</para> + + <example> + <title xml:lang="en">Using Parameter Entities to Include Files</title> + + <para xml:lang="en">Place the entity definitions in a separate file + called <filename>chapters.ent</filename> and + containing this text:</para> + + <programlisting xml:lang="en"><!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml"></programlisting> + + <para xml:lang="en">Create a parameter entity to refer to the contents + of the file. Then use the parameter entity to load the file + into the document, which will then make all the general + entities available for use. Then use the general entities + as before:</para> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!-- Define a parameter entity to load in the chapter general entities --> +<!ENTITY % chapters SYSTEM "chapters.ent"> + +<!-- Now use the parameter entity to load in this file --> +%chapters; +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + &chapter.1; + &chapter.2; + &chapter.3; +<tag class="endtag">html</tag></programlisting> + </example> + </sect2> + + <sect2> + <title xml:lang="en">To Do…</title> + + <sect3> + <title xml:lang="en">Use General Entities to Include Files</title> + + <procedure> + <step> + <para xml:lang="en">Create three files, <filename>para1.xml</filename>, + <filename>para2.xml</filename>, and + <filename>para3.xml</filename>.</para> + + <para xml:lang="en">Put content like this in each file:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting> + </step> + + <step> + <para xml:lang="en">Edit <filename>example.xml</filename> so that it + looks like this:</para> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"> +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> + + &para1; + &para2; + &para3; + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para xml:lang="en">Produce <filename>example.html</filename> by + normalizing <filename>example.xml</filename>.</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> + </step> + + <step> + <para xml:lang="en">Load <filename>example.html</filename> into the web + browser and confirm that the + <filename>para<replaceable>n</replaceable>.xml</filename> + files have been included in + <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title xml:lang="en">Use Parameter Entities to Include Files</title> + + <note> + <para xml:lang="en">The previous steps must have completed before this + step.</para> + </note> + + <procedure> + <step> + <para xml:lang="en">Edit <filename>example.xml</filename> so that it + looks like this:</para> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % entities SYSTEM "entities.ent"> %entities; +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> + + &para1; + &para2; + &para3; + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para xml:lang="en">Create a new file called + <filename>entities.ent</filename> with this + content:</para> + + <programlisting xml:lang="en"><!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"></programlisting> + </step> + + <step> + <para xml:lang="en">Produce <filename>example.html</filename> by + normalizing <filename>example.xml</filename>.</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> + </step> + + <step> + <para xml:lang="en">Load <filename>example.html</filename> into the web + browser and confirm that the + <filename>para<replaceable>n</replaceable>.xml</filename> + files have been included in + <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-marked-sections"> + <title xml:lang="en">Marked Sections</title> + + <para xml:lang="en"><acronym>XML</acronym> provides a mechanism to indicate that + particular pieces of the document should be processed in a + special way. These are called + <quote>marked sections</quote>.</para> + + <example> + <title xml:lang="en">Structure of a Marked Section</title> + + <programlisting xml:lang="en"><![<replaceable>KEYWORD</replaceable>[ + Contents of marked section +]]></programlisting> + </example> + + <para xml:lang="en">As expected of an <acronym>XML</acronym> construct, a marked + section starts with <literal><!</literal>.</para> + + <para xml:lang="en">The first square bracket begins the marked section.</para> + + <para xml:lang="en"><replaceable>KEYWORD</replaceable> describes how this marked + section is to be processed by the parser.</para> + + <para xml:lang="en">The second square bracket indicates the start of the + marked section's content.</para> + + <para xml:lang="en">The marked section is finished by closing the two square + brackets, and then returning to the document context from the + <acronym>XML</acronym> context with + <literal>></literal>.</para> + + <sect2 xml:id="xml-primer-marked-section-keywords"> + <title xml:lang="en">Marked Section Keywords</title> + + <sect3 xml:id="xml-primer-cdata"> + <title xml:lang="en"><literal>CDATA</literal></title> + + <para xml:lang="en">These keywords denote the marked sections + <emphasis>content model</emphasis>, and allow you to change + it from the default.</para> + + <para xml:lang="en">When an <acronym>XML</acronym> parser is processing a + document, it keeps track of the + <quote>content model</quote>.</para> + + <para xml:lang="en">The content model describes the + content the parser is expecting to see and what it will do + with that content.</para> + + <para xml:lang="en">The <literal>CDATA</literal> content model is one of the + most useful.</para> + + <para xml:lang="en"><literal>CDATA</literal> is for + <quote>Character Data</quote>. When the parser is in this + content model, it expects to see only characters. In this + model the <literal><</literal> and + <literal>&</literal> symbols lose their special status, + and will be treated as ordinary characters.</para> + + <note> + <para xml:lang="en">When using <literal>CDATA</literal> in examples of + text marked up in <acronym>XML</acronym>, remember that + the content of <literal>CDATA</literal> is not validated. + The included text must be check with other means. For + example, the content could be written in another document, + validated, and then pasted into the + <literal>CDATA</literal> section.</para> + </note> + + <example> + <title xml:lang="en">Using a <literal>CDATA</literal> Marked + Section</title> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Here is an example of how to include some text that contains + many <tag class="starttag">literal</tag>&lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;<tag class="endtag">literal</tag> + symbols. The sample text is a fragment of + <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and + <tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag><![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the + elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle + brackets are used so many times, it is simpler to say the whole + example is a CDATA marked section than to use the entity names for + the left and right angle brackets throughout.<tag class="endtag">p</tag> + + <tag class="starttag">ul</tag> + <tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag> + <tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag> + <tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag> + <tag class="endtag">ul</tag> + + <tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting> + </example> + </sect3> + + <sect3 xml:id="xml-primer-include-ignore"> + <title xml:lang="en"><literal>INCLUDE</literal> and + <literal>IGNORE</literal></title> + + <para xml:lang="en">When the keyword is <literal>INCLUDE</literal>, then the + contents of the marked section will be processed. When the + keyword is <literal>IGNORE</literal>, the marked section + is ignored and will not be processed. It will not appear in + the output.</para> + + <example> + <title xml:lang="en">Using <literal>INCLUDE</literal> and + <literal>IGNORE</literal> in Marked Sections</title> + + <programlisting xml:lang="en"><![INCLUDE[ + This text will be processed and included. +]]> + +<![IGNORE[ + This text will not be processed or included. +]]></programlisting> + </example> + + <para xml:lang="en">By itself, this is not too useful. Text to be + removed from the document could be cut out, or wrapped + in comments.</para> + + <para xml:lang="en">It becomes more useful when controlled by + <link linkend="xml-primer-parameter-entities">parameter + entities</link>, yet this usage is limited + to entity files.</para> + + <para xml:lang="en">For example, suppose that documentation was produced in + a hard-copy version and an electronic version. Some extra + text is desired in the electronic version content that was + not to appear in the hard-copy.</para> + + <para xml:lang="en">Create an entity file that defines general entities to + include each chapter and guard these definitions with a + parameter entity that can be set to either + <literal>INCLUDE</literal> or <literal>IGNORE</literal> to + control whether the entity is defined. After these + conditional general entity definitions, place one more + definition for each general entity to set them to an empty + value. This technique makes use of the fact that entity + definitions cannot be overridden but the first definition + always takes effect. So the inclusion of the chapter is + controlled with the corresponding parameter entity. Set to + <literal>INCLUDE</literal>, the first general entity + definition will be read and the second one will be ignored. + Set to <literal>IGNORE</literal>, the first definition will + be ignored and the second one will take effect.</para> + + <example> + <title xml:lang="en">Using a Parameter Entity to Control a Marked + Section</title> + + <programlisting xml:lang="en"><!ENTITY % electronic.copy "INCLUDE"> + +<![%electronic.copy;[ +<!ENTITY chap.preface SYSTEM "preface.xml"> +]]> + +<!ENTITY chap.preface ""></programlisting> + + <para xml:lang="en">When producing the hard-copy version, change the + parameter entity's definition to:</para> + + <programlisting xml:lang="en"><!ENTITY % electronic.copy "IGNORE"></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title xml:lang="en">To Do…</title> + + <procedure> + <step> + <para xml:lang="en">Modify <filename>entities.ent</filename> to + contain the following:</para> + + <programlisting xml:lang="en"><!ENTITY version "1.1"> +<!ENTITY % conditional.text "IGNORE"> + +<![%conditional.text;[ +<!ENTITY para1 SYSTEM "para1.xml"> +]]> + +<!ENTITY para1 ""> + +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"></programlisting> + </step> + + <step> + <para xml:lang="en">Normalize <filename>example.xml</filename> + and notice that the conditional text is not present in the + output document. Set the parameter entity + guard to <literal>INCLUDE</literal> and regenerate the + normalized document and the text will appear again. + This method makes sense if there are more + conditional chunks depending on the same condition. For + example, to control generating printed or online + text.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-conclusion"> + <title xml:lang="en">Conclusion</title> + + <para xml:lang="en">That is the conclusion of this <acronym>XML</acronym> + primer. For reasons of space and complexity, several things + have not been covered in depth (or at all). However, the + previous sections cover enough <acronym>XML</acronym> to + introduce the organization of the <acronym>FDP</acronym> + documentation.</para> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="xhtml-markup"> + <title xml:lang="en"><acronym>XHTML</acronym> Markup</title> + + <sect1 xml:id="xhtml-markup-introduction"> + <title xml:lang="en">Introduction</title> + + <para xml:lang="en">This chapter describes usage of the <acronym>XHTML</acronym> + markup language used for the FreeBSD web site.</para> + + <para xml:lang="en"><acronym>XHTML</acronym> is the <acronym>XML</acronym> + version of the HyperText Markup Language, the markup language of + choice on the World Wide Web. More information can be found at + <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para> + + <para xml:lang="en"><acronym>XHTML</acronym> is used to mark up pages on the + FreeBSD web site. It is usually not used to mark up other + documentation, since DocBook offers a far richer set of elements + from which to choose. Consequently, <acronym>XHTML</acronym> + pages will normally only be encountered when writing for the web + site.</para> + + <para xml:lang="en"><acronym>HTML</acronym> has gone through a number of + versions. The <acronym>XML</acronym>-compliant version + described here is called <acronym>XHTML</acronym>. The latest + widespread version is <acronym>XHTML</acronym> 1.0, available in + both <emphasis>strict</emphasis> and + <emphasis>transitional</emphasis> variants.</para> + + <para xml:lang="en">The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are + available from the Ports Collection in + <package>textproc/xhtml</package>. They are + automatically installed by the <package>textproc/docproj</package> port.</para> + + <note> + <para xml:lang="en">This is <emphasis>not</emphasis> an exhaustive list of + elements, since that would just repeat the documentation for + <acronym>XHTML</acronym>. The aim is to list those elements + most commonly used. Please post questions about elements or + uses not covered here to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para> + </note> + + <note> + <title xml:lang="en">Inline Versus Block</title> + + <para xml:lang="en">In the remainder of this document, when describing + elements, <emphasis>inline</emphasis> means that the element + can occur within a block element, and does not cause a line + break. A <emphasis>block</emphasis> element, by comparison, + will cause a line break (and other processing) when it is + encountered.</para> + </note> + </sect1> + + <sect1 xml:id="xhtml-markup-fpi"> + <title xml:lang="en">Formal Public Identifier (<acronym>FPI</acronym>)</title> + + <para xml:lang="en">There are a number of <acronym>XHTML</acronym> + <acronym>FPI</acronym>s, depending upon the version, or + <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which + a document conforms. Most <acronym>XHTML</acronym> documents on + the FreeBSD web site comply with the transitional version of + <acronym>XHTML</acronym> 1.0.</para> + + <programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> + </sect1> + + <sect1 xml:id="xhtml-markup-sectional-elements"> + <title xml:lang="en">Sectional Elements</title> + + <para xml:lang="en">An <acronym>XHTML</acronym> document is normally split into + two sections. The first section, called the + <emphasis>head</emphasis>, contains meta-information about the + document, such as its title, the name of the author, the parent + document, and so on. The second section, the + <emphasis>body</emphasis>, contains content that will be + displayed to the user.</para> + + <para xml:lang="en">These sections are indicated with <tag>head</tag> + and <tag>body</tag> elements respectively. These + elements are contained within the top-level + <tag>html</tag> element.</para> + + <example> + <title xml:lang="en">Normal <acronym>XHTML</acronym> Document + Structure</title> + + <programlisting xml:lang="en"><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <tag class="starttag">body</tag> + + … + + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </example> + </sect1> + + <sect1 xml:id="xhtml-markup-block-elements"> + <title xml:lang="en">Block Elements</title> + + <sect2 xml:id="xhtml-markup-block-elements-headings"> + <title xml:lang="en">Headings</title> + + <para xml:lang="en"><acronym>XHTML</acronym> has tags to denote headings in + the document at up to six different levels.</para> + + <para xml:lang="en">The largest and most prominent heading is + <tag>h1</tag>, then <tag>h2</tag>, + continuing down to <tag>h6</tag>.</para> + + <para xml:lang="en">The element's content is the text of the heading.</para> + + <example> + <title xml:lang="en"><tag>h1</tag>, <tag>h2</tag>, + and Other Header Tags</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag> + +<!-- Document introduction goes here --> + +<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag> + +<!-- Content for the first section goes here --> + +<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag> + +<!-- Content for the first sub-section goes here --> + +<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag> + +<!-- Content for the second section goes here --></programlisting> + </example> + + <para xml:lang="en">Generally, an <acronym>XHTML</acronym> page should have + one first level heading (<tag>h1</tag>). This can + contain many second level headings (<tag>h2</tag>), + which can in turn contain many third level headings. Do not + leave gaps in the numbering.</para> + </sect2> + + <sect2 xml:id="xhtml-markup-block-elements-paragraphs"> + <title xml:lang="en">Paragraphs</title> + + <para xml:lang="en"><acronym>XHTML</acronym> supports a single paragraph + element, <tag>p</tag>.</para> + + <example> + <title xml:lang="en"><tag>p</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It can contain just about any + other element.<tag class="endtag">p</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="xhtml-markup-block-elements-block-quotations"> + <title xml:lang="en">Block Quotations</title> + + <para xml:lang="en">A block quotation is an extended quotation from another + document that will appear in a separate paragraph.</para> + + <example> + <title xml:lang="en"><tag>blockquote</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag> + +<tag class="starttag">blockquote</tag>We the People of the United States, in Order to form + a more perfect Union, establish Justice, insure domestic + Tranquility, provide for the common defence, promote the general + Welfare, and secure the Blessings of Liberty to ourselves and our + Posterity, do ordain and establish this Constitution for the + United States of America.<tag class="endtag">blockquote</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="xhtml-markup-block-elements-lists"> + <title xml:lang="en">Lists</title> + + <para xml:lang="en"><acronym>XHTML</acronym> can present the user with three + types of lists: ordered, unordered, and definition.</para> + + <para xml:lang="en">Entries in an ordered list will be numbered, while entries + in an unordered list will be preceded by bullet points. + Definition lists have two sections for each entry. The first + section is the term being defined, and the second section is + the definition.</para> + + <para xml:lang="en">Ordered lists are indicated by the <tag>ol</tag> + element, unordered lists by the <tag>ul</tag> + element, and definition lists by the <tag>dl</tag> + element.</para> + + <para xml:lang="en">Ordered and unordered lists contain listitems, indicated + by the <tag>li</tag> element. A listitem can + contain textual content, or it may be further wrapped in one + or more <tag>p</tag> elements.</para> + + <para xml:lang="en">Definition lists contain definition terms + (<tag>dt</tag>) and definition descriptions + (<tag>dd</tag>). A definition term can only contain + inline elements. A definition description can contain other + block elements.</para> + + <example> + <title xml:lang="en"><tag>ul</tag> and + <tag>ol</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>An unordered list. Listitems will probably be + preceded by bullets.<tag class="endtag">p</tag> + +<tag class="starttag">ul</tag> + <tag class="starttag">li</tag>First item<tag class="endtag">li</tag> + + <tag class="starttag">li</tag>Second item<tag class="endtag">li</tag> + + <tag class="starttag">li</tag>Third item<tag class="endtag">li</tag> +<tag class="endtag">ul</tag> + +<tag class="starttag">p</tag>An ordered list, with list items consisting of multiple + paragraphs. Each item (note: not each paragraph) will be + numbered.<tag class="endtag">p</tag> + +<tag class="starttag">ol</tag> + <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item. It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag> + + <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag> + + <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third + item.<tag class="endtag">p</tag><tag class="endtag">li</tag> +<tag class="endtag">ol</tag></programlisting> + </example> + + <example> + <title xml:lang="en">Definition Lists with <tag>dl</tag></title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">dl</tag> + <tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag> + + <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag> + + <tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag> + + <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag> + + <tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag> + + <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag> +<tag class="endtag">dl</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="xhtml-markup-block-elements-preformatted-text"> + <title xml:lang="en">Pre-formatted Text</title> + + <para xml:lang="en">Pre-formatted text is shown to the user exactly as it is + in the file. Text is shown in a fixed font. Multiple spaces + and line breaks are shown exactly as they are in the + file.</para> + + <para xml:lang="en">Wrap pre-formatted text in the <tag>pre</tag> + element.</para> + + <example> + <title xml:lang="en"><tag>pre</tag> Example</title> + + <para xml:lang="en">For example, the <tag>pre</tag> tags could be + used to mark up an email message:</para> + + <programlisting xml:lang="en"><tag class="starttag">pre</tag> From: nik@FreeBSD.org + To: freebsd-doc@FreeBSD.org + Subject: New documentation available + + There is a new copy of my primer for contributors to the FreeBSD + Documentation Project available at + + &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt; + + Comments appreciated. + + N<tag class="endtag">pre</tag></programlisting> + + <para xml:lang="en">Keep in mind that <literal><</literal> and + <literal>&</literal> still are recognized as special + characters in pre-formatted text. This is why the example + shown had to use <literal>&lt;</literal> instead of + <literal><</literal>. For consistency, + <literal>&gt;</literal> was used in place of + <literal>></literal>, too. Watch out for the special + characters that may appear in text copied from a plain-text + source, like an email message or program code.</para> + </example> + </sect2> + + <sect2 xml:id="xhtml-markup-block-elements-tables"> + <title xml:lang="en">Tables</title> + + <para xml:lang="en">Mark up tabular information using the + <tag>table</tag> element. A table consists of one or + more table rows (<tag>tr</tag>), each containing one + or more cells of table data (<tag>td</tag>). Each + cell can contain other block elements, such as paragraphs or + lists. It can also contain another table (this nesting can + repeat indefinitely). If the cell only contains one paragraph + then the <tag>p</tag>element is not needed.</para> + + <example> + <title xml:lang="en">Simple Use of <tag>table</tag></title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag> + +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag> + + <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> + + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> + + <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> + </example> + + <para xml:lang="en">A cell can span multiple rows and columns by adding the + <tag class="attribute">rowspan</tag> or + <tag class="attribute">colspan</tag> attributes with + values for the number of rows or columns to be spanned.</para> + + <example> + <title xml:lang="en">Using + <tag class="attribute">rowspan</tag></title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to + it on the right.<tag class="endtag">p</tag> + +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> + + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag> + + <tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> + </example> + + <example> + <title xml:lang="en">Using + <tag class="attribute">colspan</tag></title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag> + +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> + + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> + + <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> + </example> + + <example> + <title xml:lang="en">Using <tag class="attribute">rowspan</tag> and + <tag class="attribute">colspan</tag> + Together</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of + cells merged into one. The other cells are normal.<tag class="endtag">p</tag> + +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag> + + <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> + + <tag class="starttag">tr</tag> + <!-- Because the large cell on the left merges into + this row, the first <td> will occur on its + right --> + + <tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> + + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> + + <tag class="starttag">td</tag>Bottom middle cell<tag class="endtag">td</tag> + + <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> + </example> + </sect2> + </sect1> + + <sect1 xml:id="xhtml-markup-inline-elements"> + <title xml:lang="en">In-line Elements</title> + + <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information"> + <title xml:lang="en">Emphasizing Information</title> + + <para xml:lang="en">Two levels of emphasis are available in + <acronym>XHTML</acronym>, <tag>em</tag> and + <tag>strong</tag>. <tag>em</tag> is for a + normal level of emphasis and <tag>strong</tag> + indicates stronger emphasis.</para> + + <para xml:lang="en"><tag>em</tag> is typically rendered in italic + and <tag>strong</tag> is rendered in bold. This is + not always the case, and should not be relied upon. According + to best practices, web pages only hold structural and + semantical information, and stylesheets are later applied to + them. Think of semantics, not formatting, when using these + tags.</para> + + <example> + <title xml:lang="en"><tag>em</tag> and + <tag>strong</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while + <tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text"> + <title xml:lang="en">Indicating Fixed-Pitch Text</title> + + <para xml:lang="en">Content that should be rendered in a fixed pitch + (typewriter) typeface is tagged with <tag>tt</tag> + (for <quote>teletype</quote>).</para> + + <example> + <title xml:lang="en"><tag>tt</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>Many system settings are stored in + <tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="xhtml-markup-inline-elements-links"> + <title xml:lang="en">Links</title> + + <note> + <para xml:lang="en">Links are also inline elements.</para> + </note> + + <sect3 xml:id="xhtml-markup-inline-elements-linking"> + <title xml:lang="en">Linking to Other Documents on the Web</title> + + <para xml:lang="en">A link points to the <acronym>URL</acronym> of a + document on the web. The link is indicated with + <tag>a</tag>, and the + <tag class="attribute">href</tag> attribute contains + the <acronym>URL</acronym> of the target document. The + content of the element becomes the link, indicated to the + user by showing it in a different color or with an + underline.</para> + + <example> + <title xml:lang="en">Using + <tag class="starttag">a href="..."</tag></title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>More information is available at the + <tag class="starttag">a href="http://www.&os;.org/"</tag>&os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">This link always takes the user to the top of the linked + document.</para> + </sect3> + + <sect3 xml:id="xhtml-markup-inline-elements-specific-parts"> + <title xml:lang="en">Linking to Specific Parts of Documents</title> + + <para xml:lang="en">To link to a specific point within a document, that + document must include an <emphasis>anchor</emphasis> at the + desired point. Anchors are included by setting the + <tag class="attribute">id</tag> attribute of an + element to a name. This example creates an anchor by + setting the <tag class="attribute">id</tag> + attribute of a <tag class="element">p</tag> + element.</para> + + <example> + <title xml:lang="en">Creating an Anchor</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced + in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">Links to anchors are similar to plain links, but include + a <literal>#</literal> symbol and the anchor's + <acronym>ID</acronym> at the end of the + <acronym>URL</acronym>.</para> + + <example> + <title xml:lang="en">Linking to a Named Part of a Different + Document</title> + + <para xml:lang="en">The <literal>samplepara</literal> example is part of a + document called <filename>foo.html</filename>. A link to + that specific paragraph in the document is constructed in + this example.</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>More information can be found in the + <tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of + <tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> + </example> + + <para xml:lang="en">To link to a named anchor within the same document, omit + the document's <acronym>URL</acronym>, and just use the + <literal>#</literal> symbol followed by the name of the + anchor.</para> + + <example> + <title xml:lang="en">Linking to a Named Part of the Same Document</title> + + <para xml:lang="en">The <literal>samplepara</literal> example + resides in this document. To link to it:</para> + + <programlisting xml:lang="en"><tag class="starttag">p</tag>More information can be found in the + <tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this + document.<tag class="endtag">p</tag></programlisting> + </example> + </sect3> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> + +<chapter version="5.0" xml:id="docbook-markup"> + + <title xml:lang="en">DocBook Markup</title> + + <sect1 xml:id="docbook-markup-introduction"> + <title xml:lang="en">Introduction</title> + + <para xml:lang="en">This chapter is an introduction to DocBook as it is used for + FreeBSD documentation. DocBook is a large and complex markup + system, but the subset described here covers the parts that are + most widely used for FreeBSD documentation. While a moderate + subset is covered, it is impossible to anticipate every + situation. Please post questions that this document does + not answer to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para> + + <para xml:lang="en">DocBook was originally developed by HaL Computer Systems and + O'Reilly & Associates to be a Document Type Definition + (<acronym>DTD</acronym>) for writing technical documentation + <footnote><para xml:lang="en">A short history can be found under <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>. + Since 1998 it is maintained by the <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> + DocBook Technical Committee</link>. As such, and unlike + LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily + oriented towards markup that describes <emphasis>what</emphasis> + something is, rather than describing <emphasis>how</emphasis> it + should be presented.</para> + + <para xml:lang="en">The DocBook <acronym>DTD</acronym> is available from the + Ports Collection in the + <package>textproc/docbook-xml</package> + port. It is automatically installed as part of the + <package>textproc/docproj</package> + port.</para> + + <note> + <title xml:lang="en">Formal Versus Informal</title> + + <para xml:lang="en">Some elements may exist in two forms, + <emphasis>formal</emphasis> and <emphasis>informal</emphasis>. + Typically, the formal version of the element will consist of a + title followed by the informal version of the element. The + informal version will not have a title.</para> + </note> + + <note> + <title xml:lang="en">Inline Versus Block</title> + + <para xml:lang="en">In the remainder of this document, when describing + elements, <emphasis>inline</emphasis> means that the element + can occur within a block element, and does not cause a line + break. A <emphasis>block</emphasis> element, by comparison, + will cause a line break (and other processing) when it is + encountered.</para> + </note> + </sect1> + + <sect1 xml:id="docbook-markup-freebsd-extensions"> + <title xml:lang="en">FreeBSD Extensions</title> + + <para xml:lang="en">The FreeBSD Documentation Project has extended the DocBook + <acronym>DTD</acronym> with additional elements and entities. + These additions serve to make some of the markup easier or more + precise.</para> + + <para xml:lang="en">Throughout the rest of this document, the term + <quote>DocBook</quote> is used to mean the FreeBSD-extended + DocBook <acronym>DTD</acronym>.</para> + + <note> + <para xml:lang="en">Most of these extensions are not unique to FreeBSD, it was + just felt that they were useful enhancements for this + particular project. Should anyone from any of the other *nix + camps (NetBSD, OpenBSD, Linux, …) be interested in + collaborating on a standard DocBook extension set, please + contact Documentation Engineering Team <email>doceng@FreeBSD.org</email>.</para> + </note> + + <sect2 xml:id="docbook-markup-freebsd-extensions-elements"> + <title xml:lang="en">FreeBSD Elements</title> + + <para xml:lang="en">The additional FreeBSD elements are not (currently) in the + Ports Collection. They are stored in the FreeBSD Subversion + tree, as <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para> + + <para xml:lang="en">FreeBSD-specific elements used in the examples below are + clearly marked.</para> + </sect2> + + <sect2 xml:id="docbook-markup-freebsd-extensions-entities"> + <title xml:lang="en">FreeBSD Entities</title> + + <para xml:lang="en">This table shows some of the most useful entities + available in the <acronym>FDP</acronym>. For a complete list, + see the <filename>*.ent</filename> files in + <filename>doc/share/xml</filename>.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <colspec colname="entity"/> + <colspec colname="expandsto"/> + <colspec colname="notes"/> + <thead> + <row> + <entry/> + <entry/> + <entry/> + </row> + </thead> + + <tbody valign="top"> + <row> + <entry namest="entity" nameend="notes" xml:lang="en"><emphasis>FreeBSD + Name Entities</emphasis></entry> + </row> + + <row> + <entry xml:lang="en"><literal>&os;</literal></entry> + <entry xml:lang="en"><literal>FreeBSD</literal></entry> + <entry/> + </row> + + <row> + <entry xml:lang="en"><literal>&os.stable;</literal></entry> + <entry xml:lang="en"><literal>FreeBSD-STABLE</literal></entry> + <entry/> + </row> + + <row> + <entry xml:lang="en"><literal>&os.current;</literal></entry> + <entry xml:lang="en"><literal>FreeBSD-CURRENT</literal></entry> + <entry/> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes" xml:lang="en">Manual Page + Entities</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&man.ls.1;</literal></entry> + <entry xml:lang="en"><citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> + <entry xml:lang="en">Usage: <literal>&man.ls.1; is the manual page + for + <command>ls</command>.</literal></entry> + </row> + + <row> + <entry xml:lang="en"><literal>&man.cp.1;</literal></entry> + <entry xml:lang="en"><citerefentry><refentrytitle>cp</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> + <entry xml:lang="en">Usage: <literal>The manual page for + <command>cp</command> is + &man.cp.1;.</literal></entry> + </row> + + <row> + <entry xml:lang="en"><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry> + <entry xml:lang="en"><emphasis>link to + <replaceable>command</replaceable> manual page in + section + <replaceable>sectionnumber</replaceable></emphasis></entry> + <entry xml:lang="en">Entities are defined for all the + <link xlink:href="@@URL_RELPREFIX@@/cgi/man.cgi">FreeBSD manual + pages</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes" xml:lang="en">FreeBSD Mailing List + Entities</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&a.doc;</literal></entry> + <entry xml:lang="en"><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link></literal></entry> + <entry xml:lang="en">Usage: <literal>A link to the + &a.doc;.</literal></entry> + </row> + + <row> + <entry xml:lang="en"><literal>&a.questions;</literal></entry> + <entry xml:lang="en"><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions">FreeBSD general questions mailing list</link></literal></entry> + <entry xml:lang="en">Usage: <literal>A link to the + &a.questions;.</literal></entry> + </row> + + <row> + <entry xml:lang="en"><literal>&a.<replaceable>listname</replaceable>;</literal></entry> + <entry xml:lang="en"><emphasis>link to + <replaceable>listname</replaceable></emphasis></entry> + <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/eresources.html#eresources-mail">FreeBSD + mailing lists</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes" xml:lang="en">FreeBSD Document + Link Entities</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&url.books.handbook;</literal></entry> + <entry xml:lang="en"><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook</literal></entry> + <entry xml:lang="en">Usage: <literal>A link to the <link + xlink:href="&url.books.handbook;/advanced-networking.html">Advanced + Networking</link> chapter of the + Handbook.</literal></entry> + </row> + + <row> + <entry xml:lang="en"><literal>&url.books.<replaceable>bookname</replaceable>;</literal></entry> + <entry xml:lang="en"><emphasis>relative path to + <replaceable>bookname</replaceable></emphasis></entry> + <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/">FreeBSD + books</link>.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&url.articles.committers-guide;</literal></entry> + <entry xml:lang="en"><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide</literal></entry> + <entry xml:lang="en">Usage: <literal>A link to the <link + xlink:href="&url.articles.committers-guide;">Committer's + Guide</link> + article.</literal></entry> + </row> + + <row> + <entry xml:lang="en"><literal>&url.articles.<replaceable>articlename</replaceable>;</literal></entry> + <entry xml:lang="en"><emphasis>relative path to + <replaceable>articlename</replaceable></emphasis></entry> + <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/">FreeBSD + articles</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes" xml:lang="en">Other Operating + System Name Entities</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&linux;</literal></entry> + <entry xml:lang="en"><trademark class="registered">Linux</trademark></entry> + <entry xml:lang="en">The <trademark class="registered">Linux</trademark> operating system.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&unix;</literal></entry> + <entry xml:lang="en"><trademark class="registered">UNIX</trademark></entry> + <entry xml:lang="en">The <trademark class="registered">UNIX</trademark> operating system.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&windows;</literal></entry> + <entry xml:lang="en"><trademark class="registered">Windows</trademark></entry> + <entry xml:lang="en">The <trademark class="registered">Windows</trademark> operating system.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes" xml:lang="en">Miscellaneous + Entities</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&prompt.root;</literal></entry> + <entry><prompt>#</prompt></entry> + <entry xml:lang="en">The <systemitem class="username">root</systemitem> user + prompt.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&prompt.user;</literal></entry> + <entry><prompt>%</prompt></entry> + <entry xml:lang="en">A prompt for an unprivileged user.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&postscript;</literal></entry> + <entry xml:lang="en"><trademark class="registered">PostScript</trademark></entry> + <entry xml:lang="en">The + <trademark class="registered">PostScript</trademark> programming language.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&tex;</literal></entry> + <entry xml:lang="en"><application>TeX</application></entry> + <entry xml:lang="en">The + <application>TeX</application> typesetting language.</entry> + </row> + + <row> + <entry xml:lang="en"><literal>&xorg;</literal></entry> + <entry xml:lang="en">Xorg</entry> + <entry xml:lang="en">The Xorg open source X + Window System.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-fpi"> + <title xml:lang="en">Formal Public Identifier (FPI)</title> + + <para xml:lang="en">In compliance with the DocBook guidelines for writing + <acronym>FPI</acronym>s for DocBook customizations, the + <acronym>FPI</acronym> for the FreeBSD extended DocBook + <acronym>DTD</acronym> is:</para> + + <programlisting xml:lang="en">PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> + </sect1> + + <sect1 xml:id="docbook-markup-document-structure"> + <title xml:lang="en">Document Structure</title> + + <para xml:lang="en">DocBook allows structuring documentation in several ways. + The FreeBSD Documentation Project uses two primary types of DocBook + document: the book and the article.</para> + + <para xml:lang="en">Books are organized into <tag>chapter</tag>s. + This is a mandatory requirement. There may be + <tag>part</tag>s between the book and the chapter to + provide another layer of organization. For example, the + Handbook is arranged in this way.</para> + + <para xml:lang="en">A chapter may (or may not) contain one or more sections. + These are indicated with the <tag>sect1</tag> element. + If a section contains another section then use the + <tag>sect2</tag> element, and so on, up to + <tag>sect5</tag>.</para> + + <para xml:lang="en">Chapters and sections contain the remainder of the + content.</para> + + <para xml:lang="en">An article is simpler than a book, and does not use + chapters. Instead, the content of an article is organized into + one or more sections, using the same <tag>sect1</tag> + (and <tag>sect2</tag> and so on) elements that are used + in books.</para> + + <para xml:lang="en">The nature of the document being written should be used to + determine whether it is best marked up as a book or an article. + Articles are well suited to information that does not need to be + broken down into several chapters, and that is, relatively + speaking, quite short, at up to 20-25 pages of content. Books + are best suited to information that can be broken up into + several chapters, possibly with appendices and similar content + as well.</para> + + <para xml:lang="en">The <link xlink:href="@@URL_RELPREFIX@@/docs.html">FreeBSD + tutorials</link> are all marked up as articles, while this + document, the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/index.html">FAQ</link>, + and the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">Handbook</link> are all marked up as books, for + example.</para> + + <sect2 xml:id="docbook-markup-starting-a-book"> + <title xml:lang="en">Starting a Book</title> + + <para xml:lang="en">The content of a book is contained within the + <tag>book</tag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the book. This is either + meta-information, used for reference purposes, or additional + content used to produce a title page.</para> + + <para xml:lang="en">This additional information is contained within + <tag>info</tag>.</para> + + <example> + <title xml:lang="en">Boilerplate <tag>book</tag> with + <tag>info</tag></title> + + <!-- Cannot put this in a marked section because of the + replaceable elements --> + + <programlisting xml:lang="en"><tag class="starttag">book</tag> + <tag class="starttag">info</tag> + <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + … + +<tag class="endtag">book</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-starting-an-article"> + <title xml:lang="en">Starting an Article</title> + + <para xml:lang="en">The content of the article is contained within the + <tag>article</tag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the article. This is + either meta-information, used for reference purposes, or + additional content used to produce a title page.</para> + + <para xml:lang="en">This additional information is contained within + <tag>info</tag>.</para> + + <example> + <title xml:lang="en">Boilerplate <tag>article</tag> with + <tag>info</tag></title> + + <!-- Cannot put this in a marked section because of the + replaceable elements --> + + <programlisting xml:lang="en"><tag class="starttag">article</tag> + <tag class="starttag">info</tag> + <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + … + +<tag class="endtag">article</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-indicating-chapters"> + <title xml:lang="en">Indicating Chapters</title> + + <para xml:lang="en">Use <tag>chapter</tag> to mark up your chapters. + Each chapter has a mandatory <tag>title</tag>. + Articles do not contain chapters, they are reserved for + books.</para> + + <example> + <title xml:lang="en">A Simple Chapter</title> + + <programlisting xml:lang="en"><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag> + + ... +<tag class="endtag">chapter</tag></programlisting> + </example> + + <para xml:lang="en">A chapter cannot be empty; it must contain elements in + addition to <tag>title</tag>. If you need to + include an empty chapter then just use an empty + paragraph.</para> + + <example> + <title xml:lang="en">Empty Chapters</title> + + <programlisting xml:lang="en"><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag> + + <tag class="starttag">para</tag><tag class="endtag">para</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-sections-below-chapters"> + <title xml:lang="en">Sections Below Chapters</title> + + <para xml:lang="en">In books, chapters may (but do not need to) be broken up + into sections, subsections, and so on. In articles, sections + are the main structural element, and each article must contain + at least one section. Use the + <tag>sect<replaceable>n</replaceable></tag> element. + The <replaceable>n</replaceable> indicates the section number, + which identifies the section level.</para> + + <para xml:lang="en">The first + <tag>sect<replaceable>n</replaceable></tag> is + <tag>sect1</tag>. You can have one or more of these + in a chapter. They can contain one or more + <tag>sect2</tag> elements, and so on, down to + <tag>sect5</tag>.</para> + + <example> + <title xml:lang="en">Sections in Chapters</title> + + <programlisting xml:lang="en"><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag> + + … + <tag class="endtag">sect1</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag> + + <tag class="starttag">sect3</tag> + <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag> + + … + <tag class="endtag">sect3</tag> + <tag class="endtag">sect2</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag> + + … + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + + <note> + <para xml:lang="en">Section numbers are automatically generated and + prepended to titles when the document is rendered to an + output format. The generated section numbers and titles + from the example above will be:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">1.1. First Section</para> + </listitem> + + <listitem> + <para xml:lang="en">1.2. Second Section</para> + </listitem> + + <listitem> + <para xml:lang="en">1.2.1. First Sub-Section</para> + </listitem> + + <listitem> + <para xml:lang="en">1.2.1.1. First Sub-Sub-Section</para> + </listitem> + + <listitem> + <para xml:lang="en">1.2.2. Second Sub-Section</para> + </listitem> + </itemizedlist> + </note> + </sect2> + + <sect2 xml:id="docbook-markup-subdividing-part"> + <title xml:lang="en">Subdividing Using <tag>part</tag> + Elements</title> + + <para xml:lang="en"><tag>part</tag>s introduce another level of + organization between <tag>book</tag> and + <tag>chapter</tag> with one or more + <tag>part</tag>s. This cannot be done in an + <tag>article</tag>.</para> + + <programlisting xml:lang="en"><tag class="starttag">part</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>History<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> +<tag class="endtag">part</tag></programlisting> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-block-elements"> + <title xml:lang="en">Block Elements</title> + + <sect2 xml:id="docbook-markup-paragraphs"> + <title xml:lang="en">Paragraphs</title> + + <para xml:lang="en">DocBook supports three types of paragraphs: + <tag>formalpara</tag>, <tag>para</tag>, and + <tag>simpara</tag>.</para> + + <para xml:lang="en">Almost all paragraphs in FreeBSD documentation use + <tag>para</tag>. <tag>formalpara</tag> + includes a <tag>title</tag> element, and + <tag>simpara</tag> disallows some elements from + within <tag>para</tag>. Stick with + <tag>para</tag>.</para> + + <example> + <title xml:lang="en"><tag>para</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>This is a paragraph. It can contain just about any + other element.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">This is a paragraph. It can contain just about any + other element.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-block-quotations"> + <title xml:lang="en">Block Quotations</title> + + <para xml:lang="en">A block quotation is an extended quotation from another + document that should not appear within the current paragraph. + These are rarely needed.</para> + + <para xml:lang="en">Blockquotes can optionally contain a title and an + attribution (or they can be left untitled and + unattributed).</para> + + <example> + <title xml:lang="en"><tag>blockquote</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag> + +<tag class="starttag">blockquote</tag> + <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag> + + <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag> + + <tag class="starttag">para</tag>We the People of the United States, in Order to form a more + perfect Union, establish Justice, insure domestic Tranquility, + provide for the common defence, promote the general Welfare, and + secure the Blessings of Liberty to ourselves and our Posterity, do + ordain and establish this Constitution for the United States of + America.<tag class="endtag">para</tag> +<tag class="endtag">blockquote</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">A small excerpt from the US Constitution:</para> + + <blockquote> + <title xml:lang="en">Preamble to the Constitution of the United + States</title> + + <attribution xml:lang="en">Copied from a web site + somewhere</attribution> + + <para xml:lang="en">We the People of the United States, in Order to form + a more perfect Union, establish Justice, insure domestic + Tranquility, provide for the common defence, promote the + general Welfare, and secure the Blessings of Liberty to + ourselves and our Posterity, do ordain and establish + this Constitution for the United States of + America.</para> + </blockquote> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-tips-notes"> + <title xml:lang="en">Tips, Notes, Warnings, Cautions, and Important + Information</title> + + <para xml:lang="en">Extra information may need to be separated from + the main body of the text. Typically this is + <quote>meta</quote> information of which the user should be + aware.</para> + + <para xml:lang="en">Several types of admonitions are available: + <tag>tip</tag>, <tag>note</tag>, + <tag>warning</tag>, <tag>caution</tag>, and + <tag>important</tag>.</para> + + <para xml:lang="en">Which admonition to choose depends on the situation. + The DocBook + documentation suggests:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">Note is for information that should be heeded by + all readers.</para> + </listitem> + + <listitem> + <para xml:lang="en">Important is a variation on Note.</para> + </listitem> + + <listitem> + <para xml:lang="en">Caution is for information regarding possible data + loss or software damage.</para> + </listitem> + + <listitem> + <para xml:lang="en">Warning is for information regarding possible + hardware damage or injury to life or limb.</para> + </listitem> + </itemizedlist> + + <example> + <title xml:lang="en"><tag>tip</tag> and <tag>important</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">tip</tag> + <tag class="starttag">para</tag>&os; may reduce stress.<tag class="endtag">para</tag> +<tag class="endtag">tip</tag> + +<tag class="starttag">important</tag> + <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions + are visually jarring and can have the opposite of the + intended effect.<tag class="endtag">para</tag> +<tag class="endtag">important</tag></programlisting> + </example> + + <para xml:lang="en">Appearance:</para> + <!-- Need to do this outside of the example --> + <tip> + <para xml:lang="en">FreeBSD may reduce stress.</para> + </tip> + + <important> + <para xml:lang="en">Please use admonitions sparingly. Too many admonitions + are visually jarring and can have the opposite of the + intended effect.</para> + </important> + </sect2> + + <sect2 xml:id="docbook-markup-example"> + <title>舉例</title> + + <para xml:lang="en">Examples can be shown with <tag>example</tag>.</para> + + <example> + <title xml:lang="en"><tag>example</tag> Source</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">example</tag> + <tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag> + + <tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag> +<tag class="endtag">example</tag></programlisting> + </example> + + <!-- Need to do this outside of the example --> + <para xml:lang="en">Appearance:</para> + + <example> + <title xml:lang="en">Rendered <tag>example</tag></title> + + <para xml:lang="en">Empty files can be created easily:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>touch file1 file2 file3</userinput></screen> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-lists-and-procedures"> + <title xml:lang="en">Lists and Procedures</title> + + <para xml:lang="en">Information often needs to be presented as lists, or as a + number of steps that must be carried out in order to + accomplish a particular goal.</para> + + <para xml:lang="en">To do this, use <tag>itemizedlist</tag>, + <tag>orderedlist</tag>, <tag>variablelist</tag>, or + <tag>procedure</tag>. There are other types of list + elements in DocBook, but we will not cover them here.</para> + + <para xml:lang="en"><tag>itemizedlist</tag> and + <tag>orderedlist</tag> are similar to their + counterparts in <acronym>HTML</acronym>, <tag>ul</tag> + and <tag>ol</tag>. Each one consists of one or more + <tag>listitem</tag> elements, and each + <tag>listitem</tag> contains one or more block + elements. The <tag>listitem</tag> elements are + analogous to <acronym>HTML</acronym>'s <tag>li</tag> + tags. However, unlike HTML, they are required.</para> + + <example> + <title xml:lang="en"><tag>itemizedlist</tag> and + <tag>orderedlist</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">itemizedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">itemizedlist</tag> + +<tag class="starttag">orderedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">orderedlist</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">This is the first itemized item.</para> + </listitem> + + <listitem> + <para xml:lang="en">This is the second itemized item.</para> + </listitem> + </itemizedlist> + + <orderedlist> + <listitem> + <para xml:lang="en">This is the first ordered item.</para> + </listitem> + + <listitem> + <para xml:lang="en">This is the second ordered item.</para> + </listitem> + </orderedlist> + </example> + + <para xml:id="docbook-markup-varlist" xml:lang="en">An alternate and often + useful way of presenting information is the + <tag>variablelist</tag>. These are lists where each entry has + a term and a description. They are well suited for many types + of descriptions, and present information in a form that is + often easier for the reader than sections and + subsections.</para> + + <para xml:lang="en">A <tag>variablelist</tag> has a <tag>title</tag>, and then + pairs of <tag>term</tag> and <tag>listitem</tag> + entries.</para> + + <example xml:id="docbook-markup-variablelist-example"> + <title xml:lang="en"><tag>variablelist</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">variablelist</tag> + <tag class="starttag">varlistentry</tag> + <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>In parallel communications, groups of bits arrive + at the same time over multiple communications + channels.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + <tag class="endtag">varlistentry</tag> + + <tag class="starttag">varlistentry</tag> + <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>In serial communications, bits arrive one at a + time over a single communications + channel.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + <tag class="endtag">varlistentry</tag> +<tag class="endtag">variablelist</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <variablelist> + <varlistentry> + <term xml:lang="en">Parallel</term> + + <listitem> + <para xml:lang="en">In parallel communications, groups of bits arrive + at the same time over multiple communications + channels.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en">Serial</term> + + <listitem> + <para xml:lang="en">In serial communications, bits arrive one at a + time over a single communications channel.</para> + </listitem> + </varlistentry> + </variablelist> + </example> + + <para xml:lang="en">A <tag>procedure</tag> shows a series of + <tag>step</tag>s, which may in turn + consist of more <tag>step</tag>s or + <tag>substep</tag>s. Each <tag>step</tag> + contains block elements and may include an optional title.</para> + + <para xml:lang="en">Sometimes, steps are not sequential, but present a choice: + do <emphasis>this</emphasis> or do <emphasis>that</emphasis>, + but not both. For these alternative choices, use + <tag>stepalternatives</tag>.</para> + + <example> + <title xml:lang="en"><tag>procedure</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">procedure</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Finally, do one of these.<tag class="endtag">para</tag> + + <tag class="starttag">stepalternatives</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + <tag class="endtag">stepalternatives</tag> + <tag class="endtag">step</tag> +<tag class="endtag">procedure</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <procedure> + <step> + <para xml:lang="en">Do this.</para> + </step> + + <step> + <para xml:lang="en">Then do this.</para> + </step> + + <step> + <para xml:lang="en">And now do this.</para> + </step> + + <step> + <para xml:lang="en">Finally, do one of these:</para> + + <stepalternatives> + <step> + <para xml:lang="en">Go left.</para> + </step> + + <step> + <para xml:lang="en">Go right.</para> + </step> + </stepalternatives> + </step> + </procedure> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-showing-file-samples"> + <title xml:lang="en">Showing File Samples</title> + + <para xml:lang="en">Fragments of a file (or perhaps a complete file) are shown + by wrapping them in the <tag>programlisting</tag> + element.</para> + + <para xml:lang="en">White space and line breaks within + <tag>programlisting</tag> <emphasis>are</emphasis> + significant. In particular, this means that the opening tag + should appear on the same line as the first line of the + output, and the closing tag should appear on the same line + as the last line of the output, otherwise spurious blank + lines may be included.</para> + + <example> + <title xml:lang="en"><tag>programlisting</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; + +int +main(void) +{ + printf("hello, world\n"); +}<tag class="endtag">programlisting</tag></programlisting> + + <para xml:lang="en">Notice how the angle brackets in the + <literal>#include</literal> line need to be referenced by + their entities instead of being included literally.</para> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">When finished, the program will look like this:</para> + + <programlisting xml:lang="en">#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-callouts"> + <title xml:lang="en">Callouts</title> + + <para xml:lang="en">A callout is a visual marker for referring to a + piece of text or specific position within an + example.</para> + + <para xml:lang="en">Callouts are marked with the <tag>co</tag> + element. Each element must have a unique + <literal>id</literal> assigned to it. After the example, + include a <tag>calloutlist</tag> that describes each + callout.</para> + + <example> + <title xml:lang="en"><tag>co</tag> and + <tag>calloutlist</tag> Example</title> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co xml:id="co-ex-include"</tag> + +int <tag class="emptytag">co xml:id="co-ex-return"</tag> +main(void) +{ + printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag> +}<tag class="endtag">programlisting</tag> + +<tag class="starttag">calloutlist</tag> + <tag class="starttag">callout arearefs="co-ex-include"</tag> + <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> + + <tag class="starttag">callout arearefs="co-ex-return"</tag> + <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an + int.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> + + <tag class="starttag">callout arearefs="co-ex-printf"</tag> + <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes + <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> +<tag class="endtag">calloutlist</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">When finished, the program will look like this:</para> + + <programlisting xml:lang="en">#include <stdio.h> <co xml:id="co-ex-include"/> + +int <co xml:id="co-ex-return"/> +main(void) +{ + printf("hello, world\n"); <co xml:id="co-ex-printf"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ex-include"> + <para xml:lang="en">Includes the standard IO header file.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para xml:lang="en">Specifies that <function>main()</function> returns + an int.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para xml:lang="en">The <function>printf()</function> call that writes + <literal>hello, world</literal> to standard + output.</para> + </callout> + </calloutlist> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-tables"> + <title xml:lang="en">Tables</title> + + <para xml:lang="en">Unlike <acronym>HTML</acronym>, DocBook does not need + tables for layout purposes, as the stylesheet handles those + issues. Instead, just use tables for marking up tabular + data.</para> + + <para xml:lang="en">In general terms (and see the DocBook documentation for + more detail) a table (which can be either formal or informal) + consists of a <tag>table</tag> element. This contains + at least one <tag>tgroup</tag> element, which + specifies (as an attribute) the number of columns in this + table group. Within the tablegroup there is one + <tag>thead</tag> element, which contains elements for + the table headings (column headings), and one + <tag>tbody</tag> which contains the body of the + table.</para> + + <para xml:lang="en">Both <tag>tgroup</tag> and + <tag>thead</tag> contain <tag>row</tag> + elements, which in turn contain <tag>entry</tag> + elements. Each <tag>entry</tag> element specifies + one cell in the table.</para> + + <example> + <title xml:lang="en"><tag>informaltable</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">informaltable pgwide="1"</tag> + <tag class="starttag">tgroup cols="2"</tag> + <tag class="starttag">thead</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">thead</tag> + + <tag class="starttag">tbody</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">tbody</tag> + <tag class="endtag">tgroup</tag> +<tag class="endtag">informaltable</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry xml:lang="en">This is Column Head 1</entry> + <entry xml:lang="en">This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry xml:lang="en">Row 1, column 1</entry> + <entry xml:lang="en">Row 1, column 2</entry> + </row> + + <row> + <entry xml:lang="en">Row 2, column 1</entry> + <entry xml:lang="en">Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para xml:lang="en">Always use the <literal>pgwide</literal> attribute with + a value of <literal>1</literal> with the + <tag>informaltable</tag> element. A bug in Internet + Explorer can cause the table to render incorrectly if this + is omitted.</para> + + <para xml:lang="en">Table borders can be suppressed by setting the + <literal>frame</literal> attribute to <literal>none</literal> + in the <tag>informaltable</tag> element. For example, + <literal>informaltable frame="none"</literal>.</para> + + <example> + <title xml:lang="en">Table with <literal>frame="none"</literal> Example</title> + + <para xml:lang="en">Appearance:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry xml:lang="en">This is Column Head 1</entry> + <entry xml:lang="en">This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry xml:lang="en">Row 1, column 1</entry> + <entry xml:lang="en">Row 1, column 2</entry> + </row> + + <row> + <entry xml:lang="en">Row 2, column 1</entry> + <entry xml:lang="en">Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-examples"> + <title xml:lang="en">Examples for the User to Follow</title> + + <para xml:lang="en">Examples for the user to follow are often necessary. + Typically, these will consist of dialogs with the computer; + the user types in a command, the user gets a response back, + the user types another command, and so on.</para> + + <para xml:lang="en">A number of distinct elements and entities come into + play here.</para> + + <variablelist> + <varlistentry> + <term xml:lang="en"><tag>screen</tag></term> + + <listitem> + <para xml:lang="en">Everything the user sees in this example will be + on the computer screen, so the next element is + <tag>screen</tag>.</para> + + <para xml:lang="en">Within <tag>screen</tag>, white space is + significant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><tag>prompt</tag>, + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal></term> + + <listitem> + <para xml:lang="en">Some of the things the user will be seeing on the + screen are prompts from the computer (either from the + operating system, command shell, or application). These + should be marked up using + <tag>prompt</tag>.</para> + + <para xml:lang="en">As a special case, the two shell prompts for the + normal user and the root user have been provided as + entities. To indicate the user is at a shell prompt, + use one of <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> as necessary. They + do not need to be inside + <tag>prompt</tag>.</para> + + <note> + <para xml:lang="en"><literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> are FreeBSD + extensions to DocBook, and are not part of the + original <acronym>DTD</acronym>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><tag>userinput</tag></term> + + <listitem> + <para xml:lang="en">When displaying text that the user should type in, + wrap it in <tag>userinput</tag> tags. It will + be displayed differently than system output text.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title xml:lang="en"><tag>screen</tag>, <tag>prompt</tag>, + and <tag>userinput</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag> +foo1 +foo2 +foo3 +&prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag> +foo2 +&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag> +<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag> +&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag> +This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +<prompt>%</prompt> <userinput>ls -1 | grep foo2</userinput> +foo2 +<prompt>%</prompt> <userinput>su</userinput> +<prompt>Password: </prompt> +<prompt>#</prompt> <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen> + </example> + + <note> + <para xml:lang="en">Even though we are displaying the contents of the file + <filename>foo2</filename>, it is <emphasis>not</emphasis> + marked up as <tag>programlisting</tag>. Reserve + <tag>programlisting</tag> for showing fragments of + files outside the context of user actions.</para> + </note> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-inline-elements"> + <title xml:lang="en">In-line Elements</title> + + <sect2 xml:id="docbook-markup-inline-emphasizing"> + <title xml:lang="en">Emphasizing Information</title> + + <para xml:lang="en">To emphasize a particular word or phrase, use + <tag>emphasis</tag>. This may be presented as + italic, or bold, or might be spoken differently with a + text-to-speech system.</para> + + <para xml:lang="en">There is no way to change the presentation of the + emphasis within the document, no equivalent of + <acronym>HTML</acronym>'s <tag>b</tag> and + <tag>i</tag>. If the information being presented is + important, then consider presenting it in + <tag>important</tag> rather than + <tag>emphasis</tag>.</para> + + <example> + <title xml:lang="en"><tag>emphasis</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>&os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag> + premiere &unix;-like operating system for the Intel + architecture.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">FreeBSD is without doubt <emphasis>the</emphasis> + premiere <trademark class="registered">UNIX</trademark>-like operating system for the Intel + architecture.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-acronyms"> + <title xml:lang="en">Acronyms</title> + + <para xml:lang="en">Many computer terms are <emphasis>acronyms</emphasis>, + words formed from the first letter of each word in a + phrase. Acronyms are marked up into + <tag>acronym</tag> elements. It is helpful to the + reader when an acronym is defined on the first use, as shown + in the example below.</para> + + <example> + <title xml:lang="en"><tag>acronym</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149 + defined the use of avian carriers for transmission of + Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The + quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently + transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Request For Comments (<acronym>RFC</acronym>) 1149 + defined the use of avian carriers for transmission of + Internet Protocol (<acronym>IP</acronym>) data. The + quantity of <acronym>IP</acronym> data currently + transmitted in that manner is unknown.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-quotations"> + <title xml:lang="en">Quotations</title> + + <para xml:lang="en">To quote text from another document or source, or to + denote a phrase that is used figuratively, use + <tag>quote</tag>. Most of the markup tags available + for normal text are also available from within a + <tag>quote</tag>.</para> + + <example> + <title xml:lang="en"><tag>quote</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>However, make sure that the search does not go beyond the + <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>, + as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">However, make sure that the search does not go beyond + the <quote>boundary between local and public + administration</quote>, as <acronym>RFC</acronym> 1535 + calls it.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-keys"> + <title xml:lang="en">Keys, Mouse Buttons, and Combinations</title> + + <para xml:lang="en">To refer to a specific key on the keyboard, use + <tag>keycap</tag>. To refer to a mouse button, use + <tag>mousebutton</tag>. And to refer to + combinations of key presses or mouse clicks, wrap them all + in <tag>keycombo</tag>.</para> + + <para xml:lang="en"><tag>keycombo</tag> has an attribute called + <literal>action</literal>, which may be one of + <literal>click</literal>, <literal>double-click</literal>, + <literal>other</literal>, <literal>press</literal>, + <literal>seq</literal>, or <literal>simul</literal>. The + last two values denote whether the keys or buttons should be + pressed in sequence, or simultaneously.</para> + + <para xml:lang="en">The stylesheets automatically add any connecting + symbols, such as <literal>+</literal>, between the key + names, when wrapped in <tag>keycombo</tag>.</para> + + <example> + <title xml:lang="en">Keys, Mouse Buttons, and Combinations Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>To switch to the second virtual terminal, press + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type + <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>My window manager is configured so that + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag> + <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">To switch to the second virtual terminal, press + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>.</para> + + <para xml:lang="en">To exit <command>vi</command> without saving changes, + type <keycombo action="seq"> + <keycap>Esc</keycap> + <keycap>:</keycap> + <keycap>q</keycap> + <keycap>!</keycap></keycombo>.</para> + + <para xml:lang="en">My window manager is configured so that + <keycombo action="simul"> + <keycap>Alt</keycap> + <mousebutton>right</mousebutton></keycombo> mouse button + is used to move windows.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-applications"> + <title xml:lang="en">Applications, Commands, Options, and Cites</title> + + <para xml:lang="en">Both applications and commands are frequently referred to + when writing documentation. The distinction between them is + that an application is the name of a program or suite of + programs that fulfill a particular task. A command is the + filename of a program that the user can type and run at a + command line.</para> + + <para xml:lang="en">It is often necessary to show some of the options that a + command might take.</para> + + <para xml:lang="en">Finally, it is often useful to list a command with its + manual section number, in the <quote>command(number)</quote> + format so common in Unix manuals.</para> + + <para xml:lang="en">Mark up application names with + <tag>application</tag>.</para> + + <para xml:lang="en">To list a command with its manual section + number (which should be most of the time) the DocBook + element is <tag>citerefentry</tag>. This will + contain a further two elements, + <tag>refentrytitle</tag> and + <tag>manvolnum</tag>. The content of + <tag>refentrytitle</tag> is the name of the command, + and the content of <tag>manvolnum</tag> is the + manual page section.</para> + + <para xml:lang="en">This can be cumbersome to write, and so a series of + <link linkend="xml-primer-general-entities">general + entities</link> have been created to make this easier. + Each entity takes the form + <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para xml:lang="en">The file that contains these entities is in + <filename>doc/share/xml/man-refs.ent</filename>, and can be + referred to using this <acronym>FPI</acronym>:</para> + + <programlisting xml:lang="en">PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para xml:lang="en">Therefore, the introduction to FreeBSD documentation will + usually include this:</para> + + <programlisting xml:lang="en"><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]></programlisting> + + <para xml:lang="en">Use <tag>command</tag> to include a command + name <quote>in-line</quote> but present it as something the + user should type.</para> + + <para xml:lang="en">Use <tag>option</tag> to mark up the options + which will be passed to a command.</para> + + <para xml:lang="en">When referring to the same command multiple times in + close proximity, it is preferred to use the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + notation to markup the first reference and use + <tag>command</tag> to markup subsequent references. + This makes the generated output, especially + <acronym>HTML</acronym>, appear visually better.</para> + + <example> + <title xml:lang="en">Applications, Commands, and Options Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most + widely used Unix mail application.<tag class="starttag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the + <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1; + programs.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current + status of messages in the mail queue. Check this on the command + line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en"><application>Sendmail</application> is the most widely + used Unix mail application.</para> + + <para xml:lang="en"><application>Sendmail</application> includes the + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <citerefentry><refentrytitle>mailq</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and <citerefentry><refentrytitle>newaliases</refentrytitle><manvolnum>1</manvolnum></citerefentry> + programs.</para> + + <para xml:lang="en">One of the command line parameters to + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <option>-bp</option>, will display the + current status of messages in the mail queue. Check this + on the command line by running + <command>sendmail -bp</command>.</para> + </example> + + <note> + <para xml:lang="en">Notice how the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + notation is easier to follow.</para> + </note> + </sect2> + + <sect2 xml:id="docbook-markup-files"> + <title xml:lang="en">Files, Directories, Extensions, Device Names</title> + + <para xml:lang="en">To refer to the name of a file, a directory, a file + extension, or a device name, use <tag>filename</tag>.</para> + + <example> + <title xml:lang="en"><tag>filename</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>The source for the Handbook in English is found in + <tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>. + The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>. + There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a + number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected + by the system, and appears in + <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">The source for the Handbook in English is found in + <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. + The main file is called <filename>book.xml</filename>. + There is also a <filename>Makefile</filename> and a number + of files with a <filename>.ent</filename> extension.</para> + + <para xml:lang="en"><filename>kbd0</filename> is the first keyboard detected + by the system, and appears in + <filename>/dev</filename>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-name-of-ports"> + <title xml:lang="en">The Name of Ports</title> + + <note> + <title xml:lang="en">FreeBSD Extension</title> + + <para xml:lang="en">These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para xml:lang="en">To include the name of a program from the FreeBSD + Ports Collection in the document, use the <tag>package</tag> + tag. Since the Ports Collection can be installed in any + number of locations, only include the category and the port + name; do not include <filename>/usr/ports</filename>.</para> + + <para xml:lang="en">By default, <tag>package</tag> refers to a binary package. + To refer to a port that will be built from source, set the + <literal>role</literal> attribute to + <literal>port</literal>.</para> + + <example> + <title xml:lang="en"><tag>package</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary + package to view network traffic.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be + built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Install the <package>net/wireshark</package> binary + package to view network traffic.</para> + + <para xml:lang="en"><package role="port">net/wireshark</package> can also be + built and installed from the Ports Collection.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-hosts"> + <title xml:lang="en">Hosts, Domains, IP Addresses, User Names, Group Names, + and Other System Items</title> + + <note> + <title xml:lang="en">FreeBSD Extension</title> + + <para xml:lang="en">These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para xml:lang="en">Information for <quote>system items</quote> is marked up + with <tag>systemitem</tag>. The <literal>class</literal> + attribute is used to identify the particular type of + information shown.</para> + + <variablelist> + <varlistentry> + <term xml:lang="en"><literal>class="domainname"</literal></term> + + <listitem> + <para xml:lang="en">The text is a domain name, such as + <literal>FreeBSD.org</literal> or + <literal>ngo.org.uk</literal>. There is no hostname + component.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>class="etheraddress"</literal></term> + + <listitem> + <para xml:lang="en">The text is an Ethernet <acronym>MAC</acronym> + address, expressed as a series of 2 digit hexadecimal + numbers separated by colons.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>class="fqdomainname"</literal></term> + + <listitem> + <para xml:lang="en">The text is a Fully Qualified Domain Name, with + both hostname and domain name parts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>class="ipaddress"</literal></term> + + <listitem> + <para xml:lang="en">The text is an <acronym>IP</acronym> address, + probably expressed as a dotted quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>class="netmask"</literal></term> + + <listitem> + <para xml:lang="en">The text is a network mask, which might be + expressed as a dotted quad, a hexadecimal string, or as + a <literal>/</literal> followed by a number + (<acronym>CIDR</acronym> notation).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>class="systemname"</literal></term> + + <listitem> + <para xml:lang="en">With <literal>class="systemname"</literal> + the marked up information is the simple hostname, such + as <literal>freefall</literal> or + <literal>wcarchive</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>class="username"</literal></term> + + <listitem> + <para xml:lang="en">The text is a username, like + <literal>root</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><literal>class="groupname"</literal></term> + + <listitem> + <para xml:lang="en">The text is a groupname, like + <literal>wheel</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title xml:lang="en"><tag>systemitem</tag> and Classes Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>The local machine can always be referred to by the + name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP + address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag> + domain contains a number of different hosts, including + <tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and + <tag class="starttag">systemitem class="fqdomainname"</tag>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an + interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>) + <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of + <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can + also be expressed as + <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies + every network card in existence. A typical + <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like + <tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>To carry out most system administration functions + requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">The local machine can always be referred to by the name + <systemitem>localhost</systemitem>, which will have the IP + address + <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> + + <para xml:lang="en">The + <systemitem class="fqdomainname">FreeBSD.org</systemitem> + domain contains a number of different hosts, including + <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and + <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para> + + <para xml:lang="en">When adding an <acronym>IP</acronym> alias to an + interface (using <command>ifconfig</command>) + <emphasis>always</emphasis> use a netmask of + <systemitem class="netmask">255.255.255.255</systemitem> + (which can also be expressed as + <systemitem class="netmask">0xffffffff</systemitem>).</para> + + <para xml:lang="en">The <acronym>MAC</acronym> address uniquely identifies + every network card in existence. A typical + <acronym>MAC</acronym> address looks like <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> + + <para xml:lang="en">To carry out most system administration functions + requires logging in as + <systemitem class="username">root</systemitem>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-uri"> + <title xml:lang="en">Uniform Resource Identifiers + (<acronym>URI</acronym>s)</title> + + <para xml:lang="en">Occasionally it is useful to show a + Uniform Resource Identifier (<acronym>URI</acronym>) without + making it an active hyperlink. The <tag>uri</tag> element + makes this possible:</para> + + <example> + <title xml:lang="en"><tag>uri</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text: + <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not + create a link.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">This <acronym>URL</acronym> shows only as text: + <uri>https://www.FreeBSD.org</uri>. It does not + create a link.</para> + </example> + + <para xml:lang="en">To create links, see + <xref linkend="docbook-markup-links"/>.</para> + </sect2> + + <sect2 xml:id="docbook-markup-email-addresses"> + <title xml:lang="en">Email Addresses</title> + + <para xml:lang="en">Email addresses are marked up as <tag>email</tag> + elements. In the <acronym>HTML</acronym> output format, the + wrapped text becomes a hyperlink to the email address. Other + output formats that support hyperlinks may also make the email + address into a link.</para> + + <example> + <title xml:lang="en"><tag>email</tag> with a Hyperlink Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>An email address that does not actually exist, like + <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an + example.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">An email address that does not actually exist, like + <email>notreal@example.com</email>, can be used as an + example.</para> + </example> + + <para xml:lang="en">A FreeBSD-specific extension allows setting the + <literal>role</literal> attribute to <literal>nolink</literal> + to prevent the creation of the hyperlink to the email + address.</para> + + <example> + <title xml:lang="en"><tag>email</tag> Without a Hyperlink Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Sometimes a link to an email address like + <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not + desired.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Sometimes a link to an email address like + <email role="nolink">notreal@example.com</email> is not + desired.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-describing-makefiles"> + <title xml:lang="en">Describing <filename>Makefile</filename>s</title> + + <note> + <title xml:lang="en">FreeBSD Extension</title> + + <para xml:lang="en">These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para xml:lang="en">Two elements exist to describe parts of + <filename>Makefile</filename>s, <tag>buildtarget</tag> + and <tag>varname</tag>.</para> + + <para xml:lang="en"><tag>buildtarget</tag> identifies a build target + exported by a <filename>Makefile</filename> that can be + given as a parameter to <command>make</command>. + <tag>varname</tag> identifies a variable that can be + set (in the environment, on the command line with + <command>make</command>, or within the + <filename>Makefile</filename>) to influence the + process.</para> + + <example> + <title xml:lang="en"><tag>buildtarget</tag> and + <tag>varname</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> + are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and + <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will + rebuild the application, and invoking + <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary + files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the + build process.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a + number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag> + and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Two common targets in a <filename>Makefile</filename> + are <buildtarget xml:lang="en">all</buildtarget> and + <buildtarget xml:lang="en">clean</buildtarget>.</para> + + <para xml:lang="en">Typically, invoking <buildtarget xml:lang="en">all</buildtarget> will + rebuild the application, and invoking + <buildtarget xml:lang="en">clean</buildtarget> will remove the temporary + files (<filename>.o</filename> for example) created by the + build process.</para> + + <para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> may be controlled by a + number of variables, including <varname>CLOBBER</varname> + and <varname>RECURSE</varname>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-literal-text"> + <title xml:lang="en">Literal Text</title> + + <para xml:lang="en">Literal text, or text which should be entered verbatim, is + often needed in documentation. This is text that is excerpted + from another file, or which should be copied exactly as shown + from the documentation into another file.</para> + + <para xml:lang="en">Some of the time, <tag>programlisting</tag> will + be sufficient to denote this text. But + <tag>programlisting</tag> is not always appropriate, + particularly when you want to include a portion of a file + <quote>in-line</quote> with the rest of the + paragraph.</para> + + <para xml:lang="en">On these occasions, use + <tag>literal</tag>.</para> + + <example> + <title xml:lang="en"><tag>literal</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel + configuration file determines the size of many system tables, and is + a rough guide to how many simultaneous logins the system will + support.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">The <literal>maxusers 10</literal> line in the kernel + configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous + logins the system will support.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-replaceable"> + <title xml:lang="en">Showing Items That the User <emphasis>Must</emphasis> + Fill In</title> + + <para xml:lang="en">There will often be times when the user is shown + what to do, or referred to a file or command line, but + cannot simply copy the example provided. Instead, they + must supply some information themselves.</para> + + <para xml:lang="en"><tag>replaceable</tag> is designed for this + eventuality. Use it <emphasis>inside</emphasis> other + elements to indicate parts of that element's content that + the user must replace.</para> + + <example> + <title xml:lang="en"><tag>replaceable</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <informalexample> + <screen xml:lang="en"><prompt>%</prompt> <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para xml:lang="en"><tag>replaceable</tag> can be used in many + different elements, including <tag>literal</tag>. + This example also shows that <tag>replaceable</tag> + should only be wrapped around the content that the user + <emphasis>is</emphasis> meant to provide. The other content + should be left alone.</para> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag> + line in the kernel configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous logins the system will + support.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value + for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">The + <literal>maxusers <replaceable>n</replaceable></literal> + line in the kernel configuration file determines the size + of many system tables, and is a rough guide to how many + simultaneous logins the system will support.</para> + + <para xml:lang="en">For a desktop workstation, <literal>32</literal> is a + good value for <replaceable>n</replaceable>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-gui-buttons"> + <title xml:lang="en">Showing <acronym>GUI</acronym> Buttons</title> + + <para xml:lang="en">Buttons presented by a graphical user interface are marked + with <tag>guibutton</tag>. To make the text look more + like a graphical button, brackets and non-breaking spaces are + added surrounding the text.</para> + + <example> + <title xml:lang="en"><tag>guibutton</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Edit the file, then click + <tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the + changes.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Edit the file, then click + <guibutton>[ Save ]</guibutton> to save the + changes.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-system-errors"> + <title xml:lang="en">Quoting System Errors</title> + + <para xml:lang="en">System errors generated by FreeBSD are marked with + <tag>errorname</tag>. This indicates the exact error + that appears.</para> + + <example> + <title xml:lang="en"><tag>errorname</tag> Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <informalexample> + <screen xml:lang="en"><errorname>Panic: cannot mount root</errorname></screen> + </informalexample> + </example> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-images"> + <title xml:lang="en">Images</title> + + <important> + <para xml:lang="en">Image support in the documentation is somewhat + experimental. The mechanisms described here are unlikely to + change, but that is not guaranteed.</para> + + <para xml:lang="en">To provide conversion between different image formats, the + <package>graphics/ImageMagick</package> + port must be installed. This port is not included in the + <package>textproc/docproj</package> meta + port, and must be installed separately.</para> + + <para xml:lang="en">A good example of the use of images is the + <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> + document. Examine the files in that directory to see how + these elements are used together. Build different output + formats to see how the format determines what images are shown + in the rendered document.</para> + </important> + + <sect2 xml:id="docbook-markup-image-formats"> + <title xml:lang="en">Image Formats</title> + + <para xml:lang="en">The following image formats are currently supported. An + image file will automatically be converted to bitmap or vector + image depending on the output document format.</para> + + <para xml:lang="en">These are the <emphasis>only</emphasis> formats in which + images should be committed to the documentation + repository.</para> + + <variablelist> + <varlistentry> + <term xml:lang="en"><acronym>EPS</acronym> (Encapsulated + Postscript)</term> + + <listitem> + <para xml:lang="en">Images that are primarily vector based, such as + network diagrams, time lines, and similar, should be in + this format. These images have a + <filename>.eps</filename> extension.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><acronym>PNG</acronym> (Portable Network + Graphic)</term> + + <listitem> + <para xml:lang="en">For bitmaps, such as screen captures, use this + format. These images have the <filename>.png</filename> + extension.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><acronym>PIC</acronym> (PIC graphics language)</term> + + <listitem> + <para xml:lang="en"><acronym>PIC</acronym> is a language for drawing + simple vector-based figures used in the <citerefentry><refentrytitle>pic</refentrytitle><manvolnum>1</manvolnum></citerefentry> + utility. These images have the + <filename>.pic</filename> extension.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><acronym>SCR</acronym> (SCReen capture)</term> + + <listitem> + <para xml:lang="en">This format is specific to screenshots of console + output. The following command generates an SCR file + <filename>shot.scr</filename> from video buffer of + <filename>/dev/ttyv0</filename>:</para> + + <screen xml:lang="en"><prompt>#</prompt> <userinput><command>vidcontrol -p</command> < <filename><replaceable>/dev/ttyv0</replaceable></filename> > <filename><replaceable>shot.scr</replaceable></filename></userinput></screen> + + <para xml:lang="en">This is preferable to <acronym>PNG</acronym> format + for screenshots because the <acronym>SCR</acronym> file + contains plain text of the command lines so that it can + be converted to a <acronym>PNG</acronym> image or a + plain text depending on the output document + format.</para> + </listitem> + </varlistentry> + </variablelist> + + <para xml:lang="en">Use the appropriate format for each image. Documentation + will often have a mix of <acronym>EPS</acronym> and + <acronym>PNG</acronym> images. The + <filename>Makefile</filename>s ensure that the correct format + image is chosen depending on the output format used. + <emphasis>Do not commit the same image to the repository in + two different formats</emphasis>.</para> + + <important> + <para xml:lang="en">The Documentation Project may eventually switch to using + the <acronym>SVG</acronym> (Scalable Vector Graphic) format + for vector images. However, the current state of + <acronym>SVG</acronym> capable editing tools makes this + impractical.</para> + </important> + </sect2> + + <sect2 xml:id="docbook-markup-image-file-locations"> + <title xml:lang="en">Image File Locations</title> + + <para xml:lang="en">Image files can be stored in one of several locations, + depending on the document and image:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">In the same directory as the document itself, usually + done for articles and small books that keep all their + files in a single directory.</para> + </listitem> + + <listitem> + <para xml:lang="en">In a subdirectory of the main document. Typically + done when a large book uses separate subdirectories to + organize individual chapters.</para> + + <para xml:lang="en">When images are stored in a subdirectory of the + main document directory, the subdirectory name must be + included in their paths in the + <filename>Makefile</filename> and the + <tag>imagedata</tag> element.</para> + </listitem> + + <listitem> + <para xml:lang="en">In a subdirectory of + <filename>doc/share/images</filename> named after the + document. For example, images for the Handbook are stored + in <filename>doc/share/images/books/handbook</filename>. + Images that work for multiple translations are stored in + this upper level of the documentation file tree. + Generally, these are images that can be used unchanged in + non-English translations of the document.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 xml:id="docbook-markup-image-markup"> + <title xml:lang="en">Image Markup</title> + + <para xml:lang="en">Images are included as part of a <tag>mediaobject</tag>. + The <tag>mediaobject</tag> can contain other, more specific + objects. We are concerned with two, the + <tag>imageobject</tag> and the <tag>textobject</tag>.</para> + + <para xml:lang="en">Include one <tag>imageobject</tag>, and two + <tag>textobject</tag> elements. The <tag>imageobject</tag> + will point to the name of the image file without the + extension. The <tag>textobject</tag> elements contain + information that will be presented to the user as well as, or + instead of, the image itself.</para> + + <para xml:lang="en">Text elements are shown to the reader in several + situations. When the document is viewed in + <acronym>HTML</acronym>, text elements are shown while the + image is loading, or if the mouse pointer is hovered over the + image, or if a text-only browser is being used. In formats + like plain text where graphics are not possible, the text + elements are shown instead of the graphical ones.</para> + + <para xml:lang="en">This example shows how to include an image called + <filename>fig1.png</filename> in a document. The image is a + rectangle with an A inside it:</para> + + <programlisting xml:lang="en"><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="emptytag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/> + <tag class="endtag">imageobject</tag> + + <tag class="starttag">textobject</tag> + <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/> +| A | ++---------------+<tag class="endtag">literallayout</tag> + <tag class="endtag">textobject</tag> + + <tag class="starttag">textobject</tag> + <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/> + <tag class="endtag">textobject</tag> +<tag class="endtag">mediaobject</tag></programlisting> + + <calloutlist> + <callout arearefs="co-image-ext"> + <para xml:lang="en">Include an <tag>imagedata</tag> element + inside the <tag>imageobject</tag> element. The + <literal>fileref</literal> attribute should contain the + filename of the image to include, without the extension. + The stylesheets will work out which extension should be + added to the filename automatically.</para> + </callout> + + <callout arearefs="co-image-literal"> + + <para xml:lang="en">The first <tag>textobject</tag> contains a + <tag>literallayout</tag> element, where the + <literal>class</literal> attribute is set to + <literal>monospaced</literal>. This is an opportunity to + demonstrate <acronym>ASCII</acronym> art skills. This + content will be used if the document is converted to plain + text.</para> + + <para xml:lang="en">Notice how the first and last lines of the content + of the <tag>literallayout</tag> element butt up + next to the element's tags. This ensures no extraneous + white space is included.</para> + </callout> + + <callout arearefs="co-image-phrase"> + <para xml:lang="en">The second <tag>textobject</tag> contains a + single <tag>phrase</tag> element. The contents of + this phrase will become the <literal>alt</literal> + attribute for the image when this document is converted to + <acronym>HTML</acronym>.</para> + </callout> + </calloutlist> + </sect2> + + <sect2 xml:id="docbook-markup-image-makefile-entries"> + <title xml:lang="en">Image <filename>Makefile</filename> Entries</title> + + <para xml:lang="en">Images must be listed in the <filename>Makefile</filename> + in the <varname>IMAGES</varname> variable. This variable must + contain the names of all the <emphasis>source</emphasis> + images. For example, if there are three figures, + <filename>fig1.eps</filename>, <filename>fig2.png</filename>, + <filename>fig3.png</filename>, then the + <filename>Makefile</filename> should have lines like this in + it.</para> + + <programlisting xml:lang="en">… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para xml:lang="en">or</para> + + <programlisting xml:lang="en">… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</programlisting> + + <para xml:lang="en">Again, the <filename>Makefile</filename> will work out the + complete list of images it needs to build the source document, + you only need to list the image files <emphasis>you</emphasis> + provided.</para> + </sect2> + + <sect2 xml:id="docbook-markup-images-in-subdirectories"> + <title xml:lang="en">Images and Chapters in Subdirectories</title> + + <para xml:lang="en">Be careful when separating documentation into smaller + files in different directories (see <xref linkend="xml-primer-include-using-gen-entities"/>).</para> + + <para xml:lang="en">Suppose there is a book with three chapters, and the + chapters are stored in their own directories, called + <filename>chapter1/chapter.xml</filename>, + <filename>chapter2/chapter.xml</filename>, and + <filename>chapter3/chapter.xml</filename>. If each chapter + has images associated with it, place those images in each + chapter's subdirectory (<filename>chapter1/</filename>, + <filename>chapter2/</filename>, and + <filename>chapter3/</filename>).</para> + + <para xml:lang="en">However, doing this requires including the directory + names in the <varname>IMAGES</varname> variable in the + <filename>Makefile</filename>, <emphasis>and</emphasis> + including the directory name in the <tag>imagedata</tag> + element in the document.</para> + + <para xml:lang="en">For example, if the book has + <filename>chapter1/fig1.png</filename>, then + <filename>chapter1/chapter.xml</filename> should + contain:</para> + + <programlisting xml:lang="en"><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/> + <tag class="endtag">imageobject</tag> + + … + +<tag class="endtag">mediaobject</tag></programlisting> + + <calloutlist> + <callout arearefs="co-image-dir"> + <para xml:lang="en">The directory name must be included in the + <literal>fileref</literal> attribute.</para> + </callout> + </calloutlist> + + <para xml:lang="en">The <filename>Makefile</filename> must contain:</para> + + <programlisting xml:lang="en">… +IMAGES= chapter1/fig1.png +…</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-links"> + <title xml:lang="en">Links</title> + + <note> + <para xml:lang="en">Links are also in-line elements. To show a + <acronym>URI</acronym> without creating a link, see + <xref linkend="docbook-markup-uri"/>.</para> + </note> + + <sect2 xml:id="docbook-markup-links-ids"> + <title xml:lang="en"><literal>xml:id</literal> Attributes</title> + + <para xml:lang="en">Most DocBook elements accept an <literal>xml:id</literal> + attribute to give that part of the document a unique name. + The <literal>xml:id</literal> can be used as a target for a + crossreference or link.</para> + + <para xml:lang="en">Any portion of the document that will be a link target + must have an <literal>xml:id</literal> attribute. Assigning + an <literal>xml:id</literal> to all chapters and sections, + even if there are no current plans to link to them, is a good + idea. These <literal>xml:id</literal>s can be used as unique + reference points by anyone referring to the + <acronym>HTML</acronym> version of the document.</para> + + <example> + <title xml:lang="en"><literal>xml:id</literal> on Chapters and + Sections Example</title> + + <programlisting xml:lang="en"><tag class="starttag">chapter xml:id="introduction"</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is the introduction. It contains a subsection, + which is identified as well.<tag class="endtag">para</tag> + + <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag> + <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + + <para xml:lang="en">Use descriptive values for <literal>xml:id</literal> + names. The values must be unique within the entire document, + not just in a single file. In the example, the subsection + <literal>xml:id</literal> is constructed by appending text to + the chapter <literal>xml:id</literal>. This ensures that the + <literal>xml:id</literal>s are unique. It also helps both + reader and anyone editing the document to see where the link + is located within the document, similar to a directory path to + a file.</para> + </sect2> + + <sect2 xml:id="docbook-markup-links-crossreferences"> + <title xml:lang="en">Crossreferences with <literal>xref</literal></title> + + <para xml:lang="en"><tag>xref</tag> provides the reader with a link to jump to + another section of the document. The target + <literal>xml:id</literal> is specified in the + <literal>linkend</literal> attribute, and <tag>xref</tag> + generates the link text automatically.</para> + + <example> + <title xml:lang="en"><tag>xref</tag> Example</title> + + <para xml:lang="en">Assume that this fragment appears somewhere in a + document that includes the <literal>xml:id</literal> + example shown above:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>More information can be found + in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>More specific information can be found + in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">The link text will be generated automatically, looking + like (<emphasis>emphasized</emphasis> text indicates the + link text):</para> + + <blockquote> + <para xml:lang="en">More information can be found in <emphasis>Chapter + 1, Introduction</emphasis>.</para> + + <para xml:lang="en">More specific information can be found in + <emphasis>Section 1.1, + <quote>More Details</quote></emphasis>.</para> + </blockquote> + </example> + + <para xml:lang="en">The link text is generated automatically from the chapter + and section number and <literal>title</literal> + elements.</para> + </sect2> + + <sect2 xml:id="docbook-markup-links-to-web-documents"> + <title xml:lang="en">Linking to Other Documents on the + Web</title> + + <para xml:lang="en">The link element described here allows the writer to + define the link text. When link text is used, it is very important to be descriptive + to give the reader an idea of where the link goes. + Remember that DocBook can be rendered to multiple + types of media. The reader might be looking at a printed book + or other form of media where there are no links. If the link + text is not descriptive enough, the reader might not be able to + locate the linked section.</para> + + <para xml:lang="en">The <literal>xlink:href</literal> attribute + is the <acronym>URL</acronym> of the page, + and the content of the element is the text that + will be displayed for the user to activate.</para> + + <para xml:lang="en">In many situations, it is preferable to show the actual + <acronym>URL</acronym> rather than text. This can be done by + leaving out the element text entirely.</para> + + <example> + <title xml:lang="en"><tag>link</tag> to a FreeBSD Documentation Web + Page Example</title> + + <para xml:lang="en">Link to the book or article <acronym>URL</acronym> + entity. To link to a specific chapter in a book, add a + slash and the chapter file name, followed by an optional + anchor within the chapter. For articles, link to the + article <acronym>URL</acronym> entity, followed by an + optional anchor within the article. + <acronym>URL</acronym> entities can be found in + <filename>doc/share/xml/urls.ent</filename>.</para> + + <para xml:lang="en">Usage for FreeBSD book links:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Read the <tag class="starttag">link + xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN + introduction<tag class="endtag">link</tag>, then pick the nearest mirror from + the list of <tag class="starttag">link + xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion + mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Read the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-intro">SVN + introduction</link>, then pick the nearest mirror from + the list of <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion + mirror sites</link>.</para> + + <para xml:lang="en">Usage for FreeBSD article links:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Read this + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article + about the BSD license<tag class="endtag">link</tag>, or just the + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Read this + <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl">article + about the BSD license</link>, or just the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl#intro">introduction</link>.</para> + </example> + + <example> + <title xml:lang="en"><tag>link</tag> to a FreeBSD Web Page Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the + <tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Of course, you could stop reading this document and go + to the <link xlink:href="@@URL_RELPREFIX@@/index.html">FreeBSD + home page</link> instead.</para> + </example> + + <example> + <title xml:lang="en"><tag>link</tag> to an External Web + Page Example</title> + + <para xml:lang="en">Usage:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on + <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID + Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Appearance:</para> + + <para xml:lang="en">Wikipedia has an excellent reference on <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Tables</link>.</para> + + <para xml:lang="en">The link text can be omitted to show the actual + URL:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">The same link can be entered using shorter + notation instead of a separate ending tag:</para> + + <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="emptytag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">The two methods are equivalent. Appearance:</para> + + <para xml:lang="en">Wikipedia has an excellent reference on GUID Partition + Tables: <uri xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para> + </example> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="stylesheets"> + <title xml:lang="en">Style Sheets</title> + + <para xml:lang="en"><acronym>XML</acronym> is concerned with content, and says + nothing about how that content should be presented to the reader + or rendered on paper. Multiple <emphasis>style sheet</emphasis> + languages have been developed to describe visual layout, including + Extensible Stylesheet Language Transformation + (<acronym>XSLT</acronym>), Document Style Semantics and + Specification Language (<acronym>DSSSL</acronym>), and Cascading + Style Sheets (<acronym>CSS</acronym>).</para> + + <para xml:lang="en">The <acronym>FDP</acronym> documents use + <acronym>XSLT</acronym> stylesheets to transform DocBook into + <acronym>XHTML</acronym>, and then <acronym>CSS</acronym> + formatting is applied to the <acronym>XHTML</acronym> pages. + Printable output is currently rendered with legacy + <acronym>DSSSL</acronym> stylesheets, but this will probably + change in the future.</para> + + <sect1 xml:id="stylesheets-css"> + <title xml:lang="en"><acronym>CSS</acronym></title> + + <para xml:lang="en">Cascading Style Sheets (<acronym>CSS</acronym>) are a + mechanism for attaching style information (font, weight, size, + color, and so forth) to elements in an <acronym>XHTML</acronym> + document without abusing <acronym>XHTML</acronym> to do + so.</para> + + <sect2> + <title xml:lang="en">The DocBook Documents</title> + + <para xml:lang="en">The FreeBSD <acronym>XSLT</acronym> and + <acronym>DSSSL</acronym> stylesheets refer to + <filename>docbook.css</filename>, which is expected to be + present in the same directory as the <acronym>XHTML</acronym> + files. The project-wide <acronym>CSS</acronym> file is copied + from <filename>doc/share/misc/docbook.css</filename> when + documents are converted to <acronym>XHTML</acronym>, and is + installed automatically.</para> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="translations"> + <title>翻譯</title> + + <para>本章是翻譯 FreeBSD 文件(包含：FAQ, Handbook, tutorials, manual pages等)的常見問題(FAQ)。</para> + + <para>本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文翻譯計劃的翻譯 FAQ 為母本而來的， 原始撰稿者為 Frank Gründer <email>elwood@mc5sys.in-berlin.de</email>，並由 Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。</para> + + <para>本 FAQ 是由文件工程團隊 <email>doceng@FreeBSD.org</email> 所維護。</para> + + <qandaset> + <qandaentry> + <question> + <para><phrase>i18n</phrase> 跟 <phrase>l10n</phrase> 是什麼呢？</para> + </question> + + <answer> + <para><phrase>i18n</phrase> 是 <phrase>internationalization</phrase> 而 <phrase>l10n</phrase> 是 <phrase>localization</phrase>。這些都是為了書寫方便而用的簡寫。</para> + + <para><phrase>i18n</phrase> 就是開頭為 <quote>i</quote> 後面有 18 個字母，最後接 <quote>n</quote>。同樣地， <phrase>l10n</phrase> 是開頭為 <quote>l</quote> 後面有 10 個字母，最後接 <quote>n</quote>。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>有專門給譯者參與討論的 mailing list 嗎？</para> + </question> + + <answer> + <para>有的，不同的語系翻譯者都各自有自屬的 mailing lists。這份 <link xlink:href="http://www.freebsd.org/docproj/translations.html"> 翻譯計劃清單</link> 有列出各翻譯計劃的詳細 mailing lists 及相關網站。此外，有一般翻譯討論的<email>freebsd-translators@freebsd.org</email>郵件論壇。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>需要更多人一起參與翻譯嗎？</para> + </question> + + <answer> + <para>當然囉，越多人參與翻譯，那麼就能夠越快翻完，而且英文版文件若有增減、更新的話， 各翻譯版也可以儘快同步囉。</para> + + <para>不一定得是專業譯者，才能參與翻譯的。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>有要求哪些語言能力呢</para> + </question> + + <answer> + <para>理論上，必須要對英文非常熟稔，而且很明顯地，對想翻譯的語言必須要能運用自如。</para> + + <para>英文也並非一定要會的。比如說，可以把西班牙文(Spanish)的 FAQ 翻譯為匈牙利文(Hungarian)。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>該學會哪些程式的使用呢？</para> + </question> + + <answer> + <para>強烈建議在自己機器上也建立 FreeBSD Subversion repository 的備份(至少文件部分)，這可以執行：</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen> + + <para><link xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link>是公共的 <literal>SVN</literal> 伺服器。可以從<link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion 鏡相站</link>清單檢查認證的伺服器。</para> + + <note> + <para>這需要安裝<package>devel/subversion</package> 套件。</para> + </note> + + <para>你可以很自在地使用<application>svn</application>。他可以讓你察看文件檔案不同版本之間的修改差異。</para> + + <para>例如你要看<filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename> 版本<literal>r33733</literal> 和 <literal>r33734</literal> 的差異，請執行：</para> + + <screen><prompt>%</prompt> <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>要怎麼找出來還有誰要跟我一起翻譯的呢？</para> + </question> + + <answer> + <para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">文件計劃的翻譯 </link> 列了目前已知的各翻譯者成果 ，如果已經有其他人也在做跟你一樣的翻譯工作，那麼請不要重複浪費人力， 請與他們聯繫看看還有哪些地方可以幫上忙的。</para> + + <para>若上面並未列出你母語的翻譯，或是也有人要翻譯但還未公開宣布的話，那麼就寄信到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project 郵遞論壇 </link>。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>都沒人翻譯為我所使用的語言，該怎麼辦？</para> + </question> + + <answer> + <para>恭喜啊，你剛好踏上 <quote>FreeBSD <replaceable>你的母語</replaceable> 文件翻譯計劃</quote>的啟程之路，歡迎上船。</para> + + <para>首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已， 因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para> + + <para>寫信到 FreeBSD documentation project 郵遞論壇 向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料</para> + + <para>若你的國家已經有人提供 FreeBSD 的 mirror(映設) 服務的話，那麼就先跟他們聯繫， 並詢問你是否在上面可以有網頁空間來放相關計劃資料， 以及是否可以有提供 email 帳號或 mailing list 服務。</para> + + <para>然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦，或是如何上手之類的說明文章。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>已經翻好一些文件了，該寄到哪呢？</para> + </question> + + <answer> + <para>這要看情況而定。 若你是在翻譯團隊內做的話(像是日本、德國)， 他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。</para> + + <para>若你是某語系的唯一翻譯者(或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃) ，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？</para> + + <para xml:lang="en">or</para> + + <para>我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？</para> + </question> + + <answer> + <para>首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說： 把它擺到現有文件架構內是可以正確編譯成功的。</para> + + <para>目前，FreeBSD 文件都是放在最上層的 <filename>head/</filename> 目錄內。 而該目錄下的則依其語系來做分類命名的，依照 ISO639 定義(在比比 1999/01/20 還新的 FreeBSD 版本的/usr/share/misc/iso639 )。</para> + + <para>若你這個語系可能會有不同編碼方式(像是：中文) 那麼就應該會像下面這樣，來依你所使用的編碼方式細分</para> + + <para>最後，你應該建立好各文件的目錄了。</para> + + <para>舉例來說，假設有瑞典文(Swedish)版的翻譯，那麼應該會長像：</para> + + <programlisting>head/ + sv_SE.ISO8859-1/ + Makefile + htdocs/ + docproj/ + books/ + faq/ + Makefile + book.xml</programlisting> + + <para><literal>sv_SE.ISO8859-1</literal>是依照 <filename><replaceable>語系(lang)</replaceable>.<replaceable>編碼(encoding)</replaceable></filename> 的規則來建立的譯名。 請注意：其中有兩個 Makefiles 檔，它們是用來建構文件的。</para> + + <para>然後請用 <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 與 <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來把你的翻譯文件壓縮起來，並寄到本計劃來。</para> + + <screen><prompt>%</prompt> <userinput>cd doc</userinput> +<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput> +<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput></screen> + + <para>接著，把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上，若你沒有自己網頁空間的話(ISP不提供) ，那麼可以該檔寄到 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 來。</para> + + <para>還有，記得用 Bugzilla 提交一個報告以通知大家；你已經寄出翻譯文件了， 還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好， 因為這也有助於提升翻譯品質的流暢度。</para> + + <para>最後，會有人(可能是文件計劃總管，或是 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 成員) 會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點：</para> + + <orderedlist> + <listitem> + <para>你的檔案是否都有用 RCS tag (像是 "ID" 之類的)？</para> + </listitem> + + <listitem> + <para><filename>sv_SE.ISO8859-1</filename> 是否可以順利<command>make all</command> 編譯呢？</para> + </listitem> + + <listitem> + <para><command>make install</command> 是否結果有正確</para> + </listitem> + </orderedlist> + + <para>若有問題的話，那麼檢閱者會叮嚀你，來讓這些翻譯成果可以正確使用。</para> + + <para>若沒問題的話，那麼就會很快把你的翻譯成果 commit 進去了。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>可以加入某語系或某國家才有的東西到翻譯內容內嗎？</para> + </question> + + <answer> + <para>我們希望不要這麼做。</para> + + <para>舉例來說，假設你正準備把 Handbook 翻譯為韓文版， 並希望把韓國零售商也加到你翻譯的 Handbook 韓文版內。</para> + + <para>我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 …) 因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。 此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。</para> + + <para>若你有某國才有的資料，請(用 Bugzilla )提供給英文版 Handbook 以作為修訂 ，然後再把英文版的修訂部分，翻為你要翻譯的 Handbook 吧。</para> + + <para>謝謝。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>要怎麼把該語系特有的字元寫進去翻譯內容呢？</para> + </question> + + <answer> + <para>文件內所有的非 ASCII(Non-ASCII) 字元，都要使用 SGML entities 才能寫進去。</para> + + <para>簡單來說，長相一開頭會是 and 符號(&)，然後是該 entity 名稱，最後接上分號(;)。</para> + + <para>這些 entity 名稱都是 ISO8879 所制訂的，而 port tree 內則 <package>textproc/iso8879</package>。</para> + + <para>以下舉一些例子：</para> + + <segmentedlist> + <segtitle>Entity名稱</segtitle> + + <segtitle>實際樣子</segtitle> + + <segtitle xml:lang="en">Description</segtitle> + + <seglistitem> + <seg>&eacute;</seg> + <seg>é</seg> + <seg>小 <quote>e</quote>，並帶尖、重音(acute accent)</seg> + </seglistitem> + + <seglistitem> + <seg>&Eacute;</seg> + <seg>É</seg> + <seg>大 <quote>E</quote>，並帶尖、重音(acute accent)</seg> + </seglistitem> + + <seglistitem> + <seg>&uuml;</seg> + <seg>ü</seg> + <seg>小 <quote>u</quote>，並帶日耳曼語系中的母音變化(umlaut)</seg> + </seglistitem> + </segmentedlist> + + <para>在裝了 iso8879 這個 port 之後，就可以在 <filename>/usr/local/share/xml/iso8879</filename> 找到這些的詳細列表。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>如何稱呼讀者呢？</para> + </question> + + <answer> + <para>在英文文件內，讀者都是以 <quote>you</quote> 來稱呼，而有些語言並沒有正式/非正式的區隔。</para> + + <para>若你所要翻的語言可以區別這些差異，那麼請用該語系在一般技術文件上所使用的稱呼吧。 如果容易造成困惑的話，那麼請改用較中性的稱呼來取代。</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>翻譯成果內要不要附上一些其他訊息呢？</para> + </question> + + <answer> + <para>要。</para> + + <para>每份英文版原稿的開頭，通常會有像下面的內容：</para> + + <programlisting><!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--></programlisting> + + <para>實際上的內容可能稍有不同，但每份原稿都會附上 $FreeBSD$ 這一行以及<literal>The FreeBSD Documentation Project</literal> 宣告。 請注意：$FreeBSD 開頭的這行是會由 Subversion 隨著每次異動而自動更改的， 所以，新檔案的話請保持原狀(也就是只要寫 $FreeBSD$ 就好了)。</para> + + <para>翻譯文件中，必須都要有 $FreeBSD$ 這行，並且把 <literal>FreeBSD Documentation Project</literal> 這行改為 <literal>The FreeBSD <replaceable>你的語系</replaceable> Documentation Project</literal>。</para> + + <para>此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。</para> + + <para>因此呢，西班牙文版(Spanish)的檔案開頭應該是長像這樣：</para> + + <programlisting><!-- + The FreeBSD Spanish Documentation Project + + $FreeBSD$ + Original revision: r38674 +--></programlisting> + </answer> + </qandaentry> + </qandaset> +</chapter> + + +<!-- + The FreeBSD Documentation Project + $FreeBSD$ +--> +<chapter version="5.0" xml:id="po-translations"> + + <title><acronym>PO</acronym> 翻譯</title> + + <sect1 xml:id="po-translations-introduction"> + <title xml:lang="en">Introduction</title> + + <para><link xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym> <application>gettext</application></link> 系統提供翻譯者一個簡單的方法來建立和維護文件的翻譯。翻譯的字串從原始文件題取出來到<acronym>PO</acronym> (Portable Object) 檔。字串的翻譯用另外的編輯器輸入。翻譯的字串可以直接使用，或是編譯成原始文件的完整翻譯版本。</para> + </sect1> + + <sect1 xml:id="po-translations-quick-start"> + <title>快速上手</title> + + <para xml:lang="en">The procedure shown in + <xref linkend="overview-quick-start"/> is assumed to have + already been performed, but the <literal>TRANSLATOR</literal> + option must be enabled in the + <package role="port">textproc/docproj</package> port. If that + option was not enabled, display the options menu and enable + it, then reinstall the port:</para> + + <screen><prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput> +<prompt>#</prompt> <userinput>make config</userinput> +<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput></screen> + + <para xml:lang="en">This example shows the creation of a Spanish translation of + the short <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds">Leap + Seconds</link> article.</para> + + <procedure xml:id="po-translations-quick-start-install-po-editor"> + <title xml:lang="en">Install a <acronym>PO</acronym> Editor</title> + + <step> + <para>編輯翻譯檔案需要<acronym>PO</acronym>編輯器。這個範例使用<package role="ports">editors/poedit</package>。</para> + + <screen><prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput> +<prompt>#</prompt> <userinput>make install clean</userinput></screen> + </step> + </procedure> + + <procedure xml:id="po-translations-quick-start-initial-setup"> + <title xml:lang="en">Initial Setup</title> + + <para xml:lang="en">When a new translation is first created, the directory + structure and <filename>Makefile</filename> must be created or + copied from the English original:</para> + + <step> + <para>建立新翻譯的目錄。英文文章原始碼位於 <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename> 。西班牙文翻譯將會放在 <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename> 。除了語系目錄的名稱外，其他路徑相同。</para> + + <screen><prompt>%</prompt> <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen> + </step> + + <step> + <para>從原始文件處將 <filename>Makefile</filename> 複製到翻譯目錄。</para> + + <screen><prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \ + ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen> + </step> + </procedure> + + <procedure xml:id="po-translations-quick-start-translation"> + <title>翻譯</title> + + <para xml:lang="en">Translating a document consists of two steps: extracting + translatable strings from the original document, and entering + translations for those strings. These steps are repeated + until the translator feels that enough of the document has + been translated to produce a usable translated + document.</para> + + <step> + <para>從英文的原始文件提取字串到 <acronym>PO</acronym> 檔：</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> +<prompt>%</prompt> <userinput>make po</userinput></screen> + </step> + + <step> + <para>使用 <acronym>PO</acronym> 編輯器將翻譯輸入 <acronym>PO</acronym> 檔。有幾個不同的編輯器可以使用。這裡用的是 <package role="port">editors/poedit</package> 的 <filename>poedit</filename> 。</para> + + <para><acronym>PO</acronym> 檔名是兩個字元的語系碼後面接底線和兩個字元的區域碼。以西班牙語來說，檔名是 <filename>es_ES.po</filename> 。</para> + + <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> + </step> + </procedure> + + <procedure xml:id="po-translations-quick-generating-a-translated-document"> + <title xml:lang="en">Generating a Translated Document</title> + + <step> + <para>產生翻譯文件</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> +<prompt>%</prompt> <userinput>make tran</userinput></screen> + + <para>產生的文件名稱與英文原始文件名稱相符，文章通常是 <filename>article.xml</filename> ，書籍是 <filename>book.xml</filename> 。</para> + </step> + + <step> + <para>可以轉換成 <acronym>HTML</acronym> 來檢查產生的檔案，並用瀏覽器來察看。</para> + + <screen><prompt>%</prompt> <userinput>make FORMATS=html</userinput> +<prompt>%</prompt> <userinput>firefox article.html</userinput></screen> + </step> + </procedure> + </sect1> + + <sect1 xml:id="po-translations-creating"> + <title>建立新翻譯</title> + + <para xml:lang="en">The first step to creating a new translated document is + locating or creating a directory to hold it. FreeBSD puts + translated documents in a subdirectory named for their + language and region in the format + <filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable></filename>. + <replaceable>lang</replaceable> is a two-character lowercase + code. It is followed by an underscore character and then the + two-character uppercase <replaceable>REGION</replaceable> + code.</para> + + <table xml:id="po-translations-language-names" frame="none"> + <title>語系名稱</title> + + <tgroup cols="5"> + <thead> + <row> + <entry>語言</entry> + <entry>地區</entry> + <entry>翻譯目錄名稱</entry> + <entry><acronym>PO</acronym> 檔名稱</entry> + <entry>字元集</entry> + </row> + </thead> + + <tbody> + <row> + <entry>英文</entry> + <entry>美國</entry> + <entry><filename>en_US.ISO8859-1</filename></entry> + <entry><filename>en_US.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>孟加拉文</entry> + <entry>孟加拉</entry> + <entry><filename>bn_BD.UTF-8</filename></entry> + <entry><filename>bn_BD.po</filename></entry> + <entry><acronym>UTF</acronym>-8</entry> + </row> + + <row> + <entry>丹麥文</entry> + <entry>丹麥</entry> + <entry><filename>da_DK.ISO8859-1</filename></entry> + <entry><filename>da_DK.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>德文</entry> + <entry>德國</entry> + <entry><filename>de_DE.ISO8859-1</filename></entry> + <entry><filename>de_DE.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>希臘文</entry> + <entry>希臘</entry> + <entry><filename>el_GR.ISO8859-7</filename></entry> + <entry><filename>el_GR.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-7</entry> + </row> + + <row> + <entry>西班牙文</entry> + <entry>西班牙</entry> + <entry><filename>es_ES.ISO8859-1</filename></entry> + <entry><filename>es_ES.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>法文</entry> + <entry>法國</entry> + <entry><filename>fr_FR.ISO8859-1</filename></entry> + <entry><filename>fr_FR.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>匈牙利文</entry> + <entry>匈牙利</entry> + <entry><filename>hu_HU.ISO8859-2</filename></entry> + <entry><filename>hu_HU.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-2</entry> + </row> + + <row> + <entry>義大利文</entry> + <entry>義大利</entry> + <entry><filename>it_IT.ISO8859-15</filename></entry> + <entry><filename>it_IT.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-15</entry> + </row> + + <row> + <entry>日文</entry> + <entry>日本</entry> + <entry><filename>ja_JP.eucJP</filename></entry> + <entry><filename>ja_JP.po</filename></entry> + <entry><acronym>EUC</acronym> JP</entry> + </row> + + <row> + <entry>韓文</entry> + <entry>韓國</entry> + <entry><filename>ko_KR.UTF-8</filename></entry> + <entry><filename>ko_KR.po</filename></entry> + <entry><acronym>UTF</acronym>-8</entry> + </row> + + <row> + <entry>蒙古文</entry> + <entry>蒙古</entry> + <entry><filename>mn_MN.UTF-8</filename></entry> + <entry><filename>mn_MN.po</filename></entry> + <entry><acronym>UTF</acronym>-8</entry> + </row> + + <row> + <entry>荷蘭文</entry> + <entry>荷蘭</entry> + <entry><filename>nl_NL.ISO8859-1</filename></entry> + <entry><filename>nl_NL.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>挪威文</entry> + <entry>挪威</entry> + <entry><filename>no_NO.ISO8859-1</filename></entry> + <entry><filename>no_NO.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>波蘭文</entry> + <entry>波蘭</entry> + <entry><filename>pl_PL.ISO8859-2</filename></entry> + <entry><filename>pl_PL.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-2</entry> + </row> + + <row> + <entry>葡萄牙文</entry> + <entry>巴西</entry> + <entry><filename>pt_BR.ISO8859-1</filename></entry> + <entry><filename>pt_BR.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-1</entry> + </row> + + <row> + <entry>俄文</entry> + <entry>俄羅斯</entry> + <entry><filename>ru_RU.KOI8-R</filename></entry> + <entry><filename>ru_RU.po</filename></entry> + <entry><acronym>KOI</acronym>8-R</entry> + </row> + + <row> + <entry>賽爾維亞</entry> + <entry>賽爾維亞文</entry> + <entry><filename>sr_YU.ISO8859-2</filename></entry> + <entry><filename>sr_YU.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-2</entry> + </row> + + <row> + <entry>土耳其文</entry> + <entry>土耳其</entry> + <entry><filename>tr_TR.ISO8859-9</filename></entry> + <entry><filename>tr_TR.po</filename></entry> + <entry><acronym>ISO</acronym> 8859-9</entry> + </row> + + <row> + <entry>中文</entry> + <entry>中國</entry> + <entry><filename>zh_CN.UTF-8</filename></entry> + <entry><filename>zh_CN.po</filename></entry> + <entry><acronym>UTF</acronym>-8</entry> + </row> + + <row> + <entry>中文</entry> + <entry>台灣</entry> + <entry><filename>zh_TW.UTF-8</filename></entry> + <entry><filename>zh_TW.po</filename></entry> + <entry><acronym>UTF</acronym>-8</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>翻譯位於主要文件目錄的子目錄，這裡假設如 <xref linkend="overview-quick-start"/> 所示，是 <filename>~/doc/</filename>。例如德文位於 <filename>~/doc/de_DE.ISO8859-1/</filename>， 法文位於 <filename>~/doc/fr_FR.ISO8859-1/</filename>。</para> + + <para>每個語系目錄包含不同文件類型的子目錄，通常是 <filename>articles/</filename> 和 <filename>books/</filename>。</para> + + <para>將目錄名稱組合起來就是文章或書的完整路徑。例如，NanoBSD 文章的法語翻譯在 <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename> 。而使用手冊的蒙古文翻譯在<filename>~/doc/mn_MN.UTF-8/books/handbook/</filename> 。</para> + + <para>當翻譯到一個新語系時必須建立一個新的語系目錄。如果語系目錄已經存在，那只需要有 <filename>articles/</filename> 或 <filename>books/</filename> 的子目錄。</para> + + <para>FreeBSD 文件的編譯是由同一個目錄的 <filename>Makefile</filename> 控制。簡單的文章可以從原始的英語目錄直接複製 <filename>Makefile</filename> 過來。書籍的翻譯流程結合多個獨立的 <filename>book.xml</filename> 和 <filename>chapter.xml</filename> 成為一個檔案， 所以書籍翻譯的 <filename>Makefile</filename> 必須複製並修改。</para> + + <example xml:id="po-translations-creating-example"> + <title xml:lang="en">Creating a Spanish Translation of the Porter's + Handbook</title> + + <para>建立<link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook">Porter 手冊</link>的西班牙文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename> 的書籍。</para> + + <procedure> + <step> + <para>西班牙文 books 目錄 <filename>~/doc/es_ES.ISO8859-1/books/</filename> 已經存在，所以只要建立 Porter 手冊的子目錄：</para> + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput> +<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput> +A porters-handbook</screen> + </step> + + <step> + <para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> +<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput> +A Makefile</screen> + + <para>修改 <filename>Makefile</filename> 內容以產生單一的 <filename>book.xml</filename>：</para> + + <programlisting># +# $FreeBSD$ +# +# Build the FreeBSD Porter's Handbook。 +# + +MAINTAINER=doc@FreeBSD.org + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# XML content +SRCS= book.xml + +# Images from the cross-document image library +IMAGES_LIB+= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png +IMAGES_LIB+= callouts/4.png +IMAGES_LIB+= callouts/5.png +IMAGES_LIB+= callouts/6.png +IMAGES_LIB+= callouts/7.png +IMAGES_LIB+= callouts/8.png +IMAGES_LIB+= callouts/9.png +IMAGES_LIB+= callouts/10.png +IMAGES_LIB+= callouts/11.png +IMAGES_LIB+= callouts/12.png +IMAGES_LIB+= callouts/13.png +IMAGES_LIB+= callouts/14.png +IMAGES_LIB+= callouts/15.png +IMAGES_LIB+= callouts/16.png +IMAGES_LIB+= callouts/17.png +IMAGES_LIB+= callouts/18.png +IMAGES_LIB+= callouts/19.png +IMAGES_LIB+= callouts/20.png +IMAGES_LIB+= callouts/21.png + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> + + <para xml:lang="en">Now the document structure is ready for the translator + to begin translating with + <command>make po</command>.</para> + </step> + </procedure> + </example> + + <example xml:id="po-translations-creating-example-french"> + <title>建立 <acronym>PGP</acronym> 金鑰文章的法語翻譯。</title> + + <para>建立 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/pgpkeys"><acronym>PGP</acronym> 金鑰文章</link>的法文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename> 的文章。</para> + + <procedure> + <step> + <para>法文 article 目錄 <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> 已經存在，所以只要建立 <acronym>PGP</acronym> 金鑰文章的子目錄：</para> + <screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput> +<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput> +A pgpkeys</screen> + </step> + + <step> + <para>從原始文件的目錄複製 <filename>Makefile</filename> ：</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput> +<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput> +A Makefile</screen> + + <para>檢查 <filename>Makefile</filename> 的內容。因為這是簡單的文章，此例的 <filename>Makefile</filename> 不用修改。第二行的 <literal>$FreeBSD...$</literal> 版本字串將會在檔案提交時被版本控制系統替換掉。</para> + + <programlisting># +# $FreeBSD$ +# +# Article：PGP Keys + +DOC?= article + +FORMATS?= html +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.xml + +# To build with just key fingerprints, set FINGERPRINTS_ONLY。 + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> + + <para>文章結構處理好後， 可以執行建立 <command>make po</command> 建立 <acronym>PO</acronym> 檔。</para> + </step> + </procedure> + </example> + </sect1> + + <sect1 xml:id="po-translations-translating"> + <title xml:lang="en">Translating</title> + + <para><application>gettext</application>系統大幅減少翻譯者要追蹤的事情。 字串從原始文件提取到<acronym>PO</acronym> 檔。再用 <acronym>PO</acronym> 檔編輯器輸入字串的翻譯。</para> + + <para>FreeBSD <acronym>PO</acronym> 翻譯系統不會覆蓋掉 <acronym>PO</acronym> 檔。所以提取步驟可以在任何時候重複執行來更新 <acronym>PO</acronym> 檔。</para> + + <para>用 <acronym>PO</acronym> 檔編輯器來編輯檔案。此例是用 <package role="port">editors/poedit</package>，因為它很簡單而且系統需求低。其他的 <acronym>PO</acronym> 檔編輯器提供一些特點，能使翻譯工作更輕鬆。Ports 裡有數個編輯器，包括 <package role="port">devel/gtranslator</package> 。</para> + + <para>保留 <acronym>PO</acronym> 檔是很重要的。它包含所有的翻譯成果。</para> + + <example xml:id="po-translations-translating-example"> + <title>翻譯 Porter 手冊到西班牙文</title> + + <para>輸入 Porter 手冊的西班牙文內容</para> + + <procedure> + <step> + <para>切換到西班牙文 Porter 手冊的目錄並更新 <acronym>PO</acronym> 檔。產生的 <acronym>PO</acronym> 檔如 <xref linkend="po-translations-language-names"/> 所示，名叫 <filename>es_ES.po</filename> 。</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> +<prompt>%</prompt> <userinput>make po</userinput></screen> + </step> + + <step> + <para>使用 <acronym>PO</acronym> 檔編輯器輸入翻譯：</para> + + <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> + </step> + </procedure> + </example> + </sect1> + + <sect1 xml:id="po-translations-tips"> + <title xml:lang="en">Tips for Translators</title> + + <sect2 xml:id="po-translations-tips-xmltags"> + <title>保留 <acronym>XML</acronym> 標籤</title> + + <para xml:lang="en">Preserve <acronym>XML</acronym> tags that are shown in + the English original.</para> + + <example> + <title>保留 <acronym>XML</acronym> 標籤</title> + + <para>英文原文：</para> + + <programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting> + + <para>西班牙文翻譯：</para> + + <programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting> + </example> + </sect2> + + <sect2 xml:id="po-translations-tips-spaces"> + <title>保留空白</title> + + <para>保留要翻譯字串前後的空白。翻譯的版本也要有這些空白。</para> + </sect2> + + <sect2 xml:id="po-translations-tips-verbatim"> + <title>不要翻譯的標籤</title> + + <para>有些標籤的內容要一字不差地保留，不要翻譯。</para> + + <itemizedlist xml:id="po-translations-tips-verbatim-list"> + <listitem> + <para><tag class="starttag">citerefentry</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">command</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">filename</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">literal</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">manvolnum</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">orgname</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">package</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">programlisting</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">prompt</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">refentrytitle</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">screen</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">userinput</tag></para> + </listitem> + + <listitem> + <para><tag class="starttag">varname</tag></para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 xml:id="po-translations-literal-dollar"> + <title><literal>$FreeBSD$</literal> 字串</title> + + <para>檔案裡的 $FreeBSD$ 版本字串需要特別處理。例如 <xref linkend="po-translations-creating-example"/> 裡，這些字串不是要被展開 (expanded)。英文文件使用 <literal>&dollar;</literal> entities 來避免使用實際的金錢符號。</para> + + <programlisting>&dollar;FreeBSD&dollar;</programlisting> + + <para>版本控制符號不會把 <literal>&dollar;</literal> entities 看成金錢符號，所以不會把字串展開成版本字串。</para> + + <para>當 <acronym>PO</acronym> 檔建立後，範例中的 <literal>&dollar;</literal> entities 被實際的金錢符號取代。當檔案提交時，產生的 <literal>$FreeBSD$</literal> 將會被版本控制系統展開。</para> + + <para>英文文件用的相同技術可以被用在翻譯上。翻譯時用 <literal>&dollar;</literal> 來取代金錢符號，輸入到 <acronym>PO</acronym> 檔編輯器：</para> + + <programlisting>&dollar;FreeBSD&dollar;</programlisting> + </sect2> + + <!-- + <sect2 xml:id="po-translations-tips-makefile"> + <title>Modifying the <filename>Makefile</filename></title> + + <para>What needs to be changed in the + <filename>Makefile</filename>?</para> + </sect2> + + <sect2 xml:id="po-translations-tips-locale"> + <title>Setting Locales for Editing</title> + + <para>Locale settings so the <acronym>PO</acronym> editor works + correctly?</para> + </sect2> + + <sect2 xml:id="po-translations-tips-poeditors"> + <title>Settings for Specific <acronym>PO</acronym> + Editors</title> + + <para>Per bcr: turn off "intelligent quotes" in + Mac poedit.</para> + </sect2> + + <sect2 xml:id="po-translations-tips-tm"> + <title>Using Translation Memory</title> + + <para>Using translation memory. Saving, updating, sharing + with other members of a translation team.</para> + </sect2> + + <sect2 xml:id="po-translations-tips-submitting"> + <title>Submitting Translations</title> + + <para>Submitting translations as diffs, committing + <acronym>PO</acronym> files.</para> + </sect2> + --> + </sect1> + + <sect1 xml:id="po-translations-building"> + <title>編譯翻譯的文件</title> + + <para>原文的翻譯版本可以在任何時候被建立。未翻譯的部份會以英文呈獻。大部份 <acronym>PO</acronym> 編輯器有指標可以顯示翻譯完成度。這讓翻譯者更容易看翻譯好的字串是否足夠來編譯最終的文件。</para> + + <example xml:id="po-translations-building-example"> + <title xml:lang="en">Building the Spanish Porter's Handbook</title> + + <para>編譯和預覽之前範例翻譯的西班牙文版 Porter 手冊</para> + + <procedure> + <step> + <para>編譯翻譯好的文件。因為原文是書籍，所以產生的文件是<filename>book.xml</filename>。</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> +<prompt>%</prompt> <userinput>make tran</userinput></screen> + </step> + + <step> + <para>轉換翻譯好的<filename>book.xml</filename>成<acronym>HTML</acronym>並用<application>Firefox</application>來瀏覽。這和英文版是相同的步驟，其他 <varname>FORMATS</varname> 也可以這樣做。請見<xref linkend="doc-build-rendering-common-formats"/> 。</para> + + <screen><prompt>%</prompt> <userinput>make FORMATS=html</userinput> +<prompt>%</prompt> <userinput>firefox book.html</userinput></screen> + </step> + </procedure> + </example> + </sect1> + + <sect1 xml:id="po-translations-submitting"> + <title>提交新翻譯</title> + + <para>準備要提交的新翻譯。這包含新增檔案到版本控制系統，對檔案設定額外的屬性，並建立 diff 來提交。</para> + + <para>範例中產生的 diff 檔可以被附加到 <link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">documentation bug report</link> 或 <link xlink:href="https://reviews.freebsd.org/">code review</link> 。</para> + + <example xml:id="po-translations-submitting-spanish"> + <title>NanoBSD 文章的西班牙文翻譯</title> + + <procedure> + <step> + <para>增加 FreeBSD 版本字串註解到 <acronym>PO</acronym> 檔的第一行：</para> + + <programlisting>#$FreeBSD$</programlisting> + </step> + + <step> + <para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統：</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput> +<prompt>%</prompt> <userinput>ls</userinput> +Makefile article.xml es_ES.po +<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput> +A Makefile +A article.xml +A es_ES.po</screen> + </step> + + <step> + <para>設定這些檔案的 <application>Subversion</application> <literal>svn:keywords</literal> 屬性到 <literal>FreeBSD=%H</literal>，讓提交時 <literal>$FreeBSD$</literal> 字串可以被展開成路徑、版本、日期和作者。</para> + + <screen><prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput> +property 'svn:keywords' set on 'Makefile' +property 'svn:keywords' set on 'article.xml' +property 'svn:keywords' set on 'es_ES.po'</screen> + </step> + + <step> + <para>設定檔案的<acronym>MIME</acronym> 類型。書籍和文章是 <literal>text/xml</literal> ，<acronym>PO</acronym> 檔是 <literal>text/x-gettext-translation</literal> 。</para> + + <screen><prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput> +property 'svn:mime-type' set on 'es_ES.po' +<prompt>%</prompt> <userinput>svn propset svn:mime-type text/xml article.xml</userinput> +property 'svn:mime-type' set on 'article.xml'</screen> + </step> + + <step> + <para>從 <filename>~/doc/</filename> 建立這些新檔案的 diff，讓檔名顯示完整的路徑。這可以幫助提交者辨識目標語系目錄。</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput> +<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput></screen> + </step> + </procedure> + </example> + + <example xml:id="po-translations-submitting-korean-utf8"> + <title>Explaining-BSD 文章的韓文 <acronym>UTF-8</acronym> 翻譯</title> + + <procedure> + <step> + <para>增加 FreeBSD 版本字串註解到 <acronym>PO</acronym> 檔的第一行：</para> + + <programlisting>#$FreeBSD$</programlisting> + </step> + + <step> + <para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統：</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput> +<prompt>%</prompt> <userinput>ls</userinput> +Makefile article.xml ko_KR.po +<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput> +A Makefile +A article.xml +A ko_KR.po</screen> + </step> + + <step> + <para>設定這些檔案的 <application>Subversion</application> <literal>svn:keywords</literal> 屬性到 <literal>FreeBSD=%H</literal>，讓提交時 <literal>$FreeBSD$</literal> 字串可以被展開成路徑、版本、日期和作者。</para> + + <screen><prompt>%</prompt> <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput> +property 'svn:keywords' set on 'Makefile' +property 'svn:keywords' set on 'article.xml' +property 'svn:keywords' set on 'ko_KR.po'</screen> + </step> + + <step> + <para>設定檔案的 <acronym>MIME</acronym> 類型。因為這些檔案使用 <acronym>UTF-8</acronym> 字元集，這也需要指定。為了防止版本控制系統將這些檔案誤認為二進位資料，<literal>fbsd:notbinary</literal> 屬性也需要設定。</para> + + <screen><prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/x-gettext-translation；charset=UTF-8' ko_KR.po</userinput> +property 'svn:mime-type' set on 'ko_KR.po' +<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput> +property 'fbsd:notbinary' set on 'ko_KR.po' +<prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/xml；charset=UTF-8' article.xml</userinput> +property 'svn:mime-type' set on 'article.xml' +<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes article.xml</userinput> +property 'fbsd:notbinary' set on 'article.xml'</screen> + </step> + + <step> + <para>從 <filename>~/doc/</filename> 建立這些新檔案的 diff。</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput> +<userinput>svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff</userinput></screen> + </step> + </procedure> + </example> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="writing-style"> + <title>寫作風格</title> + + <sect1 xml:id="writing-style-tips"> + <title>叮嚀</title> + + <para xml:lang="en">Technical documentation can be improved by consistent use of + several principles. Most of these can be classified into three + goals: <emphasis>be clear</emphasis>, + <emphasis>be complete</emphasis>, and + <emphasis>be concise</emphasis>. These goals can conflict with + each other. Good writing consists of a balance between + them.</para> + + <sect2 xml:id="writing-style-be-clear"> + <title xml:lang="en">Be Clear</title> + + <para xml:lang="en">Clarity is extremely important. The reader may be a + novice, or reading the document in a second language. Strive + for simple, uncomplicated text that clearly explains the + concepts.</para> + + <para xml:lang="en">Avoid flowery or embellished speech, jokes, or colloquial + expressions. Write as simply and clearly as possible. Simple + text is easier to understand and translate.</para> + + <para xml:lang="en">Keep explanations as short, simple, and clear as possible. + Avoid empty phrases like <quote>in order to</quote>, which + usually just means <quote>to</quote>. Avoid potentially + patronizing words like <quote>basically</quote>. Avoid Latin + terms like <quote>i.e.</quote> or <quote>cf.</quote>, which + may be unknown outside of academic or scientific + groups.</para> + + <para xml:lang="en">Write in a formal style. Avoid addressing the reader + as <quote>you</quote>. For example, say + <quote>copy the file to <filename>/tmp</filename></quote> + rather than <quote>you can copy the file to + <filename>/tmp</filename></quote>.</para> + + <para xml:lang="en">Give clear, correct, <emphasis>tested</emphasis> examples. + A trivial example is better than no example. A good example + is better yet. Do not give bad examples, identifiable by + apologies or sentences like <quote>but really it should never + be done that way</quote>. Bad examples are worse than no + examples. Give good examples, because <emphasis>even when + warned not to use the example as shown</emphasis>, the + reader will usually just use the example as shown.</para> + + <para xml:lang="en">Avoid <emphasis>weasel words</emphasis> like + <quote>should</quote>, <quote>might</quote>, + <quote>try</quote>, or <quote>could</quote>. These words + imply that the speaker is unsure of the facts, and + create doubt in the reader.</para> + + <para xml:lang="en">Similarly, give instructions as imperative commands: not + <quote>you should do this</quote>, but merely + <quote>do this</quote>.</para> + </sect2> + + <sect2 xml:id="writing-style-be-complete"> + <title xml:lang="en">Be Complete</title> + + <para xml:lang="en">Do not make assumptions about the reader's abilities or + skill level. Tell them what they need to know. Give links to + other documents to provide background information without + having to recreate it. Put yourself in the reader's place, + anticipate the questions they will ask, and answer + them.</para> + </sect2> + + <sect2 xml:id="writing-style-be-concise"> + <title xml:lang="en">Be Concise</title> + + <para xml:lang="en">While features should be documented completely, sometimes + there is so much information that the reader cannot easily + find the specific detail needed. The balance between being + complete and being concise is a challenge. One approach is to + have an introduction, then a <quote>quick start</quote> + section that describes the most common situation, followed by + an in-depth reference section.</para> + </sect2> + </sect1> + + <sect1 xml:id="writing-style-guidelines"> + <title xml:lang="en">Guidelines</title> + + <para xml:lang="en">To promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for + authors to follow.</para> + + <variablelist> + <varlistentry> + <term xml:lang="en">Use American English Spelling</term> + + <listitem> + <para xml:lang="en">There are several variants of English, with different + spellings for the same word. Where spellings differ, use + the American English variant. <quote>color</quote>, not + <quote>colour</quote>, <quote>rationalize</quote>, not + <quote>rationalise</quote>, and so on.</para> + + <note> + <para xml:lang="en">The use of British English may be accepted in the + case of a contributed article, however the spelling must + be consistent within the whole document. The other + documents such as books, web site, manual pages, etc. + will have to use American English.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en">Do not use contractions</term> + + <listitem> + <para xml:lang="en">Do not use contractions. Always spell the phrase out + in full. <quote>Don't use contractions</quote> is + wrong.</para> + + <para xml:lang="en">Avoiding contractions makes for a more formal tone, is + more precise, and is slightly easier for + translators.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en">Use the serial comma</term> + + <listitem> + <para xml:lang="en">In a list of items within a paragraph, separate each + item from the others with a comma. Separate the last item + from the others with a comma and the word + <quote>and</quote>.</para> + + <para xml:lang="en">For example:</para> + + <blockquote> + <para xml:lang="en">This is a list of one, two and three items.</para> + </blockquote> + + <para xml:lang="en">Is this a list of three items, <quote>one</quote>, + <quote>two</quote>, and <quote>three</quote>, or a list of + two items, <quote>one</quote> and <quote>two and + three</quote>?</para> + + <para xml:lang="en">It is better to be explicit and include a serial + comma:</para> + + <blockquote> + <para xml:lang="en">This is a list of one, two, and three items.</para> + </blockquote> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en">Avoid redundant phrases</term> + + <listitem> + <para xml:lang="en">Do not use redundant phrases. In particular, + <quote>the command</quote>, <quote>the file</quote>, and + <quote>man command</quote> are often redundant.</para> + + <para xml:lang="en">For example, commands:</para> + + <informalexample> + <para xml:lang="en">Wrong: Use the <command>svn</command> command to + update sources.</para> + </informalexample> + + <informalexample> + <para xml:lang="en">Right: Use <command>svn</command> to update + sources.</para> + </informalexample> + + <para xml:lang="en">Filenames:</para> + + <informalexample> + <para xml:lang="en">Wrong: … in the filename + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <informalexample> + <para xml:lang="en">Right: … in + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <para xml:lang="en">Manual page references (the second example uses + <tag>citerefentry</tag> with the + <literal>&man.csh.1;</literal> entity):.</para> + + <informalexample> + <para xml:lang="en">Wrong: See <command>man csh</command> for more + information.</para> + </informalexample> + + <informalexample> + <para xml:lang="en">Right: See <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </informalexample> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en">Two spaces between sentences</term> + + <listitem> + <para xml:lang="en">Always use two spaces between sentences, as it + improves readability and eases use of tools such as + <application>Emacs</application>.</para> + + <para xml:lang="en">A period and spaces followed by a capital letter + does not always mark a new sentence, especially in names. + <quote>Jordan K. Hubbard</quote> is a good example. It + has a capital <literal>H</literal> following a period and + a space, and is certainly not a new sentence.</para> + </listitem> + </varlistentry> + </variablelist> + + <para xml:lang="en">For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of + Style</link>, by William Strunk.</para> + </sect1> + + <sect1 xml:id="writing-style-guide"> + <title>風格指南</title> + + <para>由於文件是由眾多作者所維護，為了保持寫作風格的一貫性， 請遵守下列撰寫風格慣例。</para> + + <sect2> + <title xml:lang="en">Letter Case</title> + + <para>Tag 的部份都是用小寫字母，譬如是用 <tag>para</tag> ，<emphasis>而非</emphasis><tag>PARA</tag>。</para> + + <para>而 SGML 內文則是用大寫字母表示，像是： <literal><!ENTITY…></literal> 及 <literal><!DOCTYPE…></literal>， <emphasis>而不是</emphasis> <literal><!entity…></literal> 及 <literal><!doctype…></literal>。</para> + </sect2> + + <sect2 xml:id="writing-style-acronyms"> + <title xml:lang="en">Acronyms</title> + + <para>縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法， 比如：<quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>。 定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙， 除非使用完整詞彙可以更能表達語意)來表達即可。 通常每本書只會第一次提到時，才會列出完整詞彙， 但若您高興也可以在每章第一次提到時又列出完整詞彙。</para> + + <para>所有縮寫要包在<tag>acronym</tag>標籤內。</para> + </sect2> + + <sect2 xml:id="writing-style-indentation"> + <title>縮排</title> + + <para><emphasis>無論</emphasis>檔案縮排設定為何， 每個檔案的第一行都不縮排。</para> + + <para>未完的標籤會以多兩個空白來增加縮排， 結尾的標籤則少兩個空白來縮減縮排。 若已達 8 個空白，則以 tab 取代之。 此外，在 tab 前面不要再用空白，也不要在每行後面加上空白。 每個 tag 的內文若超過一行的話，則接下來的就多兩個空白以做縮排。</para> + + <para>舉個例子，這節所用的寫法大致是下面這樣：</para> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>The first line in each file starts with no indentation, + <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of + the file which might contain the current file。<tag class="endtag">para</tag> + + ... + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + + <para xml:lang="en">Tags containing long attributes follow the same + rules. Following the indentation rules in this case helps + editors and writers see which content is inside the + tags:</para> + + <programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link + linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag> + section if there are problems booting. Powering down and + disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk + will allow it to be kept as an offline backup.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &os; + system. Refer to the article <tag class="starttag">link + xlink:href="&url.articles.gjournal-desktop;"</tag>Implementing UFS + Journaling on a Desktop PC<tag class="endtag">link</tag> for detailed + instructions.<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">When an element is too long to fit on the remainder of a + line without wrapping, moving the start tag to the next line + can make the source easier to read. In this example, the + <literal>systemitem</literal> element has been moved to the + next line to avoid wrapping and indenting:</para> + + <programlisting><tag class="starttag">para</tag>With file flags, even + <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be + prevented from removing or altering files。<tag class="endtag">para</tag></programlisting> + + <para xml:lang="en">Configurations to help various text editors conform to + these guidelines can be found in + <xref linkend="editor-config"/>.</para> + </sect2> + + <sect2 xml:id="writing-style-tag-style"> + <title>標籤風格</title> + + <sect3 xml:id="writing-style-tag-style-spacing"> + <title>標籤空行</title> + + <para>同一縮排等級的標籤要以空一行來做區隔，而不同縮排等級的則不必。 比如：</para> + + <informalexample> + <programlisting><tag class="starttag">article lang='en'</tag> + <tag class="starttag">articleinfo</tag> + <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag> + + <tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>... + ... + ...<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">articleinfo</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">article</tag></programlisting> + </informalexample> + </sect3> + + <sect3 xml:id="writing-style-tag-style-separating"> + <title>標籤的分行</title> + + <para>像是 <tag>itemizedlist</tag> 這類的標籤事實上本身不含任何文字資料，必須得由其他標籤來補充內文。 這類的標籤會獨用一整行。</para> + + <para>另外，像是 <tag>para</tag> 及 <tag>term</tag> 這類的標籤並不需搭配其他標籤， 就可附上文字資料，並且在標籤後面的<emphasis>同一行</emphasis>內即可立即寫上這些內文。</para> + + <para>當然，這兩類的標籤結尾時也是跟上面道理相同。</para> + + <para>不過，當上述這兩種標籤混用時，會有很明顯的困擾。</para> + + <para>當第一類標籤的後面接上第二類標籤的話， 那麼要把這兩類標籤各自分行來寫。 後者標籤的段落， 也是需要做適當縮排調整。</para> + + <para>而第二類標籤結尾時，可以與第一類標籤的結尾放在同一行。</para> + </sect3> + </sect2> + + <sect2 xml:id="writing-style-whitespace-changes"> + <title>空白的更改</title> + + <para><emphasis>在提交修改時，請別在修改內容的同時， 也一起更改編排格式。</emphasis>。</para> + + <para>如此一來，像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容， 而不用費心思去判斷該行的改變，是由於格式重排或者內容異動。</para> + + <para>舉例說明，若要在某段加上兩個句子，如此一來該段落的某行勢必會超出 80 縱列，這時請先 commmit 修改。 接著，再修飾過長行落的換行，然後再次 commit 之。 而第二次的 commit 紀錄，請明確說明這只是 whitespace-only (修改空白而已) 的更改，如此一來，翻譯團隊就可以忽略第二次 commit 了 。</para> + </sect2> + + <sect2 xml:id="writing-style-nonbreaking-space"> + <title>Nonbreaking space</title> + + <para>請避免一些情況下的斷行：造成版面醜醜的、或是須連貫表達的同一句子。 斷行的情況會隨所閱讀的工具不同而有所不同。 尤其是透過純文字瀏覽器來看 HTML 時會更明顯看到類似下面這樣不好的編排段落：</para> + + <literallayout class="monospaced">Data capacity ranges from 40 MB to 15 +GB。 Hardware compression …</literallayout> + + <para>請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行， 以下示範如何使用 nonbreaking spaces：</para> + + <itemizedlist> + <listitem> + <para>在數字與單位之間：</para> + <programlisting>57600&nbsp;bps</programlisting> + </listitem> + + <listitem> + <para>在程式名稱與版號之間：</para> + <programlisting>&os;&nbsp;9.2</programlisting> + </listitem> + + <listitem> + <para>multiword 之間 (使用時請小心，像是 <quote>The FreeBSD Brazilian Portuguese Documentation Project</quote> 這類由三到四個字所組成的， 則不用加。)：</para> + <programlisting>Sun&nbsp;Microsystems</programlisting> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 xml:id="writing-style-word-list"> + <title>詞彙表</title> + + <para>以下詞彙表列出使用在 FreeBSD 文件的正確拼法和大小寫。 若找不到要找的詞彙，請詢問 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link> 。</para> + + <informaltable frame="none" pgwide="0"> + <tgroup cols="3"> + <thead> + <row> + <entry>Word</entry> + <entry>XML Code</entry> + <entry>Notes</entry> + </row> + </thead> + + <tbody> + <row> + <entry>CD-ROM</entry> + + <entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry> + </row> + + <row> + <entry>DoS (Denial of Service)</entry> + <entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry> + </row> + + <row> + <entry>email</entry> + </row> + + <row> + <entry>file system</entry> + </row> + + <row> + <entry>IPsec</entry> + </row> + + <row> + <entry>Internet</entry> + </row> + + <row> + <entry>manual page</entry> + </row> + + <row> + <entry>mail server</entry> + </row> + + <row> + <entry>name server</entry> + </row> + + <row> + <entry>Ports Collection</entry> + </row> + + <row> + <entry>read-only</entry> + </row> + + <row> + <entry>Soft Updates</entry> + </row> + + <row> + <entry>stdin</entry> + <entry><tag class="starttag">varname</tag>stdin<tag class="endtag">varname</tag></entry> + </row> + + <row> + <entry>stdout</entry> + <entry><tag class="starttag">varname</tag>stdout<tag class="endtag">varname</tag></entry> + </row> + + <row> + <entry>stderr</entry> + <entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry> + </row> + + <row> + <entry>Subversion</entry> + + <entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry> + <entry>不要用大寫<literal>SVN</literal>來表示 Subversion應用程式。以<tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>來表示指令。</entry> + </row> + + <row> + <entry xml:lang="en"><trademark class="registered">UNIX</trademark></entry> + <entry xml:lang="en"><literal>&unix;</literal></entry> + </row> + + <row> + <entry>userland</entry> + <entry/> + <entry xml:lang="en">things that apply to user space, not the + kernel</entry> + </row> + + <row> + <entry>web server</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> +</chapter> + + +<!-- Copyright (c) 2013 Warren Block + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS + IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="editor-config"> + + <title xml:lang="en">Editor Configuration</title> + + <para xml:lang="en">Adjusting text editor configuration can make working on + document files quicker and easier, and help documents conform to + <acronym>FDP</acronym> guidelines.</para> + + <sect1 xml:id="editor-config-vim"> + <title xml:lang="en"><application>Vim</application></title> + + <para xml:lang="en">Install from <package>editors/vim</package> + or <package>editors/vim-lite</package>.</para> + + <sect2 xml:id="editor-config-vim-config"> + <title xml:lang="en">Configuration</title> + + <para xml:lang="en">Edit <filename>~/.vimrc</filename>, adding these + lines:</para> + + <programlisting xml:lang="en">if has("autocmd") + au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML() + au BufNewFile,BufRead *.[1-9] call ShowSpecial() +endif " has(autocmd) + +function Set_Highlights() + "match ExtraWhitespace /^\s* \s*\|\s\+$/ + highlight default link OverLength ErrorMsg + match OverLength /\%71v.\+/ + return 0 +endfunction + +function ShowSpecial() + setlocal list listchars=tab:>>,trail:*,eol:$ + hi def link nontext ErrorMsg + return 0 +endfunction " ShowSpecial() + +function Set_SGML() + setlocal number + syn match sgmlSpecial "&[^;]*;" + setlocal syntax=sgml + setlocal filetype=xml + setlocal shiftwidth=2 + setlocal textwidth=70 + setlocal tabstop=8 + setlocal softtabstop=2 + setlocal formatprg="fmt -p" + setlocal autoindent + setlocal smartindent + " Rewrap paragraphs + noremap P gqj + " Replace spaces with tabs + noremap T :s/ /\t/<CR> + call ShowSpecial() + call Set_Highlights() + return 0 +endfunction " Set_SGML()</programlisting> + </sect2> + + <sect2 xml:id="editor-config-vim-use"> + <title xml:lang="en">Use</title> + + <para xml:lang="en">Press <keycap>P</keycap> to reformat paragraphs or text that has been selected in Visual mode. Press + <keycap>T</keycap> to replace groups of eight spaces with a + tab.</para> + </sect2> + </sect1> + + <sect1 xml:id="editor-config-emacs"> + <title xml:lang="en"><application>Emacs</application></title> + + <para xml:lang="en">Install from + <package>editors/emacs</package> + or <package>editors/xemacs</package>.</para> + + <para xml:lang="en">Edit <filename>~/.emacs</filename>, adding this + line:</para> + + <programlisting xml:lang="en">(add-hook 'nxml-mode-hook 'turn-on-auto-fill)</programlisting> + </sect1> + + <sect1 xml:id="editor-config-nano"> + <title xml:lang="en"><application>nano</application></title> + + <para xml:lang="en">Install from + <package>editors/nano</package> or + <package>editors/nano-devel</package>.</para> + + <sect2 xml:id="editor-config-nano-config"> + <title xml:lang="en">Configuration</title> + + <para xml:lang="en">Copy the sample <acronym>XML</acronym> syntax highlight + file to the user's home directory:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen> + + <para xml:lang="en">Add these lines to the new + <filename>~/.nanorc</filename>.</para> + + <programlisting xml:lang="en">syntax "xml" "\.([jrs]html?|xml|xslt?)$" +# trailing whitespace +color ,blue "[[:space:]]+$" +# multiples of eight spaces at the start a line +# (after zero or more tabs) should be a tab +color ,blue "^([TAB]*[ ]{8})+" +# tabs after spaces +color ,yellow "( )+TAB" +# highlight indents that have an odd number of spaces +color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}" +# lines longer than 70 characters +color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"</programlisting> + + <para xml:lang="en">Process the file to create embedded tabs:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen> + </sect2> + + <sect2 xml:id="editor-config-nano-use"> + <title xml:lang="en">Use</title> + + <para xml:lang="en">Specify additional helpful options when running the + editor:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen> + + <para xml:lang="en">Users of <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> can define an alias in + <filename>~/.cshrc</filename> to automate these + options:</para> + + <programlisting xml:lang="en">alias nano "nano -AKipwz -r 70 -T8"</programlisting> + + <para xml:lang="en">After the alias is defined, the options will be added + automatically:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="see-also"> + <title xml:lang="en">See Also</title> + + <para xml:lang="en">This document is deliberately not an exhaustive discussion of + XML, the DTDs listed, and the FreeBSD Documentation Project. For + more information about these, you are encouraged to see the + following web sites.</para> + + <sect1 xml:id="see-also-fdp"> + <title>FreeBSD 文件計劃</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="@@URL_RELPREFIX@@/docproj/index.html">FreeBSD 文件計劃網頁</link></para> + </listitem> + + <listitem> + <para><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">FreeBSD 使用手冊</link></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="see-also-xml"> + <title>XML</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://www.w3.org/XML/">W3C's XML 網頁 SGML/XML 網頁</link></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="see-also-html"> + <title>HTML</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://www.w3.org/">全球資訊網協會</link></para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.w3.org/TR/REC-html40/">The HTML 4.0 規格表</link></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="see-also-docbook"> + <title>DocBook</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://www.oasis-open.org/docbook/">The DocBook 技術委員會</link>， DocBook DTD的維護者</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.docbook.org/">DocBook：The Definitive Guide</link>， DocBook DTD的線上文件。</para> + </listitem> + + <listitem> + <para xml:lang="en"><link xlink:href="http://docbook.sourceforge.net/">The DocBook + Open Repository</link> contains DSSSL stylesheets and + other resources for people using DocBook</para> + </listitem> + </itemizedlist> + </sect1> + +</chapter> + + + +<!-- Copyright (c) 2000 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<appendix version="5.0" xml:id="examples"> + + <title>舉例</title> + + <para xml:lang="en">These examples are not exhaustive—they do not contain + all the elements that might be desirable to use, particularly in a + document's front matter. For more examples of DocBook markup, + examine the <acronym>XML</acronym> source for this and other + documents available in the <application>Subversion</application> + <literal>doc</literal> repository, or available online starting at + <uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para> + + <sect1 xml:id="examples-docbook-book"> + <title>DocBook <tag>book</tag></title> + + <example> + <title>DocBook <tag>book</tag></title> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> + +<tag class="starttag">book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:lang="en"</tag> + + <tag class="starttag">info</tag> + <tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag>2000<tag class="endtag">year</tag> + <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>If your book has an abstract then it should go here。<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + <tag class="starttag">preface</tag> + <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed + here。<tag class="endtag">para</tag> + <tag class="endtag">preface</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is the first chapter in my book。<tag class="endtag">para</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is the first section in my book。<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> + <tag class="endtag">chapter</tag> +<tag class="endtag">book</tag></programlisting> + </example> + </sect1> + + <sect1 xml:id="examples-docbook-article"> + <title>DocBook <tag>article</tag></title> + + <example> + <title>DocBook <tag>article</tag></title> + + <programlisting><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> + +<tag class="starttag">article xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:lang="en"</tag> + + <tag class="starttag">info</tag> + <tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag>2000<tag class="endtag">year</tag> + <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>If your article has an abstract then it should go here。<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is the first section in my article。<tag class="endtag">para</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is the first sub-section in my article。<tag class="endtag">para</tag> + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">article</tag></programlisting> + </example> + </sect1> +</appendix> + <index/> </book> |