Date: Tue, 21 Jun 2016 01:19:43 +0000 (UTC) From: Kevin Lo <kevlo@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r48972 - head/zh_TW.UTF-8/books/fdp-primer Message-ID: <201606210119.u5L1Jh8x001297@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: kevlo (src,ports committer) Date: Tue Jun 21 01:19:43 2016 New Revision: 48972 URL: https://svnweb.freebsd.org/changeset/doc/48972 Log: - Move all usable previous translation to the po translation of zh_TW fdp-primer. - New translation of Chapter 12 PO translation Submitted by: RayCherng Yu <raycherng at gmail dot com> Reviewed by: wblock Differential Revision: https://reviews.freebsd.org/D6869 Added: head/zh_TW.UTF-8/books/fdp-primer/zh_TW.po (contents, props changed) Modified: head/zh_TW.UTF-8/books/fdp-primer/Makefile head/zh_TW.UTF-8/books/fdp-primer/book.xml Modified: head/zh_TW.UTF-8/books/fdp-primer/Makefile ============================================================================== --- head/zh_TW.UTF-8/books/fdp-primer/Makefile Mon Jun 20 21:48:39 2016 (r48971) +++ head/zh_TW.UTF-8/books/fdp-primer/Makefile Tue Jun 21 01:19:43 2016 (r48972) @@ -20,20 +20,6 @@ INSTALL_ONLY_COMPRESSED?= # XML content SRCS= book.xml -SRCS+= overview/chapter.xml -SRCS+= psgml-mode/chapter.xml -SRCS+= see-also/chapter.xml -SRCS+= sgml-markup/chapter.xml -SRCS+= sgml-primer/chapter.xml -SRCS+= stylesheets/chapter.xml -SRCS+= structure/chapter.xml -SRCS+= doc-build/chapter.xml -SRCS+= the-website/chapter.xml -SRCS+= tools/chapter.xml -SRCS+= translations/chapter.xml -SRCS+= writing-style/chapter.xml - -SRCS+= examples/appendix.xml # Images from the cross-document image library IMAGES_LIB= callouts/1.png Modified: head/zh_TW.UTF-8/books/fdp-primer/book.xml ============================================================================== --- head/zh_TW.UTF-8/books/fdp-primer/book.xml Mon Jun 20 21:48:39 2016 (r48971) +++ head/zh_TW.UTF-8/books/fdp-primer/book.xml Tue Jun 21 01:19:43 2016 (r48972) @@ -1,8 +1,32 @@ <?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -]> +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ +<!ENTITY % chapters SYSTEM "chapters.ent"> +<!-- + Creates entities for each chapter in the Documentation Project Primer. + Each entity is named chap.foo, where foo is the value of the id + attribute on that chapter, and corresponds to the name of the + directory in which that chapter's .xml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ +--><!ENTITY chap.overview SYSTEM "overview/chapter.xml"> +<!ENTITY chap.tools SYSTEM "tools/chapter.xml"> +<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml"> +<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> +<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> +<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> +<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> +<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> +<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> +<!ENTITY chap.translations SYSTEM "translations/chapter.xml"> +<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml"> +<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml"> +<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml"> +<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml"> +<!ENTITY app.examples SYSTEM "examples/appendix.xml"> +<!-- ENTITY index SYSTEM "index.xml" -->]> <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. Redistribution and use in source (SGML DocBook) and 'compiled' forms @@ -33,71 +57,96 @@ POSSIBILITY OF SUCH DAMAGE. $FreeBSD$ - Original revision: 1.27 --> -<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw"> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW"> <info><title>FreeBSD 文件計畫入門書</title> <author><orgname>FreeBSD 文件計劃</orgname></author> - <copyright> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <holder role="mailto:doceng@FreeBSD.org">DocEng</holder> - </copyright> + <copyright><year>1998</year> <year>1999</year> <year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <holder role="mailto:doceng@FreeBSD.org">DocEng</holder></copyright> <pubdate role="rcs">$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - &legalnotice; + +<legalnotice xml:id="legalnotice"> + <title>版權</title> + + <para xml:lang="en">Redistribution and use in source (XML DocBook) and 'compiled' + forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions are + met:</para> + + <orderedlist> + <listitem> + <para xml:lang="en">Redistributions of source code (XML DocBook) must retain the + above copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified.</para> + </listitem> + + <listitem> + <para xml:lang="en">Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must + reproduce the above copyright notice, this list of conditions and + the following disclaimer in the documentation and/or other + materials provided with the distribution.</para> + </listitem> + </orderedlist> + + <important> + <para xml:lang="en">THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION + PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, + BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL + THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, + BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR + TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE + USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + DAMAGE.</para> + </important> +</legalnotice> + <abstract> - <para>感謝您參與 FreeBSD 文件計劃(簡稱:FDP, FreeBSD Documentation Project),您的點滴貢獻,都相當寶貴。</para> + <para>感謝您參與 FreeBSD 文件計劃,您的點滴貢獻,都相當寶貴。</para> - <para>本入手書內容包括:如何開始著手翻譯的各項細節,以及會用到的一些好用工具(包括:必備工具、輔助工具) - ,以及文件計畫的宗旨。</para> + <para>本入手書內容包括:如何開始著手貢獻FreeBSD 文件計劃 (簡稱: <acronym>FDP</acronym> )的各項細節,以及會用到的一些工具、軟體 ,以及文件計畫的宗旨。</para> - <para>本文件還在草稿,尚未完稿。未完成的章節,我們會在章節名稱旁邊加註『<literal>*</literal> 』以作識別。</para> + <para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para> </abstract> </info> <preface xml:id="preface"> - <title>序言</title> + <title>序</title> <sect1 xml:id="preface-prompts"> <title>Shell 提示符號(Prompts)</title> - <para>下表顯示出一般帳號與 root 的提示符號,在所有的文件例子中會用提示符號(prompt) - ,來提醒您該用哪種帳號才對。</para> + <para>下表顯示出一般使用者帳號與 root 的提示符號,在所有的文件例子中會用提示符號(prompt) ,來提醒您該用哪種帳號才對。</para> <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> <entry>帳號</entry> - <entry>提示符號(Prompt)</entry> + <entry>提示符號</entry> </row> </thead> <tbody> <row> - <entry>普通帳號</entry> - <entry>&prompt.user;</entry> + <entry>一般使用者</entry> + <entry><prompt>%</prompt></entry> </row> <row> <entry><systemitem class="username">root</systemitem></entry> - <entry>&prompt.root;</entry> + <entry><prompt>#</prompt></entry> </row> </tbody> </tgroup> @@ -107,7 +156,7 @@ <sect1 xml:id="preface-conventions"> <title>書中所用的編排風格</title> - <para>下表為本書中所使用編排風格方式:</para> + <para>下表為本書中所使用編排風格方式</para> <informaltable frame="none" pgwide="1"> <tgroup cols="2"> @@ -121,12 +170,12 @@ <tbody> <row> <entry>指令</entry> - <entry>使用 <command>ls -a</command> 來列出所有的檔案。</entry> + <entry>使用 <command>ls -l</command> 來列出所有的檔案。</entry> </row> <row> <entry>檔名</entry> - <entry>修改 <filename>.login</filename> 檔。</entry> + <entry>編輯 <filename>.login</filename> 。</entry> </row> <row> @@ -137,40 +186,33 @@ <row> <entry>輸入指令後,螢幕上會出現的對應內容。</entry> - <entry><screen>&prompt.user; <userinput>su</userinput> -Password:</screen></entry> + <entry><screen><prompt>%</prompt> <userinput>date +"The time is %H:%M"</userinput> +The time is 09:18</screen></entry> </row> <row> - <entry>要參考的線上手冊(manual)</entry> - - <entry>以 <citerefentry> - <refentrytitle>su</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> 來切換帳號。</entry> + <entry>要參考的線上手冊</entry> + <entry>使用 <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來切換帳號。</entry> </row> <row> - <entry>在講到帳號(user)、群組(group)的名稱的時候...</entry> - - <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry> + <entry>使用者名稱和群組名稱</entry> + <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry> </row> <row> - <entry>語氣的強調</entry> - - <entry>你『必須』這麼做才行。</entry> + <entry>語氣的強調。</entry> + <entry>使用者<emphasis>必須</emphasis>這樣做</entry> </row> <row> <entry>打指令時,可替換的部份</entry> - <entry>要刪除檔案的話,請打 <command>rm 要刪除的檔名</command></entry> + <entry>要搜尋線上手冊的關鍵字,請輸入 <command>man -k <replaceable>關鍵字</replaceable></command></entry> </row> <row> - <entry>環境變數設定</entry> - + <entry>環境變數。</entry> <entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry> </row> </tbody> @@ -179,29 +221,28 @@ Password:</screen></entry> </sect1> <sect1 xml:id="preface-notes"> - <title>『Note、Tip、Important、Warning、Example』的運用</title> + <title>注意、技巧、重要訊息、警告、與範例的運用。</title> - <para>以下文字是『注意』、『技巧』、『重要訊息』、『警告』、『範例』的運用。</para> + <para>出現在本文中的注意、警告、與範例。</para> <note> - <para>表示需要注意的事項,其中包括您需要注意的事情,因為這些事情可能會影響到操作結果。</para> + <para>注意:表示需要注意的事項,其中包括您需要注意的事情,因為這些事情可能會影響到操作結果。</para> </note> <tip> - <para>提供可能對您有用或簡化操作方式的技巧說明。</para> + <para>提示:提供可能對您有用的資訊,例如簡化操作方式的技巧說明。</para> </tip> <important> - <para>表示要特別注意的事情。一般來說,它們會包括操作指令時需要加的額外參數。</para> + <para>重要:表示要特別注意的事情。一般來說,它們會包括操作指令時需要加的額外參數。</para> </important> <warning> - <para>表示警告事項,比如如果您不注意則可能導致的損失。這些損失可能是對您或硬體造成實際傷害, - 也可能是無法估計的損害,例如一時疏忽而刪除重要檔案...。</para> + <para>警告:表示警告事項,比如如果您不則可能導致的損失。這些損失可能是對您或硬體造成實際傷害, 也可能是無法估計的損害,例如一時疏忽而刪除重要檔案...。</para> </warning> <example> - <title>這是舉例說明</title> + <title>一個範例</title> <para>這是舉例說明而已,通常包含應遵循的指令範例,或顯示某些特定動作所可能發生的結果。</para> </example> @@ -210,25 +251,8472 @@ Password:</screen></entry> <sect1 xml:id="preface-acknowledgements"> <title>感謝</title> - <para>在此要感謝 Sue Blake, Patrick Durusau, Jon Hamilton, Peter - Flynn, Christopher Maden 這些人的協助與閱讀初期草稿,並提供許多寶貴的潤稿意見與評論。</para> + <para>在此要感謝 Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, Christopher Maden 這些人的協助與閱讀初期草稿,並提供許多寶貴的潤稿意見與評論。</para> </sect1> </preface> - &chap.overview; - &chap.tools; - &chap.xml-primer; - &chap.xml-markup; - &chap.stylesheets; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.translations; - &chap.writing-style; - &chap.psgml-mode; - &chap.see-also; + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="overview"> + <title>概論</title> + + <para>歡迎參與 FreeBSD 文件計劃( 簡稱 <acronym>FDP</acronym> ) 。維持優秀質量的文件對 FreeBSD 的成功來說十分重要,您的點滴貢獻都是十分寶貴的。</para> + + <para>本文件描述:『 <acronym>FDP</acronym> 的架構有哪些』、『如何撰寫並提交文件』、 『如何有效運用工具來協助撰稿』。</para> + + <para>歡迎大家對 <acronym>FDP</acronym> 做出貢獻。唯一的成員要求就有貢獻的意願。</para> + + <para>本入門書指出如何:</para> + + <itemizedlist> + <listitem> + <para>瞭解有哪些文件是由 <acronym>FDP</acronym> 所維護的。</para> + </listitem> + + <listitem> + <para>安裝所需的文件工具和檔案</para> + </listitem> + + <listitem> + <para>修改文件</para> + </listitem> + + <listitem> + <para>提交修改以供審核並納入 FreeBSD 文件</para> + </listitem> + </itemizedlist> + + <sect1 xml:id="overview-doc"> + <title>FreeBSD 文件組</title> + + <para><acronym>FDP</acronym> 負責四類 FreeBSD 文件</para> + + <itemizedlist> + <listitem> + <para><emphasis>使用手冊</emphasis>: 使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para> + </listitem> + + <listitem> + <para><emphasis>FAQ</emphasis> 主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講,就是『問答集』格式) 通常會擺在這裡面的問答格式,不會放太長的詳細內容。</para> + </listitem> + + <listitem> + <para><emphasis>線上手冊 ( manual pages )</emphasis>:英文版的系統 manual 並不是由 <acronym>FDP</acronym> 所撰寫的,因為它們是屬於 base system 的部份。 然而,<acronym>FDP</acronym> 可以修改這些文件,來讓這些文件寫得更清楚,甚至是勘正錯誤的地方。</para> + </listitem> + + <listitem> + <para><emphasis>網站</emphasis>: 這是 FreeBSD 在網路上的主要部份,位於 <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link> 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方</para> + </listitem> + </itemizedlist> + + <para>翻譯團隊負責翻譯使用手冊和網站到不同的語言。線上手冊目前並未翻譯</para> + + <para>FreeBSD 網站、使用手冊、和 <acronym>FAQ</acronym> 的文件原始碼可以在 <literal>https://svn.FreeBSD.org/doc/</literal> 的文件庫取得。</para> + + <para>線上手冊的原始碼則是在 <literal>https://svn.FreeBSD.org/base/</literal> 的原始碼庫可以取得。</para> + + <para>文件提交訊息可以用 <command>svn log</command> 察看。 提交訊息也會保存在<uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>。</para> + + <para>這些儲存庫的網頁版位於<link xlink:href="https://svnweb.FreeBSD.org/doc/"/> 和 <link xlink:href="https://svnweb.FreeBSD.org/base/"/>。</para> + + <para>許多人會寫 FreeBSD 的教學文件或是 how-to 文章。有些保存在 <acronym>FDP</acronym> 的檔案中。其他一些文件則是作者希望放在他處。<acronym>FDP</acronym> 會盡力提供這些文件的連結。</para> + </sect1> + + <sect1 xml:id="overview-quick-start"> + <title>快速上手</title> + + <para>在編輯 FreeBSD 文件之前,有一些準備工作要做。 首先,請訂閱 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 文件計劃郵件論壇</link>。 有些團隊成員也會出現在<link xlink:href="http://www.efnet.org/">EFnet</link>的<literal>#bsddocs</literal> <acronym>IRC</acronym> 頻道。這些人可以幫忙解決文件相關的問題。</para> + + <procedure> + <step> + <para>安裝 <package>textproc/docproj</package> 套件或 port。這個meta-port 會安裝所有編輯和建構 FreeBSD 文件需要的軟體。</para> + </step> + + <step> + <para>在<filename>~/doc</filename>安裝 FreeBSD 文件庫的本地端工作副本 ( 請見 <xref linkend="working-copy"/> )。</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para>設定文字編輯器:</para> + + <itemizedlist> + <listitem> + <para>Word wrap 設為70個字元。</para> + </listitem> + + <listitem> + <para>Tab stops 設成 。</para> + </listitem> + + <listitem> + <para>將句首每八個空白以一個 tab 替換。</para> + </listitem> + </itemizedlist> + + <para>特定編輯器的設定方式列於 <xref linkend="editor-config"/>。</para> + </step> + + <step> + <para>更新本地端工作副本</para> + + <screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para>編輯需要修改的文件檔案。如果檔案需要大幅度的編修,請先諮詢郵件論壇。</para> + + <para>標籤 ( tag ) 和 entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>. 。</para> + </step> + + <step> + <para>編輯完後,執行以下指令來檢查是否有問題:</para> + + <screen><prompt>%</prompt> <userinput>igor -R filename.xml | less -RS</userinput></screen> + + <para>檢查輸出並重新編輯檔案來修正顯示的錯誤,然後重新執行指令來找出剩下的問題。重複執行直到所有錯誤都解決完。</para> + </step> + + <step> + <para>修正送出前請先建構測試 (build-test ) 。在編輯的文件目錄最頂層執行 <userinput>make</userinput>,將會產生 split HTML 格式的文件。例如要建構 <acronym>HTML</acronym> 格式的英文版使用手冊,請在 <filename>en_US.ISO8859-1/books/handbook/</filename> 目錄執行 <command>make</command> 。</para> + </step> + + <step> + <para>修改並測試完後,產生<quote>diff 檔</quote>:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> + + <para>設一個可辨識的檔名。如上例中,是使用手冊的<filename>bsdinstall</filename> 部份的修改。</para> + </step> + + <step> + <para>使用網頁版 <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">Problem Report</link> 系統提交 diff 檔。 如果使用網頁版,請輸入<emphasis>[修正檔] <replaceable>問題簡短描述</replaceable></emphasis>的概要 。選擇 <literal>docs</literal> 分類和 <literal>doc-bug</literal>類別。在訊息的主體中,輸入修正的簡短描述和其他相關的重要的細節。使用<guibutton>[ Browse... ]</guibutton> 按鈕來附加 diff 檔。</para> + </step> + </procedure> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="tools"> + <title>工具</title> + + <para>有些工具軟體用來管理 FreeBSD 文件,並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的,但是裝了之後會更容易進行文件製作工作。</para> + + <sect1 xml:id="tools-required"> + <title>必備工具</title> + + <para>從 Ports Collection 安裝 <package>textproc/docproj</package>。這個 <emphasis>組合型 port (meta-port)</emphasis> 會安裝處理 FreeBSD 文件需要的所有應用程式。以下列出特定元件的進一步說明。</para> + + <sect2> + <title><acronym>DTD</acronym>s 與 <acronym>Entities</acronym></title> + + <para>FreeBSD 文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 組。這些都會經由 <package>textproc/docproj</package> port 來安裝。</para> + + <variablelist> + <varlistentry> + <term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)</term> + + <listitem> + <para><acronym>XHTML</acronym> 是全球資訊網的一種標記語言,也是整個 FreeBSD 網站所使用的格式。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term> + + <listitem> + <para>DocBook 設計來製作技術文件的標記語言版本。FreeBSD 文件是以 DocBook 來撰寫。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ISO 8879 entities (<package>textproc/iso8879</package>)</term> + + <listitem> + <para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用, 包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 xml:id="tools-optional"> + <title>輔助工具</title> + + <para>不一定得裝下列的應用程式才行,但是,出的格式也更具彈性。</para> + + <sect2> + <title>軟體</title> + + <variablelist> + + <varlistentry> + <term><application>Vim</application> (<package>editors/vim</package>)</term> + + <listitem> + <para>一個很受歡迎的編輯器,可以處理 <acronym>XML</acronym> 和他的衍生相關文件,例如 DocBook <acronym>XML</acronym>。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Emacs</application> 或 <application>XEmacs</application> (<package>editors/emacs</package> 或 <package>editors/xemacs</package>)</term> + + <listitem> + <para>這兩個編輯器都包含特別模式來編輯用 <acronym>XML</acronym> <acronym>DTD</acronym> 標記的文件。這個模式包含指令來減少打字量,並可以幫忙減少錯誤的發生。</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 2013 Warren Block + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS + IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="working-copy"> + <title>工作副本</title> + + <para xml:lang="en">The <emphasis>working copy</emphasis> is a copy of the FreeBSD + repository documentation tree downloaded onto the local computer. + Changes are made to the local working copy, tested, and then + submitted as patches to be committed to the main + repository.</para> + + <para xml:lang="en">A full copy of the documentation tree can occupy 700 megabytes + of disk space. Allow for a full gigabyte of space to have room + for temporary files and test versions of various output + formats.</para> + + <para xml:lang="en"><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link> + is used to manage the FreeBSD documentation files. It is installed + by <package>textproc/docproj</package> as one of + the required applications.</para> + + <sect1 xml:id="working-copy-doc-and-src"> + <title xml:lang="en">Documentation and Manual Pages</title> + + <para xml:lang="en">FreeBSD documentation is not just books and articles. Manual + pages for all the commands and configuration files are also part + of the documentation, and part of the <acronym>FDP</acronym>'s + territory. Two repositories are involved: + <literal>doc</literal> for the books and articles, and + <literal>base</literal> for the operating system and manual + pages. To edit manual pages, the <literal>base</literal> + repository must be checked out separately.</para> + + <para xml:lang="en">Repositories may contain multiple versions of documentation + and source code. New modifications are almost always made only + to the latest version, called <literal>head</literal>.</para> + </sect1> + + <sect1 xml:id="working-copy-choosing-directory"> + <title xml:lang="en">Choosing a Directory</title> + + <para xml:lang="en">FreeBSD documentation is traditionally stored in + <filename>/usr/doc/</filename>, and system + source code with manual pages in + <filename>/usr/src/</filename>. These + directory trees are relocatable, and users may want to put the + working copies in other locations to avoid interfering with + existing information in the main directories. The examples + that follow use <filename>~/doc</filename> + and <filename>~/src</filename>, both + subdirectories of the user's home directory.</para> + </sect1> + + <sect1 xml:id="working-copy-checking-out"> + <title xml:lang="en">Checking Out a Copy</title> + + <para xml:lang="en">A download of a working copy from the repository is called + a <emphasis>checkout</emphasis>, and done with + <command>svn checkout</command>. This example checks out a + copy of the latest version (<literal>head</literal>) of + the main documentation tree:</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + + <para xml:lang="en">A checkout of the source code to work on manual pages is + very similar:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-updating"> + <title xml:lang="en">Updating a Working Copy</title> + + <para xml:lang="en">The documents and files in the FreeBSD repository change daily. + People modify files and commit changes frequently. Even a short + time after an initial checkout, there will already be + differences between the local working copy and the main FreeBSD + repository. To update the local version with the changes that + have been made to the main repository, use + <command>svn update</command> on the directory containing the + local working copy:</para> + + <screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> + + <para xml:lang="en">Get in the protective habit of using + <command>svn update</command> before editing document files. + Someone else may have edited that file very recently, and the + local working copy will not include the latest changes until it + has been updated. Editing the newest version of a file is much + easier than trying to combine an older, edited local file with + the newer version from the repository.</para> + </sect1> + + <sect1 xml:id="working-copy-revert"> + <title xml:lang="en">Reverting Changes</title> + + <para xml:lang="en">Sometimes it turns out that changes were + not necessary after all, or the writer just wants to start over. + Files can be <quote>reset</quote> to their unchanged form with + <command>svn revert</command>. For example, to erase the edits + made to <filename>chapter.xml</filename> and reset it to + unmodified form:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-making-diff"> + <title xml:lang="en">Making a Diff</title> + + <para xml:lang="en">After edits to a file or group of files are completed, the + differences between the local working copy and the version on + the FreeBSD repository must be collected into a single file for + submission. These <emphasis>diff</emphasis> files are produced + by redirecting the output of <command>svn diff</command> into a + file:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> + + <para xml:lang="en">Give the file a meaningful name that identifies the + contents. The example above is for spelling fixes to the whole + documentation tree.</para> + + <para xml:lang="en">If the diff file is to be submitted with the web + <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a FreeBSD + problem report</link></quote> interface, add a + <filename>.txt</filename> extension to give the earnest and + simple-minded web form a clue that the contents are plain + text.</para> + + <para xml:lang="en">Be careful: <command>svn diff</command> includes all changes + made in the current directory and any subdirectories. If there + are files in the working copy with edits that are not ready to + be submitted yet, provide a list of only the files that are to + be included:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-subversion-references"> + <title xml:lang="en"><application>Subversion</application> References</title> + + <para xml:lang="en">These examples show very basic usage of + <application>Subversion</application>. More detail is available + in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link> + and the <link xlink:href="http://subversion.apache.org/docs/">Subversion + documentation</link>.</para> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="structure"> + <title xml:lang="en">Documentation Directory Structure</title> + + <para xml:lang="en">Files and directories in the + <filename>doc/</filename> tree follow a + structure meant to:</para> + + <orderedlist> + <listitem> + <para xml:lang="en">Make it easy to automate converting the document to other + formats.</para> + </listitem> + + <listitem> + <para xml:lang="en">Promote consistency between the different documentation + organizations, to make it easier to switch between working on + different documents.</para> + </listitem> + + <listitem> + <para xml:lang="en">Make it easy to decide where in the tree new documentation + should be placed.</para> + </listitem> + </orderedlist> + + <para xml:lang="en">In addition, the documentation tree must accommodate + documents in many different languages and encodings. It is + important that the documentation tree structure does not enforce + any particular defaults or cultural preferences.</para> + + <sect1 xml:id="structure-top"> + <title xml:lang="en">The Top Level, + <filename>doc/</filename></title> + + <para xml:lang="en">There are two types of directory under + <filename>doc/</filename>, each with very + specific directory names and meanings.</para> + + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry xml:lang="en">Directory</entry> + <entry xml:lang="en">Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top" xml:lang="en"> + <filename>share</filename></entry> + + <entry xml:lang="en">Contains files that are not specific to the various + translations and encodings of the documentation. + Contains subdirectories to further categorize the + information. For example, the files that comprise the + <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> infrastructure are in + <filename>share/mk</filename>, while + the additional <acronym>XML</acronym> support files + (such as the FreeBSD extended DocBook + <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry> + </row> + + <row> + <entry valign="top" xml:lang="en"> + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> + + <entry xml:lang="en">One directory exists for each available translation + and encoding of the documentation, for example + <filename>en_US.ISO8859-1/</filename> + and <filename>zh_TW.UTF-8/</filename>. + The names are long, but by fully specifying the language + and encoding we prevent any future headaches when a + translation team wants to provide documentation in the + same language but in more than one encoding. This also + avoids problems that might be caused by a future switch + to Unicode.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="structure-locale"> + <title xml:lang="en">The + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> + Directories</title> + + <para xml:lang="en">These directories contain the documents themselves. The + documentation is split into up to three more categories at + this level, indicated by the different directory names.</para> + + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry xml:lang="en">Directory</entry> + <entry xml:lang="en">Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top" xml:lang="en"> + <filename>articles</filename></entry> + + <entry xml:lang="en">Documentation marked up as a DocBook + <tag>article</tag> (or equivalent). Reasonably + short, and broken up into sections. Normally only + available as one <acronym>XHTML</acronym> file.</entry> + </row> + + <row> + <entry valign="top" xml:lang="en"><filename>books</filename></entry> + + <entry xml:lang="en">Documentation marked up as a DocBook + <tag>book</tag> (or equivalent). Book length, + and broken up into chapters. Normally available as both + one large <acronym>XHTML</acronym> file (for people with + fast connections, or who want to print it easily from a + browser) and as a collection of linked, smaller + files.</entry> + </row> + + <row> + <entry valign="top" xml:lang="en"> + <filename>man</filename></entry> + + <entry xml:lang="en">For translations of the system manual pages. This + directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename> + directories, corresponding to the sections that have + been translated.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para xml:lang="en">Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> + directory will have all of these subdirectories. It depends + on how much translation has been accomplished by that + translation team.</para> + </sect1> + + <sect1 xml:id="structure-document"> + <title xml:lang="en">Document-Specific Information</title> + + <para xml:lang="en">This section contains specific notes about particular + documents managed by the FDP.</para> + + <sect2> + <title xml:lang="en">The Handbook</title> + + <subtitle xml:lang="en"><filename>books/handbook/</filename></subtitle> + + <para xml:lang="en">The Handbook is written in DocBook <acronym>XML</acronym> + using the FreeBSD DocBook extended <acronym>DTD</acronym>.</para> + + <para xml:lang="en">The Handbook is organized as a DocBook + <tag>book</tag>. The book is divided into + <tag>part</tag>s, each of which contains several + <tag>chapter</tag>s. <tag>chapter</tag>s are + further subdivided into sections (<tag>sect1</tag>) + and subsections (<tag>sect2</tag>, + <tag>sect3</tag>) and so on.</para> + + <sect3> + <title xml:lang="en">Physical Organization</title> + + <para xml:lang="en">There are a number of files and directories within the + <filename>handbook</filename> directory.</para> + + <note> + <para xml:lang="en">The Handbook's organization may change over time, and + this document may lag in detailing the organizational + changes. Post questions about Handbook organization to the + <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para> + </note> + + <sect4> + <title xml:lang="en"><filename>Makefile</filename></title> + + <para xml:lang="en">The <filename>Makefile</filename> defines some + variables that affect how the <acronym>XML</acronym> + source is converted to other formats, and lists the + various source files that make up the Handbook. It then + includes the standard <filename>doc.project.mk</filename>, + to bring in the rest of the code that handles converting + documents from one format to another.</para> + </sect4> + + <sect4> + <title xml:lang="en"><filename>book.xml</filename></title> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201606210119.u5L1Jh8x001297>