aboutsummaryrefslogtreecommitdiff
path: root/zh_TW.UTF-8/articles
diff options
context:
space:
mode:
authorLi-Wen Hsu <lwhsu@FreeBSD.org>2014-05-29 16:48:07 +0000
committerLi-Wen Hsu <lwhsu@FreeBSD.org>2014-05-29 16:48:07 +0000
commit163ba6b752e2d1b900f88ba29324ed5998b14551 (patch)
tree3010592efec60252103b5e76eab918b0491bb533 /zh_TW.UTF-8/articles
parent536050cea8f16998f8fbddf6b4aff8469e149ec0 (diff)
downloaddoc-163ba6b752e2d1b900f88ba29324ed5998b14551.tar.gz
doc-163ba6b752e2d1b900f88ba29324ed5998b14551.zip
Convert zh_TW from Big5 to UTF-8.
Approved by: bcr
Notes
Notes: svn path=/head/; revision=44974
Diffstat (limited to 'zh_TW.UTF-8/articles')
-rw-r--r--zh_TW.UTF-8/articles/Makefile15
-rw-r--r--zh_TW.UTF-8/articles/Makefile.inc5
-rw-r--r--zh_TW.UTF-8/articles/contributing/Makefile22
-rw-r--r--zh_TW.UTF-8/articles/contributing/article.xml465
-rw-r--r--zh_TW.UTF-8/articles/cvs-freebsd/Makefile21
-rw-r--r--zh_TW.UTF-8/articles/cvs-freebsd/article.xml570
-rw-r--r--zh_TW.UTF-8/articles/freebsd-questions/Makefile22
-rw-r--r--zh_TW.UTF-8/articles/freebsd-questions/article.xml610
-rw-r--r--zh_TW.UTF-8/articles/hubs/Makefile17
-rw-r--r--zh_TW.UTF-8/articles/hubs/article.xml1051
-rw-r--r--zh_TW.UTF-8/articles/mailing-list-faq/Makefile26
-rw-r--r--zh_TW.UTF-8/articles/mailing-list-faq/article.xml416
-rw-r--r--zh_TW.UTF-8/articles/nanobsd/Makefile28
-rw-r--r--zh_TW.UTF-8/articles/nanobsd/article.xml434
-rw-r--r--zh_TW.UTF-8/articles/pr-guidelines/Makefile19
-rw-r--r--zh_TW.UTF-8/articles/pr-guidelines/article.xml875
-rw-r--r--zh_TW.UTF-8/articles/problem-reports/Makefile19
-rw-r--r--zh_TW.UTF-8/articles/problem-reports/article.xml1103
-rw-r--r--zh_TW.UTF-8/articles/remote-install/Makefile30
-rw-r--r--zh_TW.UTF-8/articles/remote-install/article.xml475
20 files changed, 6223 insertions, 0 deletions
diff --git a/zh_TW.UTF-8/articles/Makefile b/zh_TW.UTF-8/articles/Makefile
new file mode 100644
index 0000000000..dda9fb6ed3
--- /dev/null
+++ b/zh_TW.UTF-8/articles/Makefile
@@ -0,0 +1,15 @@
+# $FreeBSD$
+
+SUBDIR =
+SUBDIR+= contributing
+SUBDIR+= cvs-freebsd
+SUBDIR+= freebsd-questions
+SUBDIR+= hubs
+SUBDIR+= mailing-list-faq
+SUBDIR+= nanobsd
+SUBDIR+= pr-guidelines
+SUBDIR+= problem-reports
+SUBDIR+= remote-install
+
+DOC_PREFIX?= ${.CURDIR}/../..
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/Makefile.inc b/zh_TW.UTF-8/articles/Makefile.inc
new file mode 100644
index 0000000000..e9ca57f579
--- /dev/null
+++ b/zh_TW.UTF-8/articles/Makefile.inc
@@ -0,0 +1,5 @@
+#
+# $FreeBSD$
+#
+
+DESTDIR?= ${DOCDIR}/zh_TW.UTF-8/articles/${.CURDIR:T}
diff --git a/zh_TW.UTF-8/articles/contributing/Makefile b/zh_TW.UTF-8/articles/contributing/Makefile
new file mode 100644
index 0000000000..72cfc4b491
--- /dev/null
+++ b/zh_TW.UTF-8/articles/contributing/Makefile
@@ -0,0 +1,22 @@
+#
+# The FreeBSD Traditional Chinese Project
+#
+# Original Revision: 1.6
+# $FreeBSD$
+#
+# Article: Contributing to FreeBSD
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?=gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.xml
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/contributing/article.xml b/zh_TW.UTF-8/articles/contributing/article.xml
new file mode 100644
index 0000000000..56ff1a66e0
--- /dev/null
+++ b/zh_TW.UTF-8/articles/contributing/article.xml
@@ -0,0 +1,465 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!--
+ The FreeBSD Documentation Project
+ The FreeBSD Chinese (Traditional) Documentation Project
+
+ Original Revision: 1.506
+ Chased Revision: 1.508
+-->
+<article 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>
+
+
+ <abstract>
+ <para>無論是個人或是各種組織,如果希望為 FreeBSD 提供幫助,都可以在本文中找到合適的方法。</para>
+ </abstract>
+
+ <authorgroup>
+ <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>原著: </contrib></author>
+ </authorgroup>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.ieee;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ </info>
+
+ <indexterm><primary>貢獻</primary></indexterm>
+
+ <para>你希望替 FreeBSD 做點什麼嗎?太好了,我們歡迎你。FreeBSD
+ 正是有賴於廣大使用者的貢獻才得以發展壯大的。我們不僅非常感謝您所做的貢獻,而且,這些工作對於 FreeBSD 的持續發展也至關重要。</para>
+
+
+ <para>也許與您想像的不同,您既不必得是一名出色的 Programmer,也無須和
+ FreeBSD core team 成員有很好的私交,我們會一視同仁的對待您的工作。
+ FreeBSD 的開發人員遍布全球,大家技術專長各異,年齡分布也非常廣泛。
+ 然而,每天我們都在面對持續增加的工作,而苦於沒有足夠的人手,因此我們隨時歡迎您的幫助。</para>
+
+ <para>FreeBSD 計劃所處理的是一個完整的作業系統環境,而不只是一個 kernel 或是一些零散的工具包。
+ 因此,我們的 <filename>TODO</filename> 待辦任務列表裡包含各式各樣的工作:
+ 從文件、使用者測試、demo,到系統安裝程式和更專業的 kernel 開發。
+ 因此無論您的技術水準如何,從事何種領域,都可以幫助這個計劃。</para>
+
+ <para>我們鼓勵從事和 FreeBSD 相關工作的企業和我們聯繫。
+ 您需要一些特殊的擴展來使您的產品運轉起來嗎?
+ 您會發現我們很樂意答應您的請求,除非是特別稀奇古怪的。
+ 您是否正從事相關的增值業務? 讓我們來幫助您吧,
+ 我們也許可以在某些方面相互合作。
+ 自由軟體界正在努力打破舊有的框框(像是關於軟體開發、銷售和維護),
+ 我們希望懇請您至少能給它一次機會。</para>
+
+ <sect1 xml:id="contrib-what">
+ <title>我們的需求</title>
+
+ <para>下面列出了一些需要完成的任務和子計劃,
+ 它們代表 <filename>TODO</filename>(待辦任務列表)
+ 列表的意思,以及使用者的要求。</para>
+
+ <sect2 xml:id="non-programmer-tasks">
+ <title>正在進行中的任務(非程式開發人員)</title>
+
+ <para>很多參加 FreeBSD 計劃的人不是 Programmer。
+ 這個計劃裡有文件撰寫者、網頁設計師、以及技術支援人員。
+ 對於這些義工來說,他們只需要貢獻一些時間,並且具有學習的意願。</para>
+
+ <orderedlist>
+ <listitem>
+ <para>您可以時常翻閱 FAQ 和手冊(Handbook)
+ ,如果發現有解釋不清楚的地方,或是不合時宜的文件,甚至完全不正確的地方,
+ 都請告訴我們。當然,若能順手把他們修正,並把勘誤寄給我們,那就更好了。:)
+ (SGML 其實並不難學,但我們也不反對您直接提交一般 ASCII 的純文字版本)。</para>
+ </listitem>
+
+ <listitem>
+ <para>幫助我們把 FreeBSD 文件翻譯成你的母語。
+ 如果你的母語版本已經存在了,
+ 也可以翻譯一些額外的文件,或者檢查那些已有的文件是否為最新版。
+ 您可以先簡單看看 FreeBSD 文件計劃中有關 <link xlink:href="&url.books.fdp-primer;/translations.html">翻譯時的常見問題</link>。
+ 參加翻譯工作,並不是說您要孤軍奮戰翻譯所有 FreeBSD 文件。
+ 身為義工,要做多少工作完全取決於您的意願。一旦某個人開始翻譯了,
+ 之後幾乎一定會有其他人參與到這些工作中來。
+ 如果時間有限,或者精力不夠去翻譯整份文件,那可以首先去翻譯安裝指南。</para>
+ </listitem>
+
+ <listitem>
+ <para>閱讀 &a.questions; 並偶爾翻閱(甚至有規律地這樣做) &ng.misc;
+ 。與別人分享您的專業知識,
+ 並幫助他們解決問題,是件令人愉悅的事情;
+ 有時候,您甚至可以在這個過程中學到一些新東西!
+ 這些論壇有時也會為您激發出一些不錯的想法。</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+
+ <sect2 xml:id="ongoing-programmer-tasks">
+ <title>正在進行中的任務(程式開發人員)</title>
+ <para>列在這裡的大部分任務都需要您投入可觀的時間,或者需要您在 FreeBSD kernel
+ 方面有豐富的知識,或者兩者都要。當然這裡也有很多重要的任務,適合像是
+ <quote>weekend hackers</quote> 這類只用週末就可以搞定的 Hacker。</para>
+
+ <orderedlist>
+ <listitem>
+ <para>如果您正在跑的是 FreeBSD -CURRENT 版本,並且網路速度還不錯,
+ 那麼可以到 <systemitem class="fqdomainname">current.FreeBSD.org</systemitem>,
+ 這台每天會有一個新版本 &mdash; 如果您有空,
+ 您可以三不五時下載並安裝,
+ 其間如果出了什麼問題,請告訴我們。</para>
+ </listitem>
+
+ <listitem>
+ <para>閱讀 &a.bugs;。這些問題,或許您能提供有建設性意義的意見,
+ 或者幫忙測試一些 patch 。此外,甚至可以嘗試修正其中的一些問題。</para>
+ </listitem>
+
+ <listitem>
+ <para>如果您知道有一些修正已經在 -CURRENT 上成功地使用,
+ 但在經過一段時間(通常是 2 週左右)之後,仍未合併到 -STABLE
+ (這步驟就是 MFC -- Merged From Current),那麼可以給相關的 committer 人員發封禮貌的提醒信。</para>
+ </listitem>
+
+ <listitem>
+ <para>將第三方(3rd party)軟體加入到原始碼中的
+ <filename>src/contrib</filename> 目錄。</para>
+ </listitem>
+
+ <listitem>
+ <para>確保 <filename>src/contrib</filename> 中的原始碼是最新的。</para>
+ </listitem>
+
+ <listitem>
+ <para>編譯原始碼(或是部分原始碼)時,請改用更高的警告等級(warning level)
+ 以便偵錯(debug)用,並在完成測試、確認正常完畢之後,清除這些編譯的警告等級。</para>
+ </listitem>
+
+ <listitem>
+ <para>更新那些在 ports 中使用過時的東西,
+ 例如 <function>gets()</function> 或包含
+ <filename>malloc.h</filename> 所產生的警告。</para>
+ </listitem>
+
+ <listitem>
+ <para>如果有為 ports 作了任何修正,
+ 請記得將您的 patch 發給原作者 (這樣下次升級時,您的工作會變得輕鬆一些)。</para>
+ </listitem>
+
+ <listitem>
+ <para>先取得正式的標準,如 &posix; 的副本。
+ 在 <link xlink:href="&url.base;/projects/c99/index.html">FreeBSD
+ C99 &amp; POSIX 標準相容計劃</link> 網站上,可以得到相關鏈接。
+ 請將 FreeBSD 的行為與上述的標準進行比較,若所得結果與 C99 &amp; POSIX 標準不同的話,
+ 特別是那些細節地方的微小差異,請發一個關於它的 PR (問題報告)。
+ 如果可能,請指出如何修正它,並隨 PR 提交 patch 。
+ 如果您認為標準有問題,請向這些規格標準的相關團體,請求對其進行重新的考慮。</para>
+ </listitem>
+
+ <listitem>
+ <para>為這份列表提供更多建議!</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+
+ <sect2>
+ <title>查閱整個 PR 資料庫</title>
+
+ <indexterm><primary>問題報告資料庫</primary></indexterm>
+
+ <para><link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD
+ PR 列表</link> 這裡會顯示目前所有 PR 的問題狀態,以及由
+ FreeBSD 使用者提交的改進建議。
+ PR 資料庫同時包括了開發人員和非開發人員的任務。
+ 查看那些尚未解決的 PR,並看看是否有您感興趣的任務。
+ 這其中可能有一些是非常簡單的問題,只需要看一看並確認 PR 是正確的。
+ 另外一些可能會非常複雜,或者完全未附任何修正。</para>
+
+ <para>首先看一看那些還沒有人接手的 PR。
+ 如果 PR 已經分配給了其它人,但看起來是您能夠處理的,
+ 您可以寄信給那個人,並詢問您是否可以提供幫助 &mdash;
+ 他們可能已經有可供測試的 patch ,或有一些可供討論的意見。</para>
+ </sect2>
+
+ <sect2>
+ <title>由 <quote>Ideas</quote> 中選一項</title>
+
+ <para><link xlink:href="&url.base;/projects/ideas/">&os; list of
+ projects and ideas for volunteers</link> 同樣地開放給有意願參與
+ &os; 計劃的人。
+ 這份清單將持續地更新,同時提供各個項目的資訊給所有人
+ (不論是否為程式設計人員)。</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="contrib-how">
+ <title>如何提供幫助</title>
+
+ <para>基本上可以分為以下 5 種方式:</para>
+
+ <sect2 xml:id="contrib-general">
+ <title>錯誤報告和意見發表</title>
+
+ <para>通常,<emphasis>一般</emphasis>
+ 的技術想法和建議應該發到 &a.hackers;。
+ 同樣地,對於這些東西有興趣的人 (當然,
+ 他們同時還要能夠容忍 <emphasis>大量的</emphasis> 郵件!)
+ 可以考慮訂閱 &a.hackers;。
+ 請參閱 <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">FreeBSD
+ 使用手冊</link> 以了解關於這個郵遞論壇,
+ 以及其它郵遞論壇的詳細情況。</para>
+
+ <para>如果您發現了 bug 或者想要提交某些修改,
+ 請透過 &man.send-pr.1; 程式或使用
+ <link xlink:href="&url.base;/send-pr.html">網頁介面
+ 的回報</link> 來提交。請試著填寫 PR 的每個項目。
+ 一般來說,除非 patch 檔超過 65 KB,我們建議在 PR 中直接附上 patch 就可以了。
+ 若可直接套用 patch 到原始碼的話,那麼建議在 PR 的
+ Synopsis 欄位註明 <literal>[PATCH]</literal>。
+ 對了,在附上 patch 時,請 <emphasis>不要</emphasis>
+ 透過滑鼠的『複製、貼上』來進行,因為這樣做會把 Tab 變成空格,
+ 會導致 patch 就不能用了。如果 patch 超過 20KB,
+ 請考慮壓縮它並使用 &man.uuencode.1; 來進行編碼。</para>
+
+ <para>在寫完 PR 之後,您會收到一封確認郵件以及事件追蹤編號。
+ 請保留這個編號,因為事後可以用這編號發信到 &a.bugfollowup;
+ 來回覆、提供關於該事件的後續資料。您需要做的是將編號放到郵件的標題中,
+ 例如 <literal>"Re:
+ kern/3377"</literal>。
+ 若是同一問題的回覆方面,應該透過這種方式來進行。</para>
+
+ <para>如果您在一段時間 (超過 3 天甚至 1 週,這取決於您的郵件服務)之後仍然沒有收到確認信
+ 或者由於一些原因無法使用 &man.send-pr.1; 程式,
+ 則可以發信到 &a.bugs; 來請別人幫你代寄。</para>
+
+ <para>請參閱 <link xlink:href="&url.articles.problem-reports;/article.html">這篇文章</link>
+ 了解如何撰寫好的問題報告。</para>
+ </sect2>
+
+ <sect2>
+ <title>對於文件的修訂</title>
+
+ <indexterm><primary>提交文件</primary></indexterm>
+
+ <para>文件的修改方面,是由 &a.doc; 來審查。
+ 請參閱 <link xlink:href="&url.books.fdp-primer;/index.html">FreeBSD Documentation Project Primer</link>
+ 來獲得完整的教學細節。
+ 請按照 <xref linkend="contrib-general"/> 中介紹的方法使用 &man.send-pr.1;
+ 來提交新的文件,或者改善現有的文件 (哪怕是很小的改進也是歡迎的!)。</para>
+ </sect2>
+
+ <sect2>
+ <title>對於現有原始碼的修改</title>
+
+ <indexterm><primary>FreeBSD-CURRENT</primary></indexterm>
+
+ <para>在現有原始碼上進行修改或增加功能,在某種程度上是需要更多技巧的事,
+ 並且還跟您對於目前 FreeBSD 的開發現狀了解程度有關。
+ 有多種方式可以得到被稱作 <quote>FreeBSD-CURRENT</quote>
+ 的 FreeBSD 開發版本。
+ 請參閱 FreeBSD 使用手冊的 <link xlink:href=" &url.books.handbook;/current-stable.html">相關部份</link> ,來了解使用 FreeBSD-CURRENT 的詳情。</para>
+
+ <para>在舊的原始碼上進行修改,則通常可能原始碼已過時,
+ 或與新的版本差異太大而無法被重新整合到 FreeBSD 中。
+ 如果您有訂 &a.announce; 以及 &a.current; 的話,
+ 則可以透過它們來大致了解目前的開發狀態。</para>
+
+ <para>若您能夠儘量以最新的原始碼來進行您的修改,
+ 則下一步要做的事情就是產生您所修改的 diff 檔,
+ 並將它發給 FreeBSD 的維護人員。這項工作可以透過 &man.diff.1;
+ 命令來完成。</para>
+
+ <para>提交 patch 時,建議 &man.diff.1; 格式採用 unified diff (可以用 <command>diff
+ -u</command> 來產生)。不過,如果您修改了大量的原始碼,
+ 則使用 <command>diff -c</command> 來生成的 context diff
+ 的 diff 可能更容易閱讀,因而推薦使用。一般而言,大都是採用 <command>diff -ruN</command> 即可。</para>
+
+ <indexterm>
+ <primary><command>diff</command></primary>
+ </indexterm>
+
+ <para>例如:</para>
+
+ <para>
+ <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen>
+
+ 或
+
+ <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen>
+
+ 將會對特定目錄,產生 context 的 diff 檔。</para>
+
+ <para>或者像是...
+ <screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen>
+ 或
+ <screen>&prompt.user; <userinput>diff -u -r olddir newdir</userinput></screen>
+
+ 將產生一樣的 diff ,但是格式為 unified 。</para>
+
+ <para>更多的細節部份,請參閱 &man.diff.1;。</para>
+
+ <para>一旦您使用 &man.diff.1; 來產生 diff 檔 (可以使用
+ &man.patch.1; 命令來測試一下),就可以提交它們,以便被 FreeBSD 收錄。
+ 透過使用 <xref linkend="contrib-general"/>
+ 中所介紹的 &man.send-pr.1; 程式就可以完成這項工作。
+ 請注意:不要只把 diff 檔發到 &a.hackers;,
+ 否則它們可能會被遺忘! 我們會非常感激您提交的修改
+ (這是一個義工計劃!); 因為我們都很忙,
+ 因此有時不一定能夠立即修正問題,但 PR 資料庫將一直保持著這些記錄,
+ 因此只要有人有了時間它們就能被改正了。
+ 如果您的問題報告中包括 patch ,不要忘了在標題加上
+ <literal>[PATCH]</literal> 來強調一下。</para>
+
+ <indexterm>
+ <primary><command>uuencode</command></primary>
+ </indexterm>
+
+ <para>如果您認為合適 (例如增、刪檔案或更改檔名),
+ 還可以考慮使用
+ <command>tar</command> 來將檔案打包,然後用 &man.uuencode.1;
+ 來編碼。此外,也可以用 &man.shar.1; 產生的方式。</para>
+
+ <para>如果您的修改可能存在潛在的爭議,例如,
+ 您不確定相關的版權問題,或者感覺需要經過更嚴格的復審才可以發佈它們,
+ 則應直接發給 &a.core;,而不是透過 &man.send-pr.1; 來發送。
+ &a.core; 這小組成員大多從事 FreeBSD 的日常工作。
+ 需要注意的是,這個小組也因此十分忙碌,
+ 因此只有在非常必要的時候,才應寫信給他們。</para>
+
+ <para>請參考 &man.intro.9; 和 &man.style.9; 以了解關於撰寫程式碼的風格偏好。
+ 若能在送出相關程式碼之前,先了解這些,那對大家來說將是極大的幫助。</para>
+ </sect2>
+
+ <sect2>
+ <title>新原始碼或重要的加值軟體包</title>
+
+ <para>如果您打算提供規模較大的原始碼,或者為 FreeBSD 增加重要的新功能,
+ 則可能必須將它們透過 uuencode 進行編碼,或傳到某個 Web 或
+ FTP 站點,以便更多的人能夠得到它。如果您沒有這樣的主機,
+ 請到相關的 FreeBSD 郵遞論壇提出,看看是否有人願意幫您放置它們。</para>
+
+ <para>對於大量的原始碼而言,關於版權的問題肯定會被提出。
+ FreeBSD 基本系統中能夠使用的版權聲明包括:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>BSD<indexterm><primary>BSD 版權聲明</primary></indexterm> 版權。我們傾向於使用這類授權的原始碼,
+ 因為它『不附加多餘的條件』,因而更能夠吸引商業企業使用。
+ FreeBSD 並不反對商業公司使用它的原始碼,相反,
+ 我們積極地鼓勵商業公司使用我們的原始碼,
+ 當然,如果它們若最終能把部分原始碼,重新捐贈給 FreeBSD 就更好了。</para>
+ </listitem>
+
+ <listitem>
+ <para>GNU General Public License,或簡稱 <quote>GPL</quote>。<indexterm><primary>GPL</primary><see>GNU General Public License</see></indexterm><indexterm><primary>GNU General Public License</primary></indexterm>
+ 我們並不很歡迎使用這樣授權的原始碼,
+ 因為商業公司使用它需要做更多的工作。不過,由於很多使用
+ GPL 授權的原始碼目前是無法避免的 (compiler, assembler, text formatter等等)
+ ,拒絕使用所有採用這樣授權的軟體是很不明智的。
+ 採用 GPL 授權的原始碼會被放到原始碼的一些特定的位置,例如
+ <filename>/sys/gnu</filename> 或
+ <filename>/usr/src/gnu</filename>,以便那些認為 GPL
+ 可能會造成麻煩的人能夠作出適當的判斷。</para>
+ </listitem>
+ </orderedlist>
+
+ <para>使用其它授權的原始碼在進入 FreeBSD 之前必須經過慎重的復審和考慮。
+ 採用包含嚴厲限制的商業授權的原始碼,一般來說會被拒絕,
+ 但我們鼓勵這些原始碼的作者,透過自己的管道來發布它們。</para>
+
+ <para>若要在您的成果上加入 <quote>BSD-based</quote> 版權的話,
+ 請把下列文字放到每份原始碼的最開始部分,
+ 並用適當的文字替換 <literal>%%</literal> 之間的文字。</para>
+
+ <programlisting>Copyright (c) %%proper_years_here%%
+ %%your_name_here%%, %%your_state%% %%your_zip%%.
+ 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 as
+ the first lines of this file unmodified.
+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 %%your_name_here%% ``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 %%your_name_here%% 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.
+
+ &#36;Id&#36;</programlisting>
+
+ <para>為了方便您的使用,在
+ <filename>/usr/share/examples/etc/bsd-style-copyright</filename>
+ 也可以找到此授權的副本。</para>
+ </sect2>
+
+ <sect2>
+ <title>贊助資金、硬體或 Internet mirror</title>
+
+ <para>我們非常願意接受各種形式的捐贈,以進一步拓展 FreeBSD 計劃
+ ,因為有您的支持,像我們這樣的義工努力才能夠有更大的成就!
+ 捐贈硬體也非常重要,因為這樣能夠幫助我們增加可支援的硬體種類,
+ 而我們中的很多人並沒有足夠的資金來購置這些硬體。</para>
+
+ <sect3 xml:id="donations">
+ <title>捐款</title>
+
+ <para>FreeBSD 基金會是一個非營利的、有課稅豁免權的基金會,
+ 之所以會建立這個基金會,是為了讓 FreeBSD 計劃能夠可長可久。
+ 因為該基金會屬 501(c)3 實體,一般而言捐款給基金會的話,可以免繳美國聯邦收入稅,
+ 以及科羅拉多州收入稅。通常對於有課稅豁免權的實體進行捐贈的話,
+ 可以折抵聯邦收入中應課稅部分的金額。</para>
+
+ <para>您可以把支票寄往:
+ <address>
+ The FreeBSD Foundation
+ <street>7321 Brockway Dr.</street>
+ <city>Boulder</city>, <state>CO</state> <postcode>80303</postcode>
+ <country>USA</country>
+ </address>
+ </para>
+
+ <para>FreeBSD 基金會現在可以透過 PayPal 從網上接受捐款。
+ 如果您想向基金會捐款,請參閱 <link xlink:href="http://www.freebsdfoundation.org">FreeBSD 基金會</link> 網站。</para>
+
+ <para>關於 FreeBSD 基金會的更多詳情,可以在 <link xlink:href="http://people.FreeBSD.org/~jdp/foundation/announcement.html">FreeBSD
+ 基金會 -- 介紹</link> 找到。要聯絡基金會,
+ 請發送電子郵件到
+ <email>bod@FreeBSDFoundation.org</email>。</para>
+ </sect3>
+
+ <sect3>
+ <title>捐贈硬體</title>
+ <indexterm><primary>捐贈</primary></indexterm>
+
+ <para>FreeBSD 計劃歡迎任何人捐贈可以使用的硬體。
+ 如果您有興趣捐贈硬體,請聯繫 <link xlink:href="&url.base;/donations/">捐贈聯絡人辦公室</link>。</para>
+ </sect3>
+
+ <sect3>
+ <title>成為 FreeBSD mirror 的網站</title>
+
+ <para>我們歡迎新的 FTP、WWW 或
+ <command>cvsup</command> mirror 站。如果您希望成為這樣的 mirror 站,
+ 請參閱 <link xlink:href="&url.articles.hubs;/index.html">如何架設 FreeBSD mirror</link>
+ 一文,以了解進一步的情況。</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <index/>
+</article>
diff --git a/zh_TW.UTF-8/articles/cvs-freebsd/Makefile b/zh_TW.UTF-8/articles/cvs-freebsd/Makefile
new file mode 100644
index 0000000000..f7f1f12588
--- /dev/null
+++ b/zh_TW.UTF-8/articles/cvs-freebsd/Makefile
@@ -0,0 +1,21 @@
+# $FreeBSD$
+#
+# Article: Setting up a CVS repository - the FreeBSD way
+#
+# Build the Traditional Chinese Version
+
+MAINTAINER= stijn@win.tue.nl
+
+DOC?= article
+
+FORMATS?= html
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.xml
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/cvs-freebsd/article.xml b/zh_TW.UTF-8/articles/cvs-freebsd/article.xml
new file mode 100644
index 0000000000..8f589b7c26
--- /dev/null
+++ b/zh_TW.UTF-8/articles/cvs-freebsd/article.xml
@@ -0,0 +1,570 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!-- $FreeBSD$ -->
+<!-- The FreeBSD Documentation Project -->
+<!-- Setting up a CVS repository - the FreeBSD way -->
+<!-- Translate into Chinese by jose@jose.idv.tw -->
+<!-- English Version: 1.15 -->
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <info><title>建立 CVS 儲存庫(repository) - 使用 FreeBSD 的方式</title>
+
+
+ <author><personname><firstname>Stijn</firstname><surname>Hoop</surname></personname><affiliation>
+ <address><email>stijn@win.tue.nl</email></address>
+ </affiliation></author>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <copyright>
+ <year>2001</year>
+ <year>2002</year>
+ <year>2003</year>
+ <holder role="mailto:stijn@win.tue.nl">Stijn Hoop</holder>
+ </copyright>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <abstract>
+ <para>這份文件描述了使用和 FreeBSD 專案相同的命令稿來建立 CVS 儲存庫的步驟
+ 。這和標準 CVS 建立的儲存庫相較之下有許多優點,包含了更多對於原始碼樹的
+ granular access 控制,以及為每一次的提交產生易讀的電子郵件。</para>
+ </abstract>
+ </info>
+
+ <sect1 xml:id="introduction">
+ <title>簡介</title>
+
+ <para>大多數的開放原始碼軟體專案都使用 <application>CVS</application> 作為
+ 他們的原始碼控制系統。當 <application>CVS</application> 有這樣的優點存在
+ 時,它也有部份的瑕疵和缺點。其中之一的原因是和其他的開發者分享原始碼樹能
+ 夠快速地導致系統管理的惡夢,特別是如果其中一人希望保護部份的原始碼樹免受
+ 於一般的存取。</para>
+
+ <para>FreeBSD 是其中一個使用 <application>CVS</application> 的專案,同時也
+ 是基於它的開發者遍佈於全世界。他們撰寫了一些命令稿使得管理儲存庫變得更加
+ 容易。最近這些命令稿由 &a.joe; 重新整理過且更標準化,使得在其他的專案上再
+ 次使用這些命令稿會更加容易。本文件將描述使用這些新的命令稿的方法。</para>
+
+ <para>為了使本文件中的訊息有用,你需要熟悉 <application>CVS</application>
+ 基本的操作方式。</para>
+ </sect1>
+
+ <sect1 xml:id="first-setup">
+ <title>基本設定</title>
+
+ <warning>
+ <para>最好的方式是在一個全新的儲存庫中執行這些步驟,並確定你了解所有的後
+ 果。同時,請確定你有最新且可讀的資料備份!</para>
+ </warning>
+
+ <sect2>
+ <title>初始化儲存庫</title>
+
+ <para>首先要做的是建立一個新的儲存庫,執行下列命令告訴
+ <application>CVS</application> 建立並初始化:</para>
+
+ <screen>&prompt.user; <userinput>cvs -d path-to-repository init</userinput></screen>
+
+ <para>這命令告訴 <application>CVS</application> 建立
+ <filename>CVSROOT</filename> 的目錄,這個目錄裡放置了所有的組態檔。</para>
+ </sect2>
+
+ <sect2>
+ <title>設定儲存庫的群組</title>
+
+ <para>現在我們將建立一個擁有該儲存庫的群組,所有的開發者必須加入這個群組
+ ,這樣他們才能夠存取該儲存庫。我們假設群組名稱是以 FreeBSD 內定的
+ <literal>ncvs</literal>。</para>
+
+ <screen>&prompt.root; <userinput>pw groupadd ncvs</userinput></screen>
+
+ <para>接者你需要使用 &man.chown.8; 將目錄所有者指定給剛剛新增的群組:</para>
+
+ <screen>&prompt.root; <userinput>chown -R :ncvs path-to-your-repository</userinput></screen>
+
+ <para>如此一來沒有適當的群組許可將沒有其他人可以寫入該儲存庫。</para>
+ </sect2>
+
+ <sect2>
+ <title>取回原始檔案</title>
+
+ <para>現在你需要從 FreeBSD 儲存庫中取回 <filename>CVSROOT</filename> 目錄,
+ 從 FreeBSD 匿名的 CVS 映射站來取回會是最簡單的方法。請查閱 <link xlink:href="&url.books.handbook;/anoncvs.html">在 handbook 中的相關章節</link>來
+ 獲得更多資訊。我們假設取回的檔案存放在相同目錄下的
+ <filename>CVSROOT-freebsd</filename> 目錄中。</para>
+ </sect2>
+
+ <sect2>
+ <title>複製 FreeBSD 的命令稿</title>
+
+ <para>接下來我們要複製 FreeBSD <filename>CVSROOT</filename> 裡的檔案到你
+ 的儲存庫中。如果你是孰悉於 <application>CVS</application>,你也許會想你
+ 可以直接匯入這些命令稿,試圖更容易的同時和更新的版本同步;不過,事實是
+ <application>CVS</application> 在這個部份有缺點:當匯入檔案到
+ <filename>CVSROOT</filename> 時,它並不會更新組態檔。為了要認出這些檔案
+ ,你還需要在匯入它們後一一重新提交,這就失去了
+ <literal>cvs import</literal> 的價值。因此,建議的方法是僅複製這些命令
+ 稿過去。</para>
+
+ <para>若上述內容對你沒有意義是不重要的&mdash;因為最後的結果都是一樣的。
+ 首先匯出你的 <filename>CVSROOT</filename>,然後複製剛剛取回的 FreeBSD
+ 檔案到本地的目錄中(尚未變動過):</para>
+
+ <screen>&prompt.user; <userinput>cvs -d path-to-your-repository checkout CVSROOT</userinput>
+&prompt.user; <userinput>cd CVSROOT</userinput>
+&prompt.user; <userinput>cp ../CVSROOT-freebsd/* .</userinput>
+&prompt.user; <userinput>cvs add *</userinput></screen>
+
+ <para>注意:你很可能會得到一段關於某些目錄沒有被複製的警告,這是正常的,
+ 你並不需要用到這些目錄。</para>
+ </sect2>
+
+ <sect2>
+ <title>命令稿說明</title>
+
+ <para>現在你的工作目錄中有了完整 FreeBSD 專案在它們的儲存庫中使用的命令稿
+ 的複本,以下是每個檔案簡單的介紹。</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>access</filename> - 此檔案在預設的安裝中沒有被用到。
+ 這是使用在<link linkend="freebsdspecific">FreeBSD 的特殊設定</link>中
+ ,用來控制儲存庫的存取。如果你不希望使用這個設定的話你可以刪除這個檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>avail</filename> - 此檔案控制儲存庫的存取。在此檔案中
+ 你可以指定允許存取儲存庫的群組,也可以針對目錄或檔案來拒絕提交。你應該
+ 調整為在你的儲存庫中將包含的群組和目錄。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>cfg.pm</filename> - 此檔案說明了設定內容,並提供預設的設定。
+ 你<emphasis>不</emphasis>該修改此檔案,而該將修改的設定放到
+ <filename>cfg_local.pm</filename>。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>cfg_local.pm</filename> - 此檔案包含所有的系統設定值
+ 。你應該設定所有列在此的設定,例如提交的郵件要寄到哪、在哪些主機上
+ 的使用者可以提交等等。更多的相關資訊在稍後會提到。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>checkoutlist</filename> - 此檔案列出所有在
+ <application>CVS</application> 控制下此目錄中的檔案,除了標準在
+ <literal>cvs init</literal> 建立出的檔案。你可以刪除某些不需要的
+ FreeBSD 特殊的檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>commit_prep.pl</filename> - 此命令稿執行各種提交前的檢查,
+ 基於你是否在 <filename>cfg_local.pm</filename> 中啟用。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>commitcheck</filename> - 此命令稿會直接影響
+ <application>CVS</application>。首先它會使用
+ <filename>cvs_acls.pl</filename> 來檢查提交者是否可以存取指定的原始碼樹,
+ 然後執行 <filename>commit_prep.pl</filename> 來確認各種提交前的檢查。
+ 如果一切正常,<application>CVS</application> 將允許此次提交繼續執行。
+ 你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>commitinfo</filename> - 此檔案是
+ <application>CVS</application> 用來定義在提交前所要執行的程式&mdash;在
+ 此例中是 <filename>commitcheck</filename>。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>config</filename> - 儲存庫的設定選項。你可以修改為你
+ 想要的,但大多數的管理者可能會保留預設值。更多關於可以在此設定的選項
+ 資訊可以查閱 <application>CVS</application> 手冊。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>cvs_acls.pl</filename> - 此命令稿定義提交者的身分,以
+ 及他/她是否允許存取原始碼樹,它是基於 <filename>avail</filename> 中
+ 的設定。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>cvsignore</filename> - 此檔案列出哪些檔案
+ <application>CVS</application> 不用處理到儲存庫中,你可以修改成你想
+ 要的。更多關於可以此檔案的說明可以查閱 <application>CVS</application>
+ 手冊。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>cvswrappers</filename> - 此檔案是
+ <application>CVS</application> 用來啟用或停用關鍵字展開,或者是否檔
+ 案該被視為二進位檔。你可以修改成你想要的。更多關於可以此檔案的說明
+ 可以查閱 <application>CVS</application> 手冊。注意 <literal>-t</literal>
+ 和 <literal>-f</literal> 選項在 <application>CVS</application>
+ client/server 並不能夠正確的運作。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>edithook</filename> - 此檔案已經沒有在使用了,留著只
+ 是為了某些有意義的原因。你可以安全地刪除此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>editinfo</filename> - <application>CVS</application>
+ 使用這個檔案來強迫你使用特定的編輯器。FreeBSD 沒有使用這個功能,因
+ 為輸入日誌訊息已經由 <filename>verifymsg</filename> 和
+ <filename>logcheck</filename> 來完成。這是因為
+ <filename>editinfo</filename> 功能在從遠端提交或是使用
+ <literal>-m</literal> 或 <literal>-F</literal> 選項時不會執行。你不
+ 該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>exclude</filename> - 此檔案列出被
+ <filename>commit_prep.pl</filename> 定義不能包含修正版標頭的檔案。
+ 在 FreeBSD 版本的設定中,所有在修正版控制下的檔案需有一個修正版標頭
+ ,(像是 &dollar;FreeBSD&dollar;)。在此檔案中所有符合一行一個的檔
+ 案名稱將不會被檢查。你可以在此檔案中為不需要修正版標頭的檔案新增一
+ 個正規運算式。為了安裝這些命令稿,最好的方法是排除
+ <filename>CVSROOT/</filename> 會受到標頭的檢查。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>log_accum.pl</filename> - 此命令稿會處理由
+ <filename>logcheck</filename> 所提供的日誌訊息,並且將之為備份目的
+ 附加於儲存庫中的記錄檔案。同時也執行要將郵件寄到你提供的信箱中的程
+ 式(在 <filename>cfg_local.pm</filename> 中)。它和
+ <application>CVS</application> 之間是由 <filename>loginfo</filename>
+ 負責溝通。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>logcheck</filename> - 此檔案分析提交者提供的日誌訊息
+ ,並試圖對其作清理動作。它和 <application>CVS</application> 之間是
+ 由 <filename>verifymsg</filename> 負責溝通。你不該更動此檔案。</para>
+
+ <note><para>此命令稿依附於本地的 FreeBSD <application>CVS</application>
+ 處理:FreeBSD 版本在此命令稿修改過後才讀取日誌訊息;標準的
+ <application>CVS</application> 版本雖然能夠檢查語法上是否正確,但並
+ 不會清理日誌訊息。<application>CVS</application> 1.11.2 可以透過在
+ <filename>config</filename> 設定 <literal>RereadLogAfterVerify=always</literal>
+ 來和 FreeBSD 版本有相同的作用。</para></note>
+ </listitem>
+
+ <listitem>
+ <para><filename>loginfo</filename> - 此檔案是
+ <application>CVS</application> 用來控制日誌訊息要寄到哪裡,而
+ <filename>log_accum.pl</filename> 負責處理。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>modules</filename> - 此檔案保留了
+ <application>CVS</application> 原始的意義。你應該刪除新增的 FreeBSD
+ 模組,並修改為你想要的內容。更多關於可以此檔案的說明可以查閱
+ <application>CVS</application> 手冊。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>notify</filename> - 此檔案為
+ <application>CVS</application> 用來控制監看某個檔案。在 FreeBSD 的
+ 儲存庫中沒有使用到此檔案,你可以修改成你想要的。更多關於可以此檔案
+ 的說明可以查閱 <application>CVS</application> 手冊。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>options</filename> - 此檔案僅限使用於 FreeBSD 和 Debian
+ 的 <application>CVS</application> 版本。它包含了需要在修正版標頭中
+ 展開的關鍵字。你可以修改為符合你指定在 <filename>cfg_local.pm</filename>
+ 的關鍵字。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>rcsinfo</filename> - 此檔案定義提交時儲存庫所要使用的
+ 日誌訊息樣式範本,如 <filename>rcstemplate</filename>。FreeBSD 預設
+ 為所有的儲存庫使用同一個樣式範本,你可以加入其他你想要的。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>rcstemplate</filename> - 此檔案是提交者在提交時會看到
+ 的日誌訊息樣式範本,你應該修改為你定義在 <filename>cfg_local.pm</filename>
+ 的各種參數。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>tagcheck</filename> - 此檔案控制在儲存庫中貼上標籤的
+ 存取。標準的 FreeBSD 版本拒絕名為 RELENG* 的標籤,因為這是 release
+ engineering 的工作。你可以根據需要來修改此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>taginfo</filename> - 此檔案控制執行在儲存庫中貼上標籤
+ 的存取的命令稿,如 <filename>tagcheck</filename>。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>unwrap</filename> - 此命令稿可以用來在匯出時自動<quote>解開</quote>
+ 二進位檔(請見 <filename>cvswrappers</filename>)。現在 FreeBSD 並
+ 沒有使用此設定,因為此功能在遠端提交時並不是執行的非常完善。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>verifymsg</filename> - 此檔案用來執行和日誌訊息相關的
+ 命令稿,如 <filename>logcheck</filename>。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>wrap</filename> - 此命令稿可以用來在提交時自動<quote>包裹</quote>
+ 二進位檔(請見 <filename>cvswrappers</filename>)。現在 FreeBSD 並
+ 沒有使用此設定,因為此功能在遠端提交時並不是執行的非常完善。你不該更動此檔案。</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>自訂命令稿</title>
+
+ <para>接下來的步驟要設定這些命令稿使得它們可以在你的環境中運作。你應該檢
+ 查所有在目錄中的檔案,並修改為符合你的設定。尤其,你會想要修改下列的檔案:</para>
+
+ <procedure>
+ <step>
+ <para>如果你不希望使用<link linkend="freebsdspecific">FreeBSD 的特殊設定</link>,
+ 你可以安全地刪除 <filename>access</filename>:</para>
+
+ <screen>&prompt.user; <userinput>cvs rm -f access</userinput></screen>
+ </step>
+
+ <step>
+ <para>編輯 <filename>avail</filename> 來包含你想控制存取的各種儲存庫
+ 目錄,請確定你有保留 <literal>avail||CVSROOT</literal> 這一行,否則
+ 你將會在下一步把你自己鎖在外面。</para>
+
+ <para>另外你可以在此檔案中新增開發者的群組,FreeBSD 預設使用
+ <filename>access</filename> 來列出所有的開發者,但你可以使用任何你
+ 想要用的檔案。如果你想的話也可以新增群組(請使用指定在
+ <filename>cvs_acls.pl</filename> 上層裡的語法)。</para>
+ </step>
+
+ <step>
+ <para>編輯 <filename>cfg_local.pm</filename> 來包含你需要的選項。尤其
+ 你應該檢視一下下列的設定項目:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>%TEMPLATE_HEADERS</literal> - 這是用來取得日誌訊
+ 息內容的程序,並加入將呈現的郵件項目和提供非空值的訊息。你可
+ 以刪除 <literal>PR</literal> 和 <literal>MFC after</literal>
+ 敘述,當然也可以加入你想要的。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>$MAIL_BRANCH_HDR</literal> - 如果你想要在每一封
+ 提交的郵件中加入描述是在哪一個分支中提交的標頭,那麼請定義為
+ 符合你的設定。如果你不想使用這樣的標頭,那麼請設定為空值。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>@COMMIT_HOSTS</literal> - 定義使用者能夠提交的主機。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>$MAILADDRS</literal> - 設定應該收到提交郵件的郵
+ 件位址。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>@LOG_FILE_MAP</literal> - 以你所需要的來修改這個
+ 陣列,每個設定值應該符合被提交的目錄,而提交的日誌訊息會以
+ <filename>commitlogs</filename> 的名稱儲存在每個被設定的目錄下。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>$COMMITCHECK_EXTRA</literal> - 如果你不想使用
+ <link linkend="freebsdspecific">FreeBSD 特殊的存取控制</link>
+ 功能,你可以在此檔案中刪除對 <literal>$COMMITCHECK_EXTRA</literal>
+ 的定義。</para>
+ </listitem>
+ </itemizedlist>
+
+ <note><para>修改 <literal>$IDHEADER</literal> 的功能只有在 FreeBSD
+ 平台上可以運作,它是相依在 FreeBSD 的特殊 <application>CVS</application>
+ 設定上。</para></note>
+
+ <para>你可以檢查 <filename>cfg.pm</filename> 是否有其他的參數可以修改
+ ,但是修改最好是有原因的。</para>
+ </step>
+
+ <step>
+ <para>刪除 <filename>exclude</filename> 中關於FreeBSD 的特殊設定的敘
+ 述(如以 <literal>^ports/</literal> 為開頭的每一行等)。此外,註解
+ 掉以 <literal>^CVSROOT/</literal> 為開頭的行列,然後新增一行只有
+ <literal>^CVSROOT/</literal>。等到關鍵字展開的命令稿安裝好後,你可
+ 以在 <filename>CVSROOT</filename> 目錄中的檔案裡加上標頭,然後再恢
+ 復剛剛註解的行列,但在你還沒有提交前則只保持這樣。</para>
+ </step>
+
+ <step>
+ <para>編輯 <filename>modules</filename>,並刪除所有 FreeBSD 的群組。
+ 加入你需要的模組。</para>
+ </step>
+
+ <step>
+ <note><para>此步驟只有在你於 <filename>cfg_local.pm</filename> 中指定
+ 了 <literal>$IDHEADER</literal> 才有必要設定(只有在 FreeBSD 的特殊
+ <application>CVS</application> 設定上才能夠執行)。</para></note>
+
+ <para>編輯 <filename>options</filename> 以符合你在
+ <filename>cfg_local.pm</filename> 中設定的標籤名稱。並在所有的檔案
+ 中搜尋 <literal>FreeBSD</literal> 並替換為你設定的標籤名稱。</para>
+ </step>
+
+ <step>
+ <para>修改 <filename>rcstemplate</filename> 為和在
+ <filename>cfg_local.pm</filename> 中相同的設定。</para>
+ </step>
+
+ <step>
+ <para>選擇性的刪除在 <filename>tagcheck</filename> 中針對 FreeBSD 檢
+ 查的設定。你可以僅僅在檔案的最上層加上 <literal>exit 0</literal> 來
+ 取消所有標籤的檢查。</para>
+ </step>
+
+ <step>
+ <para>在你完成前的最後一件事是確認 commitlogs 可以正確儲存。預設會儲
+ 存在儲存庫中的 <filename>commitlogs</filename> 子目錄中,而這個目錄
+ 需要先建立:</para>
+
+ <screen>&prompt.user; <userinput>mkdir commitlogs</userinput>
+&prompt.user; <userinput>cvs add commitlogs</userinput></screen>
+ </step>
+ </procedure>
+
+ <para>現在,在細心的檢視過後,你可以提交你的修改了。確定你先前有在
+ <filename>avail</filename> 中允許你自己存取 <filename>CVSROOT</filename>
+ 目錄,因為如果沒有這樣做的話你會把你自己鎖在外面。完整確認過後請執行下
+ 列命令:</para>
+
+ <screen>&prompt.user; <userinput>cvs commit -m '- Initial FreeBSD scripts commit'</userinput></screen>
+ </sect2>
+
+ <sect2>
+ <title>測試設定</title>
+
+ <para>你已經準備好做基本的測試了:強制提交 <filename>avail</filename>
+ 以確認每件事都如預期的運作。</para>
+
+ <screen>&prompt.user; <userinput>cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' avail</userinput></screen>
+
+ <para>如果一切正常,那麼恭喜了!你現在已經為你的儲存庫建立好 FreeBSD 的命
+ 令稿了。如果 <application>CVS</application> 仍然有警告什麼,回頭檢視上
+ 述的步驟是否有正確的執行。</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="freebsdspecific">
+ <title>FreeBSD 的特殊設定</title>
+
+ <para>FreeBSD 專案自己使用一個有點不同的設定,那就是同時也使用 FreeBSD
+ <filename>CVSROOT</filename> 中的 <filename>freebsd</filename> 子目錄。因
+ 為大量的提交者必須在相同的群組中,因此專案寫了一個簡單的 wrapper 來確認提
+ 交者可以正確的提交,並設定儲存庫的群組名稱。</para>
+
+ <para>如果你的儲存庫也需要這樣的功能,那麼下面就會介紹如何建立,不過首先要
+ 先來看一段複雜的概述。</para>
+
+ <sect2>
+ <title>FreeBSD 設定中使用的檔案</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>access</filename> - 此檔案用來控制儲存庫的存取。你
+ 應該編輯並加入所有在專案中的成員。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>freebsd/commitmail.pl</filename> - 此檔案已經沒有在
+ 使用了,留著只是為了某些有意義的原因。你不該更動此檔案。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>freebsd/cvswrap.c</filename> - 此 CVS wrapper 原始
+ 碼是用來建立檢查所有存取的工作。更多的訊息在稍後會提出。你應該編
+ 輯 <literal>ACCESS</literal> 和 <literal>REALCVS</literal> 的路徑
+ 以符合你的設定。</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>freebsd/mailsend.c</filename> - 此檔案是 FreeBSD 設
+ 定 mailing lists 需要的,你不該更動此檔案。</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>步驟</title>
+
+ <procedure>
+ <step>
+ <para>只有加入你的使用者名稱到 <filename>access</filename> 中。</para>
+ </step>
+
+ <step>
+ <para>編輯 <filename>cvswrap.c</filename> 的路徑以符合你的設定,定義
+ 在大寫的 <literal>ACCESS</literal> 中。同時如果預設值不符合你的情況
+ 的話也應該修改本地實際的 <command>cvs</command> 程式所在位置。原始
+ 的 <filename>cvswrap.c</filename> 希望替代伺服端的 CVS 程式,例如可
+ 能會是 <filename>/usr/bin/ncvs</filename>。</para>
+
+ <para>我的 <filename>cvswrap.c</filename> 是這樣:</para>
+
+ <programlisting>#define ACCESS "/local/cvsroot/CVSROOT/access"
+#define REALCVS "/usr/bin/ncvs"</programlisting>
+ </step>
+
+ <step>
+ <para>接下來是建立 wrapper 來確認你在提交時是在正確的群組中。
+ 在你的 <filename>CVSROOT</filename> 中的
+ <filename>cvswrap.c</filename> 要能夠使用。</para>
+
+ <para>在你完成編輯並加入正確的路徑後我們要來編譯原始碼:</para>
+
+ <screen>&prompt.user; <userinput>cc -o cvs cvswrap.c</userinput></screen>
+
+ <para>然後進行需要設定(此步驟需要 root 權限):</para>
+
+ <screen>&prompt.root; <userinput>mv /usr/bin/cvs /usr/bin/ncvs</userinput>
+&prompt.root; <userinput>mv cvs /usr/bin/cvs</userinput>
+&prompt.root; <userinput>chown root:ncvs /usr/bin/cvs /usr/bin/ncvs</userinput>
+&prompt.root; <userinput>chmod o-rx /usr/bin/ncvs</userinput>
+&prompt.root; <userinput>chmod u-w,g+s /usr/bin/cvs</userinput></screen>
+
+ <para>這會將 wrapper 安裝成預設的 <command>cvs</command> 程式,請確定
+ 任何要使用儲存庫的人應該有正確的存取權限。</para>
+ </step>
+
+ <step>
+ <para>現在你可以刪除所有在儲存庫群組中的使用者,所有的存取控制會經由
+ wrapper 完成,同時 wrapper 會設定存取的正確群組。</para>
+ </step>
+ </procedure>
+ </sect2>
+
+ <sect2>
+ <title>測試設定</title>
+
+ <para>你的 wrapper 現在應該已經安裝好了,你當然也可以強制提交
+ <filename>access</filename> 來測試是否正常:</para>
+
+ <screen>&prompt.user; <userinput>cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' access</userinput></screen>
+
+ <para>同樣地,如果有錯誤,檢查是否上述所有步驟都有正確的執行。</para>
+ </sect2>
+ </sect1>
+</article>
diff --git a/zh_TW.UTF-8/articles/freebsd-questions/Makefile b/zh_TW.UTF-8/articles/freebsd-questions/Makefile
new file mode 100644
index 0000000000..e0524136c2
--- /dev/null
+++ b/zh_TW.UTF-8/articles/freebsd-questions/Makefile
@@ -0,0 +1,22 @@
+#
+# $FreeBSD$
+# Original revision: 1.6
+#
+# Article: How to get best results from the FreeBSD-questions mailing list
+
+MAINTAINER=chinsan.tw@gmail.com
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.xml
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/freebsd-questions/article.xml b/zh_TW.UTF-8/articles/freebsd-questions/article.xml
new file mode 100644
index 0000000000..ad017406e0
--- /dev/null
+++ b/zh_TW.UTF-8/articles/freebsd-questions/article.xml
@@ -0,0 +1,610 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!--
+ Original revision: 1.24
+-->
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <info><title>如何在 FreeBSD-questions mailing list 上得到正解</title>
+
+
+ <author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname><affiliation>
+ <address><email>grog@FreeBSD.org</email></address>
+ </affiliation></author>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.microsoft;
+ &tm-attrib.netscape;
+ &tm-attrib.opengroup;
+ &tm-attrib.qualcomm;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <abstract>
+ <para>本文主要是給準備寫信到 FreeBSD-questions mailing list 的人提供一些參考。
+ 我們會給你一些發問的技巧與建議,以便讓你的答案得到更有用的答覆。</para>
+
+ <para>本文會定期發到 FreeBSD-questions mailing list 上。</para>
+ </abstract>
+ </info>
+
+ <sect1>
+ <title xml:id="Introduction">簡介</title>
+
+ <para><literal>FreeBSD-questions</literal> is a mailing list maintained by
+ the FreeBSD project to help people who have questions about the normal
+ use of FreeBSD. Another group, <literal>FreeBSD-hackers</literal>,
+ discusses more advanced questions such as future development
+ work.</para>
+
+ <note>
+ <para>The term <quote>hacker</quote> has nothing to do with breaking
+ into other people's computers. The correct term for the latter
+ activity is <quote>cracker</quote>, but the popular press has not found
+ out yet. The FreeBSD hackers disapprove strongly of cracking
+ security, and have nothing to do with it. For a longer description of
+ hackers, see Eric Raymond's <link xlink:href="http://www.catb.org/~esr/faqs/hacker-howto.html">How To Become
+ A Hacker</link></para>
+ </note>
+
+ <para>This is a regular posting aimed to help both those seeking advice
+ from FreeBSD-questions (the <quote>newcomers</quote>), and also those
+ who answer the questions (the <quote>hackers</quote>).</para>
+
+ <para>Inevitably there is some friction, which stems from the different
+ viewpoints of the two groups. The newcomers accuse the hackers of being
+ arrogant, stuck-up, and unhelpful, while the hackers accuse the
+ newcomers of being stupid, unable to read plain English, and expecting
+ everything to be handed to them on a silver platter. Of course, there is
+ an element of truth in both these claims, but for the most part these
+ viewpoints come from a sense of frustration.</para>
+
+ <para>In this document, I would like to do something to relieve this
+ frustration and help everybody get better results from
+ FreeBSD-questions. In the following section, I recommend how to submit
+ a question; after that, we will look at how to answer one.</para>
+ </sect1>
+
+ <sect1>
+ <title xml:id="subscribe">How to subscribe to FreeBSD-questions</title>
+
+ <para>FreeBSD-questions is a mailing list, so you need mail access. Point
+ your WWW browser to the <link xlink:href="&a.questions.url;">information page of the FreeBSD-questions mailing list</link>.
+ In the section titled <quote>Subscribing to freebsd-questions</quote> fill
+ in the <quote>Your email address</quote> field; the other fields are optional.
+ </para>
+
+ <note>
+ <para>The password fields in the subscription form provide only mild
+ security, but should prevent others from messing with your
+ subscription. <emphasis>Do not use a valuable password</emphasis> as
+ it will occasionally be emailed back to you in cleartext.</para>
+ </note>
+
+ <para>You will receive a confirmation message from
+ <application>mailman</application>; follow the included instructions
+ to complete your subscription.</para>
+
+ <para>Finally, when you get the <quote>Welcome</quote> message from
+ <application>mailman</application> telling you the details of the list
+ and subscription area password, <emphasis>please save it</emphasis>.
+ If you ever should want to leave the list, you will need the information
+ there. See the next section for more details.</para>
+ </sect1>
+
+ <sect1>
+ <title xml:id="unsubscribe">How to unsubscribe from FreeBSD-questions</title>
+
+ <para>When you subscribed to FreeBSD-questions, you got a welcome message
+ from <application>mailman</application>. In this message, amongst
+ other things, it told you how to unsubscribe. Here is a typical
+ message:</para>
+
+ <literallayout class="monospaced">Welcome to the freebsd-questions@freebsd.org mailing list!
+
+To post to this list, send your email to:
+
+ freebsd-questions@freebsd.org
+
+General information about the mailing list is at:
+
+ http://lists.freebsd.org/mailman/listinfo/freebsd-questions
+
+If you ever want to unsubscribe or change your options (e.g., switch to
+or from digest mode, change your password, etc.), visit your
+subscription page at:
+
+http://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de
+
+You can also make such adjustments via email by sending a message to:
+
+ freebsd-questions-request@freebsd.org
+
+with the word `help' in the subject or body (don't include the
+quotes), and you will get back a message with instructions.
+
+You must know your password to change your options (including changing
+the password, itself) or to unsubscribe. It is:
+
+ 12345
+
+Normally, Mailman will remind you of your freebsd.org mailing list
+passwords once every month, although you can disable this if you
+prefer. This reminder will also include instructions on how to
+unsubscribe or change your account options. There is also a button on
+your options page that will email your current password to you.</literallayout>
+
+ <para>From the URL specified in your <quote>Welcome</quote> message you
+ may visit the <quote>Account management page</quote> and enter a request
+ to <quote>Unsubscribe</quote> you from FreeBSD-questions mailing
+ list.</para>
+
+ <para>A confirmation message will be sent to you from
+ <application>mailman</application>; follow the included instructions
+ to finish unsubscribing.</para>
+
+ <para>If you have done this, and you still can not figure out what
+ is going on, send a message to
+ <email>freebsd-questions-request@FreeBSD.org</email>, and they will
+ sort things out for you. <emphasis>Do not</emphasis> send a message to
+ FreeBSD-questions: they can not help you.</para>
+ </sect1>
+
+ <sect1>
+ <title xml:id="askwho">Should I ask <literal>-questions</literal> or
+ <literal>-hackers</literal>?</title>
+
+ <para>Two mailing lists handle general questions about FreeBSD,
+ <literal>FreeBSD-questions</literal> and
+ <literal>FreeBSD-hackers</literal>. In some cases, it is not really
+ clear which group you should ask. The following criteria should help
+ for 99% of all questions, however:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>If the question is of a general nature, ask
+ <literal>FreeBSD-questions</literal>. Examples might be questions
+ about installing FreeBSD or the use of a particular &unix;
+ utility.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you think the question relates to a bug, but you are not sure,
+ or you do not know how to look for it, send the message to
+ <literal>FreeBSD-questions</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the question relates to a bug, and you are
+ <emphasis>sure</emphasis> that it is a bug (for example, you can
+ pinpoint the place in the code where it happens, and you maybe have
+ a fix), then send the message to
+ <literal>FreeBSD-hackers</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the question relates to enhancements to FreeBSD, and you
+ can make suggestions about how to implement them, then send the
+ message to <literal>FreeBSD-hackers</literal>.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>There are also a number of other specialized mailing lists, for
+ example <literal>FreeBSD-isp</literal>, which caters to the interests of
+ ISPs (Internet Service Providers) who run FreeBSD. If you happen to be
+ an ISP, this does not mean you should automatically send your questions
+ to <literal>FreeBSD-isp</literal>. The criteria above still apply, and
+ it is in your interest to stick to them, since you are more likely to get
+ good results that way.</para>
+ </sect1>
+
+ <sect1>
+ <title xml:id="before">Before submitting a question</title>
+
+ <para>You can (and should) do some things yourself before asking a question
+ on one of the mailing lists:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Try solving the problem on your own. If you post a question which
+ shows that you have tried to solve the problem, your question will
+ generally attract more positive attention from people reading it.
+ Trying to solve the problem yourself will also enhance your understanding
+ of FreeBSD, and will eventually let you use your knowledge to help others
+ by answering questions posted to the mailing lists.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Read the manual pages, and the FreeBSD documentation (either
+ installed in <filename>/usr/doc</filename> or accessible via WWW at
+ <uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>), especially the
+ <link xlink:href="&url.books.handbook;/index.html">handbook</link>
+ and the <link xlink:href="&url.books.faq;/index.html">FAQ</link>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Browse and/or search the archives for the mailing list, to see if your
+ question or a similar one has been asked (and possibly answered) on the
+ list. You can browse and/or search the mailing list archives
+ at <uri xlink:href="http://www.FreeBSD.org/mail">http://www.FreeBSD.org/mail</uri>
+ and <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
+ respectively. This can be done at other WWW sites as well, for example
+ at <uri xlink:href="http://marc.theaimsgroup.com">http://marc.theaimsgroup.com</uri>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Use a search engine such as <link xlink:href="http://www.google.com">Google</link>
+ or <link xlink:href="http://www.yahoo.com">Yahoo</link> to find answers to your question.
+ Google even has a <link xlink:href="http://www.google.com/bsd">BSD-specific search interface</link>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title xml:id="submit">How to submit a question</title>
+
+ <para>When submitting a question to FreeBSD-questions, consider the
+ following points:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Remember that nobody gets paid for answering a FreeBSD
+ question. They do it of their own free will. You can influence this
+ free will positively by submitting a well-formulated question
+ supplying as much relevant information as possible. You can
+ influence this free will negatively by submitting an incomplete,
+ illegible, or rude question. It is perfectly possible to send a
+ message to FreeBSD-questions and not get an answer even if you
+ follow these rules. It is much more possible to not get an answer if
+ you do not. In the rest of this document, we will look at how to get
+ the most out of your question to FreeBSD-questions.</para>
+ </listitem>
+
+ <listitem>
+ <para>Not everybody who answers FreeBSD questions reads every message:
+ they look at the subject line and decide whether it interests them.
+ Clearly, it is in your interest to specify a subject. <quote>FreeBSD
+ problem</quote> or <quote>Help</quote> are not enough. If you provide no subject at
+ all, many people will not bother reading it. If your subject is not
+ specific enough, the people who can answer it may not read
+ it.</para>
+ </listitem>
+
+ <listitem>
+ <para>Format your message so that it is legible, and
+ PLEASE DO NOT SHOUT!!!!!. We appreciate that a lot of people do not
+ speak English as their first language, and we try to make
+ allowances for that, but it is really painful to try to read a
+ message written full of typos or without any line breaks.</para>
+
+ <para>Do not underestimate the effect that a poorly formatted mail
+ message has, not just on the FreeBSD-questions mailing list.
+ Your mail message is all people see of you, and if it is poorly
+ formatted, one line per paragraph, badly spelt, or full of
+ errors, it will give people a poor impression of you.</para>
+
+ <para>A lot of badly formatted messages come from
+ <link xlink:href="http://www.lemis.com/email.html">bad mailers or badly
+ configured mailers</link>. The following mailers are known to
+ send out badly formatted messages without you finding out about
+ them:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>cc:Mail</para>
+ </listitem>
+
+ <listitem>
+ <para>&eudora;</para>
+ </listitem>
+
+ <listitem>
+ <para>exmh</para>
+ </listitem>
+
+ <listitem>
+ <para>&microsoft; Exchange</para>
+ </listitem>
+
+ <listitem>
+ <para>&microsoft; Internet Mail</para>
+ </listitem>
+
+ <listitem>
+ <para>&microsoft; &outlook;</para>
+ </listitem>
+
+ <listitem>
+ <para>&netscape;</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>As you can see, the mailers in the Microsoft world are frequent
+ offenders. If at all possible, use a &unix; mailer. If you must use a
+ mailer under Microsoft environments, make sure it is set up
+ correctly. Try not to use <acronym>MIME</acronym>: a lot of people
+ use mailers which do not get on very well with
+ <acronym>MIME</acronym>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Make sure your time and time zone are set correctly. This may
+ seem a little silly, since your message still gets there, but many
+ of the people you are trying to reach get several hundred messages a
+ day. They frequently sort the incoming messages by subject and by
+ date, and if your message does not come before the first answer, they
+ may assume they missed it and not bother to look.</para>
+ </listitem>
+
+ <listitem>
+ <para>Do not include unrelated questions in the same message. Firstly,
+ a long message tends to scare people off, and secondly, it is more
+ difficult to get all the people who can answer all the questions to
+ read the message.</para>
+ </listitem>
+
+ <listitem>
+ <para>Specify as much information as possible. This is a difficult
+ area, and we need to expand on what information you need to submit,
+ but here is a start:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>In nearly every case, it is important to know the version of
+ FreeBSD you are running. This is particularly the case for
+ FreeBSD-CURRENT, where you should also specify the date of the
+ sources, though of course you should not be sending questions
+ about -CURRENT to FreeBSD-questions.</para>
+ </listitem>
+
+ <listitem><para>With any problem which <emphasis>could</emphasis> be
+ hardware related, tell us about your hardware. In case of
+ doubt, assume it is possible that it is hardware. What kind of
+ CPU are you using? How fast? What motherboard? How much
+ memory? What peripherals?</para>
+
+ <para>There is a judgement call here, of course, but the output of
+ the &man.dmesg.8; command can frequently be very useful, since it
+ tells not just what hardware you are running, but what version of
+ FreeBSD as well.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you get error messages, do not say <quote>I get error
+ messages</quote>, say (for example) <quote>I get the error
+ message 'No route to host'</quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your system panics, do not say <quote>My system
+ panicked</quote>, say (for example) <quote>my system panicked
+ with the message 'free vnode isn't'</quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you have difficulty installing FreeBSD, please tell us
+ what hardware you have. In particular, it is important to know
+ the IRQs and I/O addresses of the boards installed in your
+ machine.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you have difficulty getting PPP to run, describe the
+ configuration. Which version of PPP do you use? What kind of
+ authentication do you have? Do you have a static or dynamic IP
+ address? What kind of messages do you get in the log
+ file?</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>A lot of the information you need to supply is the output of
+ programs, such as &man.dmesg.8;, or console messages, which usually
+ appear in <filename>/var/log/messages</filename>. Do not try to copy
+ this information by typing it in again; it is a real pain, and you are
+ bound to make a mistake. To send log file contents, either make a
+ copy of the file and use an editor to trim the information to what
+ is relevant, or cut and paste into your message. For the output of
+ programs like &man.dmesg.8;, redirect the output to a file and
+ include that. For example,</para>
+
+ <screen>&prompt.user; <userinput>dmesg &gt; /tmp/dmesg.out</userinput></screen>
+
+ <para>This redirects the information to the file
+ <filename>/tmp/dmesg.out</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you do all this, and you still do not get an answer, there
+ could be other reasons. For example, the problem is so complicated
+ that nobody knows the answer, or the person who does know the answer
+ was offline. If you do not get an answer after, say, a week, it
+ might help to re-send the message. If you do not get an answer to
+ your second message, though, you are probably not going to get one
+ from this forum. Resending the same message again and again will
+ only make you unpopular.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To summarize, let's assume you know the answer to the following
+ question (yes, it is the same one in each case).
+ You choose which of these two questions you would be more prepared to
+ answer:</para>
+
+ <example>
+ <title>Message 1</title>
+
+ <literallayout class="monospaced">Subject: HELP!!?!??
+I just can't get hits damn silly FereBSD system to
+workd, and Im really good at this tsuff, but I have never seen
+anythign sho difficult to install, it jst wont work whatever I try
+so why don't you guys tell me what I doing wrong.</literallayout>
+ </example>
+
+ <example>
+ <title>Message 2</title>
+
+ <literallayout class="monospaced">Subject: Problems installing FreeBSD
+
+I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot
+of difficulty installing it. I have a 66 MHz 486 with 16 MB of
+memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball
+disk and a Toshiba 3501XA CDROM drive. The installation works just
+fine, but when I try to reboot the system, I get the message
+<quote>Missing Operating System</quote>.</literallayout>
+ </example>
+ </sect1>
+
+ <sect1>
+ <title xml:id="followup">How to follow up to a question</title>
+
+ <para>Often you will want to send in additional information to a question
+ you have already sent. The best way to do this is to reply to your
+ original message. This has three advantages:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>You include the original message text, so people will know what
+ you are talking about. Do not forget to trim unnecessary text out,
+ though.</para>
+ </listitem>
+
+ <listitem>
+ <para>The text in the subject line stays the same (you did remember to
+ put one in, did you not?). Many mailers will sort messages by
+ subject. This helps group messages together.</para>
+ </listitem>
+
+ <listitem>
+ <para>The message reference numbers in the header will refer to the
+ previous message. Some mailers, such as
+ <link xlink:href="http://www.mutt.org/">mutt</link>, can
+ <emphasis>thread</emphasis> messages, showing the exact
+ relationships between the messages.</para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1>
+ <title xml:id="answer">How to answer a question</title>
+
+
+ <para>Before you answer a question to FreeBSD-questions, consider:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>A lot of the points on submitting questions also apply to
+ answering questions. Read them.</para>
+ </listitem>
+
+ <listitem>
+ <para>Has somebody already answered the question? The easiest way to
+ check this is to sort your incoming mail by subject: then
+ (hopefully) you will see the question followed by any answers, all
+ together.</para>
+
+ <para>If somebody has already answered it, it does not automatically
+ mean that you should not send another answer. But it makes sense to
+ read all the other answers first.</para>
+ </listitem>
+
+ <listitem>
+ <para>Do you have something to contribute beyond what has already been
+ said? In general, <quote>Yeah, me too</quote> answers do not help
+ much, although there are exceptions, like when somebody is
+ describing a problem he is having, and he does not know whether it is
+ his fault or whether there is something wrong with the hardware or
+ software. If you do send a <quote>me too</quote> answer, you should
+ also include any further relevant information.</para>
+ </listitem>
+
+ <listitem>
+ <para>Are you sure you understand the question? Very frequently, the
+ person who asks the question is confused or does not express himself
+ very well. Even with the best understanding of the system, it is
+ easy to send a reply which does not answer the question. This
+ does not help: you will leave the person who submitted the question
+ more frustrated or confused than ever. If nobody else answers, and
+ you are not too sure either, you can always ask for more
+ information.</para>
+ </listitem>
+
+ <listitem>
+ <para>Are you sure your answer is correct?
+ If not, wait a day or so. If nobody else comes up with a
+ better answer, you can still reply and say, for example, <quote>I
+ do not know if this is correct, but since nobody else has
+ replied, why don't you try replacing your ATAPI CDROM with
+ a frog?</quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Unless there is a good reason to do otherwise, reply to the
+ sender and to FreeBSD-questions. Many people on the
+ FreeBSD-questions are <quote>lurkers</quote>: they learn by reading
+ messages sent and replied to by others. If you take a message which
+ is of general interest off the list, you are depriving these people
+ of their information. Be careful with group replies; lots of people
+ send messages with hundreds of CCs. If this is the case, be sure to
+ trim the Cc: lines appropriately.</para>
+ </listitem>
+
+ <listitem>
+ <para>Include relevant text from the original message. Trim it to the
+ minimum, but do not overdo it. It should still be possible for
+ somebody who did not read the original message to understand what
+ you are talking about.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use some technique to identify which text came from the original
+ message, and which text you add. I personally find that prepending
+ <quote><literal>&gt; </literal></quote> to the original message
+ works best. Leaving white space after the
+ <quote><literal>&gt; </literal></quote> and leave empty lines
+ between your text and the original text both make the result more
+ readable.</para>
+ </listitem>
+
+ <listitem>
+ <para>Put your response in the correct place (after the text to which
+ it replies). It is very difficult to read a thread of responses
+ where each reply comes before the text to which it replies.</para>
+ </listitem>
+
+ <listitem>
+ <para>Most mailers change the subject line on a reply by prepending a
+ text such as <quote>Re: </quote>. If your mailer does not do it
+ automatically, you should do it manually.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the submitter did not abide by format conventions (lines too
+ long, inappropriate subject line), <emphasis>please</emphasis> fix
+ it. In the case of an incorrect subject line (such as
+ <quote>HELP!!??</quote>), change the subject line to (say)
+ <quote>Re: Difficulties with sync PPP (was: HELP!!??)</quote>. That
+ way other people trying to follow the thread will have less
+ difficulty following it.</para>
+
+ <para>In such cases, it is appropriate to say what you did and why you
+ did it, but try not to be rude. If you find you can not answer
+ without being rude, do not answer.</para>
+
+ <para>If you just want to reply to a message because of its bad
+ format, just reply to the submitter, not to the list. You can just
+ send him this message in reply, if you like.</para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+</article>
diff --git a/zh_TW.UTF-8/articles/hubs/Makefile b/zh_TW.UTF-8/articles/hubs/Makefile
new file mode 100644
index 0000000000..f04f8a971f
--- /dev/null
+++ b/zh_TW.UTF-8/articles/hubs/Makefile
@@ -0,0 +1,17 @@
+#
+# $FreeBSD$
+#
+# Article: Mirroring FreeBSD
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?=gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.xml
+
+DOC_PREFIX?= ${.CURDIR}/../../..
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/hubs/article.xml b/zh_TW.UTF-8/articles/hubs/article.xml
new file mode 100644
index 0000000000..8e73b481b7
--- /dev/null
+++ b/zh_TW.UTF-8/articles/hubs/article.xml
@@ -0,0 +1,1051 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!-- $FreeBSD$ -->
+<!-- The FreeBSD Documentation Project -->
+<!-- Mirroring FreeBSD -->
+<!-- Translate into Chinese by chinsan.tw@gmail.com -->
+<!-- English Version: 1.62 -->
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <info><title>Mirroring FreeBSD</title>
+
+ <authorgroup>
+ <author><personname><firstname>Jun</firstname><surname>Kuriyama</surname></personname><affiliation>
+ <address><email>kuriyama@FreeBSD.org</email></address>
+ </affiliation></author>
+ <author><personname><firstname>Valentino</firstname><surname>Vaschetto</surname></personname><affiliation>
+ <address><email>logo@FreeBSD.org</email></address>
+ </affiliation></author>
+ <author><personname><firstname>Daniel</firstname><surname>Lang</surname></personname><affiliation>
+ <address><email>dl@leo.org</email></address>
+ </affiliation></author>
+ <author><personname><firstname>Ken</firstname><surname>Smith</surname></personname><affiliation>
+ <address><email>kensmith@FreeBSD.org</email></address>
+ </affiliation></author>
+ </authorgroup>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.cvsup;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <abstract>
+ <para>這是份還在草稿中的文章,主要是(尤其是給各區網中心管理者的參考)介紹如何 mirror FreeBSD。</para>
+ </abstract>
+ </info>
+
+ <sect1 xml:id="mirror-contact">
+ <title>聯繫方式</title>
+
+ <para>若要找整個 Mirror 機制的協調者,可以 email 到 <email>mirror-admin@FreeBSD.org</email>。此外,這裡也有份
+ &a.hubs;。</para>
+ </sect1>
+
+ <sect1 xml:id="mirror-requirements">
+ <title>成為 FreeBSD mirrors 的必備條件</title>
+ <sect2 xml:id="mirror-diskspace">
+ <title>硬碟空間</title>
+ <para>
+ 硬碟空間是最重要的必備條件之一。
+ Depending on the set of releases, architectures,
+ and degree of completeness you want to mirror, a huge
+ amount of disk space may be consumed. Also keep in mind
+ that <emphasis>official</emphasis> mirrors are probably required to be
+ complete. The CVS repository and the web pages should
+ always be mirrored completely. Also note that the
+ numbers stated here are reflecting the current
+ state (at &rel2.current;-RELEASE/&rel.current;-RELEASE). Further development and
+ releases will only increase the required amount.
+ Also make sure to keep some (ca. 10-20%) extra space
+ around just to be sure.
+ Here are some approximate figures:
+ </para>
+ <itemizedlist>
+ <listitem><para>完整 FTP Distribution: 126 GB</para></listitem>
+ <listitem><para>CVS repository: 2.7 GB</para></listitem>
+ <listitem><para>CTM deltas: 1.8 GB</para></listitem>
+ <listitem><para>Web pages: 300 MB</para></listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2 xml:id="mirror-bandwidth">
+ <title>網路頻寬</title>
+ <para>
+ 當然,你一定要能連上 Internet。
+ 頻寬需求多少,這要看你所想要的 mirror 程度而定。
+ 若只想要 mirror 一部份的 FreeBSD 檔案以作為網站或 intranet 的局部用途,
+ 那麼頻寬需求會明顯比成為公共服務用途的小一些。
+ 若想成為 official mirror 之一的話,那麼頻寬就勢必得增加才夠用。以下,我們僅列出一些估計值以做為參考:
+ </para>
+ <itemizedlist>
+ <listitem><para>Local site, no public access: basically no minimum,
+ but &lt; 2 Mbps could make syncing too slow.</para></listitem>
+ <listitem><para>Unofficial public site: 34 Mbps is probably a good start.</para></listitem>
+ <listitem><para>Official site: &gt; 100 Mbps is recommended, and your host
+ should be connected as close as possible to your border router.</para></listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2 xml:id="mirror-system">
+ <title>系統需求、CPU、RAM</title>
+ <para>
+ One thing this depends on the expected number of clients,
+ which is determined by the server's policy. It is
+ also affected by the types of services you want to offer.
+ Plain FTP or HTTP services may not require a huge
+ amount of resources. Watch out if you provide
+ CVSup, rsync or even AnonCVS. This can have a huge
+ impact on CPU and memory requirements. Especially
+ rsync is considered a memory hog, and CVSup does
+ indeed consume some CPU. For AnonCVS it might
+ be a nice idea to set up a memory resident file system (MFS) of at least
+ 300 MB, so you need to take this into account
+ for your memory requirements. The following
+ are just examples to give you a very rough hint.
+ </para>
+ <para>
+ For a moderately visited site that offers
+ <application>Rsync</application>, you might
+ consider a current CPU with around 800MHz - 1 GHz,
+ and at least 512MB RAM. This is probably the
+ minimum you want for an <emphasis>official</emphasis>
+ site.
+ </para>
+ <para>
+ For a frequently used site you definitely need
+ more RAM (consider 2GB as a good start)
+ and possibly more CPU, which could also mean
+ that you need to go for a SMP system.
+ </para>
+ <para>
+ You also want to consider a fast disk subsystem.
+ Operations on the CVS repository require a fast
+ disk subsystem (RAID is highly advised). A SCSI
+ controller that has a cache of its own can also
+ speed up things since most of these services incur a
+ large number of small modifications to the disk.
+ </para>
+ </sect2>
+ <sect2 xml:id="mirror-services">
+ <title>Services to offer</title>
+ <para>
+ Every mirror site is required to have a set of core services
+ available. In addition to these required services, there are
+ a number of optional services that
+ server administrators may choose to offer. This section explains
+ which services you can provide and how to go about implementing them.
+ </para>
+ <sect3 xml:id="mirror-serv-ftp">
+ <title>FTP (required for FTP fileset)</title>
+ <para>
+ This is one of the most basic services, and
+ it is required for each mirror offering public
+ FTP distributions. FTP access must be
+ anonymous, and no upload/download ratios
+ are allowed (a ridiculous thing anyway).
+ Upload capability is not required (and <emphasis>must</emphasis>
+ never be allowed for the FreeBSD file space).
+ Also the FreeBSD archive should be available under
+ the path <filename>/pub/FreeBSD</filename>.
+ </para>
+ <para>
+ There is a lot of software available which
+ can be set up to allow anonymous FTP
+ (in alphabetical order).
+ <itemizedlist>
+ <listitem><para><command>/usr/libexec/ftpd</command>: FreeBSD's own ftpd
+ can be used. Be sure to read &man.ftpd.8;.</para>
+ </listitem>
+ <listitem>
+ <para><package>ftp/ncftpd</package>: A commercial package,
+ free for educational use.</para>
+ </listitem>
+ <listitem>
+ <para><package>ftp/oftpd</package>: An ftpd designed with
+ security as a main focus.</para>
+ </listitem>
+ <listitem>
+ <para><package>ftp/proftpd</package>: A modular and very flexible ftpd.</para>
+ </listitem>
+ <listitem>
+ <para><package>ftp/pure-ftpd</package>: Another ftpd developed with
+ security in mind.</para>
+ </listitem>
+ <listitem><para><package>ftp/twoftpd</package>: As above.</para></listitem>
+ <listitem><para><package>ftp/vsftpd</package>: The <quote>very secure</quote> ftpd.</para></listitem>
+ <listitem>
+ <para><package>ftp/wu-ftpd</package>: The ftpd from Washington
+ University. It has become infamous, because of the huge
+ amount of security issues that have been found in it.
+ If you do choose to use this software be sure to
+ keep it up to date.
+ </para>
+ </listitem>
+ </itemizedlist>
+ FreeBSD's <application>ftpd</application>, <application>proftpd</application>,
+ <application>wu-ftpd</application> and maybe <application>ncftpd</application>
+ are among the most commonly used FTPds.
+ The others do not have a large userbase among mirror sites. One
+ thing to consider is that you may need flexibility in limiting
+ how many simultaneous connections are allowed, thus limiting how
+ much network bandwidth and system resources are consumed.
+ </para>
+ </sect3>
+ <sect3 xml:id="mirror-serv-rsync">
+ <title>Rsync (optional for FTP fileset)</title>
+ <para>
+ <application>Rsync</application> is often offered for access to the
+ contents of the FTP area of FreeBSD, so other mirror sites can use your system as their source. The
+ protocol is different from FTP in many ways.
+ It is much more
+ bandwidth friendly, as only differences between files
+ are transferred instead of whole files when they change.
+ <application>Rsync</application> does require a significant amount of memory for
+ each instance. The size depends on the size of
+ the synced module in terms of the number of directories and
+ files. <application>Rsync</application> can use <command>rsh</command> and
+ <command>ssh</command> (now default) as a transport,
+ or use its own protocol for stand-alone access
+ (this is the preferred method for public rsync servers).
+ Authentication, connection limits, and other restrictions
+ may be applied. There is just one software package
+ available:
+ <itemizedlist>
+ <listitem><para><package>net/rsync</package></para></listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+ <sect3 xml:id="mirror-serv-http">
+ <title>HTTP (required for web pages, optional for FTP fileset)</title>
+ <para>
+ If you want to offer the FreeBSD web pages, you will need
+ to install a web server.
+ You may optionally offer the FTP fileset via HTTP.
+ The choice of web server software is left up to the mirror administrator.
+ Some of the most popular choices are:
+
+ <itemizedlist>
+ <listitem>
+ <para><package>www/apache13</package>:
+ <application>Apache</application> is the most widely
+ deployed web server on the Internet. It is used
+ extensively by the FreeBSD Project. You may also wish to
+ use the next generation of the
+ <application>Apache</application> web server, available
+ in the ports collection as <package>www/apache22</package>.</para>
+ </listitem>
+
+ <listitem>
+ <para><package>www/thttpd</package>:
+ If you are going to be serving a large amount of static content
+ you may find that using an application such as thttpd is more
+ efficient than <application>Apache</application>. It is
+ optimized for excellent performance on FreeBSD.</para>
+ </listitem>
+
+ <listitem>
+ <para><package>www/boa</package>:
+ <application>Boa</application> is another alternative to
+ <application>thttpd</application> and
+ <application>Apache</application>. It should provide
+ considerably better performance than
+ <application>Apache</application> for purely static
+ content. It does not, at the time of this writing,
+ contain the same set of optimizations for FreeBSD that
+ are found in <application>thttpd</application>.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+ <sect3 xml:id="mirror-serv-cvsup">
+ <title>CVSup (desired for CVS repository)</title>
+ <para>
+ <application>CVSup</application> is a very efficient way of distributing files.
+ It works similar to <application>rsync</application>, but was specially designed for
+ use with CVS repositories. If you want to offer the
+ FreeBSD CVS repository, you really want to consider
+ offering it via <application>CVSup</application>. It is possible to offer
+ the CVS repository via <application>AnonCVS</application>, FTP,
+ <application>rsync</application> or HTTP, but
+ people would benefit much more from <application>CVSup</application> access.
+ <application>CVSup</application> was developed by &a.jdp;.
+ It is a bit tricky to install on non-FreeBSD platforms,
+ since it is written in Modula-3 and therefore requires
+ a Modula-3 environment. John Polstra has built a
+ stripped down version of M3 that is sufficient to
+ run <application>CVSup</application>, and can be installed much easier.
+ See <link xlink:href="http://www.polstra.com/projects/freeware/ezm3/">Ezm3</link>
+ for details. Related ports are:
+
+ <itemizedlist>
+ <listitem>
+ <para><package>net/cvsup</package>: The native CVSup port (client and server)
+ which requires <package>lang/ezm3</package> now.</para>
+ </listitem>
+ <listitem>
+ <para><package>net/cvsup-mirror</package>: The CVSup mirror kit, which requires
+ <package>net/cvsup-without-gui</package>, and configures it mirror-ready. Some
+ site administrators may want a different setup though.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ There are a few more like
+ <package>net/cvsup-without-gui</package> you might want to have
+ a look at. If you prefer a static binary package, take a look
+ <link xlink:href="http://people.FreeBSD.org/~jdp/s1g/">here</link>.
+ This page still refers to the S1G bug that was present
+ in <application>CVSup</application>. Maybe
+ John will set up a generic download-site to get
+ static binaries for various platforms.
+ </para>
+ <para>
+ It is possible to use <application>CVSup</application> to offer
+ any kind of fileset, not just CVS repositories,
+ but configuration can be complex.
+ <application>CVSup</application> is known to eat some CPU on both the server and the
+ client, since it needs to compare lots of files.
+ </para>
+ </sect3>
+ <sect3 xml:id="mirror-anoncvs">
+ <title>AnonCVS (optional for CVS repository)</title>
+ <para>
+ If you have the CVS repository, you may want to offer
+ anonymous CVS access. A short warning first:
+ There is not much demand for it,
+ it requires some experience, and you need to know
+ what you are doing.
+ </para>
+ <para>
+ Generally there are two ways
+ to access a CVS repository remotely: via
+ <emphasis>pserver</emphasis> or via <command>ssh</command>
+ (we do not consider <command>rsh</command>).
+ For anonymous access, <emphasis>pserver</emphasis> is
+ very well suited, but some still offer <command>ssh</command>
+ access as well. There is a custom crafted
+ <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/FreeBSD-CVS/anoncvs.shar">wrapper</link>
+ in the CVS repository, to be used as a login-shell for the
+ anonymous ssh account. It does a chroot, and therefore
+ requires the CVS repository to be available under the
+ anonymous user's home-directory. This may not be possible
+ for all sites. If you just offer <emphasis>pserver</emphasis>
+ this restriction does not apply, but you may run with
+ more security risks. You do not need to install any special
+ software, since &man.cvs.1; comes with
+ FreeBSD. You need to enable access via <command>inetd</command>,
+ so add an entry into your <filename>/etc/inetd.conf</filename>
+ like this:
+ <programlisting>
+cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --allow-root=/home/ncvs pserver
+ </programlisting>
+ See the manpage for details of the options. Also see the CVS <emphasis>info</emphasis>
+ page about additional ways to make sure access is read-only.
+ It is advised that you create an unprivileged account,
+ preferably called <systemitem class="username">anoncvs</systemitem>.
+ Also you need to create a file <filename>passwd</filename>
+ in your <filename>/home/ncvs/CVSROOT</filename> and assign a
+ CVS password (empty or <literal>anoncvs</literal>) to that user.
+ The directory <filename>/anoncvstmp</filename> is a special
+ purpose memory based file system. It is not required but
+ advised since &man.cvs.1; creates a shadow directory
+ structure in your <filename>/tmp</filename> which is
+ not used after the operation but slows things
+ dramatically if real disk operations are required.
+ Here is an excerpt from <filename>/etc/fstab</filename>,
+ how to set up such a MFS:
+ <programlisting>
+/dev/da0s1b /anoncvstmp mfs rw,-s=786432,-b=4096,-f=512,-i=560,-c=3,-m=0,nosuid,nodev 0 0
+ </programlisting>
+ This is (of course) tuned a lot, and was suggested by &a.jdp;.
+ </para>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 xml:id="mirror-howto">
+ <title>How to Mirror FreeBSD</title>
+ <para>
+ Ok, now you know the requirements and how to offer
+ the services, but not how to get it. :-)
+ This section explains how to actually mirror
+ the various parts of FreeBSD, what tools to use,
+ and where to mirror from.
+ </para>
+ <sect2 xml:id="mirror-ftp">
+ <title>FTP</title>
+ <para>
+ The FTP area is the largest amount of data that
+ needs to be mirrored. It includes the <emphasis>distribution
+ sets</emphasis> required for network installation, the
+ <emphasis>branches</emphasis> which are actually snapshots
+ of checked-out source trees, the <emphasis>ISO Images</emphasis>
+ to write CD-ROMs with the installation distribution,
+ a live file system, lots of packages, the ports tree,
+ distfiles, and a huge amount of packages. All of course
+ for various FreeBSD versions,
+ and various architectures.
+ </para>
+ <sect3 xml:id="mirror-ftp-ftp">
+ <title>With FTP mirror</title>
+ <para>
+ You can use a <application>FTP mirror</application>
+ program to get the files. Some of the most commonly used are:
+ <itemizedlist>
+ <listitem><para><package>ftp/mirror</package></para></listitem>
+ <listitem><para><package>ftp/ftpmirror</package></para></listitem>
+ <listitem><para><package>ftp/emirror</package></para></listitem>
+ <listitem><para><package>ftp/spegla</package></para></listitem>
+ <listitem><para><package>ftp/omi</package></para></listitem>
+ <listitem><para><package>ftp/wget</package></para></listitem>
+ </itemizedlist>
+
+ <package>ftp/mirror</package> was very popular, but seemed
+ to have some drawbacks, as it is written in &man.perl.1;,
+ and had real problems with mirroring large
+ directories like a FreeBSD site. There are rumors that
+ the current version has fixed this by allowing
+ a different algorithm for comparing
+ the directory structure to be specified.
+ </para>
+ <para>
+ In general FTP is not really good for mirroring. It transfers
+ the whole file if it has changed, and does
+ not create a single data stream which would benefit from
+ a large TCP congestion window.
+ </para>
+ </sect3>
+ <sect3 xml:id="mirror-ftp-rsync">
+ <title>With rsync</title>
+ <para>
+ A better way to mirror the FTP area is <application>rsync</application>.
+ You can install the port <package>net/rsync</package> and then use
+ rsync to sync with your upstream host.
+ <application>rsync</application> is already mentioned
+ in <xref linkend="mirror-serv-rsync"/>.
+ Since <application>rsync</application> access is not
+ required, your preferred upstream site may not allow it.
+ You may need to hunt around a little bit to find a site
+ that allows <application>rsync</application> access.
+ <note>
+ <para>
+ Since the number of <application>rsync</application>
+ clients will have a significant impact on the server
+ machine, most admins impose limitations on their
+ server. For a mirror, you should ask the site maintainer
+ you are syncing from about their policy, and maybe
+ an exception for your host (since you are a mirror).
+ </para>
+ </note>
+ A command line to mirror FreeBSD might look like:
+ <screen>&prompt.user; <userinput>rsync -vaz --delete ftp4.de.FreeBSD.org::FreeBSD/ /pub/FreeBSD/</userinput>
+ </screen>
+ Consult the documentation for <application>rsync</application>,
+ which is also available at
+ <link xlink:href="http://rsync.samba.org/">http://rsync.samba.org/</link>,
+ about the various options to be used with rsync.
+ If you sync the whole module (unlike subdirectories),
+ be aware that the module-directory (here "FreeBSD")
+ will not be created, so you cannot omit the target directory.
+ Also you might
+ want to set up a script framework that calls such a command
+ via &man.cron.8;.
+ </para>
+ </sect3>
+ <sect3 xml:id="mirror-ftp-cvsup">
+ <title>With CVSup</title>
+ <para>
+ A few sites, including the one-and-only <systemitem class="fqdomainname">ftp-master.FreeBSD.org</systemitem>
+ even offer <application>CVSup</application> to mirror the contents of
+ the FTP space. You need to install a <application>CVSup</application>
+ client, preferably from the port <package>net/cvsup</package>.
+ (Also reread <xref linkend="mirror-serv-cvsup"/>.)
+ A sample <filename>supfile</filename> suitable for <systemitem class="fqdomainname">ftp-master.FreeBSD.org</systemitem>
+ looks like this:
+ <programlisting>
+ #
+ # FreeBSD archive supfile from master server
+ #
+ *default host=ftp-master.FreeBSD.org
+ *default base=/usr
+ *default prefix=/pub
+ #*default release=all
+ *default delete use-rel-suffix
+ *default umask=002
+
+ # If your network link is a T1 or faster, comment out the following line.
+ #*default compress
+
+ FreeBSD-archive release=all preserve
+ </programlisting>
+
+ It seems <application>CVSup</application> would be the best
+ way to mirror the archive in terms of efficiency, but
+ it is only available from few sites.
+ <note xml:id="mirror-cvsup-s-option">
+ <para>
+ Please have look at the <application>CVSup</application> documentation
+ like &man.cvsup.1; and consider using the <option>-s</option>
+ option. This reduces I/O operations by assuming the
+ recorded information about each file is correct.</para>
+ </note>
+ </para>
+ </sect3>
+ </sect2>
+ <sect2 xml:id="mirror-cvs">
+ <title>Mirroring the CVS repository</title>
+ <para>There are various ways to mirror the CVS repository.
+ <application>CVSup</application> is the most common method.</para>
+
+ <sect3 xml:id="mirror-cvs-cvsup">
+ <title>Using CVSup</title>
+ <para>
+ <application>CVSup</application> is described in some
+ detail in <xref linkend="mirror-serv-cvsup"/> and <xref linkend="mirror-ftp-cvsup"/>.
+ </para>
+ <para>It is very easy to setup a
+ <application>CVSup</application> mirror. Installing
+ <package>net/cvsup-mirror</package> will
+ make sure all of the needed programs are installed and then
+ gather all the needed information to configure the mirror.</para>
+ <note>
+ <para>
+ Please do not forget to consider the hint
+ mentioned in <link linkend="mirror-cvsup-s-option">this note</link>
+ above.
+ </para>
+ </note>
+ </sect3>
+ <sect3 xml:id="mirror-cvs-other">
+ <title>Using other methods</title>
+ <para>
+ Using other methods than <application>CVSup</application> is
+ generally not recommended. We describe them in short here
+ anyway. Since most sites offer the CVS repository as
+ part of the FTP fileset under the path
+ <filename>/pub/FreeBSD/development/FreeBSD-CVS</filename>,
+ the following methods could be used.
+ <itemizedlist>
+ <listitem><para><application>FTP</application></para></listitem>
+ <listitem><para><application>Rsync</application></para></listitem>
+ <listitem><para><application>HTTP</application></para></listitem>
+ </itemizedlist>
+
+ <important>
+ <para>AnonCVS cannot be used to mirror the CVS repository
+ since CVS does not allow you to access the repository
+ itself, only checked out versions of the modules.</para>
+ </important>
+ </para>
+ </sect3>
+ </sect2>
+ <sect2 xml:id="mirror-www">
+ <title>Mirroring the WWW pages</title>
+ <para>
+ The best way is to check out the <emphasis>www</emphasis>
+ distribution from CVS. If you have a local mirror of the
+ CVS repository, it is as easy as:
+ <screen>&prompt.user; <userinput>cvs -d /home/ncvs co www</userinput></screen>
+ and a <emphasis>cronjob</emphasis>, that calls <command>cvs up -d -P</command>
+ on a regular basis, maybe just after your repository was updated.
+ Of course, the files need to remain in a directory available
+ for public WWW access. The installation and configuration of a
+ web server is not discussed here.
+ </para>
+
+ <para>
+ If you do not have a local repository, you can use
+ <application>CVSup</application> to maintain an <quote>up to date copy</quote>
+ of the www pages. A sample supfile can be found in
+ <filename>/usr/share/examples/cvsup/www-supfile</filename> and
+ could look like this:
+ <programlisting>
+ #
+ # WWW module supfile for FreeBSD
+ #
+ *default host=cvsup3.de.FreeBSD.org
+ *default base=/usr
+ *default prefix=/usr/local
+ *default release=cvs tag=.
+ *default delete use-rel-suffix
+
+ # If your network link is a T1 or faster, comment out the following line.
+ *default compress
+
+ # This collection retrieves the www/ tree of the FreeBSD repository
+ www
+ </programlisting>
+ </para>
+ <para>
+ Using <package>ftp/wget</package> or other web-mirror tools is
+ not recommended.
+ </para>
+ <sect3 xml:id="mirror-www-doc">
+ <title>Mirroring the FreeBSD documentation</title>
+ <para>
+ Since the documentation is referenced a lot from the
+ web pages, it is recommended that you mirror the
+ FreeBSD documentation as well. However, this is not
+ as trivial as the www-pages alone.
+ </para>
+ <para>
+ First of all, you should get the doc sources,
+ again preferably via <application>CVSup</application>.
+ Here is a corresponding sample supfile:
+ <programlisting>
+ #
+ # FreeBSD documentation supfile
+ #
+ *default host=cvsup3.de.FreeBSD.org
+ *default base=/usr
+ *default prefix=/usr/share
+ *default release=cvs tag=.
+ *default delete use-rel-suffix
+
+ # If your network link is a T1 or faster, comment out the following line.
+ #*default compress
+
+ # This will retrieve the entire doc branch of the FreeBSD repository.
+ # This includes the handbook, FAQ, and translations thereof.
+ doc-all
+ </programlisting>
+ </para>
+ <para>
+ Then you need to install a couple of ports.
+ You are lucky, there is a meta-port:
+ <package>textproc/docproj</package> to do the work
+ for you. You need to set up some
+ environment variables, like
+ <literal>SGML_CATALOG_FILES</literal>.
+ Also have a look at your <filename>/etc/make.conf</filename>
+ (copy <filename>/usr/share/examples/etc/make.conf</filename> if
+ you do not have one), and look at the
+ <literal>DOC_LANG</literal> variable.
+ Now you are probably ready to run <command>make</command>
+ in your doc directory (<filename>/usr/share/doc</filename>
+ by default) and build the documentation.
+ Again you need to make it accessible for your web server
+ and make sure the links point to the right location.
+ <important>
+ <para>
+ The building of the documentation, as well as lots
+ of side issues, is documented itself in the
+ <link xlink:href="&url.books.fdp-primer;">&os; Documentation
+ Project Primer</link>.
+ Please read this piece of documentation, especially if you
+ have problems building the documentation.
+ </para>
+ </important>
+ </para>
+ </sect3>
+ </sect2>
+ <sect2 xml:id="mirror-how-often">
+ <title>How often should I mirror?</title>
+ <para>
+ Every mirror should be updated on a regular
+ basis. You will certainly need some script
+ framework for it that will be called by
+ &man.cron.8;. Since nearly every admin
+ does this his own way, we cannot give
+ specific instructions. It could work
+ like this:
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Put the command to run your mirroring application
+ in a script. Use of a plain <command>/bin/sh</command>
+ script is recommended.
+ </para>
+ </step>
+ <step>
+ <para>
+ Add some output redirections so diagnostic
+ messages are logged to a file.
+ </para>
+ </step>
+ <step>
+ <para>
+ Test if your script works. Check the logs.
+ </para>
+ </step>
+ <step>
+ <para>
+ Use &man.crontab.1; to add the script to the
+ appropriate user's &man.crontab.5;. This should be a
+ different user than what your FTP daemon runs as so that
+ if file permissions inside your FTP area are not
+ world-readable those files can not be accessed by anonymous
+ FTP. This is used to <quote>stage</quote> releases &mdash;
+ making sure all of the official mirror sites have all of the
+ necessary release files on release day.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ Here are some recommended schedules:
+ <itemizedlist>
+ <listitem><para>FTP fileset: daily</para></listitem>
+ <listitem><para>CVS repository: hourly</para></listitem>
+ <listitem><para>WWW pages: daily</para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 xml:id="mirror-where">
+ <title>Where to mirror from</title>
+ <para>
+ This is an important issue. So this section will
+ spend some effort to explain the backgrounds. We will say this
+ several times: under no circumstances should you mirror from
+ <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>.
+ </para>
+ <sect2 xml:id="mirror-where-organization">
+ <title>A few words about the organization</title>
+ <para>
+ Mirrors are organized by country. All
+ official mirrors have a DNS entry of the form
+ <systemitem class="fqdomainname">ftpN.CC.FreeBSD.org</systemitem>.
+ <emphasis>CC</emphasis> (i.e. country code) is the
+ <emphasis>top level domain</emphasis> (TLD)
+ of the country where this mirror is located.
+ <emphasis>N</emphasis> is a number,
+ telling that the host would be the <emphasis>Nth</emphasis>
+ mirror in that country.
+ (Same applies to <systemitem>cvsupN.CC.FreeBSD.org</systemitem>,
+ <systemitem>wwwN.CC.FreeBSD.org</systemitem>, etc.)
+ There are mirrors with no <emphasis>CC</emphasis> part.
+ These are the mirror sites that are very well connected and
+ allow a large number of concurrent users.
+ <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> is actually two machines, one currently
+ located in Denmark and the other in the United States.
+ It is <emphasis>NOT</emphasis> a master site and should never be
+ used to mirror from. Lots of online documentation leads
+ <quote>interactive</quote>users to
+ <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> so automated mirroring
+ systems should find a different machine to mirror from.
+ </para>
+ <para>
+ Additionally there exists a hierarchy of mirrors, which
+ is described in terms of <emphasis>tiers</emphasis>.
+ The master sites are not referred to but can be
+ described as <emphasis>Tier-0</emphasis>. Mirrors
+ that mirror from these sites can be considered
+ <emphasis>Tier-1</emphasis>, mirrors of <emphasis>Tier-1</emphasis>-mirrors,
+ are <emphasis>Tier-2</emphasis>, etc.
+ Official sites are encouraged to be of a low <emphasis>tier</emphasis>,
+ but the lower the tier the higher the requirements in
+ terms as described in <xref linkend="mirror-requirements"/>.
+ Also access to low-tier-mirrors may be restricted, and
+ access to master sites is definitely restricted.
+ The <emphasis>tier</emphasis>-hierarchy is not reflected
+ by DNS and generally not documented anywhere except
+ for the master sites. However, official mirrors with low numbers
+ like 1-4, are usually <emphasis>Tier-1</emphasis>
+ (this is just a rough hint, and there is no rule).
+ </para>
+ </sect2>
+ <sect2 xml:id="mirror-where-where">
+ <title>Ok, but where should I get the stuff now?</title>
+ <para>
+ Under no circumstances should you mirror from <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>.
+ The short answer is: from the
+ site that is closest to you in Internet terms, or gives you
+ the fastest access.
+ </para>
+ <sect3 xml:id="mirror-where-simple">
+ <title>I just want to mirror from somewhere!</title>
+ <para>
+ If you have no special intentions or
+ requirements, the statement in <xref linkend="mirror-where-where"/>
+ applies. This means:
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Look at available mirrors in your country.
+ The <link xlink:href="http://mirrorlist.FreeBSD.org/">FreeBSD
+ Mirror Database</link> can help you with this.
+ </para>
+ </step>
+ <step>
+ <para>
+ Check for those which provide fastest access
+ (number of hops, round-trip-times)
+ and offer the services you intend to
+ use (like <application>rsync</application>
+ or <application>CVSup</application>).
+ </para>
+ </step>
+ <step>
+ <para>
+ Contact the administrators of your chosen site stating your
+ request, and asking about their terms and
+ policies.
+ </para>
+ </step>
+ <step>
+ <para>
+ Set up your mirror as described above.
+ </para>
+ </step>
+ </procedure>
+ </sect3>
+ <sect3 xml:id="mirror-where-official">
+ <title>I am an official mirror, what is the right site for me?</title>
+ <para>
+ In general the description in <xref linkend="mirror-where-simple"/>
+ still applies. Of course you may want to put some
+ weight on the fact that your upstream should be of
+ a low tier.
+ There are some other considerations about <emphasis>official</emphasis>
+ mirrors that are described in <xref linkend="mirror-official"/>.
+ </para>
+ </sect3>
+ <sect3 xml:id="mirror-where-master">
+ <title>I want to access the master sites!</title>
+ <para>
+ If you have good reasons and good prerequisites,
+ you may want and get access to one of the
+ master sites. Access to these sites is
+ generally restricted, and there are special policies
+ for access. If you are already an <emphasis>official</emphasis>
+ mirror, this certainly helps you getting access.
+ In any other case make sure your country really needs another mirror.
+ If it already has three or more, ask the <quote>zone administrator</quote> (<email>hostmaster@CC.FreeBSD.org</email>) or &a.hubs; first.</para>
+
+ <para>
+ Whoever helped you become, an <emphasis>official</emphasis>
+ should have helped you gain access to an appropriate upstream
+ host, either one of the master sites or a suitable Tier-1
+ site. If not, you can send email to
+ <email>mirror-admin@FreeBSD.org</email> to request help with
+ that.
+ </para>
+ <para>
+ There are three master sites for the FTP fileset and
+ one for the CVS repository (the web pages and docs are
+ obtained from CVS, so there is no need for master).
+ </para>
+ <sect4 xml:id="mirror-where-master-ftp">
+ <title>ftp-master.FreeBSD.org</title>
+ <para>
+ This is the master site for the FTP fileset.
+ </para>
+ <para>
+ <systemitem>ftp-master.FreeBSD.org</systemitem> provides
+ <application>rsync</application> and <application>CVSup</application>
+ access, in addition to FTP.
+ Refer to <xref linkend="mirror-ftp-rsync"/> and
+ <xref linkend="mirror-ftp-cvsup"/> how to access
+ via these protocols.
+ </para>
+ <para>
+ Mirrors are also encouraged to allow <application>rsync</application>
+ access for the FTP contents, since they are
+ <emphasis>Tier-1</emphasis>-mirrors.
+ </para>
+ </sect4>
+ <sect4 xml:id="mirror-where-master-cvsup">
+ <title>cvsup-master.FreeBSD.org</title>
+ <para>
+ This is the master site for the CVS repository.
+ </para>
+ <para>
+ <systemitem>cvsup-master.FreeBSD.org</systemitem> provides
+ <application>CVSup</application> access only.
+ See <xref linkend="mirror-cvs-cvsup"/> for details.
+ </para>
+ <para>
+ To get access, you need to contact the &a.cvsup-master;.
+ Make sure you read the
+ <link xlink:href="http://people.FreeBSD.org/~jdp/cvsup-access/">FreeBSD CVSup Access Policy</link>
+ first!
+ </para>
+ <para>
+ Set up the required authentication by following
+ <link xlink:href="http://people.FreeBSD.org/~jdp/cvpasswd/">these
+ instructions</link>. Make sure you specify the server as
+ <systemitem>freefall.FreeBSD.org</systemitem> on the <command>cvpasswd</command>
+ command line, as described in this document,
+ even when you are contacting
+ <systemitem>cvsup-master.FreeBSD.org</systemitem>
+ </para>
+ </sect4>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 xml:id="mirror-official">
+ <title>Official Mirrors</title>
+ <para>
+ Official mirrors 站為具有下列條件的 mirror 站
+ <itemizedlist>
+ <listitem>
+ <para>
+ a) 有 <systemitem>FreeBSD.org</systemitem> DNS entry
+ (通常為 CNAME 紀錄)。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ b) 被 FreeBSD 文件列為 offical mirror 站(像是 handbook)。
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ 除了以上述方式來分辨是否為 official mirrors 站之外,
+ Official mirrors 站不一定得為 <emphasis>Tier-1</emphasis>-mirrors 站。
+ 然而,只要是 <emphasis>Tier-1</emphasis>-mirror 站的話,就一定會是
+ official mirrors 站。
+ </para>
+ <sect2 xml:id="mirror-official-requirements">
+ <title>Special Requirements for official (tier-1) mirrors</title>
+ <para>
+ It is not so easy to state requirements for all
+ official mirrors, since the project is sort of
+ tolerant here. It is more easy to say,
+ what <emphasis>official tier-1 mirrors</emphasis>
+ are required to. All other official mirrors
+ can consider this a big <emphasis>should</emphasis>.
+ <note>
+ <para>
+ The following applies mainly to the FTP fileset,
+ since a CVS repository should always be mirrored
+ completely, and the web pages are a case of
+ its own.
+ </para>
+ </note>
+ </para>
+ <para>
+ Tier-1 mirrors are required to:
+ <itemizedlist>
+ <listitem><para>carry the complete fileset</para></listitem>
+ <listitem><para>allow access to other mirror sites</para></listitem>
+ <listitem><para>provide <application>FTP</application> and
+ <application>rsync</application> access</para></listitem>
+ </itemizedlist>
+
+ Furthermore, admins should be subscribed to the &a.hubs;.
+ See <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">this link</link> for details, how to subscribe.
+ </para>
+ <important>
+ <para>It is <emphasis>very</emphasis> important for a hub administrator, especially
+ Tier-1 hub admins, to check the
+ <link xlink:href="http://www.FreeBSD.org/releng/">release schedule</link>
+ for the next FreeBSD release. This is important because it will tell you when the
+ next release is scheduled
+ to come out, and thus giving you time to prepare for the big spike of traffic which follows it.
+ </para>
+ <para>
+ It is also important that hub administrators try to keep their mirrors as up-to-date as
+ possible (again, even more crucial for Tier-1 mirrors). If Mirror1 does not update for a
+ while, lower tier mirrors will begin to mirror old data from Mirror1 and thus begins
+ a downward spiral... Keep your mirrors up to date!
+ </para>
+ </important>
+ </sect2>
+ <sect2 xml:id="mirror-official-become">
+ <title>How to become official then?</title>
+ <para>
+ An interesting question, especially, since the state
+ of being official comes with some benefits, like a much
+ higher bill from your ISP as more people will be using
+ your site. Also it may be a key requirement to get access
+ to a master site.
+ </para>
+ <para>
+ Before applying, please consider (again) if
+ another official mirror is really needed for
+ your region. Check first with your zone administrator (<email>hostmaster@CC.FreeBSD.org</email>) or, if that fails, ask on the &a.hubs;.
+ </para>
+ <para>Ok, here is how to do it:</para>
+ <procedure>
+ <step>
+ <para>
+ Get the mirror running in first place (maybe not
+ using a master site, yet).
+ </para>
+ </step>
+ <step>
+ <para>
+ <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">Subscribe</link> to the &a.hubs;.
+ </para>
+ </step>
+ <step>
+ <para>
+ If everything works so far, contact the DNS administrator responsible
+ for your region/country, and ask for a DNS entry for your
+ site. The admin should able to be contacted via
+ <email>hostmaster@CC.FreeBSD.org</email>, where
+ <emphasis>CC</emphasis> is your country code/TLD.
+ Your DNS entry will be as described
+ in <xref linkend="mirror-where-organization"/>.
+ </para>
+ <para>
+ If there is no subdomain set up for your
+ country yet, you should contact
+ <email>mirror-admin@FreeBSD.org</email>,
+ or you can try the &a.hubs; first.
+ </para>
+ </step>
+ <step>
+ <para>
+ Whoever helps you get an official name should send email
+ to <email>mirror-admin@FreeBSD.org</email> so your site will be
+ added to the mirror list in the
+ <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook">FreeBSD
+ Handbook</link>.
+ </para>
+ </step>
+ </procedure>
+ <para>That is it.</para>
+ </sect2>
+ </sect1>
+ <sect1 xml:id="mirror-statpages">
+ <title>Some statistics from mirror sites</title>
+ <para>
+ Here are links to the stat pages of your favorite mirrors
+ (a.k.a. the only ones who feel like providing stats).
+ </para>
+ <sect2 xml:id="mirror-statpagesftp">
+ <title>FTP site statistics</title>
+ <itemizedlist>
+ <listitem>
+ <para>ftp.is.FreeBSD.org - <email>hostmaster@is.FreeBSD.org</email> -
+ <link xlink:href="http://www.rhnet.is/status/draupnir/draupnir.html">
+ (Bandwidth)</link> <link xlink:href="http://www.rhnet.is/status/ftp/ftp-notendur.html">(FTP
+ processes)</link> <link xlink:href="http://www.rhnet.is/status/ftp/http-notendur.html">(HTTP processes)
+ </link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>ftp.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> -
+ <link xlink:href="http://www.cz.FreeBSD.org/stats/mrtg/net.html">(Bandwidth)</link>
+ <link xlink:href="http://www.freebsd.cz/stats/mrtg/ftpd.html">(FTP processes)</link>
+ <link xlink:href="http://www.freebsd.cz/stats/mrtg/rsyncd.html">(rsync processes)</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>ftp2.ru.FreeBSD.org - <email>mirror@macomnet.ru</email> -
+ <link xlink:href="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html">(Bandwidth)</link>
+ <link xlink:href="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html">(HTTP and FTP users)</link>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2 xml:id="mirror-statpagescvsup">
+ <title>CVSup site stats</title>
+ <itemizedlist>
+ <listitem>
+ <para>cvsup[23456].jp.FreeBSD.org - <email>kuriyama@FreeBSD.org</email> - <link xlink:href="http://home.jp.FreeBSD.org/stats/mrtg/cvsup/">(CVSup processes)</link></para>
+ </listitem>
+ <listitem>
+ <para>cvsup.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> -
+ <link xlink:href="http://www.freebsd.cz/stats/mrtg/cvsupd.html">(CVSup processes)</link></para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+</article>
diff --git a/zh_TW.UTF-8/articles/mailing-list-faq/Makefile b/zh_TW.UTF-8/articles/mailing-list-faq/Makefile
new file mode 100644
index 0000000000..53a873470a
--- /dev/null
+++ b/zh_TW.UTF-8/articles/mailing-list-faq/Makefile
@@ -0,0 +1,26 @@
+#
+# $FreeBSD$
+#
+# Article: Frequently Asked Questions About The FreeBSD Mailing Lists
+
+DOC?= article
+
+FORMATS?= html
+
+INSTALL_COMPRESSED?=gz
+INSTALL_ONLY_COMPRESSED?=
+
+WITH_ARTICLE_TOC?=YES
+
+#
+# SRCS lists the individual XML files that make up the document. Changes
+# to any of these files will force a rebuild
+#
+
+# XML content
+SRCS= article.xml
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/mailing-list-faq/article.xml b/zh_TW.UTF-8/articles/mailing-list-faq/article.xml
new file mode 100644
index 0000000000..d85000e6e7
--- /dev/null
+++ b/zh_TW.UTF-8/articles/mailing-list-faq/article.xml
@@ -0,0 +1,416 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!-- $FreeBSD$ -->
+<!-- The FreeBSD Documentation Project -->
+<!-- FreeBSD Mailing Lists 常見問答集 -->
+<!-- Translate into Chinese by chinsan.tw@gmail.com -->
+<!-- English Version: 1.7 -->
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <info><title>&os; Mailing Lists 常見問答集</title>
+
+
+ <authorgroup>
+ <author><personname><surname>The &os; Documentation Project</surname></personname></author>
+ </authorgroup>
+
+ <copyright>
+ <year>2004</year>
+ <year>2005</year>
+ <year>2006</year>
+ <holder>&os; 文件計畫</holder>
+ </copyright>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <abstract>
+ <para>這是有關 &os; mailing lists 的 FAQ。如果您對協助本文件/翻譯計畫
+ 的進行有興趣的話,請寄 e-mail 到
+ &a.doc;。此外,隨時可從 <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/mailing-list-faq/index.html">
+ FreeBSD 網站</link> 拿到這份文件的最新版本。
+ 也可以利用 HTTP 來下載 <link xlink:href="article.html">HTML</link>
+ 文件,或是經由 <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">
+ FreeBSD FTP 站</link> 下載純文字、&postscript;、或 PDF 版本的檔案。
+ 您也可以在這裡使用
+ <link xlink:href="&url.base;/search/search.html">搜尋 FAQ 資料</link>
+ 的功能。</para>
+ </abstract>
+ </info>
+
+ <sect1 xml:id="introduction">
+ <title>前言</title>
+
+ <para>如同其他 FAQs 一樣,本文主要目的是希望涵蓋在 &os; mailing
+ lists 上面的常見問題(當然,包括答案)。
+ 雖然,原本構想是希望能降低這些重複問題的網路流量,但如今已被公認 FAQs 也是相當好用的資源之一。</para>
+
+ <para>本文主要是描述社群之間所培養的一些禮儀(或默契),但本文本身並非『聖旨』般的權威。
+ 若發現本文內有任何技術瑕疵,或者是想建議可以增加哪些部分的話,請送 PR,或是 email 到 &a.doc;。謝囉!</para>
+
+ <qandaset>
+ <qandaentry>
+ <question xml:id="purpose">
+ <para>&os; mailing lists 的目的為何?</para>
+ </question>
+
+ <answer>
+ <para>&os; mailing lists 主要是提供 &os; 社群間的溝通管道,這裡有各式專題領域的探討,以及興趣交流。</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="audience">
+ <para>&os; mailing lists 的參與者有哪些?</para>
+ </question>
+
+ <answer>
+ <para>這個問題,要看各個 list 的『版規(charter)』定位而有所不同。有些 lists 主要是 developers 在參與討論的;
+ 而有些則主要是幾乎整體 &os; 社群都可以隨意參與討論的。請看 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">這份清單</link> 上面有目前所有 list 的摘要說明。</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="participation-who">
+ <para>&os; mailing lists 對任何人都是開放參與的嗎?</para>
+ </question>
+
+ <answer>
+ <para>再重複一次,這要看各個 list 的『版規(charter)』定位而有所不同。
+ 請在發文前,先注意閱讀該 list 的『版規(charter)』,並遵守相關原則。
+ 如此一來,才會讓大家都能溝通更無礙。</para>
+
+ <para>如果看了上一個問答內的清單之後,還是不清楚要到哪個 list 去發問的話,
+ 那麼可以試著把問題丟到 freebsd-questions 看看(但請先看下面講的補充)。</para>
+
+ <para>請注意:習慣上所有 mailing lists 都是開放發表討論的,也不必得先成為訂閱會員才行。
+ 這是相當審慎的選擇,來讓參與 &os; 社群更輕鬆容易,並鼓勵互相分享彼此的想法。
+ 然而,由於過去有些人的濫用,有些 lists 現在開始限制參與討論的部分,以避免不必要的困擾。</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="subscribe">
+ <para>要怎麼訂閱呢?</para>
+ </question>
+
+ <answer>
+ <para>可以用 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">
+ Mailman 網頁介面</link> 來訂閱任何公開的 lists。</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="unsubscribe">
+ <para>要怎麼退訂?</para>
+ </question>
+
+ <answer>
+ <para>一樣請用剛上面說的網頁介面,或者 mailing list 上面每封信結尾處都會有相關 URL 連結的指示說明。</para>
+
+ <para>千萬請不要直接寫信到這些公開的 mailing lists 說你要退訂。
+ 首先呢..因為本來就不是這樣退訂的,其次你會惹來眾怒而招來圍剿、筆戰。
+ 這是很典型的退訂錯誤示範,請不要這樣做。</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="archives">
+ <para>可以找到舊信的資料庫嗎?</para>
+ </question>
+
+ <answer>
+ <para>嗯,有!可以在 <link xlink:href="http://docs.FreeBSD.org/mail/">這邊</link>
+ 找到相關的舊信資料庫(archive)。</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="digest">
+ <para>mailing lists 可有摘要版呢?</para>
+ </question>
+
+ <answer>
+ <para>當然也有,請看 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">
+ Mailman 網頁介面</link>。</para>
+ </answer>
+ </qandaentry>
+ </qandaset>
+ </sect1>
+
+ <sect1 xml:id="etiquette">
+ <title>Mailing List 的參與禮儀</title>
+
+ <para>在 mailing lists 上參與討論,就像在其他社群一樣,我們都需要一些溝通上的共識。
+ 發言請注重禮儀(或默契),切勿無的放矢。</para>
+
+ <qandaset>
+ <qandaentry>
+ <question xml:id="before-posting">
+ <para>在發文之前,有什麼注意事項呢?</para>
+ </question>
+
+ <answer>
+ <para>最重要的是你已經看了這篇文章,然而,若您對 &os; 不熟的話,
+ 可能需要先廣泛閱讀
+ <link xlink:href="&url.base;/docs/books.html">相關書籍及文章</link>
+ 來先熟悉這套作業系統和一些典故,尤其是其中的 <link xlink:href="&url.books.faq;/index.html">
+ &os; 常見問答集 (FAQ)</link> 文件,
+ <link xlink:href="&url.books.handbook;/index.html">
+ &os; 使用手冊(Handbook)</link>,
+ 以及相關文章:<link xlink:href="&url.articles.freebsd-questions;/article.html">
+ How to get best results from the FreeBSD-questions mailing list</link>、
+ <link xlink:href="&url.articles.explaining-bsd;/article.html">
+ Explaining BSD</link>、以及 <link xlink:href="&url.articles.new-users;/article.html">
+ &os; First Steps</link>。</para>
+
+ <para>此外,對上述文件內已有解答的部份又提出來問的話,會被認為是相當不禮貌的。
+ 這並不是因為這群志工是相當吝於回答的,而是一再被相同的問題不斷疲勞轟炸之後,所產生的挫折感很重。
+ 尤其是現成答案明明就在眼前,卻仍同樣問題滿天飛,這實在是...。
+ 請注意:這些 &os; 相關文件幾乎都是由一群無薪志工的好心成果,而他們也是人。</para>
+ </answer>
+
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="inappropriate">
+ <para>如何避免不當發文呢?</para>
+ </question>
+
+ <answer>
+ <itemizedlist>
+ <listitem>
+ <para>發文時,請務必遵守該 mailing list 的遊戲規則。</para>
+ </listitem>
+
+ <listitem>
+ <para>不要作人身攻擊。好的網路公民,應該要有更高的言行標準。</para>
+ </listitem>
+
+ <listitem>
+ <para>請不要試圖作 Spam 行為(廣告、轉貼多處等不請自來行為)。
+ 所有 mailing lists 都會積極禁止這些違規者,一旦有的話,那麼後果請自行負責。</para>
+ </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="etiquette-posting">
+ <para>發文時,有什麼該注意的嗎?</para>
+ </question>
+
+ <answer>
+ <itemizedlist>
+ <listitem>
+ <para>發文時,請保持一行約 75 個字元就自動斷行,因為並不是每個看的人都有很炫的圖形介面(GUI)看信軟體。</para>
+ </listitem>
+
+ <listitem>
+ <para>請注意:事實上,網路頻寬並不是無限的。
+ 並非每個讀者的頻寬都很大,所以若想貼一些像是 <filename>config.log</filename>
+ 之類的設定檔內容,或是大量的 stack trace 紀錄,那麼請把它放在自己網站上,然後貼出該網址 URL 就行了。
+ 還有一件事,請記住,這些信件都會被舊信資料庫保存下來,所以這樣作會造成保存的資料庫會很快被塞到很大,
+ 甚至可能塞爆 Server 的硬碟空間。</para>
+ </listitem>
+
+ <listitem>
+ <para>文章是要讓人看得懂,所以請注意版面編排的可讀性,還有..
+ 千 萬 不 要 大 聲 嚷 叫!!!!! 這點可不只 &os; mailing lists 才需如此注意,
+ 請勿低估文章『基本編排』的重要性、連鎖效應。
+ 信中的表達方式通常就代表著別人眼中的你,若文章讓人看了很吃力(霧煞煞)、拼字錯誤百出、
+ 充滿語意或邏輯錯誤、或是文內充滿一堆驚嘆號,這會讓人對你印象觀感極差。</para>
+ </listitem>
+
+ <listitem>
+ <para>在一些特定的 list 場合,請用適當的語言來溝通。許多非英語系的mailing
+ lists 可以到
+ <link xlink:href="&url.base;/community/mailinglists.html">
+ 這邊</link> 查看看。</para>
+
+ <para>對於許多母語不是英語的人,我們都能諒解他們的苦楚,並且試著儘量多多包涵。
+ 英文非母語的人,我們會儘量不惡意批評拼字或文法錯誤之處。
+ &os; 在這方面,一直有相當優秀的紀錄,請讓我們繼續保持這傳統吧。</para>
+ </listitem>
+
+ <listitem>
+ <para>寫信時,請用相容標準的 Mail User Agent (MUA)程式。
+ <link xlink:href="http://www.lemis.com/email.html">不良的(或設定錯誤的)寄信程式</link>
+ 這裡列有許多信件格式的錯誤示範。以下是一些已知的寄信程式的不良示範:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>cc:Mail</para>
+ </listitem>
+
+ <listitem>
+ <para>(舊版的)&eudora;</para>
+ </listitem>
+
+ <listitem>
+ <para>exmh</para>
+ </listitem>
+
+ <listitem>
+ <para>&microsoft; Exchange</para>
+ </listitem>
+
+ <listitem>
+ <para>&microsoft; Internet Mail</para>
+ </listitem>
+
+ <listitem>
+ <para>&microsoft; &outlook;</para>
+ </listitem>
+
+ <listitem>
+ <para>(舊版的)&netscape;</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>如同上述所見,Microsoft 出的一堆寄信程式通常都是不相容標準格式的。
+ 請儘量改用 &unix; 上的寄信程式。若必須在 Microsoft 環境下使用寄信程式的話,
+ 請記得確認設定是否正確。請儘量不要用 <acronym>MIME</acronym> 格式:
+ 因為有一堆人都在濫用 <acronym>MIME</acronym> 信件格式。</para>
+ </listitem>
+
+ <listitem>
+ <para>請確認:時間與時區設定是否正確。
+ 這問題看起來有點蠢,因為你寄出的信還是會到達 mailing list 上,
+ 但是呢,每位 mailing lists 上的訂戶每天都會看數百封的信,
+ 他們通常會把信件以標題跟時間作為排序依據。
+ 若你的信沒有在第一篇正解之前就先出現的話,他們就會假設可能是漏收你這封信,
+ 然後就沒再去看你那封信了。</para>
+ </listitem>
+
+ <listitem>
+ <para>請提供程式出現的相關訊息,像是 &man.dmesg.8; 或者 console
+ messages 也就是通常會出現在 <filename>/var/log/messages</filename> 出現的。
+ 請不要用手打,因為這不僅很苦,而且也可能打錯字或亂掉原有格式。請直接把相關的 log 檔丟出來,
+ 或是用編輯器來剪裁、或是用滑鼠複製/貼上來完成。舉個例子,如果是要把像是 <command>dmesg</command>
+ 的程式訊息倒入到某個檔案去的話,那麼作法如下:</para>
+
+ <screen>&prompt.user; <userinput>dmesg &gt; /tmp/dmesg.out</userinput></screen>
+
+ <para>這樣子會把訊息送到 <filename>/tmp/dmesg.out</filename> 檔內。</para>
+ </listitem>
+
+ <listitem>
+ <para>在用滑鼠剪貼時,請注意是否有犯一些細節的剪貼壞習慣。
+ 尤其是像貼 <filename>Makefiles</filename> 之類檔案時,由於 <literal>tab</literal>
+ 鍵所打出來的分格,是屬於特殊字元。因此,在 <link xlink:href="&url.base;/support.html#gnats">
+ GNATS PR 資料庫</link> 上很常看到這類很常見的惱人問題:
+ <filename>Makefiles</filename> 內的 tab 經過剪貼後,變成『空白(white space)』
+ 或是困擾的 <literal>=3B</literal> escape sequence,這些會讓 committers 們十分不爽。</para>
+ </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="etiquette-replying">
+ <para>在 mailing lists 上回文的話,有什麼要特別注意的嗎?</para>
+ </question>
+
+ <answer>
+ <itemizedlist>
+ <listitem>
+ <para>請適當調整文章引言長度。回文時,引言部份請引『有談到的』部分為主,但請不要過與不及。
+ 應該保留涉及討論範圍的原文,這樣子才能讓沒看過前面文章的人知道是在講什麼,而非一頭霧水。</para>
+
+ <para>還有一點也很重要,原文若是幅度相當長的話,記得註明 "yes, I see this too"。</para>
+ </listitem>
+
+ <listitem>
+ <para>善用技巧來確認原文與自己寫的部份:
+ 通常會在原文的每行前面加上 <quote><literal>&gt; </literal></quote> 以作記號。
+ 請記得保留 <quote><literal>&gt; </literal></quote> 符號後面的空白,並且在原文以及你所寫的段落之間加上空行,
+ 以便閱讀。</para>
+ </listitem>
+
+ <listitem>
+ <para>請不要斷章取義、穿鑿附會:通常對原始文章『斷章取義』、『穿鑿附會』會讓大家很不爽,因為他們原意並非如此,卻被曲解。</para>
+ </listitem>
+
+ <listitem>
+ <para>回文時,不要寫在原文上面(<literal>top post</literal>)。
+ 這個意思是:若要回文時,請寫在原文下方,不要寫在原文上面,以免讓人有時空錯置的錯亂混淆。</para>
+ <!-- 注意:下面這是故意幽默效果的問答 -->
+ <itemizedlist>
+ <listitem>
+ <para>答: Because it reverses the logical flow of
+ conversation.</para>
+ </listitem>
+ <listitem>
+ <para>問: Why is top posting frowned upon?</para>
+ </listitem>
+ </itemizedlist>
+ <para>(感謝 Randy Bush 提供笑話)</para>
+ </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+ </qandaset>
+ </sect1>
+
+ <sect1 xml:id="recurring">
+ <title>Mailing Lists 上的重複性問題</title>
+
+ <para>在 mailing lists 上參與討論,就像在其他社群一樣,我們都需要一些溝通上的共識。
+ 許多 mailing lists 都會假設參與討論者都大致知道 FreeBSD 計劃的一些歷史淵源。
+ 尤其是社群的新手總是定期會不斷重複問類似問題。
+ 每個發文的人,都有責任來避免掉入這樣的惡性循環輪迴內。
+ 因此,應儘可能讓 mailing list 上能正常討論,而避免讓自己陷入筆戰泥沼。</para>
+
+ <para>要怎麼避免呢?最好的方法就是善用這些 <link xlink:href="http://docs.FreeBSD.org/mail/">
+ mailing list 舊信資料庫(archives)</link>,來瞭解相關背景。
+ 正由於這原因,所以 <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">
+ mailing list 搜尋介面</link> 就顯得非常好用。
+ (若這方法仍無法找到有用的答案,那麼請改用自己愛用的搜尋引擎吧)</para>
+
+ <para>透過這些舊信資料庫,不只可瞭解先前討論過哪些話題,也可以知道:是怎麼討論的、
+ 哪些人參與討論過、主要看的人又是哪些人。
+ 入境隨俗這些原則不只是 &os; mailing list 上才這樣,一樣可以適合其他地方。</para>
+
+ <para>archives 的內容無疑地相當廣泛,而且會有些問題不斷反覆出現,
+ 有時討論到後面總會離題。無論如何,在發問前的義務就是先做好功課,
+ 以避免這類的月經文惡性循環,尤其是令人反感的 <literal>bikeshed(打嘴砲)</literal>。</para>
+ </sect1>
+
+ <sect1 xml:id="bikeshed">
+ <title>什麼是 "Bikeshed" 呀?</title>
+ <para>單就字面上意思解釋的話,<literal>bikeshed</literal> 是指專門給腳踏車、機車之類的兩輪交通工具使用的遮雨棚,
+ 然而呢,在 &os; 這邊的說法卻有其他意思(帶有貶抑)指的是:
+ 某些特定話題的重複討論,尤其是指在 &os; 社群內絕不會有共識,且有爭議的話題。
+ (這字彙的起源在 <link xlink:href="&url.books.faq;/misc.html#BIKESHED-PAINTING">
+ 這份文件</link> 內有更多說明)。你只要在發信到任一 &os; mailing lists 之前,知道這個基本概念就行了。</para>
+
+ <para>一般來講,『bikeshed』是很容易產生許多波的筆戰與額外討論的爭議話題,如果事先不知道這些背景的話。</para>
+
+ <para>拜託,請幫個忙讓討論回歸正常,而不要只是到處打嘴砲而已。感恩!</para>
+ </sect1>
+
+ <sect1 xml:id="acknowledgments">
+ <title>致謝</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>&a.grog;</term>
+ <listitem>
+ <para><link xlink:href="&url.articles.freebsd-questions;/article.html">
+ How to get best results from the FreeBSD-questions mailing list</link> 一文的原作者,
+ 我們從他這文內獲得許多 mailing list 上的禮儀(或默契)寫作題材。</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>&a.linimon;</term>
+ <listitem>
+ <para>本 FAQ 雛形的原作</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+</article>
diff --git a/zh_TW.UTF-8/articles/nanobsd/Makefile b/zh_TW.UTF-8/articles/nanobsd/Makefile
new file mode 100644
index 0000000000..38de994f6c
--- /dev/null
+++ b/zh_TW.UTF-8/articles/nanobsd/Makefile
@@ -0,0 +1,28 @@
+#
+# The FreeBSD Traditional Chinese Project
+#
+# Original Revision: 1.2
+# $FreeBSD$
+#
+# Article: Introduction to NanoBSD
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+# 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
+
+SRCS= article.xml
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/nanobsd/article.xml b/zh_TW.UTF-8/articles/nanobsd/article.xml
new file mode 100644
index 0000000000..44702eb5df
--- /dev/null
+++ b/zh_TW.UTF-8/articles/nanobsd/article.xml
@@ -0,0 +1,434 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!--
+ The FreeBSD Documentation Project
+ The FreeBSD Chinese (Traditional) Documentation Project
+
+ Original Revision: 1.1
+-->
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <info><title>NanoBSD 簡介</title>
+
+
+ <authorgroup>
+ <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname></author>
+ </authorgroup>
+
+ <copyright>
+ <year>2006</year>
+ <holder>The FreeBSD Documentation Project</holder>
+ </copyright>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <abstract>
+ <para>這篇文件提供了關於 <application>NanoBSD</application> 工具的情報介紹,
+ 這工具可用來建立用於嵌入式環境應用程式的 &os; 系統映像檔,
+ 以便存放到 Compact Flash 卡(或隨身碟)。</para>
+ </abstract>
+ </info>
+
+ <sect1 xml:id="intro">
+ <title>NanoBSD 簡介</title>
+
+ <indexterm><primary>NanoBSD</primary></indexterm>
+
+ <para><application>NanoBSD</application> 是 &a.phk; 目前正在開發的一項工具。
+ 它可用來建立用於嵌入式環境應用程式的 &os; 系統映像檔,
+ 以便存放到 Compact Flash 卡(或隨身碟,mass storage medium)。</para>
+
+ <para>這一工具也可以用來自製安裝映像檔,
+ 以簡化俗稱為 <quote>嵌入式系統(computer appliances)</quote> 的系統安裝、維護工作。
+ 通常,每個嵌入式系統產品都有限定硬體和軟體,
+ 或者換言之,所有的應用程式都是預先裝好的。
+ 這些設備可以直接放到現有的網路中,而且(幾乎是)立即使用。</para>
+
+ <para><application>NanoBSD</application> 提供的功能包括:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>可以和 &os; 一樣使用 Ports 和 Packages &mdash;
+ 所有的應用程序都可以在 <application>NanoBSD</application> 中直接使用,
+ 而方式與 &os; 完全一樣。</para>
+ </listitem>
+
+ <listitem>
+ <para>功能絲毫未損 &mdash; 在 &os; 做的任何工作,都可以在
+ <application>NanoBSD</application> 中使用,
+ 除非您在建立 <application>NanoBSD</application> 映像檔時,
+ 有指定要拿掉它們。</para>
+ </listitem>
+
+ <listitem>
+ <para>所有東西在運行時都是唯讀的 &mdash; 可以安全地拔掉電源插頭。
+ 系統不正常關機的話,不用再跑 &man.fsck.8; 了。</para>
+ </listitem>
+
+ <listitem>
+ <para>可輕鬆編譯、自行打造 &mdash; 只需使用一個 shell script 和一個設定檔,
+ 您可以輕鬆依需求來量身訂做適用的映像檔。</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="howto">
+ <title>如何使用 NanoBSD</title>
+
+ <sect2 xml:id="design">
+ <title>NanoBSD 的設計</title>
+
+ <para>一旦將映像檔存入嵌入式硬體,就可以用它來引導 <application>NanoBSD</application>
+ 了。 預設情況下,隨身碟會劃分為三部分:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>兩個映像檔分割區: <literal>code#1</literal>
+ 和 <literal>code#2</literal>。</para>
+ </listitem>
+
+ <listitem>
+ <para>一個設定檔分割區,在運行環境中,
+ 可以將其掛載(mount)到 <filename>/cfg</filename> 目錄下。</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>這些分割區,在預設情況下是以唯讀方式掛載。</para>
+
+ <para><filename>/etc</filename> 和
+ <filename>/var</filename> 目錄均為
+ &man.md.4;(malloc)磁碟。</para>
+
+ <para>設定檔的分割區則是在
+ <filename>/cfg</filename> 目錄。
+ 它包含了用於 <filename>/etc</filename>
+ 目錄的檔案,在啟動之後暫時以唯讀方式掛載。 因此,若想要重開機保留新的設定,
+ 那麼要記得從 <filename>/etc</filename> 把改過的檔案複製回
+ <filename>/cfg</filename> 目錄才行。</para>
+
+ <example>
+ <title>把修改過 <filename>/etc/resolv.conf</filename> 設定保存起來</title>
+
+ <screen>&prompt.root; <userinput>vi /etc/resolv.conf</userinput>
+[...]
+&prompt.root; <userinput>mount /cfg</userinput>
+&prompt.root; <userinput>cp /etc/resolv.conf /cfg</userinput>
+&prompt.root; <userinput>umount /cfg</userinput></screen>
+ </example>
+
+ <note>
+ <para>只有在系統啟動過程中,以及需要修改設定檔的時候,才需要掛載含有
+ <filename>/cfg</filename> 的那個分割區。</para>
+
+ <para>一直都掛載 <filename>/cfg</filename>
+ 不是一個好主意,特別是當您把 <application>NanoBSD</application>
+ 放在不適合進行大量寫入動作的分割區時
+ (比如:由於檔案系統的同步化會定期在系統碟內寫入資料)。</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>打造 NanoBSD 映像檔</title>
+
+ <para><application>NanoBSD</application> 映像檔是透過使用非常簡單的
+ <filename>nanobsd.sh</filename> shell script 來打造的,這個 script 可以在
+ <filename>/usr/src/tools/tools/nanobsd</filename>
+ 目錄中找到。 這個 script 建立的映像檔,可以用 &man.dd.1; 工具來複製到隨身碟上。</para>
+
+ <para>打造
+ <application>NanoBSD</application> 映像檔所需的指令是:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src/tools/tools/nanobsd</userinput> <co xml:id="nbsd-cd"/>
+&prompt.root; <userinput>sh nanobsd.sh</userinput> <co xml:id="nbsd-sh"/>
+&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co xml:id="nbsd-cd2"/>
+&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co xml:id="nbsd-dd"/></screen>
+
+ <calloutlist>
+ <callout arearefs="nbsd-cd">
+ <para>進入 <application>NanoBSD</application> 打造 script 的主目錄。</para>
+ </callout>
+
+ <callout arearefs="nbsd-sh">
+ <para>開始打造過程。</para>
+ </callout>
+
+ <callout arearefs="nbsd-cd2">
+ <para>進入打造好的映像檔所在的目錄。</para>
+ </callout>
+
+ <callout arearefs="nbsd-dd">
+ <para>在隨身碟上安裝 <application>NanoBSD</application>。</para>
+ </callout>
+ </calloutlist>
+ </sect2>
+
+ <sect2>
+ <title>自行打造 NanoBSD 映像檔</title>
+
+ <para>這可能是 <application>NanoBSD</application> 最為重要,
+ 同時也是您最感興趣的功能。 同時,在開發
+ <application>NanoBSD</application> 應用程式時,這也是相當耗時的過程。</para>
+
+ <para>執行下面的指令將會
+ <filename>nanobsd.sh</filename> 讀取目前所在目錄的
+ <filename>myconf.nano</filename> 檔的設定:</para>
+
+ <screen>&prompt.root; <userinput>sh nanobsd.sh -c myconf.nano</userinput></screen>
+
+ <para>自行打造的流程,只需兩個步驟:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>自訂選項</para>
+ </listitem>
+
+ <listitem>
+ <para>自訂功能</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect3>
+ <title>自訂選項</title>
+
+ <para>透過修改設定,可以設定用於
+ <application>NanoBSD</application> 打造過程中 <literal>buildworld</literal>
+ 和 <literal>installworld</literal> 階段的編譯、安裝選項,以及
+ <application>NanoBSD</application> 主要打造過程中的選項。
+ 透過使用這些選項可以削減系統的尺寸,使之能夠放入
+ 64 MB 的隨身碟。 您還可以進一步透過這些選項來削減 &os;,
+ 直到它只包含 kernel 以及兩三個 userland 檔案為止。</para>
+
+ <para>設定檔案中包含用以代替預設值的設定選項。簡介最重要的幾項設定如下:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>NANO_NAME</literal> &mdash; 本次打造的名稱(所建立工作目錄的名稱)。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>NANO_SRC</literal> &mdash; 用以編譯、打造映像檔的 source tree 的位置。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>NANO_KERNEL</literal> &mdash; 設定用來編譯的 kernel 設定檔檔名。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>CONF_BUILD</literal> &mdash; 用於
+ <literal>buildworld</literal> 打造階段的選項。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>CONF_INSTALL</literal> &mdash; 用於
+ <literal>installworld</literal> 打造階段的選項。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>CONF_WORLD</literal> &mdash; 用於
+ <literal>buildworld</literal> 和
+ <literal>installworld</literal> 這兩個打造階段的選項。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>FlashDevice</literal> &mdash; 定義所用的嵌入式硬體類型。
+ 詳情請參考 <filename>FlashDevice.sub</filename> 檔。</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>自訂功能</title>
+
+ <para>透過在設定檔案中使用 shell 函數,可以進一步微調
+ <application>NanoBSD</application>。 舉例說明一下自行打造函數的基本方式:</para>
+
+ <programlisting>cust_foo()(
+ echo "bar=topless" &gt; \
+ &dollar;{NANO_WORLDDIR}/etc/foo
+)
+customize_cmd cust_foo</programlisting>
+
+ <para>下面舉更實際點的例子,它會把預設的
+ <filename>/etc</filename> 目錄大小,從 5MB 調整為 30MB:</para>
+
+ <programlisting>cust_etc_size()(
+ cd &dollar;{NANO_WORLDDIR}/conf
+ echo 30000 &gt; default/etc/md_size
+)
+customize_cmd cust_etc_size</programlisting>
+
+ <para>除此之外,還有幾個預設的功能定義可以用來自訂:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>cust_comconsole</literal> &mdash; 在預設 VGA 顯示卡上停用 &man.getty.8;
+ (<filename>/dev/ttyv*</filename>)並啟用 serial port 的 COM1 以作為系統 console。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>cust_allow_ssh_root</literal> &mdash; 允許 &man.sshd.8;
+ 可以用 <systemitem class="username">root</systemitem> 帳號登入。</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>cust_install_files</literal> &mdash;
+ 從 <filename>nanobsd/Files</filename>
+ 目錄中安裝檔案,這包含一些實用的系統管理 script 。</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>設定檔案舉例</title>
+
+ <para>下面是用於自行打造的 <application>NanoBSD</application> 映像檔的完整例子:</para>
+
+ <programlisting>NANO_NAME=custom
+NANO_SRC=/usr/src
+NANO_KERNEL=MYKERNEL
+NANO_IMAGES=2
+
+CONF_BUILD='
+NO_KLDLOAD=YES
+NO_NETGRAPH=YES
+NO_PAM=YES
+'
+
+CONF_INSTALL='
+NO_ACPI=YES
+NO_BLUETOOTH=YES
+NO_CVS=YES
+NO_FORTRAN=YES
+NO_HTML=YES
+NO_LPR=YES
+NO_MAN=YES
+NO_SENDMAIL=YES
+NO_SHAREDOCS=YES
+NO_EXAMPLES=YES
+NO_INSTALLLIB=YES
+NO_CALENDAR=YES
+NO_MISC=YES
+NO_SHARE=YES
+'
+
+CONF_WORLD='
+NO_BIND=YES
+NO_MODULES=YES
+NO_KERBEROS=YES
+NO_GAMES=YES
+NO_RESCUE=YES
+NO_LOCALES=YES
+NO_SYSCONS=YES
+NO_INFO=YES
+'
+
+FlashDevice SanDisk 1G
+
+cust_nobeastie()(
+ touch &dollar;{NANO_WORLDDIR}/boot/loader.conf
+ echo "beastie_disable=\"YES\"" &gt;&gt; &dollar;{NANO_WORLDDIR}/boot/loader.conf
+)
+
+customize_cmd cust_comconsole
+customize_cmd cust_install_files
+customize_cmd cust_allow_ssh_root
+customize_cmd cust_nobeastie</programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>更新 NanoBSD</title>
+
+ <para>更新 <application>NanoBSD</application> 相對 &os; 而言較為簡單:</para>
+
+ <procedure>
+ <step>
+ <para>和之前一樣打造新的 <application>NanoBSD</application> 映像檔。</para>
+ </step>
+
+ <step>
+ <para>將新的映像檔放入正運行的
+ <application>NanoBSD</application> 中未用的分割區之一。</para>
+
+ <para>與之前最初安裝 <application>NanoBSD</application> 的步驟相比,
+ 這一步驟最重要的區別在於:這次不用 <filename>_.disk.full</filename> 檔(它包含整個磁碟的映像檔),
+ 而應安裝 <filename>_.disk.image</filename> 映像檔(這個檔案中,只包含一個系統分割區)。</para>
+ </step>
+
+ <step>
+ <para>重新啟動,並從新安裝的分割區中啟動系統。</para>
+ </step>
+
+ <step>
+ <para>如果一切順利的話,升級工作就完成了。</para>
+ </step>
+
+ <step>
+ <para>如果發生了任何問題,則可以從先前的分割區啟動
+ (其中包含了舊的、 可用的映像檔),來盡快恢復系統功能。
+ 接下來可以修正新編譯的版本中存在的問題,並重複前述步驟。</para>
+ </step>
+ </procedure>
+
+ <para>要在正在運行的
+ <application>NanoBSD</application> 系統中安裝新的映像檔,可以使用位於
+ <filename>/root</filename> 目錄的
+ <filename>updatep1</filename> 或
+ <filename>updatep2</filename> script ,
+ 實際上要用哪一個 script,則取決於正在運行的系統是位於哪個分割區而定。</para>
+
+ <para>隨時提供新 <application>NanoBSD</application> 映像檔所提供的服務,
+ 以及採用的傳輸方法的不同,您可以參考並使用下列三種方式之一:</para>
+
+ <sect3>
+ <title>使用 &man.ftp.1;</title>
+
+ <para>如果傳輸速度是第一要求的話,請採用下面例子:</para>
+
+ <screen>&prompt.root; <userinput>ftp myhost
+get _.disk.image "| sh updatep1"</userinput></screen>
+ </sect3>
+
+ <sect3>
+ <title>使用 &man.ssh.1;</title>
+
+ <para>如果想更安全的話,應參考下面例子:</para>
+
+ <screen>&prompt.root; <userinput>ssh myhost cat _.disk.image.gz | zcat | sh updatep1</userinput></screen>
+ </sect3>
+
+ <sect3>
+ <title>使用 &man.nc.1;</title>
+
+ <para>如果遠程主機既不提供 &man.ftp.1; 服務,也不提供 &man.sshd.8; 服務的話:</para>
+
+ <procedure>
+ <step>
+ <para>首先,在提供映像檔的主機上開啟 TCP listen,並讓它把映像檔傳給 client:</para>
+
+ <screen>myhost&prompt.root; <userinput>nc -l 2222 &lt; _.disk.image</userinput></screen>
+
+ <note>
+ <para>請確認您所使用的 port 沒有被防火牆阻止來自
+ <application>NanoBSD</application> client 的連線請求。</para>
+ </note>
+ </step>
+ <step>
+ <para>連到提供新映像檔服務的主機,並執行 <filename>updatep1</filename> 這支 script:</para>
+
+ <screen>&prompt.root; <userinput>nc myhost 2222 | sh updatep1</userinput></screen>
+ </step>
+ </procedure>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <index/>
+</article>
diff --git a/zh_TW.UTF-8/articles/pr-guidelines/Makefile b/zh_TW.UTF-8/articles/pr-guidelines/Makefile
new file mode 100644
index 0000000000..17e369ff2c
--- /dev/null
+++ b/zh_TW.UTF-8/articles/pr-guidelines/Makefile
@@ -0,0 +1,19 @@
+#
+# $FreeBSD$
+#
+# Article: Problem Report Handling Guidelines
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?=gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.xml
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/pr-guidelines/article.xml b/zh_TW.UTF-8/articles/pr-guidelines/article.xml
new file mode 100644
index 0000000000..9a2bebcc23
--- /dev/null
+++ b/zh_TW.UTF-8/articles/pr-guidelines/article.xml
@@ -0,0 +1,875 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!-- $FreeBSD$ -->
+<!-- The FreeBSD Documentation Project -->
+<!-- Translate into Chinese by chinsan.tw@gmail.com -->
+<!-- English Version: 1.24 -->
+<!--
+ 問題回報(PR)的處理原則
+ The FreeBSD Project - http://www.FreeBSD.org
+-->
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <!-- :START of Article Metadata -->
+ <info><title>問題回報(PR)的處理原則</title>
+
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.opengroup;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <abstract>
+ <para>這篇文章主要在講:由 FreeBSD PR 維護小組所提出的一些 FreeBSD 問題回報(PR)
+ 建議,希望大家在弄 PR 時都能遵守。</para>
+ </abstract>
+
+ <authorgroup>
+ <author><personname><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></personname></author>
+
+ <author><personname><firstname>Hiten</firstname><surname>Pandya</surname></personname></author>
+ </authorgroup>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+ </info>
+ <!-- :END of Article Metadata-->
+
+ <section xml:id="intro">
+ <title>前言</title>
+
+ <para>GNATS 是 FReeBSD 計劃所採用的一套專門管理錯誤(回報bug) 系統。
+ 由於對 FreeBSD 品質保證而言,是否能準確掌握各項錯誤回報與進度是十分重要的,
+ 因此,如何正確有效使用 GNATS 也就必須注意。</para>
+
+ <para>Access to GNATS is available to FreeBSD developers, as well as
+ to the wider community. 為了讓 GNATS 資料庫使用上儘量一致,於是就產生了怎麼處理像是:followup(回文)、關閉PR等的參考原則。</para>
+ </section>
+
+ <section xml:id="pr-lifecycle">
+ <title>問題回報(PR)的生命週期</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>首先,回報者(originator)以 &man.send-pr.1; 送出 PR,然後會收到一封確認信。</para>
+ </listitem>
+
+ <listitem>
+ <para>然後,committer 們就會有人(假設叫做 Joe)發掘有興趣的 PR 並將該 PR 指派給自己來處理。
+ 或者 bugbuster 會有人(假設叫做 Jane) 就會下決定:她覺得 Joe 比較適合處理,就將該 PR 指派(assign)給他</para>
+ </listitem>
+
+ <listitem>
+ <para>Joe 會先與有問題的回報者作些意見交流(以確定這問題有進入 audit 追蹤流程內)
+ 以及判斷問題點。
+ 然後再確定問題點有寫入 audit 追蹤流程之後,然後把該 PR 狀態設為
+ <quote>analyzed(已分析)</quote>。</para>
+ </listitem>
+
+ <listitem>
+ <para>Joe 開始徹夜找出問題解法,然後將 patch 送到 follow-up(回文用),並請回報者協助測試是否正常。
+ 然後,他就會將 PR 狀態設為 <quote>feedback</quote> 囉。</para>
+ </listitem>
+
+ <listitem>
+ <para>如此重複 analyzed、feedback 幾趟之後,直到 Joe 與回報者雙方都相當滿意 patch 結果,
+ 於是就會將 patch 給 commits 進入 <literal>-CURRENT</literal> (或者若 <literal>-CURRENT</literal>
+ 上面沒這問題的話,就直接送到 <literal>-STABLE</literal>),在 commit log 內要把相關 PR 寫上去
+ (同時回報者若有送完整或部分 patch 的話,就順便記載),然後,若沒什麼事的話,就開始準備 MFC 哩。
+ (譯註:MFC意指 Merged From CURRENT ,也就是把 <literal>-CURRENT</literal> 上的東西併入 <literal>-STABLE</literal>。</para>
+ </listitem>
+
+ <listitem>
+ <para>若該 patch 不需要 MFC 的話,Joe 就會關掉(close)該 PR 了。</para>
+ </listitem>
+
+ <listitem>
+ <para>若該 patch 需要 MFC 的話,Joe 會把 PR 狀態改為 <quote>patched(已修正)</quote>,
+ 直到已經 MFC 完畢,才會 close(關掉)。</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>很多送出來的 PR 都很少附上問題的相關訊息,而有些則是相當複雜難搞,
+ 或只是提到部分表面問題而已;
+ 遇到這種情況時,是非常需要得到所有相關訊息以便解決問題。
+ 若遇到這種無解的問題或再次發生的話,就必須要 re-open(重新開啟) 該 PR,以待解決。</para>
+ </note>
+ <note>
+ <para>PR 上所附的 <quote>email address</quote> 可能因某些原因而無法收信時,遇到這種狀況,通常就是
+ followup 該 PR ,並(在 followup 時)請回報者重新提供可正常收信的 email address。
+ 當系統上的 mail 系統關閉或沒裝的時候,這通常是在使用 &man.send-pr.1; 的替代方案。</para>
+ </note>
+ </section>
+
+ <section xml:id="pr-states">
+ <title>問題回報(PR)的狀態</title>
+
+ <para>若 PR 有任何變化的話,請務必記得更新 PR 的『狀態(state)』。
+ 『狀態』應該要能正確反映該 PR 的目前進度才是。</para>
+
+ <example>
+ <title>以下是更改 PR 狀態的小例子:</title>
+
+ <para>當有可以修正問題的 PR 出現,而相關負責的 developer(s)
+ 也覺得這樣的修正可以接受,他們會 followup 該 PR,並將其狀態改為
+ <quote>feedback</quote>。同時,回報者應重新評估最終的修正結果,並回應:所回報的錯誤是否已成功修正。</para>
+ </example>
+
+ <para>每份 PR 通常會有下面這幾種狀態之一:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>open</glossterm>
+ <glossdef>
+ <para>PR 最初的狀態:這個問題被提出來,並在等待處理中。</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>analyzed</glossterm>
+ <glossdef>
+ <para>已經開始處理這問題,並且有找到疑似解決的方法。</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>feedback</glossterm>
+ <glossdef>
+ <para>需要回報者提供更詳細的相關資料,正如教學要因材施教,治病也要因人下藥,越多相關訊息,才能有最佳效果。</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>patched</glossterm>
+ <glossdef>
+ <para>已經送相關 patch 了,但仍因某些原因(MFC,或來自回報者的確認結果異常)因此尚未完畢。</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>suspended(暫緩)</glossterm>
+ <glossdef>
+ <para>因為沒附上相關訊息或參考資料,所以還沒辦法處理這問題。
+ This is a prime candidate for
+ somebody who is looking for a project to take on. If the
+ problem cannot be solved at all, it will be closed, rather
+ than suspended. The documentation project uses
+ <quote>suspended</quote> for <quote>wish-list</quote>
+ items that entail a significant amount of work which no one
+ currently has time for.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>closed</glossterm>
+ <glossdef>
+ <para>A problem report is closed when any changes have been
+ integrated, documented, and tested, or when fixing the
+ problem is abandoned.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <note>
+ <para>The <quote>patched</quote> state is directly related to
+ feedback, so you may go directly to <quote>closed</quote> state if
+ the originator cannot test the patch, and it works in your own testing.</para>
+ </note>
+ </section>
+
+ <section xml:id="pr-types">
+ <title>問題回報(PR)的種類</title>
+
+ <para>While handling problem reports, either as a developer who has
+ direct access to the GNATS database or as a contributor who
+ browses the database and submits followups with patches, comments,
+ suggestions or change requests, you will come across several
+ different types of PRs.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="pr-unassigned">PRs not yet assigned to anyone.</link></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="pr-assigned">PRs already assigned to someone.</link></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="pr-dups">重複的 PR</link></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="pr-stale">Stale PRs</link></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="pr-misfiled">Misfiled PRs</link></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following sections describe what each different type of
+ PRs is used for, when a PR belongs to one of these types, and what
+ treatment each different type receives.</para>
+
+ <section xml:id="pr-unassigned">
+ <title>Unassigned PRs</title>
+
+ <para>When PRs arrive, they are initially assigned to a generic
+ (placeholder) assignee. These are always prepended with
+ <literal>freebsd-</literal>. The exact value for this default
+ depends on the category; in most cases, it corresponds to a
+ specific &os; mailing list. Here is the current list, with
+ the most common ones listed first:</para>
+
+ <table xml:id="default-assignees-common">
+ <title>Default Assignees &mdash; most common</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Categories</entry>
+ <entry>Default Assignee</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>base system</entry>
+ <entry>bin, conf, gnu, kern, misc</entry>
+ <entry>freebsd-bugs</entry>
+ </row>
+
+ <row>
+ <entry>architecture-specific</entry>
+ <entry>alpha, i386, ia64, powerpc, sparc64</entry>
+ <entry>freebsd-<replaceable>arch</replaceable></entry>
+ </row>
+
+ <row>
+ <entry>ports collection</entry>
+ <entry>ports</entry>
+ <entry>freebsd-ports-bugs</entry>
+ </row>
+
+ <row>
+ <entry>documentation shipped with the system</entry>
+ <entry>docs</entry>
+ <entry>freebsd-doc</entry>
+ </row>
+
+ <row>
+ <entry>&os; web pages (not including docs)</entry>
+ <entry>www</entry>
+ <entry>freebsd-www</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table xml:id="default-assignees-other">
+ <title>Default Assignees &mdash; other</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Categories</entry>
+ <entry>Default Assignee</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>advocacy efforts</entry>
+ <entry>advocacy</entry>
+ <entry>freebsd-advocacy</entry>
+ </row>
+
+ <row>
+ <entry>&java.virtual.machine; problems</entry>
+ <entry>java</entry>
+ <entry>freebsd-java</entry>
+ </row>
+
+ <row>
+ <entry>standards compliance</entry>
+ <entry>standards</entry>
+ <entry>freebsd-standards</entry>
+ </row>
+
+ <row>
+ <entry>threading libraries</entry>
+ <entry>threads</entry>
+ <entry>freebsd-threads</entry>
+ </row>
+
+ <row>
+ <entry>&man.usb.4; subsystem</entry>
+ <entry>usb</entry>
+ <entry>freebsd-usb</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Do not be surprised to find that the submitter of the
+ PR has assigned it to the wrong category. If you fix the
+ category, do not forget to fix the assignment as well.
+ (In particular, our submitters seem to have a hard time
+ understanding that just because their problem manifested
+ on an i386 system, that it might be generic to all of &os;,
+ and thus be more appropriate for <literal>kern</literal>.
+ The converse is also true, of course.)</para>
+
+ <para>Certain PRs may be reassigned away from these generic
+ assignees by anyone. For assignees which are mailing lists,
+ please use the long form when making the assignment (e.g.,
+ <literal>freebsd-foo</literal> instead of <literal>foo</literal>);
+ this will avoid duplicate emails sent to the mailing list.</para>
+
+ <note>
+ <para>Here is a sample list of such entities; it is probably
+ not complete. In some cases, entries that have the short form are
+ <emphasis>aliases</emphasis>, not mailing lists.</para>
+ </note>
+
+ <table xml:id="common-assignees-base">
+ <title>Common Assignees &mdash; base system</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Suggested Category</entry>
+ <entry>Suggested Assignee</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>problem specific to the &arm; architecture</entry>
+ <entry>kern</entry>
+ <entry>freebsd-arm</entry>
+ </row>
+
+ <row>
+ <entry>problem specific to the &mips; architecture</entry>
+ <entry>kern</entry>
+ <entry>freebsd-mips</entry>
+ </row>
+
+ <row>
+ <entry>problem specific to the &powerpc; architecture</entry>
+ <entry>kern</entry>
+ <entry>freebsd-ppc</entry>
+ </row>
+
+ <row>
+ <entry>problem with Advanced Configuration and Power
+ Management (&man.acpi.4;)</entry>
+ <entry>kern</entry>
+ <entry>freebsd-acpi</entry>
+ </row>
+
+ <row>
+ <entry>problem with Asynchronous Transfer Mode (ATM)
+ drivers</entry>
+ <entry>kern</entry>
+ <entry>freebsd-atm</entry>
+ </row>
+
+ <row>
+ <entry>problem with &firewire; drivers</entry>
+ <entry>kern</entry>
+ <entry>freebsd-firewire</entry>
+ </row>
+
+ <row>
+ <entry>problem with the filesystem code</entry>
+ <entry>kern</entry>
+ <entry>freebsd-fs</entry>
+ </row>
+
+ <row>
+ <entry>problem with the &man.geom.4; subsystem</entry>
+ <entry>kern</entry>
+ <entry>freebsd-geom</entry>
+ </row>
+
+ <row>
+ <entry>problem with the &man.ipfw.4; subsystem</entry>
+ <entry>kern</entry>
+ <entry>freebsd-ipfw</entry>
+ </row>
+
+ <row>
+ <entry>problem with Integrated Services Digital Network
+ (ISDN) drivers</entry>
+ <entry>kern</entry>
+ <entry>freebsd-isdn</entry>
+ </row>
+
+ <row>
+ <entry>problem with &linux; or SVR4 emulation</entry>
+ <entry>kern</entry>
+ <entry>freebsd-emulation</entry>
+ </row>
+
+ <row>
+ <entry>problem with the networking stack</entry>
+ <entry>kern</entry>
+ <entry>freebsd-net</entry>
+ </row>
+
+ <row>
+ <entry>problem with PicoBSD</entry>
+ <entry>kern</entry>
+ <entry>freebsd-small</entry>
+ </row>
+
+ <row>
+ <entry>problem with the &man.pf.4; subsystem</entry>
+ <entry>kern</entry>
+ <entry>freebsd-pf</entry>
+ </row>
+
+ <row>
+ <entry>problem with the &man.scsi.4; subsystem</entry>
+ <entry>kern</entry>
+ <entry>freebsd-scsi</entry>
+ </row>
+
+ <row>
+ <entry>problem with the &man.sound.4; subsystem</entry>
+ <entry>kern</entry>
+ <entry>freebsd-multimedia</entry>
+ </row>
+
+ <row>
+ <entry>problem with &man.sysinstall.8;</entry>
+ <entry>bin</entry>
+ <entry>freebsd-qa</entry>
+ </row>
+
+ <row>
+ <entry>problem with the system startup scripts
+ (&man.rc.8;)</entry>
+ <entry>kern</entry>
+ <entry>freebsd-rc</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table xml:id="common-assignees-ports">
+ <title>Common Assignees &mdash; Ports Collection</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Suggested Category</entry>
+ <entry>Suggested Assignee</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>problem with the ports framework
+ (<emphasis>not</emphasis> with an individual port!)</entry>
+ <entry>ports</entry>
+ <entry>portmgr</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by apache@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>apache</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by eclipse@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>freebsd-eclipse</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by gnome@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>gnome</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by haskell@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>haskell</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by java@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>freebsd-java</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by kde@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>kde</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by
+ openoffice@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>freebsd-openoffice</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by perl@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>perl</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by python@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>freebsd-python</entry>
+ </row>
+
+ <row>
+ <entry>port which is maintained by x11@FreeBSD.org</entry>
+ <entry>ports</entry>
+ <entry>freebsd-x11</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Ports PRs which have a maintainer who is a ports committer
+ may be reassigned by anyone (but note that not every &os;
+ committer is necessarily a ports committer, so you cannot
+ simply go by the email address alone.)
+ </para>
+
+ <para>For other PRs, please do not reassign them to individuals
+ (other than yourself) unless you are certain that the assignee
+ really wants to track the PR. This will help to avoid the
+ case where no one looks at fixing a particular problem
+ because everyone assumes that the assignee is already working
+ on it.</para>
+
+ </section>
+
+ <section xml:id="pr-assigned">
+ <title>Assigned PRs</title>
+
+ <para>If a PR has the <literal>responsible</literal> field set
+ to the username of a FreeBSD developer, it means that the PR
+ has been handed over to that particular person for further
+ work.</para>
+
+ <para>Assigned PRs should not be touched by anyone but the
+ assignee. If you have comments, submit a followup. If for
+ some reason you think the PR should change state or be
+ reassigned, send a message to the assignee. If the assignee
+ does not respond within two weeks, unassign the PR and do as
+ you please.</para>
+ </section>
+
+ <section xml:id="pr-dups">
+ <title>重複的 PR</title>
+
+ <para>If you find more than one PR that describe the same issue,
+ choose the one that contains the largest amount of useful
+ information and close the others, stating clearly the number
+ of the superseding PR. If several PRs contain non-overlapping
+ useful information, submit all the missing information to one
+ in a followup, including references to the others; then close
+ the other PRs (which are now completely superseded).</para>
+ </section>
+
+ <section xml:id="pr-stale">
+ <title>Stale PRs</title>
+
+ <para>A PR is considered stale if it has not been modified in more
+ than six months. Apply the following procedure to deal with
+ stale PRs:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If the PR contains sufficient detail, try to reproduce
+ the problem in <literal>-CURRENT</literal> and
+ <literal>-STABLE</literal>. If you succeed, submit a
+ followup detailing your findings and try to find someone
+ to assign it to. Set the state to <quote>analyzed</quote>
+ if appropriate.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the PR describes an issue which you know is the
+ result of a usage error (incorrect configuration or
+ otherwise), submit a followup explaining what the
+ originator did wrong, then close the PR with the reason
+ <quote>User error</quote> or <quote>Configuration
+ error</quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the PR describes an error which you know has been
+ corrected in both <literal>-CURRENT</literal> and
+ <literal>-STABLE</literal>, close it with a message
+ stating when it was fixed in each branch.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the PR describes an error which you know has been
+ corrected in <literal>-CURRENT</literal>, but not in
+ <literal>-STABLE</literal>, try to find out when the person
+ who corrected it is planning to MFC it, or try to find
+ someone else (maybe yourself?) to do it. Set the state to
+ <quote>feedback</quote> and assign it to whomever will do
+ the MFC.</para>
+ </listitem>
+
+ <listitem>
+ <para>In other cases, ask the originator to confirm if
+ the problem still exists in newer versions. If the
+ originator does not reply within a month, close the PR
+ with the notation <quote>Feedback timeout</quote>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="pr-misfiled">
+ <title>Misfiled PRs</title>
+
+ <para>GNATS is picky about the format of a submitted bug report.
+ This is why a lot of PRs end up being <quote>misfiled</quote> if
+ the submitter forgets to fill in a field or puts the wrong sort of
+ data in some of the PR fields. This section aims to provide most
+ of the necessary details for FreeBSD developers that can help them to
+ close or refile these PRs.</para>
+
+ <para>When GNATS cannot deduce what to do with a problem report
+ that reaches the database, it sets the responsible of the PR to
+ <literal>gnats-admin</literal> and files it under the
+ <literal>pending</literal> category. This is now a
+ <quote>misfiled</quote> PR and will not appear in bug report
+ listings, unless someone explicitly asks for a list of all the
+ misfiled PRs. If you have access to the FreeBSD cluster
+ machines, you can use <command>query-pr</command> to view a
+ listing of PRs that have been misfiled:</para>
+
+ <screen>&prompt.user; <userinput>query-pr -x -q -r gnats-admin</userinput>
+ 52458 gnats-ad open serious medium Re: declaration clash f
+ 52510 gnats-ad open serious medium Re: lots of sockets in
+ 52557 gnats-ad open serious medium
+ 52570 gnats-ad open serious medium Jigdo maintainer update</screen>
+
+ <para>Commonly PRs like the ones shown above are misfiled for one
+ of the following reasons:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A followup to an existing PR, sent through email, has
+ the wrong format on its <literal>Subject:</literal>
+ header.</para>
+ </listitem>
+
+ <listitem>
+ <para>A submitter sent a Cc: to a mailing list and someone
+ followed up to that post instead of the email issued by
+ GNATS after processing. The email to the list will not
+ have the category/PRnumber tracking tag. (This is why we
+ discourage submitters from doing this exact thing.)</para>
+ </listitem>
+
+ <listitem>
+ <para>When completing the &man.send-pr.1; template, the submitter
+ forgot to set the category or class of the PR to a proper
+ value.</para>
+ </listitem>
+
+ <listitem>
+ <para>When completing the &man.send-pr.1; template, the submitter
+ set Confidential to <literal>yes</literal>. (Since we allow
+ anyone to mirror GNATS via <application>cvsup</application>,
+ our PRs are public information. Security alerts should
+ therefore not be sent via GNATS but instead via email to
+ the Security Team.)</para>
+ </listitem>
+
+ <listitem>
+ <para>It is not a real PR, but some random message sent to
+ <email>bug-followup@FreeBSD.org</email> or
+ <email>freebsd-gnats-submit@FreeBSD.org</email>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section xml:id="pr-misfiled-followups">
+ <title>Followups misfiled as new PRs</title>
+
+ <para>The first category of misfiled PRs, the one with the wrong
+ subject header, is actually the one that requires the greatest
+ amount of work from developers. These are not real PRs,
+ describing separate problem reports. When a reply is received
+ for an existing PR at one of the addresses that GNATS
+ <quote>listens</quote> to for incoming messages, the subject
+ of the reply should always be of the form:</para>
+
+ <programlisting>Subject: Re: category/number: old synopsis text</programlisting>
+
+ <para>Most mailers will add the
+ <quote><literal>Re:&nbsp;</literal></quote> part when you
+ reply to the original mail message of a PR. The
+ <quote><literal>category/number:&nbsp;</literal></quote> part
+ is a GNATS-specific convention that you have to manually
+ insert to the subject of your followup reports.</para>
+
+ <para>Any FreeBSD developer, who has direct access to the GNATS
+ database, can periodically check for PRs of this sort and move
+ interesting bits of the misfiled PR into the audit trail of
+ the original PR (by posting a proper followup to a bug report
+ to the address &a.bugfollowup;). Then
+ the misfiled PR can be closed with a message similar
+ to:</para>
+
+ <programlisting>Your problem report was misfiled. Please use the format
+"Subject: category/number: original text" when following
+up to older, existing PRs. I've added the relevant bits
+from the body of this PR to kern/12345</programlisting>
+
+ <para>Searching with <command>query-pr</command> for the
+ original PR, of which a misfiled followup is a reply, is as
+ easy as running:</para>
+
+ <screen>&prompt.user; query-pr -q -y "some text"</screen>
+
+ <para>After you locate the original PR and the misfiled
+ followups, use the <option>-F</option> option of
+ <command>query-pr</command> to save the full text of all the
+ relevant PRs in a &unix; mailbox file, i.e.:</para>
+
+ <screen>&prompt.user; <userinput>query-pr -F 52458 52474 &gt; mbox</userinput></screen>
+
+ <para>Now you can use any mail user agent to view all the PRs
+ you saved in <filename>mbox</filename>. Copy the text of all
+ the misfiled PRs in a followup to the original PR and make
+ sure you include the proper <literal>Subject:</literal>
+ header. Then close the misfiled PRs. When you close the misfiled
+ PRs remember that the submitter receives a mail notification that
+ his PR changed state to <quote>closed</quote>. Make sure you
+ provide enough details in the log about the reason of this state
+ change. Typically something like the following is ok:</para>
+
+ <programlisting>Followup to ports/45364 misfiled as a new PR.
+This was misfiled because the subject did not have the format:
+
+ Re: ports/45364: ...</programlisting>
+
+ <para>This way the submitter of the misfiled PR will know what to
+ avoid the next time a followup to an existing PR is sent.</para>
+ </section>
+
+ <section xml:id="pr-misfiled-format">
+ <title>PRs misfiled because of missing fields</title>
+
+ <para>The second type of misfiled PRs is usually the result of a
+ submitter forgetting to fill all the necessary fields when
+ writing the original PR.</para>
+
+ <para>Missing or bogus <quote>category</quote> or
+ <quote>class</quote> fields can result in a misfiled report.
+ Developers can use &man.edit-pr.1; to change the category or
+ class of these misfiled PRs to a more appropriate value and
+ save the PR.</para>
+
+ <para>Another common cause of misfiled PRs because of formatting
+ issues is quoting, changes or removal of the
+ <command>send-pr</command> template, either by the user who
+ edits the template or by mailers which do strange things to
+ plain text messages. This does not happen a lot of the time,
+ but it can be fixed with <command>edit-pr</command> too; it
+ does require a bit of work from the developer who refiles the
+ PR, but it is relatively easy to do most of the time.</para>
+ </section>
+
+ <section xml:id="pr-misfiled-notpr">
+ <title>Misfiled PRs that are not really problem reports</title>
+
+ <para>Sometimes a user wants to submit a report for a problem
+ and sends a simple email message to GNATS. The GNATS scripts
+ will recognize bug reports that are formatted using the
+ &man.send-pr.1; template. They cannot parse any sort of email
+ though. This is why submissions of bug reports that are sent
+ to <email>freebsd-gnats-submit@FreeBSD.org</email> have to
+ follow the template of <command>send-pr</command>, but email
+ reports can be sent to &a.bugs;.</para>
+
+ <para>Developers that come across PRs that look like they should have
+ been posted to &a.bugs.name; or some other list should close the
+ PR, informing the submitter in their state-change log why this
+ is not really a PR and where the message should be posted.</para>
+
+ <para>The email addresses that GNATS listens to for incoming PRs
+ have been published as part of the FreeBSD documentation, have
+ been announced and listed on the web-site. This means that
+ spammers found them. Spam messages
+ that reach GNATS are promptly filed
+ under the <quote>pending</quote> category until someone looks
+ at them. Closing one of these with &man.edit-pr.1; is very
+ annoying though, because GNATS replies to the submitter and
+ the sender's address of spam mail is never valid these days.
+ Bounces will come back for each PR that is closed.</para>
+
+ <para>Currently, with the installation of some antispam filters
+ that check all submissions to the GNATS database, the amount
+ of spam that reaches the <quote>pending</quote> state is very
+ small.</para>
+
+ <para>All developers who have access to the FreeBSD.org cluster
+ machines are encouraged to check for misfiled PRs and immediately
+ close those that are spam mail. Whenever you close one of
+ these PRs, please do the following:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Set Category to <literal>junk</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set Confidential to <literal>no</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set Responsible to yourself (and not, e.g.,
+ <literal>freebsd-bugs</literal>, which merely
+ sends more mail).</para>
+ </listitem>
+
+ <listitem>
+ <para>Set State to <literal>closed</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Junk PRs are not
+ backed up, so filing spam mail under this category makes it
+ obvious that we do not care to keep it around or waste disk
+ space for it. If you merely close them without changing the
+ category, they remain both in the master database and in
+ any copies of the database mirrored through
+ <application>cvsup</application>.</para>
+ </section>
+ </section>
+ </section>
+
+ <section xml:id="references">
+ <title>延伸閱讀</title>
+
+ <para>下面這是在寫、處理 PR 時,可以參考的資料。當然很明顯,這份清單仍須補充。</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link xlink:href="&url.articles.problem-reports;/article.html">How to
+ Write FreeBSD Problem Reports</link>&mdash;給 PR 回報者用的參考原則。</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</article>
diff --git a/zh_TW.UTF-8/articles/problem-reports/Makefile b/zh_TW.UTF-8/articles/problem-reports/Makefile
new file mode 100644
index 0000000000..ab12340558
--- /dev/null
+++ b/zh_TW.UTF-8/articles/problem-reports/Makefile
@@ -0,0 +1,19 @@
+#
+# $FreeBSD$
+#
+# Article: Writing FreeBSD Problem Reports
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?=gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.xml
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/problem-reports/article.xml b/zh_TW.UTF-8/articles/problem-reports/article.xml
new file mode 100644
index 0000000000..ebacf3e366
--- /dev/null
+++ b/zh_TW.UTF-8/articles/problem-reports/article.xml
@@ -0,0 +1,1103 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <info><title>Writing &os; Problem Reports</title>
+
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.cvsup;
+ &tm-attrib.ibm;
+ &tm-attrib.intel;
+ &tm-attrib.sparc;
+ &tm-attrib.sun;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <abstract>
+ <para>This article describes how to best formulate and submit a
+ problem report to the &os; Project.</para>
+ </abstract>
+
+ <authorgroup>
+ <author><personname><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></personname><contrib>Contributed by </contrib></author>
+
+ <author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
+ </authorgroup>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+ </info>
+
+ <indexterm><primary>problem reports</primary></indexterm>
+
+ <section xml:id="pr-intro">
+ <title>Introduction</title>
+
+ <para>One of the most frustrating experiences one can have as a
+ software user is to submit a problem report only to have it
+ summarily closed with a terse and unhelpful explanation like
+ <quote>not a bug</quote> or <quote>bogus PR</quote>. Similarly,
+ one of the most frustrating experiences as a software developer
+ is to be flooded with problem reports that are not really
+ problem reports but requests for support, or that contain little
+ or no information about what the problem is and how to reproduce
+ it.</para>
+
+ <para>This document attempts to describe how to write good problem
+ reports. What, you ask, is a good problem report? Well, to go
+ straight to the bottom line, a good problem report is one that
+ can be analyzed and dealt with swiftly, to the mutual
+ satisfaction of both user and developer.</para>
+
+ <para>Although the primary focus of this article is on &os;
+ problem reports, most of it should apply quite well to other
+ software projects.</para>
+
+ <para>Note that this article is organized thematically, not
+ chronologically, so you should read through the entire document
+ before submitting a problem report, rather than treat it as a
+ step-by-step tutorial.</para>
+ </section>
+
+ <section xml:id="pr-when">
+ <title>When to submit a problem report</title>
+
+ <para>There are many types of problems, and not all of them should
+ engender a problem report. Of course, nobody is perfect, and
+ there will be times when you are convinced you have found a bug
+ in a program when in fact you have misunderstood the syntax for
+ a command or made a typographical error in a configuration file
+ (though that in
+ itself may sometimes be indicative of poor documentation or poor
+ error handling in the application). There are still many cases
+ where submitting a problem report is clearly
+ <emphasis>not</emphasis> the right
+ course of action, and will only serve to frustrate you and the
+ developers. Conversely, there are cases where it might be
+ appropriate to submit a problem report about something else than
+ a bug&mdash;an enhancement or a feature request, for
+ instance.</para>
+
+ <para>So how do you determine what is a bug and what is not? As a
+ simple rule of thumb your problem is <emphasis>not</emphasis> a
+ bug if it can be expressed as a question (usually of the form
+ <quote>How do I do X?</quote> or <quote>Where can I find
+ Y?</quote>). It is not always quite so black and white, but the
+ question rule covers a large majority of cases. If you are looking
+ for an answer, consider posing your question to the
+ &a.questions;.</para>
+
+ <para>Some cases where it may be appropriate to submit a problem
+ report about something that is not a bug are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Requests for feature enhancements. It is generally a
+ good idea to air these on the mailing lists before
+ submitting a problem report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Notification of updates to externally maintained
+ software (mainly ports, but also externally maintained base
+ system components such as BIND or various GNU
+ utilities).</para>
+
+ <para>For unmaintained ports (<varname>MAINTAINER</varname> contains
+ <literal>ports@FreeBSD.org</literal>), such update notifications
+ might get picked up by an interested
+ committer, or you might be asked to provide a patch to update
+ the port; providing it upfront will greatly improve your chances
+ that the port will get updated in a timely manner.</para>
+
+ <para>If the port is maintained, PRs announcing new upstream releases
+ are usually not very useful since they generate supplementary work
+ for the committers, and the maintainer likely knows already there is
+ a new version, they have probably worked with the developers on it,
+ they are probably testing to see there is no regression, etc.</para>
+
+ <para>In either case, following the process described in <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's
+ Handbook</link> will yield the best results.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A bug that can not be reproduced can rarely be
+ fixed. If the bug only occurred once and you can not reproduce
+ it, and it does not seem to happen to anybody else, chances are
+ none of the developers will be able to reproduce it or figure
+ out what is wrong. That does not mean it did not happen, but it
+ does mean that the chances of your problem report ever leading
+ to a bug fix are very slim. To make matters worse, often
+ these kinds of bugs are actually caused by failing hard drives
+ or overheating processors &mdash; you should always try to rule
+ out these causes, whenever possible, before submitting a PR.</para>
+
+ <para>Next, to decide to whom you should file your problem
+ report, you need to understand that the software that makes
+ up &os; is composed of several different elements:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Code in the base system that is written and maintained
+ by &os; contributors, such as the kernel, the C library,
+ and the device drivers (categorized as <literal>kern</literal>);
+ the binary utilities (<literal>bin</literal>); the manual
+ pages and documentation (<literal>docs</literal>); and
+ the web pages (<literal>www</literal>). All bugs in
+ these areas should be reported to the &os; developers.</para>
+ </listitem>
+
+ <listitem>
+ <para>Code in the base system that is written and maintained
+ by others, and imported into &os; and adapted. Examples
+ include <application>bind</application>, &man.gcc.1;, and
+ &man.sendmail.8;. Most bugs in these areas should be reported
+ to the &os; developers; but in some cases they may need to be
+ reported to the original authors instead if the problems are
+ not &os;-specific. Usually these bugs will fall under either
+ the <literal>bin</literal> or <literal>gnu</literal>
+ categories.</para>
+ </listitem>
+
+ <listitem>
+ <para>Individual applications that are not in the base system
+ but are instead part of the &os; Ports Collection (category
+ <literal>ports</literal>). Most of these applications are
+ not written by &os; developers; what &os; provides is merely
+ a framework for installing the application. Therefore, you
+ should only report a problem to the &os; developers when you
+ believe the problem is &os;-specific; otherwise, you should
+ report it to the authors of the software.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Then you should ascertain whether or not the problem is
+ timely. There are few things
+ that will annoy a developer more than receiving a problem report
+ about a bug she has already fixed.</para>
+
+ <para>If the problem is in the base system, you should first read
+ the FAQ section on
+ <link xlink:href="&url.books.faq;/introduction.html#LATEST-VERSION">
+ &os; versions</link>, if you are not already familiar with
+ the topic. It is not possible for &os; to fix problems in
+ anything other than certain recent branches of the base system,
+ so filing a bug report about an older version will probably
+ only result in a developer advising you to upgrade to a
+ supported version to see if the problem still recurs. The
+ Security Officer team maintains the
+ <link xlink:href="http://www.freebsd.org/security/">list of supported
+ versions</link>.</para>
+
+ <para>If the problem is in a port, note that you must first
+ upgrade to the latest version of the Ports Collection and see
+ if the problem still applies. Due to the rapid pace of changes
+ in these applications, it is infeasible for &os; to support
+ anything other than the absolute latest versions, and problems
+ with older version of applications simply cannot be fixed.</para>
+ </section>
+
+ <section xml:id="pr-prep">
+ <title>Preparations</title>
+
+ <para>A good rule to follow is to always do a background search
+ before submitting a problem report. Maybe your problem has
+ already been reported; maybe it is being discussed on the
+ mailing lists, or recently was; it may even already be fixed in
+ a newer version than what you are running. You should therefore
+ check all the obvious places before submitting your problem
+ report. For &os;, this means:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The &os;
+ <link xlink:href="&url.books.faq;/index.html">Frequently Asked
+ Questions</link> (FAQ) list.
+ The FAQ attempts to provide answers for a wide range of questions,
+ such as those concerning
+ <link xlink:href="&url.books.faq;/hardware.html">hardware
+ compatibility</link>,
+ <link xlink:href="&url.books.faq;/applications.html">user
+ applications</link>,
+ and <link xlink:href="&url.books.faq;/kernelconfig.html">kernel
+ configuration</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The
+ <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing
+ lists</link>&mdash;if you are not subscribed, use
+ <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">the
+ searchable archives</link> on the &os; web site. If your
+ problem has not been discussed on the lists, you might try
+ posting a message about it and waiting a few days to see if
+ someone can spot something you have overlooked.</para>
+ </listitem>
+
+ <listitem>
+ <para>Optionally, the entire web&mdash;use your favorite
+ search engine to locate any references to your problem. You
+ may even get hits from archived mailing lists or newsgroups
+ you did not know of or had not thought to search
+ through.</para>
+ </listitem>
+
+ <listitem>
+ <para>Next, the searchable
+ <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
+ &os; PR database</link> (GNATS). Unless your problem
+ is recent or obscure, there is a fair chance it has already
+ been reported.</para>
+ </listitem>
+
+ <listitem>
+ <para>Most importantly, you should attempt to see if existing
+ documentation in the source base addresses your problem.</para>
+
+ <para>For the base &os; code, you should
+ carefully study the contents of the
+ <filename>/usr/src/UPDATING</filename> file on your system
+ or its latest version at
+ <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING">http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING</uri>.
+ (This is vital information
+ if you are upgrading from one version to
+ another&mdash;especially if you are upgrading to the
+ &os.current; branch).</para>
+
+ <para>However, if the problem is in something that was installed
+ as a part of the &os; Ports Collection, you should refer to
+ <filename>/usr/ports/UPDATING</filename> (for individual ports)
+ or <filename>/usr/ports/CHANGES</filename> (for changes
+ that affect the entire Ports Collection).
+ <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING">http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING</uri>
+ and
+ <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES">http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES</uri>
+ are also available via CVSweb.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="pr-writing">
+ <title>Writing the problem report</title>
+
+ <para>Now that you have decided that your issue merits a problem
+ report, and that it is a &os; problem, it is time to write
+ the actual problem report. Before we get into the mechanics
+ of the program used to generate and submit PRs, here are some
+ tips and tricks to help make sure that your PR will be most
+ effective.</para>
+
+ <section>
+ <title>Tips and tricks for writing a good problem report</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Do not leave the <quote>Synopsis</quote>
+ line empty.</emphasis> The PRs go both onto a mailing list
+ that goes all over the world (where the <quote>Synopsis</quote>
+ is used
+ for the <literal>Subject:</literal> line), but also into a
+ database. Anyone who comes along later and browses the
+ database by synopsis, and finds a PR with a blank subject
+ line, tends just to skip over it. Remember that PRs stay
+ in this database until they are closed by someone; an
+ anonymous one will usually just disappear in the
+ noise.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Avoid using a weak <quote>Synopsis</quote>
+ line.</emphasis> You should not assume that anyone reading
+ your PR has any context for your submission, so the more
+ you provide, the better. For instance, what part of the
+ system does the problem apply to? Do you only see the
+ problem while installing, or while running? To
+ illustrate, instead of <literal>Synopsis: portupgrade is
+ broken</literal>, see how much more informative this
+ seems: <literal>Synopsis: port sysutils/portupgrade
+ coredumps on -current</literal>. (In the case of ports,
+ it is especially helpful to have both the category and
+ portname in the <quote>Synopsis</quote> line.)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>If you have a patch, say so.</emphasis>
+ A PR with a patch included is much more likely to be
+ looked at than one without. If you are including one,
+ put the string <literal>[patch]</literal> at the
+ beginning of the <quote>Synopsis</quote>. (Although it is
+ not mandatory to use that exact string, by convention,
+ that is the one that is used.)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>If you are a maintainer, say so.</emphasis>
+ If you are maintaining a part of the source code (for
+ instance, a port), you might consider adding the string
+ <literal>[maintainer update]</literal> at the beginning of
+ your synopsis line, and you definitely should set the
+ <quote>Class</quote> of
+ your PR to <literal>maintainer-update</literal>. This way
+ any committer that handles your PR will not have to check.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Be specific.</emphasis>
+ The more information you supply about what problem you
+ are having, the better your chance of getting a response.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Include the version of &os; you are running (there
+ is a place to put that, see below) and on which architecture.
+ You should include whether you are running from a release
+ (e.g. from a CDROM or download), or from
+ a system maintained by &man.cvsup.1; (and, if so, how
+ recently you updated). If you are tracking the
+ &os.current; branch, that is the very first thing someone
+ will ask, because fixes (especially for high-profile
+ problems) tend to get committed very quickly, and
+ &os.current; users are expected to keep up.</para>
+ </listitem>
+
+ <listitem>
+ <para>Include which global options you have specified in
+ your <filename>make.conf</filename>. Note: specifying
+ <literal>-O2</literal> and above to &man.gcc.1; is
+ known to be buggy in many situations. While the
+ &os; developers will accept patches, they are
+ generally unwilling to investigate such issues due
+ to simple lack of time and volunteers, and may
+ instead respond that this just is not supported.</para>
+ </listitem>
+
+ <listitem>
+ <para>If this is a kernel problem, then be prepared to
+ supply the following information. (You do not
+ have to include these by default, which only tends to
+ fill up the database, but you should include excerpts
+ that you think might be relevant):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>your kernel configuration (including which
+ hardware devices you have installed)</para>
+ </listitem>
+ <listitem>
+ <para>whether or not you have debugging options enabled
+ (such as <literal>WITNESS</literal>), and if so,
+ whether the problem persists when you change the
+ sense of that option</para>
+ </listitem>
+ <listitem>
+ <para>a backtrace, if one was generated</para>
+ </listitem>
+ <listitem>
+ <para>the fact that you have read
+ <filename>src/UPDATING</filename> and that your problem
+ is not listed there (someone is guaranteed to ask)</para>
+ </listitem>
+ <listitem>
+ <para>whether or not you can run any other kernel as
+ a fallback (this is to rule out hardware-related
+ issues such as failing disks and overheating CPUs,
+ which can masquerade as kernel problems)</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>If this is a ports problem, then be prepared to
+ supply the following information. (You do not
+ have to include these by default, which only tends to
+ fill up the database, but you should include excerpts
+ that you think might be relevant):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>which ports you have installed</para>
+ </listitem>
+ <listitem>
+ <para>any environment variables that override the
+ defaults in <filename>bsd.port.mk</filename>, such
+ as <varname>PORTSDIR</varname></para>
+ </listitem>
+ <listitem>
+ <para>the fact that you have read
+ <filename>ports/UPDATING</filename> and that your problem
+ is not listed there (someone is guaranteed to ask)</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ </itemizedlist>
+
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Avoid vague requests for features.</emphasis>
+ PRs of the form <quote>someone should really implement something
+ that does so-and-so</quote> are less likely to get results than
+ very specific requests. Remember, the source is available
+ to everyone, so if you want a feature, the best way to
+ ensure it being included is to get to work! Also consider
+ the fact that many things like this would make a better
+ topic for discussion on <literal>freebsd-questions</literal>
+ than an entry in the PR database, as discussed above.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Make sure no one else has already submitted
+ a similar PR.</emphasis> Although this has already been
+ mentioned above, it bears repeating here. It only take a
+ minute or two to use the web-based search engine at
+ <uri xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri>.
+ (Of course, everyone is guilty of forgetting to do this
+ now and then.)</para> </listitem>
+
+ <listitem>
+ <para><emphasis>Avoid controversial requests.</emphasis>
+ If your PR addresses an area that has been controversial
+ in the past, you should probably be prepared to not only
+ offer patches, but also justification for why the patches
+ are <quote>The Right Thing To Do</quote>. As noted above,
+ a careful search of the mailing lists using the archives
+ at <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
+ is always good preparation.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Be polite.</emphasis>
+ Almost anyone who would potentially work on your PR is a
+ volunteer. No one likes to be told that they have to do
+ something when they are already doing it for some
+ motivation other than monetary gain. This is a good thing
+ to keep in mind at all times on Open Source
+ projects.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Before you begin</title>
+
+ <para>If you are using the &man.send-pr.1; program, make sure your
+ <envar>VISUAL</envar> (or <envar>EDITOR</envar> if
+ <envar>VISUAL</envar> is not set) environment variable is set
+ to something sensible.</para>
+
+ <para>You should also make sure that mail delivery works fine.
+ &man.send-pr.1; uses mail messages for the submission and
+ tracking of problem reports. If you cannot post mail messages
+ from the machine you are running &man.send-pr.1; on, your
+ problem report will not reach the GNATS database. For details
+ on the setup of mail on &os;, see the <quote>Electronic
+ Mail</quote> chapter of the &os; Handbook at
+ <uri xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html</uri>.</para>
+
+ <para>Make sure that your mailer will not mangle the message on
+ its way to GNATS. In particular, if your mailer automatically
+ breaks lines, changes tabs to spaces, or escapes newline
+ characters, any patch that you submit will be rendered
+ unusable. For the text sections, however, we request that
+ you insert manual linebreaks somewhere around 70 characters,
+ so that the web display of the PR will be readable.</para>
+
+ <para>Similar considerations apply if you are using the web-based
+ PR submittal form instead of &man.send-pr.1;. Note that
+ cut-and-paste operations can have their own side-effects on
+ text formatting. In certain cases it may be necessary to use
+ &man.uuencode.1; to ensure that patches arrive unmodified.</para>
+
+ <para>Finally, if your submission will be lengthy, you should
+ to prepare your work offline so that nothing will be lost in
+ case there is a problem submitting it. This can be an especial
+ problem with the web form.</para>
+ </section>
+
+ <section>
+ <title>Attaching patches or files</title>
+
+ <para>The following applies to submitting PRs via email:</para>
+
+ <para>The &man.send-pr.1; program has provisions for attaching
+ files to a problem report. You can attach as many files as
+ you want provided that each has a unique base name (i.e. the
+ name of the file proper, without the path). Just use the
+ <option>-a</option> command-line option to specify the names
+ of the files you wish to attach:</para>
+
+<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen>
+
+ <para>Do not worry about binary files, they will be automatically
+ encoded so as not to upset your mail agent.</para>
+
+ <para>If you attach a patch, make sure you use the
+ <option>-c</option> or <option>-u</option> option to
+ &man.diff.1; to create a context or unified diff (unified is
+ preferred), and make
+ sure to specify the exact CVS revision numbers of the files
+ you modified so the developers who read your report will be
+ able to apply them easily. For problems with the kernel or the
+ base utilities, a patch against &os.current; (the HEAD
+ CVS branch) is preferred since all new code should be applied
+ and tested there first. After appropriate or substantial testing
+ has been done, the code will be merged/migrated to the &os.stable;
+ branch.</para>
+
+ <para>If you attach a patch inline, instead of as an attachment,
+ note that the most common problem by far is the tendency of some
+ email programs to render tabs as spaces, which will completely
+ ruin anything intended to be part of a Makefile.</para>
+
+ <para>Do not send patches as attachments using
+ <command>Content-Transfer-Encoding: quoted-printable</command>.
+ These will perform character escaping and the entire patch
+ will be useless.</para>
+
+ <para>Also note that while including small patches in a PR is
+ generally all right&mdash;particularly when they fix the problem
+ described in the PR&mdash;large patches and especially new code
+ which may require substantial review before committing should
+ be placed on a web or ftp server, and the URL should be
+ included in the PR instead of the patch. Patches in email
+ tend to get mangled, especially when GNATS is involved, and
+ the larger the patch, the harder it will be for interested
+ parties to unmangle it. Also, posting a patch on the web
+ allows you to modify it without having to resubmit the entire
+ patch in a followup to the original PR. Finally, large
+ patches simply increase the size of the database, since
+ closed PRs are not actually deleted but instead kept and
+ simply marked as <literal>closed</literal>.</para>
+
+ <para>You should also take note that unless you explicitly
+ specify otherwise in your PR or in the patch itself, any
+ patches you submit will be assumed to be licensed under the
+ same terms as the original file you modified.</para>
+ </section>
+
+ <section>
+ <title>Filling out the template</title>
+
+ <para>The next section applies to the email method only:</para>
+
+ <para>When you run &man.send-pr.1;, you are presented with a
+ template. The template consists of a list of fields, some of
+ which are pre-filled, and some of which have comments explaining
+ their purpose or listing acceptable values. Do not worry
+ about the comments; they will be removed automatically if you
+ do not modify them or remove them yourself.</para>
+
+ <para>At the top of the template, below the
+ <literal>SEND-PR:</literal> lines, are the email headers. You
+ do not normally need to modify these, unless you are sending
+ the problem report from a machine or account that can send but
+ not receive mail, in which case you will want to set the
+ <literal>From:</literal> and <literal>Reply-To:</literal> to
+ your real email address. You may also want to send yourself
+ (or someone else) a carbon copy of the problem report by
+ adding one or more email addresses to the
+ <literal>Cc:</literal> header.</para>
+
+ <para>In the email template you will find the following two
+ single-line fields:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Submitter-Id:</emphasis> Do not change this.
+ The default value of <literal>current-users</literal> is
+ correct, even if you run &os.stable;.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Confidential:</emphasis> This is prefilled
+ to <literal>no</literal>. Changing it makes no sense as
+ there is no such thing as a confidential &os; problem
+ report&mdash;the PR database is distributed worldwide by
+ <application>CVSup</application>.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>The next section describes fields that are common to both
+ the email interface and the web interface:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><emphasis>Originator:</emphasis>
+ Please specify your real name, optionally followed
+ by your email address in angle brackets.
+ In the email interface, this is normally
+ prefilled with the <literal>gecos</literal> field of the
+ currently logged-in
+ user.</para>
+
+ <note>
+ <para>The email address you use will become public information
+ and may become available to spammers. You should either
+ have spam handling procedures in place, or use a temporary
+ email account. However, please note that if you do not
+ use a valid email account at all, we will not be able to
+ ask you questions about your PR.</para>
+ </note>
+
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Organization:</emphasis> Whatever you feel
+ like. This field is not used for anything
+ significant.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Synopsis:</emphasis> Fill this out with a
+ short and accurate description of the problem. The
+ synopsis is used as the subject of the problem report
+ email, and is used in problem report listings and
+ summaries; problem reports with obscure synopses tend to
+ get ignored.</para>
+
+ <para>As noted above, if your problem report includes a patch,
+ please have the synopsis start with <literal>[patch]</literal>;
+ if this is a ports PR and you are the
+ maintainer, you may consider adding
+ <literal>[maintainer update]</literal> and set the
+ <quote>Class</quote> of your PR to
+ <literal>maintainer-update</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Severity:</emphasis> One of
+ <literal>non-critical</literal>,
+ <literal>serious</literal> or
+ <literal>critical</literal>. Do not overreact; refrain
+ from labeling your problem <literal>critical</literal>
+ unless it really is (e.g. data corruption issues, serious
+ regression from previous functionality in -CURRENT)
+ or <literal>serious</literal> unless
+ it is something that will affect many users (kernel
+ panics or freezes; problems with
+ particular device drivers or system utilities). &os;
+ developers will not necessarily work on your problem faster
+ if you inflate its importance since there are so many other
+ people who have done exactly that &mdash; in fact, some
+ developers pay little attention to this field
+ because of this.</para>
+
+ <note>
+ <para>Major security problems should <emphasis>not</emphasis>
+ be filed in GNATS, because all GNATS information is public
+ knowledge. Please send such problems in private email to
+ &a.security-officer;.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Priority:</emphasis> One of
+ <literal>low</literal>, <literal>medium</literal> or
+ <literal>high</literal>. <literal>high</literal> should
+ be reserved for problems that will affect practically
+ every user of &os; and <literal>medium</literal> for
+ something that will affect many users.</para>
+
+ <note>
+ <para>This field has become so widely abused that it is
+ almost completely meaningless.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Category:</emphasis> Choose an appropriate
+ category.</para>
+
+ <note>
+ <para>There are a number of "platform" categories into which
+ bugs in the base system that are specific to one particular
+ hardware architecture should be filed. Problems that are
+ generic all across versions of &os; should probably be
+ filed as <literal>kern</literal> or <literal>bin</literal>;
+ see discussion of those categories below.</para>
+
+ <para>Example: you have a common PC-based machine, and think
+ you have encountered a problem specific to a particular
+ chipset or a particular motherboard: <literal>i386</literal>
+ is the right category.</para>
+
+ <para>Example: You are having a problem with an add-in
+ peripheral card on a commonly seen bus, or a problem with
+ a particular type of hard disk drive: in this case, it
+ probably applies to more than one architecture, and
+ <literal>kern</literal> is the right category.</para>
+ </note>
+
+ <para>Here is the current list of categories (taken from
+ <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories">http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories</uri>):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>advocacy:</literal> problems relating to
+ &os;'s public image. Rarely used.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>alpha:</literal> problems specific to the
+ Alpha platform.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>amd64:</literal> problems specific to the
+ AMD64 platform.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>bin:</literal> problems with userland
+ programs in the base system. If running &man.whereis.1;
+ shows <literal>/bin</literal>, <literal>/usr/sbin</literal>,
+ or something similar, then this is probably the right
+ category. (A few contributed programs might instead
+ need to be in <literal>gnu</literal>; see below.)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>conf:</literal> problems with
+ configuration files, default values, and so forth.
+ Things that affect <literal>/usr/share</literal>
+ or <literal>/etc/rc*</literal> belong here.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>docs:</literal> problems with manual pages
+ or on-line documentation.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>gnu:</literal> problems with imported GNU software
+ such as &man.gcc.1; or &man.grep.1;.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>i386:</literal> problems specific to the
+ &i386; platform.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>ia64:</literal> problems specific to the
+ ia64 platform.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>java:</literal> problems related to the &java;
+ Virtual Machine. (Ports that merely depend on &java; to
+ run should be filed under <literal>ports</literal>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><literal>kern:</literal> problems with
+ the kernel, (non-platform-specific) device drivers,
+ or the base libraries.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>misc:</literal> anything that does not fit
+ in any of the other categories. (Note that there is
+ almost nothing that truly belongs in this category,
+ except for problems with the release and build
+ infrastructure. Temporary build failures on
+ <literal>HEAD</literal> do not belong here. Also note
+ that it is
+ easy for things to get lost in this category).</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>ports:</literal> problems relating to the
+ ports tree.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>powerpc:</literal> problems specific to the
+ &powerpc; platform.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>sparc64:</literal> problems specific to the
+ &sparc64; platform.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>standards:</literal> Standards conformance
+ issues.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>threads:</literal> problems related to the
+ &os; threads implementation (especially on &os.current;).</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>usb:</literal> problems related to the
+ &os; USB implementation.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>www:</literal> Changes or enhancements to
+ the &os; website.
+ Problems with code found in <literal>/usr/ports/www</literal>
+ do <emphasis>not</emphasis> belong here, they belong in
+ <literal>ports</literal> instead.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Class:</emphasis> Choose one of the
+ following:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>sw-bug:</literal> software bugs.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>doc-bug:</literal> errors in
+ documentation.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>change-request:</literal> requests for
+ additional features or changes in existing
+ features.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>update:</literal> updates to ports or
+ other contributed software.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>maintainer-update:</literal> updates to
+ ports for which you are the maintainer.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Release:</emphasis> The version of &os;
+ that you are running. This is filled out automatically if
+ you are using
+ &man.send-pr.1; and need only be changed if you are
+ sending a problem report from a different system than the
+ one that exhibits the problem.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Finally, there is a series of multi-line fields:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Environment:</emphasis> This should
+ describe, as accurately as possible, the environment in
+ which the problem has been observed. This includes the
+ operating system version, the version of the specific
+ program or file that contains the problem, and any other
+ relevant items such as system configuration, other
+ installed software that influences the problem,
+ etc.&mdash;quite simply everything a developer needs to
+ know to reconstruct the environment in which the problem
+ occurs.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Description:</emphasis> A complete and
+ accurate description of the problem you are experiencing.
+ Try to avoid speculating about the causes of the problem
+ unless you are certain that you are on the right track, as
+ it may mislead a developer into making incorrect
+ assumptions about the problem.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>How-To-Repeat:</emphasis> A summary of the
+ actions you need to take to reproduce the problem.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Fix:</emphasis> Preferably a patch, or at
+ least a workaround (which not only helps other people with
+ the same problem work around it, but may also help a
+ developer understand the cause for the problem), but if
+ you do not have any firm ideas for either, it is better to
+ leave this field blank than to speculate.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Sending off the problem report</title>
+
+ <para>If you are using &man.send-pr.1;:</para>
+
+ <para>Once you are done filling out the template, have saved it,
+ and exit your editor, &man.send-pr.1; will prompt you with
+ <prompt>s)end, e)dit or a)bort?</prompt>. You can then hit
+ <userinput>s</userinput> to go ahead and submit the problem report,
+ <userinput>e</userinput> to restart the editor and make
+ further modifications, or <userinput>a</userinput> to abort.
+ If you choose the latter, your problem report will remain on
+ disk (&man.send-pr.1; will tell you the filename before it
+ terminates), so you can edit it at your leisure, or maybe
+ transfer it to a system with better net connectivity, before
+ sending it with the <option>-f</option> to
+ &man.send-pr.1;:</para>
+
+<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>
+
+ <para>This will read the specified file, validate the contents,
+ strip comments and send it off.</para>
+
+ <para>If you are using the web form:</para>
+
+ <para>Before you hit <literal>submit</literal>, you will need to
+ fill in a field containing text that is represented in image
+ form on the page. This unfortunate measure has had to be
+ adopted due to misuse by automated systems and a few misguided
+ individuals. It is a necessary evil that no one likes; please
+ do not ask us to remove it.</para>
+
+ <para>Note that you are <literal>strongly advised</literal> to
+ save your work somewhere before hitting <literal>submit</literal>.
+ A common problem for users is to have their web browser displaying
+ a stale image from its cache. If this happens to you, your
+ submission will be rejected and you may lose your work.</para>
+
+ <para>If you are unable to view images for any reason, and are also
+ unable to use &man.send-pr.1;, please accept our apologies for
+ the inconvenience and email your problem report to the bugbuster
+ team at <email>freebsd-bugbusters@FreeBSD.org</email>.</para>
+ </section>
+
+ </section>
+
+ <section xml:id="pr-followup">
+ <title>Follow-up</title>
+
+ <para>Once your problem report has been filed, you will receive a
+ confirmation by email which will include the tracking number
+ that was assigned to your problem report and a URL you can use
+ to check its status. With a little luck, someone will take an
+ interest in your problem and try to address it, or, as the case
+ may be, explain why it is not a problem. You will be
+ automatically notified of any change of status, and you will
+ receive copies of any comments or patches someone may attach to
+ your problem report's audit trail.</para>
+
+ <para>If someone requests additional information from you, or you
+ remember or discover something you did not mention in the
+ initial report, please use one of two methods to submit your
+ followup:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The easiest way is to use the followup link on
+ the individual PR's web page, which you can reach from the
+ <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
+ PR search page</link>. Clicking on this link will bring up an
+ an email window with the correct To: and Subject: lines filled in
+ (if your browser is configured to do this).</para>
+ </listitem>
+
+ <listitem>
+ <para>Alternatively, you can just mail it to
+ &a.bugfollowup;, making sure that the
+ tracking number is included in the subject so the bug tracking
+ system will know what problem report to attach it to.</para>
+
+ <note>
+ <para>If you do <emphasis>not</emphasis> include the tracking
+ number, GNATS will become confused and create an entirely
+ new PR which it then assigns to the GNATS administrator,
+ and then your followup will become lost until someone
+ comes in to clean up the mess, which could be days or
+ weeks afterwards.</para>
+
+ <para>Wrong way: <programlisting>Subject: that PR I sent</programlisting>
+ Right way: <programlisting>Subject: Re: ports/12345: compilation problem with foo/bar</programlisting></para>
+ </note>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>If the problem report remains open after the problem has
+ gone away, just send a follow-up (in the manner prescribed
+ above) saying that the problem report can be closed, and, if
+ possible, explaining how or when the problem was fixed.</para>
+ </section>
+
+ <section xml:id="pr-problems">
+ <title>If you are having problems</title>
+
+ <para>Most PRs go through the system and are accepted quickly;
+ however, at times GNATS runs behind and you may not get your
+ email confirmation for 10 minutes or even longer. Please try to
+ be patient.</para>
+
+ <para>In addition, because GNATS receives all its input via email,
+ it is absolutely vital that &os; runs all its submissions through
+ spam filters. If you do not get a response within an hour or
+ two, you may have fallen afoul of them; if so, please contact
+ the GNATS administrators at <email>bugmeister@FreeBSD.org</email>
+ and ask for help.</para>
+
+ <note>
+ <para>Among the anti-spam measures is one that weighs against
+ many common abuses seen HTML-based email (although not necessarily
+ the mere inclusion of HTML in a PR). We strongly recommend
+ against the use of HTML-based email when sending PRs: not
+ only is it more likely to fall afoul of the filters, it also
+ tends to merely clutter up the database. Plain old email is
+ strongly preferred.</para>
+ </note>
+
+ <para>On rare occasions you will encounter a GNATS bug where a
+ PR is accepted and assigned a tracking number but it does not
+ show up on the list of PRs on any of the web query pages. What
+ may have happened is that the database index has gotten out of
+ synchronization with the database itself. The way that you
+ can test whether this has happened is to pull up the
+ <link xlink:href="http://www.FreeBSD.org/cgi/query-pr.cgi">
+ view a single PR</link> page and see whether the PR shows up.
+ If it does, please notify the GNATS administrators at
+ <email>bugmeister@FreeBSD.org</email>. Note that there is a
+ <literal>cron</literal> job that periodically rebuilds the database,
+ so unless you are in a hurry, no action needs to be taken.</para>
+ </section>
+
+ <section xml:id="pr-further">
+ <title>Further Reading</title>
+
+ <para>This is a list of resources relevant to the proper writing
+ and processing of problem reports. It is by no means complete.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
+ How to Report Bugs Effectively</link>&mdash;an excellent
+ essay by Simon G. Tatham on composing useful (non-&os;-specific)
+ problem reports.</para>
+ </listitem>
+ <listitem>
+ <para><link xlink:href="&url.articles.pr-guidelines;/article.html">Problem
+ Report Handling Guidelines</link>&mdash;valuable insight
+ into how problem reports are handled by the &os;
+ developers.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <index/>
+</article>
diff --git a/zh_TW.UTF-8/articles/remote-install/Makefile b/zh_TW.UTF-8/articles/remote-install/Makefile
new file mode 100644
index 0000000000..3efa3a5e93
--- /dev/null
+++ b/zh_TW.UTF-8/articles/remote-install/Makefile
@@ -0,0 +1,30 @@
+#
+# The FreeBSD Traditional Chinese Project
+#
+# Original Revision: 1.1
+# $FreeBSD$
+#
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.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
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/zh_TW.UTF-8/articles/remote-install/article.xml b/zh_TW.UTF-8/articles/remote-install/article.xml
new file mode 100644
index 0000000000..d927f61be6
--- /dev/null
+++ b/zh_TW.UTF-8/articles/remote-install/article.xml
@@ -0,0 +1,475 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!--
+ The FreeBSD Documentation Project
+ The FreeBSD Chinese (Traditional) Documentation Project
+
+ Original Revision: 1.5
+
+-->
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
+ <info><title>遠端安裝 &os; 作業系統而不必接 Remote Console</title>
+
+
+ <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><affiliation>
+ <address><email>danger@FreeBSD.org</email></address>
+ </affiliation></author>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <copyright>
+ <year>2008</year>
+ <holder>The &os; Documentation Project</holder>
+ </copyright>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <abstract>
+ <para>本文介紹如何在沒辦法連到遠端 console 的機器做 &os; 遠端安裝。
+ 本文構想來自於作者與 &a.mm; 的合作成果,
+ 以及 &a.pjd; 所投注的諸多心血。</para>
+ </abstract>
+ </info>
+
+ <sect1 xml:id="background">
+ <title>緣起</title>
+
+ <para>世上有許多 server hosting provider,但其中有官方支援 &os;
+ 則不是相當多。 他們通常會在所提供的機器上有 &linux; distribution
+ 的安裝支援。</para>
+
+ <para>有些會讓您可選擇喜好的 &linux; distribution 來裝,
+ 像這種情況就可以試著安裝 &os;。 而有些則是會提供救急用的系統,
+ 這種也可以用來安裝 &os;。</para>
+
+ <para>本文介紹這些遠端基本安裝 &os; 的方式,以及 RAID-1 與
+ <application>ZFS</application> 設定步驟。</para>
+ </sect1>
+
+ <sect1 xml:id="intro">
+ <title>介紹</title>
+
+ <para>茲摘錄一下本文的目的以及闡述這邊所涵蓋的東西。
+ 對於無官方支援 &os; 的代管服務(colocation)用戶而言,
+ 本文中所介紹到的指令會相當有用。</para>
+
+ <procedure>
+ <step>
+ <para>正如先前 <link linkend="background">緣起</link> 所提到的,許多名聲還不賴的
+ server hosting 公司會提供一些救急用系統,可以透過
+ <acronym>LAN</acronym> 方式開機,也可以透過
+ <application>SSH</application> 方式進行管理。 通常會有該加值服務,
+ 以讓他們的客戶可以連進來修復有問題的作業系統。
+ 本節之後將介紹如何透過救急系統來安裝 &os;。</para>
+ <!-- XXXTR: Solaris has a restore command, something like
+ sysrestore, FreeBSD Should have one too. -->
+ </step>
+
+ <step>
+ <para>下一節會介紹如何在本機設定以及打造最小巧的 &os; ——
+ 該版最後會在遠端機器上透過 ramdisk 方式啟動,並以
+ <application>sysinstall</application> 從 <acronym>FTP</acronym>
+ mirror 站來安裝完整的 &os; 作業系統。</para>
+ </step>
+
+ <step>
+ <para>本文其餘部分將介紹安裝程序,以及 <application>ZFS</application>
+ 檔案系統的設定。</para>
+ </step>
+ </procedure>
+
+ <sect2 xml:id="requirements">
+ <title>需求</title>
+
+ <para>為了成功完成遠端安裝,必須要有:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>要有可以上網的作業系統,並且 <application>SSH</application>
+ 可以連線。</para>
+ </listitem>
+
+ <listitem>
+ <para>瞭解 &os; 的安裝程序</para>
+ </listitem>
+
+ <listitem>
+ <para>熟悉如何使用 &man.sysinstall.8;</para>
+ </listitem>
+
+ <listitem>
+ <para>有 &os; 安裝光碟片或者 <acronym>ISO</acronym> image 檔</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="preparation">
+ <title>準備 - <application>mfsBSD</application></title>
+
+ <para>在裝 &os; 之前,要先打造最小化的 &os; 作業系統 image 檔,
+ 以便可以從硬碟上開機。 如此一來,新的系統就可以透過網路來操作,
+ 而剩下來的安裝部分即可不必透過 console。</para>
+
+ <para>而 <application>mfsBSD</application> 這套工具就是用來打造小型的
+ &os; image 檔。 <application>mfsBSD</application> (名字其中
+ <quote>mfs</quote> 就是 <quote>memory file system</quote>)所建造出來的
+ 整套系統會透過 ramdisk 方式來運作。 由於此一特色,硬碟的部分就不受限,
+ 因此可以用來安裝完整的 &os; 作業系統。 <application>mfsBSD</application>
+ 的首頁位於 <uri xlink:href="http://people.freebsd.org/~mm/mfsbsd/">http://people.freebsd.org/~mm/mfsbsd/</uri>,
+ 其中連結有該工具的最新 release 部分。</para>
+
+ <para>請注意:<application>mfsBSD</application> 內部運作方式的細節,不
+ 在本文介紹範圍之內。 若對這方面有興趣的讀者,可至
+ <application>mfsBSD</application> 官網查閱相關文件。</para>
+
+ <para>首先下載最新的 <application>mfsBSD</application> 並解壓縮之,
+ 然後切到解壓縮後的工作目錄,也就是 <application>mfsBSD</application>
+ script 檔所在處:</para>
+
+ <screen>&prompt.root; <userinput>fetch http://people.freebsd.org/~mm/mfsbsd/mfsbsd-latest.tar.gz</userinput>
+&prompt.root; <userinput>tar xvzf mfsbsd-1.0-beta1.tar.gz</userinput>
+&prompt.root; <userinput>cd mfsbsd-1.0-beta1/</userinput></screen>
+
+ <sect2 xml:id="mfsbsd-config">
+ <title>設定 <application>mfsBSD</application></title>
+
+ <para>在將 <application>mfsBSD</application> 開機之前,
+ 有幾個重要設定要先設妥。 此時最重要的設定,很明顯就是網路設定。
+ 到底網路怎麼設最好,則取決於所處的網路環境,
+ 以及該網路卡會以哪一種驅動程式載入而定。 我們將會看到
+ <application>mfsBSD</application> 如何在任何網路情況下進行設定。</para>
+
+ <para>另一件重要事就是設定 <systemitem class="username">root</systemitem> 密碼。
+ 這點可以透過 <filename>conf/rootpw.conf</filename> 來完成。
+ 請切記:該檔密碼是以明文方式存放,因此不建議放真正平常有在用的密碼。
+ 然而這密碼只是臨時密碼而已,可以在之後開機時再做更換。</para>
+
+ <sect3>
+ <title>設定網路(<filename>conf/interfaces.conf</filename> 方式)</title>
+
+ <para>若對要裝的機器網卡為何還不知道是哪一款,但可以善加利用
+ <application>mfsBSD</application> 的自動偵測功能。
+ <application>mfsBSD</application> 的開機 script 會根據網卡的 MAC
+ 位址範圍來偵測正確的驅動程式,像是下列的
+ <filename>conf/interfaces.conf</filename> 設定內容:</para>
+
+ <programlisting>initconf_interfaces="ext1"
+initconf_mac_ext1="00:00:00:00:00:00"
+initconf_ip_ext1="192.168.0.2"
+initconf_netmask_ext1="255.255.255.0"</programlisting>
+
+ <para>別忘了在 <filename>conf/rc.conf</filename> 內要加上
+ <literal>defaultrouter</literal> 的相關設定:</para>
+
+ <programlisting>defaultrouter="192.168.0.1"</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>設定網路(<filename>conf/rc.conf</filename> 方式)</title>
+
+ <para>若已經知道網卡是哪一種,那麼要設定網路的話直接改
+ <filename>conf/rc.conf</filename> 會比較方便。
+ 該檔設定語法與 &os; 標準的 &man.rc.conf.5; 是一致的。</para>
+
+ <para>舉個例子,若知道該機器網卡是用 &man.re.4;,那麼就在
+ <filename>conf/rc.conf</filename> 做下列類似設定:</para>
+
+ <programlisting>defaultrouter="192.168.0.1"
+ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="mfsbsd-build">
+ <title>打造 <application>mfsBSD</application> image</title>
+
+ <para>打造 <application>mfsBSD</application>
+ image 檔的過程相當簡單。</para>
+
+ <para>首先是把 &os; 安裝光碟或者安裝用的 <acronym>ISO</acronym> image
+ 檔丟到 <filename>/cdrom</filename>。
+ 為維持所有例子的一致,本文假設都是用 &os; 7.0-RELEASE
+ <acronym>ISO</acronym>。 而把 ISO image 檔掛載到 <filename>/cdrom</filename> 目錄相當簡單,
+ 就是用 &man.mdconfig.8;:</para>
+
+ <screen>&prompt.root; <userinput>mdconfig -a -t vnode -u 10 -f 7.0-RELEASE-amd64-disc1.iso</userinput>
+&prompt.root; <userinput>mount_cd9660 /dev/md10 /cdrom</userinput></screen>
+
+ <para>接著就開始打造可開機的 <application>mfsBSD</application>
+ image:</para>
+
+ <screen>&prompt.root; <userinput>make BASE=/cdrom/7.0-RELEASE</userinput></screen>
+
+ <note>
+ <para>上述的 <command>make</command> 指令要在
+ <application>mfsBSD</application> 的最上層目錄執行,比方說 <filename>~/mfsbsd-1.0-beta1/</filename>。</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title><application>mfsBSD</application> 開動</title>
+
+ <para>現在 <application>mfsBSD</application> image 已經備妥,
+ 要上傳到遠端機器的救急系統或者預先安裝的 &linux; distribution。
+ 要完成這工作最適合的工具就是 <application>scp</application>:</para>
+
+ <screen>&prompt.root; <userinput>scp disk.img root@192.168.0.2:.</userinput></screen>
+
+ <para>為了能順利啟動 <application>mfsBSD</application> image,
+ 要把檔案放在欲安裝機器的第一顆(可開機)硬碟上。
+ 假設例子的第一顆開機硬碟代號為 <filename>sda</filename>,
+ 那麼作法就類似下面這樣:</para>
+
+ <screen>&prompt.root; <userinput>dd if=/root/disk.img of=/dev/sda bs=1m</userinput></screen>
+
+ <para>若一切順利,該 image 檔現在應該會在第一顆硬碟的
+ <acronym>MBR</acronym> 磁區並可以開始進行重開機了。 可以用
+ &man.ping.8; 工具來檢測該機器開機完畢與否。 一旦 ping 到之後,
+ 就可以透過 &man.ssh.1; 連進去,並且用 <systemitem class="username">root</systemitem>
+ 以及剛設定的密碼登入。</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="installation">
+ <title>&os; 作業系統的安裝</title>
+
+ <para>現在 <application>mfsBSD</application> 已順利啟動,並且應該可以透過
+ &man.ssh.1; 方式來連。 本節將介紹如何建立 slice 分割、設定
+ <application>gmirror</application> 以作 RAID-1、如何以
+ <application>sysinstall</application> 來安裝 &os;
+ 作業系統的最小化安裝。</para>
+
+ <sect2>
+ <title>準備硬碟</title>
+
+ <para>首先要作的是配置硬碟空間給 &os;,像是建立 slice 跟分割區。
+ 很明顯地,目前在跑的作業系統是載入到系統記憶體內執行,
+ 因此要對硬碟配置並無任何問題。 這些工作可以用
+ <application>sysinstall</application> 或者以 &man.fdisk.8; 搭配
+ &man.bsdlabel.8; 來完成。</para>
+
+ <para>首先先把各硬碟都先清空。 請對各硬碟作下列指令:</para>
+
+ <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad0 count=2</userinput></screen>
+
+ <para>接著,以您慣用的工具來建立 slice 以及設定 label。 通常會建議以
+ 的 <application>sysinstall</application> 工具來作會比較輕鬆,
+ 或者是強而又不太會出槌的文字介面 &unix; 標準工具(像是 &man.fdisk.8;,
+ &man.bsdlabel.8;),這部分稍後也會一併介紹。 前者部分在 &os; Handbook
+ 的 <link xlink:href="&url.books.handbook;/install-steps.html">安裝
+ &os;</link> 章節有相當詳盡的介紹,所以這邊主要要介紹的是如何建立
+ RAID-1 系統以及 <application>ZFS</application>。
+ 這邊會介紹建立以 &man.gmirror.8; 做成的小型 mirrored 檔案系統:
+ <filename>/</filename> (根目錄), <filename>/usr</filename> 以及 <filename>/var</filename>,而硬碟的其餘剩餘空間則通通以
+ &man.zpool.8; 做成 <application>ZFS</application> 的 mirrored 檔案系統
+ 。 請注意:必須要先把 &os; 作業系統裝好並開完機後,才能進行設定
+ <application>ZFS</application> 檔案系統。</para>
+
+ <para>下面的例子會介紹如何建立 slice 以及 label、在每個分割區上啟用
+ &man.gmirror.8;、如何在每個 mirrored 分割區上建立
+ <application>UFS2</application> 檔案系統:</para>
+
+ <screen>&prompt.root; <userinput>fdisk -BI /dev/ad0</userinput> <co xml:id="fdisk"/>
+&prompt.root; <userinput>fdisk -BI /dev/ad1</userinput>
+&prompt.root; <userinput>bsdlabel -wB /dev/ad0s1</userinput> <co xml:id="bsdlabel-writing"/>
+&prompt.root; <userinput>bsdlabel -wB /dev/ad1s1</userinput>
+&prompt.root; <userinput>bsdlabel -e /dev/ad0s1</userinput> <co xml:id="bsdlabel-editing"/>
+&prompt.root; <userinput>bsdlabel /dev/ad0s1 &gt; /tmp/bsdlabel.txt &amp;&amp; bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt</userinput> <co xml:id="bsdlabel-restore"/>
+&prompt.root; <userinput>gmirror label root /dev/ad[01]s1a</userinput> <co xml:id="gmirror1"/>
+&prompt.root; <userinput>gmirror label var /dev/ad[01]s1d</userinput>
+&prompt.root; <userinput>gmirror label usr /dev/ad[01]s1e</userinput>
+&prompt.root; <userinput>gmirror label -F swap /dev/ad[01]s1b</userinput> <co xml:id="gmirror2"/>
+&prompt.root; <userinput>newfs /dev/mirror/root</userinput> <co xml:id="newfs"/>
+&prompt.root; <userinput>newfs /dev/mirror/var</userinput>
+&prompt.root; <userinput>newfs /dev/mirror/usr</userinput></screen>
+
+ <calloutlist>
+ <callout arearefs="fdisk">
+ <para>對該硬碟建立 slice 並且在第零軌處將開機表作初始。
+ 請對該機器所有硬碟都作此一動作。</para>
+ </callout>
+
+ <callout arearefs="bsdlabel-writing">
+ <para>對各硬碟寫入 label 以及 bootstrap 碼。</para>
+ </callout>
+
+ <callout arearefs="bsdlabel-editing">
+ <para>現在手動修改該硬碟的 label,至於如何建立分割區(partitions)
+ 請參閱 &man.bsdlabel.8; 說明。
+ 分割區分別建立:<literal>a</literal> 是給 <filename>/</filename> (根目錄),
+ <literal>b</literal> 給 swap,
+ <literal>d</literal> 給 <filename>/var</filename>,
+ <literal>e</literal> 給 <filename>/usr</filename>,
+ 最後,會在稍後步驟把 <literal>f</literal> 給
+ <application>ZFS</application> 使用。</para>
+ </callout>
+
+ <callout arearefs="bsdlabel-restore">
+ <para>把剛剛的 label 設定先匯出,再匯入到第二顆硬碟上,
+ 如此一來兩邊的硬碟 label 設定就會同樣。</para>
+ </callout>
+
+ <callout arearefs="gmirror1">
+ <para>在各分割區上啟用 &man.gmirror.8;</para>
+ </callout>
+
+ <callout arearefs="gmirror2">
+ <para>請注意:<option>-F</option> 選項是用在 swap 上。
+ 這參數會讓 &man.gmirror.8; 認為該硬體是處於可靠狀態,
+ 即使發生電源故障或系統當掉,也不會去同步。</para>
+ </callout>
+
+ <callout arearefs="newfs">
+ <para>在各個有做 mirror 的分割區上建立 <application>UFS2</application>
+ 檔案系統</para>
+ </callout>
+ </calloutlist>
+ </sect2>
+
+ <sect2>
+ <title>系統安裝</title>
+
+ <para>這裡是最重要的一環,
+ 本節介紹實際上如何在先前一節所做好的硬碟安裝最小化的 &os;,
+ 為了完成此一目標,所有檔案系統都必須掛載妥當,才能讓
+ <application>sysinstall</application> 可以把 &os; 裝到硬碟內:</para>
+
+ <screen>&prompt.root; <userinput>mount /dev/mirror/root /mnt</userinput>
+&prompt.root; <userinput>mkdir /mnt/var /mnt/usr</userinput>
+&prompt.root; <userinput>mount /dev/mirror/var /mnt/var</userinput>
+&prompt.root; <userinput>mount /dev/mirror/usr /mnt/usr</userinput></screen>
+
+ <para>做完上述動作之後,請執行 &man.sysinstall.8;。 請從主選單中選擇
+ <guimenuitem>Custom</guimenuitem> 安裝,選
+ <guimenuitem>Options</guimenuitem> 按 <keycap>Enter</keycap>。
+ 然後以方向鍵移動到 <literal>Install Root</literal> 處,按
+ <keycap>Space</keycap> 鍵然後改為 <filename>/mnt</filename>,再按 <keycap>Enter</keycap>
+ 鍵以將修改值存起來,然後按 <keycap>q</keycap> 鍵即可離開這個
+ <guimenuitem>Options</guimenuitem> 畫面。</para>
+
+ <warning>
+ <para>請注意:本步驟極為重要,若忽略的話那麼
+ <application>sysinstall</application> 就沒辦法安裝 &os;。</para>
+ </warning>
+
+ <para>接著選 <guimenuitem>Distributions</guimenuitem>,然後移動游標到
+ <option>Minimal</option> 處,按 <keycap>Space</keycap> 鍵。
+ 本文之所以介紹最小化安裝是為了要節省網路流量,因為系統安裝是透過
+ <application>ftp</application> 方式來進行。 要離開本畫面,請選
+ <option>Exit</option> 即可。</para>
+
+ <note>
+ <para>至於 <guimenuitem>Partition</guimenuitem> 及
+ <guimenuitem>Label</guimenuitem> 步驟則可略過,
+ 因為這些目前已經都設定完畢了。</para>
+ </note>
+
+ <para>在 <guimenuitem>Media</guimenuitem> 選單中請選
+ <option>FTP</option>。 請選最近的 mirror 站,並且讓
+ <application>sysinstall</application> 假設網路已經設妥。
+ 接下來就會回到 <guimenuitem>Custom</guimenuitem> 選單。</para>
+
+ <para>最後,按下 <guimenuitem>Commit</guimenuitem> 即可開始進行安裝。
+ 完成安裝後,即可離開 <application>sysinstall</application>。</para>
+ </sect2>
+
+ <sect2>
+ <title>後續安裝步驟</title>
+
+ <para>此時 &os; 作業系統應該已經裝完,然而還有些後續流程要做。
+ 必須要做一些後續設定,才能讓 &os; 可以開機跟登入。</para>
+
+ <para>現在必須要用 &man.chroot.8; 以切到剛剛新裝好的系統內。
+ 指令如下:</para>
+
+ <screen>&prompt.root; <userinput>chroot /mnt</userinput></screen>
+
+ <para>然後再打下列指令以繼續完成:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>把 <literal>GENERIC</literal> kernel 複製到
+ <filename>/boot/kernel</filename>
+ 目錄:</para>
+
+ <screen>&prompt.root; <userinput>cp -Rp /boot/GENERIC/* /boot/kernel</userinput></screen>
+ </listitem>
+
+ <listitem>
+ <para>建立 <filename>/etc/rc.conf</filename>,
+ <filename>/etc/resolv.conf</filename> 及
+ <filename>/etc/fstab</filename> 檔案。 別忘了,要記得在
+ <filename>/etc/rc.conf</filename> 檔設相關網路設定,以及把
+ <application>sshd</application> 啟用。 此外,
+ <filename>/etc/fstab</filename> 檔應該會長像下面這樣:</para>
+
+ <programlisting># Device Mountpoint FStype Options Dump Pass#
+/dev/mirror/swap none swap sw 0 0
+/dev/mirror/root / ufs rw 1 1
+/dev/mirror/usr /usr ufs rw 2 2
+/dev/mirror/var /var ufs rw 2 2
+/dev/cd0 /cdrom cd9660 ro,noauto 0 0</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>新增 <filename>/boot/loader.conf</filename> 檔,
+ 並且內容填入下列:</para>
+
+ <programlisting>geom_mirror_load="YES"
+zfs_load="YES"</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>執行下列指令,以在下次開機時啟用 <application>ZFS</application>
+ :</para>
+
+ <screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' &gt;&gt; /etc/rc.conf </userinput></screen>
+ </listitem>
+
+ <listitem>
+ <para>使用 &man.adduser.8; 工具來新增其他使用者帳號。 別忘了,
+ 至少要有一個帳號得加入 <systemitem class="groupname">wheel</systemitem> 群組,
+ 才能在重開機後以該帳號切換為 root。</para>
+ </listitem>
+
+ <listitem>
+ <para>再次檢查上述相關的設定,是否有遺漏或打錯。</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>現在該系統終於可以重開機了,請用 &man.reboot.8;
+ 指令以重開機。</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="zfs">
+ <title>ZFS</title>
+
+ <para>系統重開機完畢之後,應該就可以登入了。 歡迎使用全新的 &os; 安裝方式,
+ 完全透過遠端而不必接上 remote console!</para>
+
+ <para>接下來只剩要調整 &man.zpool.8; 以及建立 &man.zfs.8; 檔案系統而已。
+ <application>ZFS</application> 的建立及管理是相當淺顯易懂。 首先,
+ 建立 mirrored pool:</para>
+
+ <screen>&prompt.root; <userinput>zpool create tank mirror /dev/ad[01]s1f</userinput></screen>
+
+ <para>接著,建立檔案系統:</para>
+
+ <screen>&prompt.root; <userinput>zfs create tank/ports</userinput>
+&prompt.root; <userinput>zfs create tank/src</userinput>
+&prompt.root; <userinput>zfs set compression=gzip tank/ports</userinput>
+&prompt.root; <userinput>zfs set compression=on tank/src</userinput>
+&prompt.root; <userinput>zfs set mountpoint=/usr/ports tank/ports</userinput>
+&prompt.root; <userinput>zfs set mountpoint=/usr/src tank/src</userinput></screen>
+
+ <para>一切就是這樣簡單。 若對 &os; 上的 <application>ZFS</application>
+ 細節部分有興趣,請參閱 &os; Wiki 上的 <link xlink:href="http://wiki.freebsd.org/ZFS">ZFS</link> 一節說明。</para>
+ </sect1>
+</article>