Changeset View
Changeset View
Standalone View
Standalone View
zh_TW.UTF-8/books/fdp-primer/book.xml
Context not available. | |||||
<abstract> | <abstract> | ||||
<para>感謝您參與 FreeBSD 說明文件計劃,您的點滴貢獻,都相當寶貴。</para> | <para>感謝您參與 FreeBSD 說明文件計劃,您的點滴貢獻,都相當寶貴。</para> | ||||
<para>本入手書內容包括:如何開始著手貢獻 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, <acronym>FDP</acronym>) 的各項細節,以及會用到的一些工具、軟體 ,以及文件計畫的宗旨。</para> | <para>本入手書內容包括:如何開始著手貢獻 FreeBSD 說明文件計劃 (FreeBSD Documentation Project, <acronym>FDP</acronym>) 的各項細節,以及會用到的一些工具、軟體,以及文件計畫的宗旨。</para> | ||||
<para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para> | <para>本入門書仍在持續撰寫中。任何修正或新增內容的建議都非常歡迎。</para> | ||||
</abstract> | </abstract> | ||||
Context not available. | |||||
<sect1 xml:id="preface-prompts"> | <sect1 xml:id="preface-prompts"> | ||||
<title>Shell 提示符號</title> | <title>Shell 提示符號</title> | ||||
<para>下表顯示出一般使用者帳號與 root 的提示符號,在所有的文件例子中會用提示符號(prompt) ,來提醒您該用哪種帳號才對。</para> | <para>下表顯示出一般使用者帳號與 root 的提示符號,在所有的文件例子中會用提示符號 (Prompt),來提醒您該用哪種帳號才對。</para> | ||||
<informaltable frame="none" pgwide="1"> | <informaltable frame="none" pgwide="1"> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
Context not available. | |||||
<row> | <row> | ||||
<entry>使用者名稱和群組名稱</entry> | <entry>使用者名稱和群組名稱</entry> | ||||
<entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry> | <entry>只有 <systemitem class="username">root</systemitem> 才可以做這件事。</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
Context not available. | |||||
</important> | </important> | ||||
<warning> | <warning> | ||||
<para>警告:表示警告事項,比如如果您不則可能導致的損失。這些損失可能是對您或硬體造成實際傷害, 也可能是無法估計的損害,例如一時疏忽而刪除重要檔案...。</para> | <para>警告:表示警告事項,比如如果您不則可能導致的損失。這些損失可能是對您或硬體造成實際傷害,也可能是無法估計的損害,例如一時疏忽而刪除重要檔案...。</para> | ||||
</warning> | </warning> | ||||
<example> | <example> | ||||
Context not available. | |||||
<sect1 xml:id="overview-quick-start"> | <sect1 xml:id="overview-quick-start"> | ||||
<title>快速上手</title> | <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> | <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> | <procedure> | ||||
<step> | <step> | ||||
Context not available. | |||||
<step> | <step> | ||||
<para>編輯需要修改的說明文件檔案。如果檔案需要大幅度的編修,請先諮詢郵件論壇。</para> | <para>編輯需要修改的說明文件檔案。如果檔案需要大幅度的編修,請先諮詢郵件論壇。</para> | ||||
<para>標籤 (Tag) 和 Entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>. 。</para> | <para>標籤 (Tag) 和 Entity 的使用方式可以參考 <xref linkend="xhtml-markup"/> 和 <xref linkend="docbook-markup"/>。</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
Context not available. | |||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>使用網頁版 <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">問題回報</link> 系統提交 diff 檔。 如果使用網頁版,請輸入 <emphasis>[patch] <replaceable>問題簡短描述</replaceable></emphasis> 的概要 。選擇 <literal>docs</literal> 分類和 <literal>doc-bug</literal>類別。在訊息的主體中,輸入修正的簡短描述和其他相關的重要的細節。使用 <guibutton>[!Browse...!]</guibutton> 按鈕來附加 diff 檔。</para> | <para>使用網頁版 <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">問題回報</link> 系統提交 diff 檔。如果使用網頁版,請輸入 <emphasis>[patch] <replaceable>問題簡短描述</replaceable></emphasis> 的概要 。選擇 <literal>docs</literal> 分類和 <literal>doc-bug</literal>類別。在訊息的主體中,輸入修正的簡短描述和其他相關的重要的細節。使用 <guibutton>[!Browse...!]</guibutton> 按鈕來附加 diff 檔。</para> | ||||
</step> | </step> | ||||
</procedure> | </procedure> | ||||
</sect1> | </sect1> | ||||
Context not available. | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><emphasis>常見問答集 (FAQ)</emphasis>:主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案 。 (簡單講,就是『問答集』格式) 通常會擺在這裡面的問答格式,不會放太長的詳細內容。</para> | <para><emphasis>常見問答集 (FAQ)</emphasis>:主要是收集在各郵件論壇或論壇會常問到或有可能會問到的 FreeBSD 相關問題與答案。(簡單講,就是『問答集』格式) 通常會擺在這裡面的問答格式,不會放太長的詳細內容。</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><emphasis>操作手冊 (Manual page)</emphasis>:英文版的系統手冊並不是由 <acronym>FDP</acronym> 所撰寫的,因為它們是屬於基礎系統 (Base system) 的部份。 然而,<acronym>FDP</acronym> 可以修改這些文件,來讓這些文件寫得更清楚,甚至是勘正錯誤的地方。</para> | <para><emphasis>操作手冊 (Manual page)</emphasis>:英文版的系統手冊並不是由 <acronym>FDP</acronym> 所撰寫的,因為它們是屬於基礎系統 (Base system) 的部份。然而,<acronym>FDP</acronym> 可以修改這些文件,來讓這些文件寫得更清楚,甚至是勘正錯誤的地方。</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
Context not available. | |||||
<para>線上手冊的原始碼則是在 <literal>https://svn.FreeBSD.org/base/</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>說明文件提交訊息可以用 <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>這些儲存庫的網頁版位於 <link xlink:href="https://svnweb.FreeBSD.org/doc/"/> 和 <link xlink:href="https://svnweb.FreeBSD.org/base/"/>。</para> | ||||
Context not available. | |||||
<chapter version="5.0" xml:id="tools"> | <chapter version="5.0" xml:id="tools"> | ||||
<title>工具</title> | <title>工具</title> | ||||
<para>有些工具軟體用來管理 FreeBSD 說明文件,並將他轉換成不同的輸出格式。 有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的,但是裝了之後會更容易進行文件製作工作。</para> | <para>有些工具軟體用來管理 FreeBSD 說明文件,並將他轉換成不同的輸出格式。有些則是在使用接下來章節的範例之前一定要安裝。有些工具是選擇性安裝的,但是裝了之後會更容易進行文件製作工作。</para> | ||||
<sect1 xml:id="tools-required"> | <sect1 xml:id="tools-required"> | ||||
<title>必備工具</title> | <title>必備工具</title> | ||||
<para>從 Port 套件集安裝 <package>textproc/docproj</package>。這個 <emphasis>meta-port</emphasis> 會安裝處理 FreeBSD 說明文件需要的所有應用程式。以下列出特定元件的進一步說明。</para> | <para>從 Port 套件集安裝 <package>textproc/docproj</package>。這個 <emphasis>meta-port</emphasis> 會安裝處理 FreeBSD 說明文件需要的所有應用程式。以下列出特定元件的進一步說明。</para> | ||||
<sect2> | <sect2> | ||||
<title><acronym>DTD</acronym>s 與 <acronym>Entities</acronym></title> | <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> | <para>FreeBSD 說明文件使用幾種文件類型定義 (<acronym>DTD</acronym>s) 與 <acronym>XML</acronym> entities 集合。這些都會經由 <package>textproc/docproj</package> Port 來安裝。</para> | ||||
<variablelist> | <variablelist> | ||||
<varlistentry> | <varlistentry> | ||||
Context not available. | |||||
<term>ISO 8879 entities (<package>textproc/iso8879</package>)</term> | <term>ISO 8879 entities (<package>textproc/iso8879</package>)</term> | ||||
<listitem> | <listitem> | ||||
<para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用, 包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para> | <para>在 ISO 8879:1986 之中的 entity 被許多 <acronym>DTD</acronym> 所大量使用,包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para> | ||||
</listitem> | </listitem> | ||||
</varlistentry> | </varlistentry> | ||||
</variablelist> | </variablelist> | ||||
Context not available. | |||||
<para>FreeBSD 說明文件不只有書籍與文章,還有所有指令與設定檔的操作手冊 (Manual page) 也是文件的一部份,其中也有一部份是 <acronym>FDP</acronym> 的地盤。相關的檔案庫有兩個:<literal>doc</literal> 中有書籍與文章,而 <literal>base</literal> 中有作業系統以及操作手冊。要編輯操作手冊則必須另外取出 (Checkout) <literal>base</literal> 檔案庫。</para> | <para>FreeBSD 說明文件不只有書籍與文章,還有所有指令與設定檔的操作手冊 (Manual page) 也是文件的一部份,其中也有一部份是 <acronym>FDP</acronym> 的地盤。相關的檔案庫有兩個:<literal>doc</literal> 中有書籍與文章,而 <literal>base</literal> 中有作業系統以及操作手冊。要編輯操作手冊則必須另外取出 (Checkout) <literal>base</literal> 檔案庫。</para> | ||||
<para>檔案庫中可能會含有數個版本的說明文件與原始碼。新的修改幾乎都只對最新版本 <literal>head</literal> 做更新。</para> | <para>檔案庫中可能會含有數個版本的說明文件與原始碼。新的修改幾乎都只對最新版本 <literal>head</literal> 做更新。</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="working-copy-choosing-directory"> | <sect1 xml:id="working-copy-choosing-directory"> | ||||
<title>選擇一個目錄</title> | <title>選擇一個目錄</title> | ||||
<para>FreeBSD 說明文件一般會儲存在 <filename>/usr/doc/</filename>,而系統原始碼及操作手冊則會存在 <filename>/usr/src/</filename>。這些目錄樹可改放在其他地方,使用者可能會為了避免與現有在主要目錄的資料搞混,把工作副本放在其他的地方。以下的例子會放在 <filename>~/doc</filename> 以及 <filename>~/src</filename> 兩個在使用者家目錄下的目錄。</para> | <para>FreeBSD 說明文件一般會儲存在 <filename>/usr/doc/</filename>,而系統原始碼及操作手冊則會存在 <filename>/usr/src/</filename>。這些目錄樹可改放在其他地方,有些使用者可能會為了避免與現有在主要目錄的資料搞混,把工作副本放在其他的地方。以下的例子會放在 <filename>~/doc</filename> 以及 <filename>~/src</filename> 兩個在使用者家目錄下的目錄。</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="working-copy-checking-out"> | <sect1 xml:id="working-copy-checking-out"> | ||||
Context not available. | |||||
<screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> | <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> | ||||
<para>取出原始碼編輯操作手冊的動作非常相似:</para> | <para>取出原始碼編輯操作手冊的動作也很相似:</para> | ||||
<screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> | <screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> | ||||
</sect1> | </sect1> | ||||
Context not available. | |||||
<screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> | <screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> | ||||
<para>養成良好的習慣在編輯文件檔前先執行 <command>svn update</command>,可能會有其他人才剛編輯完該檔案,本地工作副本在尚未更新前不會有最後的變更內容,編輯最新版本的檔案會比將舊版本地檔案與新版檔案庫檔案合併來的簡單多了。</para> | <para>養成良好的習慣在編輯文件檔前先執行 <command>svn update</command>,由於可能會有其他人最近才編輯完該檔案,若未更新本地工作副則不會有最新變更的內容,比其還要將舊版本地檔案與新版檔案庫檔案合併的動作來說,直接編輯最新版本的檔案要簡單多了。</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="working-copy-revert"> | <sect1 xml:id="working-copy-revert"> | ||||
<title>還原變更</title> | <title>還原變更</title> | ||||
<para>有時才做完的變更可能就變的不需要了,或者作者剛想要重新搛寫。檔案可使以使用 <command>svn revert</command> 來<quote>重設</quote>成尚未被修改刪的狀態,舉例來說,要清除所有對 <filename>chapter.xml</filename> 的修改然後還原到未修改的版本可:</para> | <para>有時才做完的變更可能就變的不需要了,或者作者剛想要重新搛寫。檔案可使以使用 <command>svn revert</command> 來<quote>重設</quote>成尚未被修改過的狀態,舉例來說,要清除所有對 <filename>chapter.xml</filename> 的修改然後還原到未修改的版本可:</para> | ||||
<screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen> | <screen xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen> | ||||
</sect1> | </sect1> | ||||
Context not available. | |||||
<entry valign="top" xml:lang="en"> | <entry valign="top" xml:lang="en"> | ||||
<filename>articles</filename></entry> | <filename>articles</filename></entry> | ||||
<entry>以 DocBook <tag>article</tag> (或同等級) 標記的說明文件。非常短,且會分成幾個小節,通常取得時只會有一個 <acronym>XHTML</acronym> 檔案。</entry> | <entry>以 DocBook <tag>article</tag> (或同等級) 標記的說明文件。非常短,且會分成幾個小節,通常取得時只會有一個 <acronym>XHTML</acronym> 檔案。</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry valign="top" xml:lang="en"><filename>books</filename></entry> | <entry valign="top" xml:lang="en"><filename>books</filename></entry> | ||||
<entry>以 DocBook <tag>book</tag> (或同等級) 標記的說明文件。有跟書籍一樣的長度,會分成數個章。通常取得時會包含一個大型的 <acronym>XHTML</acronym> 檔 (供有較快連線速度的人使用,或者那些想直接在瀏覽器列印的人) 與數個連結的較小的檔案。</entry> | <entry>以 DocBook <tag>book</tag> (或同等級) 標記的說明文件。有跟書籍一樣的長度,會分成數個章。通常取得時會包含一個大型的 <acronym>XHTML</acronym> 檔 (供有較快連線速度的人使用,或者那些想直接在瀏覽器列印的人) 與數個連結的較小的檔案。</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
Context not available. | |||||
<para>那麼放置這個 <filename>chapter.xml</filename> 的目錄則會命名為 <filename>kernelconfig</filename>。一般來說一章的所有內容會存放在這一個檔案。</para> | <para>那麼放置這個 <filename>chapter.xml</filename> 的目錄則會命名為 <filename>kernelconfig</filename>。一般來說一章的所有內容會存放在這一個檔案。</para> | ||||
<para>當有 <acronym>XHTML</acronym> 版本的使用手冊之後,也會用這個檔產出 <filename>kernelconfig.html</filename>,這個名稱是根據 <literal>id</literal> 的值而定,與目錄名稱無關。</para> | <para>當有 <acronym>XHTML</acronym> 版本的使用手冊之後,會用該檔產出 <filename>kernelconfig.html</filename>,而這個名稱也是根據 <literal>id</literal> 的值而定,與目錄名稱無關。</para> | ||||
<para>在早期版本的使用手冊,檔案皆儲存在與 <filename>book.xml</filename> 相同的目錄中,而名稱會以 <tag>chapter</tag> 元素中的 <literal>id</literal> 屬性的值來命名。現在可在每個章節之中引用圖片,每個使用手冊章節的圖片會儲存在 <filename>share/images/books/handbook</filename>,而在地化版本的圖片應放在與每個章節 <acronym>XML</acronym> 原始碼相同的目錄。命名空間會衝突是必然的,但以目錄多、檔案少與目錄少、檔案多的結構相比,目錄多、檔案少會較容易處理命名空間衝突的問題。</para> | <para>在早期版本的使用手冊,檔案皆儲存在與 <filename>book.xml</filename> 相同的目錄中,而名稱會以 <tag>chapter</tag> 元素中的 <literal>id</literal> 屬性的值來命名。現在可在每個章節之中引用圖片,每個使用手冊章節的圖片會儲存在 <filename>share/images/books/handbook</filename>,而在地化版本的圖片應放在與每個章節 <acronym>XML</acronym> 原始碼相同的目錄。命名空間會衝突是必然的,但以目錄多、檔案少與目錄少、檔案多的結構相比,目錄多、檔案少會較容易處理命名空間衝突的問題。</para> | ||||
Context not available. | |||||
<para>請勿以在使用手冊中的章節順序來命名章節或目錄,因為順序是會隨使用手冊重新組織後的內容改變的。重新組織結構應不需要去重新命名檔案,除非整個章節的階層被提升或下降。</para> | <para>請勿以在使用手冊中的章節順序來命名章節或目錄,因為順序是會隨使用手冊重新組織後的內容改變的。重新組織結構應不需要去重新命名檔案,除非整個章節的階層被提升或下降。</para> | ||||
</important> | </important> | ||||
<para><filename>chapter.xml</filename> 檔案並不是可以被單獨建置的完整 <acronym>XML</acronym> 文件,只能做為使用手冊的一部份來建置。</para> | <para><filename>chapter.xml</filename> 檔案並不是可以被單獨建置的完整 <acronym>XML</acronym> 文件,只能結合成整本使用手冊之後再一併建置。</para> | ||||
</sect4> | </sect4> | ||||
</sect3> | </sect3> | ||||
</sect2> | </sect2> | ||||
Context not available. | |||||
<sect2 xml:id="sub-make"> | <sect2 xml:id="sub-make"> | ||||
<title>子目錄的 <filename>Makefile</filename></title> | <title>子目錄的 <filename>Makefile</filename></title> | ||||
<para xml:lang="en">These <filename>Makefile</filename>s usually take the form | <para>這種 <filename>Makefile</filename> 通常採用的格式為:</para> | ||||
of:</para> | |||||
<programlisting xml:lang="en">SUBDIR =articles | <programlisting xml:lang="en">SUBDIR =articles | ||||
SUBDIR+=books | SUBDIR+=books | ||||
Context not available. | |||||
DOC_PREFIX?= ${.CURDIR}/.. | DOC_PREFIX?= ${.CURDIR}/.. | ||||
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> | .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> | ||||
<para xml:lang="en">The first four non-empty lines define the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> | <para>前四行非空白的行用來定義 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 的變數 <varname>SUBDIR</varname>, <varname>COMPAT_SYMLINK</varname> 及 <varname>DOC_PREFIX</varname>。</para> | ||||
variables <varname>SUBDIR</varname>, | |||||
<varname>COMPAT_SYMLINK</varname>, and | |||||
<varname>DOC_PREFIX</varname>.</para> | |||||
<para xml:lang="en">The <varname>SUBDIR</varname> statement and | <para><varname>SUBDIR</varname> 敘述與 <varname>COMPAT_SYMLINK</varname> 敘述示範了如何指派數值到一個變數,覆蓋先前的值。</para> | ||||
<varname>COMPAT_SYMLINK</varname> statement show how to | |||||
assign a value to a variable, overriding any previous | |||||
value.</para> | |||||
<para xml:lang="en">The second <varname>SUBDIR</varname> statement shows how a | <para><varname>SUBDIR</varname> 的第二行敘述示範如何將數值附加到目前的變數值之後,<varname>SUBDIR</varname> 變數現在變成了 <literal>articles books</literal>。</para> | ||||
value is appended to the current value of a variable. The | |||||
<varname>SUBDIR</varname> variable is now <literal>articles | |||||
books</literal>.</para> | |||||
<para xml:lang="en">The <varname>DOC_PREFIX</varname> assignment shows how a | <para><varname>DOC_PREFIX</varname> 指派式示範了如何只在變數尚未定義時才指派數值給變數。這個功能在當 <varname>DOC_PREFIX</varname> 不在 <filename>Makefile</filename> 所認為的地方時,使用者可以覆蓋這個值,並提供正確的值。</para> | ||||
value is assigned to the variable, but only if it is not | |||||
already defined. This is useful if | |||||
<varname>DOC_PREFIX</varname> is not where this | |||||
<filename>Makefile</filename> thinks it is - the user can | |||||
override this and provide the correct value.</para> | |||||
<para xml:lang="en">What does it all mean? <varname>SUBDIR</varname> | <para>這所有的敘述實際代表什麼意思呢? <varname>SUBDIR</varname> 會列出接下來建置流程應傳遞作業到那些子目錄。</para> | ||||
mentions which subdirectories below this one the build process | |||||
should pass any work on to.</para> | |||||
<para xml:lang="en"><varname>COMPAT_SYMLINK</varname> is specific to | <para><varname>COMPAT_SYMLINK</varname> 是一個用來指定語言官方編碼的相容性符號連結 (<filename>doc/en</filename> 會指向 <filename>en_US.ISO-8859-1</filename>)。</para> | ||||
compatibility symlinks (amazingly enough) for languages to | |||||
their official encoding (<filename>doc/en</filename> would | |||||
point to <filename>en_US.ISO-8859-1</filename>).</para> | |||||
<para xml:lang="en"><varname>DOC_PREFIX</varname> is the path to the root of | <para><varname>DOC_PREFIX</varname> 是到 FreeBSD 說明文件計劃樹根目錄的路徑。這並非每一次都可以很輕易找到,為了增加彈性,要改寫也很簡單。<varname>.CURDIR</varname> 是一個 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 內建的變數,代表目前目錄的路徑。</para> | ||||
the FreeBSD Document Project tree. This is not always that easy | |||||
to find, and is also easily overridden, to allow for | |||||
flexibility. <varname>.CURDIR</varname> is a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |||||
builtin variable with the path to the current | |||||
directory.</para> | |||||
<para xml:lang="en">The final line includes the FreeBSD Documentation Project's | <para>最後一行會引用 FreeBSD 說明文件計劃的全專案 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 系統檔 <filename>doc.project.mk</filename>,用來轉換這些變數成為建置的指令。</para> | ||||
project-wide <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> system file | |||||
<filename>doc.project.mk</filename> which is the glue which | |||||
converts these variables into build instructions.</para> | |||||
</sect2> | </sect2> | ||||
<sect2 xml:id="doc-make"> | <sect2 xml:id="doc-make"> | ||||
Context not available. | |||||
<para>本章節是供要翻譯 FreeBSD 說明文件 (常見問答集 (FAQ)、使用手冊 (Handbook)、教學 (Tutorial)、操作手冊 (Manual page) 等) 到各種語言的常見問答集 (FAQ)。</para> | <para>本章節是供要翻譯 FreeBSD 說明文件 (常見問答集 (FAQ)、使用手冊 (Handbook)、教學 (Tutorial)、操作手冊 (Manual page) 等) 到各種語言的常見問答集 (FAQ)。</para> | ||||
<para>本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文說明文件計劃的翻譯常見問答集為母本而來的, 原始撰稿者為 Frank Gründer <email>elwood@mc5sys.in-berlin.de</email>,並由 Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。</para> | <para>本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文說明文件計劃的翻譯常見問答集為母本而來的,原始撰稿者為 Frank Gründer <email>elwood@mc5sys.in-berlin.de</email>,並由 Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。</para> | ||||
<para>本常見問答集是由文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 所維護。</para> | <para>本常見問答集是由文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 所維護。</para> | ||||
Context not available. | |||||
<answer> | <answer> | ||||
<para><phrase>i18n</phrase> 指的是國際化 (<phrase>Internationalization</phrase>) 而 <phrase>l10n</phrase> 指的是在地化 (<phrase>Localization</phrase>)。這些都是為了書寫方便而用的簡寫。</para> | <para><phrase>i18n</phrase> 指的是國際化 (<phrase>Internationalization</phrase>) 而 <phrase>l10n</phrase> 指的是在地化 (<phrase>Localization</phrase>)。這些都是為了書寫方便而用的簡寫。</para> | ||||
<para><phrase>i18n</phrase> 就是開頭為 <quote>i</quote> 後面有 18 個字母,最後接 <quote>n</quote>。同樣地, <phrase>l10n</phrase> 是開頭為 <quote>l</quote> 後面有 10 個字母,最後接 <quote>n</quote>。</para> | <para><phrase>i18n</phrase> 就是開頭為 <quote>i</quote> 後面有 18 個字母,最後接 <quote>n</quote>。同樣地,<phrase>l10n</phrase> 是開頭為 <quote>l</quote> 後面有 10 個字母,最後接 <quote>n</quote>。</para> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
Context not available. | |||||
</question> | </question> | ||||
<answer> | <answer> | ||||
<para>當然囉,越多人參與翻譯,那麼就能夠越快翻完,而且英文版說明文件若有增減、更新的話, 各翻譯版也可以儘快同步囉。</para> | <para>當然囉,越多人參與翻譯,那麼就能夠越快翻完,而且英文版說明文件若有增減、更新的話,各翻譯版也可以儘快同步囉。</para> | ||||
<para>不一定得是專業譯者,才能參與翻譯的。</para> | <para>不一定得是專業譯者,才能參與翻譯的。</para> | ||||
</answer> | </answer> | ||||
Context not available. | |||||
</question> | </question> | ||||
<answer> | <answer> | ||||
<para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">說明文件計劃翻譯頁 </link> 列了目前已知的各翻譯者成果 ,如果已經有其他人也在做跟你一樣的翻譯工作,那麼請不要重複浪費人力, 請與他們聯繫看看還有哪些地方可以幫上忙的。</para> | <para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">說明文件計劃翻譯頁 </link> 列了目前已知的各翻譯者成果,如果已經有其他人也在做跟你一樣的翻譯工作,那麼請不要重複浪費人力,請與他們聯繫看看還有哪些地方可以幫上忙的。</para> | ||||
<para>若上面並未列出你母語的翻譯,或是也有人要翻譯但還未公開宣布的話,那麼就寄信到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 說明文件計劃郵遞論壇 </link>。</para> | <para>若上面並未列出你母語的翻譯,或是也有人要翻譯但還未公開宣布的話,那麼就寄信到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD 說明文件計劃郵遞論壇 </link>。</para> | ||||
</answer> | </answer> | ||||
Context not available. | |||||
<answer> | <answer> | ||||
<para>恭喜啊,你剛好踏上 <quote>FreeBSD <replaceable>您的語言</replaceable> 說明文件翻譯計劃</quote>的啟程之路,歡迎登船。</para> | <para>恭喜啊,你剛好踏上 <quote>FreeBSD <replaceable>您的語言</replaceable> 說明文件翻譯計劃</quote>的啟程之路,歡迎登船。</para> | ||||
<para>首先呢,先判斷是否有妥善規劃時間,因為你只有一個人在翻而已, 因此,相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para> | <para>首先呢,先判斷是否有妥善規劃時間,因為你只有一個人在翻而已,因此,相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para> | ||||
<para>寫信到文件計劃郵遞論壇 (Documentation Project mailing list) 向大家宣布你正準備要翻譯,然後文件計劃的翻譯部分就會更新相關資料。</para> | <para>寫信到文件計劃郵遞論壇 (Documentation Project mailing list) 向大家宣布你正準備要翻譯,然後文件計劃的翻譯部分就會更新相關資料。</para> | ||||
<para>若你的國家已經有人提供 FreeBSD 的鏡像站 (Mirror) 服務的話,那麼就先跟他們聯繫, 並詢問你是否在上面可以有網頁空間來放相關計劃資料,以及是否可以有提供電子郵件帳號或郵遞論壇服務。</para> | <para>若你的國家已經有人提供 FreeBSD 的鏡像站 (Mirror) 服務的話,那麼就先跟他們聯繫,並詢問你是否在上面可以有網頁空間來放相關計劃資料,以及是否可以有提供電子郵件帳號或郵遞論壇服務。</para> | ||||
<para>然後,就開始翻文件囉,一開始翻譯的時候,先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦,或是如何上手之類的說明文章。</para> | <para>然後,就開始翻文件囉,一開始翻譯的時候,先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦,或是如何上手之類的說明文章。</para> | ||||
</answer> | </answer> | ||||
Context not available. | |||||
</question> | </question> | ||||
<answer> | <answer> | ||||
<para>這要看情況而定。若你是在翻譯團隊內做的話 (像是日本團隊、德國團隊), 他們會有自己內部流程來決定翻譯文件怎麼送,這些大致流程會在他們網頁上面有寫。</para> | <para>這要看情況而定。若你是在翻譯團隊內做的話 (像是日本團隊、德國團隊),他們會有自己內部流程來決定翻譯文件怎麼送,這些大致流程會在他們網頁上面有寫。</para> | ||||
<para>若你是某語系的唯一翻譯者 (或你是負責某翻譯計劃,並想把成果回饋給 FreeBSD 計劃) ,那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para> | <para>若你是某語系的唯一翻譯者 (或你是負責某翻譯計劃,並想把成果回饋給 FreeBSD 計劃),那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
Context not available. | |||||
<para>舉例來說,假設有瑞典文 (Swedish) 版的翻譯,那麼應該會長像:</para> | <para>舉例來說,假設有瑞典文 (Swedish) 版的翻譯,那麼應該會長像:</para> | ||||
<programlisting>head/ | <programlisting xml:lang="en">head/ | ||||
sv_SE.ISO8859-1/ | sv_SE.ISO8859-1/ | ||||
Makefile | Makefile | ||||
htdocs/ | htdocs/ | ||||
Context not available. | |||||
Makefile | Makefile | ||||
book.xml</programlisting> | book.xml</programlisting> | ||||
<para><literal>sv_SE.ISO8859-1</literal>是依照 <filename><replaceable>語系 (Lang)</replaceable>.<replaceable>編碼 (Encoding)</replaceable></filename> 的規則來建立的譯名。 請注意:其中有兩個 Makefile 檔,它們是用來建置說明文件的。</para> | <para><literal>sv_SE.ISO8859-1</literal>是依照 <filename><replaceable>語系 (Lang)</replaceable>.<replaceable>編碼 (Encoding)</replaceable></filename> 的規則來建立的譯名。請注意:其中有兩個 Makefile 檔,它們是用來建置說明文件的。</para> | ||||
<para>然後請用 <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 與 <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來把你的說明文件壓縮起來,並寄到本計劃來。</para> | <para>然後請用 <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 與 <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> 來把你的說明文件壓縮起來,並寄到本計劃來。</para> | ||||
<screen><prompt>%</prompt> <userinput>cd doc</userinput> | <screen><prompt>%</prompt> <userinput>cd doc</userinput> | ||||
<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput> | <prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput> | ||||
<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput></screen> | <prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput></screen> | ||||
<para>接著,把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上,若你沒有自己網頁空間的話(ISP不提供) ,那麼可以該檔寄到文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 來。</para> | <para>接著,把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上,若你沒有自己網頁空間的話 (ISP 不提供),那麼可以該檔寄到文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 來。</para> | ||||
<para>還有,記得用 Bugzilla 提交一個回報來通知大家你已經提交說明文件了, 還有,若有人可以幫忙檢閱、複審文件的話,對翻譯品質較好, 因為這也有助於提升翻譯品質的流暢度。</para> | <para>還有,記得用 Bugzilla 提交一個回報來通知大家你已經提交說明文件了,還有,若有人可以幫忙檢閱、複審文件的話,對翻譯品質較好,因為這也有助於提升翻譯品質的流暢度。</para> | ||||
<para>最後,會有人 (可能是文件計劃管理者,或是文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 成員) 會檢閱你的翻譯文件,並確認是否可正常編譯。此外,他們會特別注意下列幾點:</para> | <para>最後,會有人 (可能是文件計劃管理者,或是文件工程團隊 Documentation Engineering Team <email>doceng@FreeBSD.org</email> 成員) 會檢閱你的翻譯文件,並確認是否可正常編譯。此外,他們會特別注意下列幾點:</para> | ||||
Context not available. | |||||
<answer> | <answer> | ||||
<para>我們希望不要這麼做。</para> | <para>我們希望不要這麼做。</para> | ||||
<para>舉例來說,假設你正準備把使用手冊 (Handbook) 翻譯為韓文版, 並希望把韓國零售商也加到你翻譯的韓文版使用手冊內。</para> | <para>舉例來說,假設你正準備把使用手冊 (Handbook) 翻譯為韓文版,並希望把韓國零售商也加到你翻譯的韓文版使用手冊內。</para> | ||||
<para>我們想不出來有啥原因,為什麼不把這些資訊提供給英文版呢?(或是德文、西班牙文、日文等 …) 因為,有可能英語讀者跑去韓國時,會想買 FreeBSD 相關產品。 此外,這也可以提升 FreeBSD 的可見度,很顯然的,這並不是件壞事啊。</para> | <para>我們想不出來有啥原因,為什麼不把這些資訊提供給英文版呢?(或是德文、西班牙文、日文等 …) 因為,有可能英語讀者跑去韓國時,會想買 FreeBSD 相關產品。此外,這也可以提升 FreeBSD 的可見度,很顯然的,這並不是件壞事啊。</para> | ||||
<para>若你有某國才有的資料,請提供給英文版使用手冊以作為修訂 (用 Bugzilla),然後再把英文版的修訂部分翻為你要翻譯的使用手冊吧。</para> | <para>若你有某國才有的資料,請提供給英文版使用手冊以作為修訂 (用 Bugzilla),然後再把英文版的修訂部分翻為你要翻譯的使用手冊吧。</para> | ||||
<para>謝謝。</para> | <para>謝謝。</para> | ||||
</answer> | </answer> | ||||
Context not available. | |||||
<seglistitem> | <seglistitem> | ||||
<seg>&Eacute;</seg> | <seg>&Eacute;</seg> | ||||
<seg>É</seg> | <seg>É</seg> | ||||
<seg>大 <quote>E</quote>,並帶尖、重音 (Acute accent)</seg> | <seg>大 <quote>E</quote>,並帶尖、重音 (Acute accent)</seg> | ||||
</seglistitem> | </seglistitem> | ||||
<seglistitem> | <seglistitem> | ||||
Context not available. | |||||
<answer> | <answer> | ||||
<para>在英文文件內,讀者都是以 <quote>you</quote> 來稱呼,而有些語言並沒有正式/非正式的區隔。</para> | <para>在英文文件內,讀者都是以 <quote>you</quote> 來稱呼,而有些語言並沒有正式/非正式的區隔。</para> | ||||
<para>若你所要翻的語言可以區別這些差異,那麼請用該語系在一般技術說明文件上所使用的稱呼吧。 如果容易造成困惑的話,那麼請改用較中性的稱呼來取代。</para> | <para>若你所要翻的語言可以區別這些差異,那麼請用該語系在一般技術說明文件上所使用的稱呼吧。如果容易造成困惑的話,那麼請改用較中性的稱呼來取代。</para> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
Context not available. | |||||
$FreeBSD$ | $FreeBSD$ | ||||
--></programlisting> | --></programlisting> | ||||
<para>實際上的內容可能稍有不同,但每份原稿都會附上 $FreeBSD$ 這一行以及 <literal>The FreeBSD Documentation Project</literal> 宣告。 請注意:$FreeBSD$ 開頭的這行是會由 Subversion 隨著每次異動而自動更改的,所以新檔案的話請保持原狀 (也就是只要寫 $FreeBSD$ 就好了)。</para> | <para>實際上的內容可能稍有不同,但每份原稿都會附上 $FreeBSD$ 這一行以及 <literal>The FreeBSD Documentation Project</literal> 宣告。請注意:$FreeBSD$ 開頭的這行是會由 Subversion 隨著每次異動而自動更改的,所以新檔案的話請保持原狀 (也就是只要寫 $FreeBSD$ 就好了)。</para> | ||||
<para>翻譯文件中,必須都要有 $FreeBSD$ 這行,並且把 <literal>FreeBSD Documentation Project</literal> 這行改為 <literal>The FreeBSD <replaceable>language</replaceable> Documentation Project</literal>。</para> | <para>翻譯文件中,必須都要有 $FreeBSD$ 這行,並且把 <literal>FreeBSD Documentation Project</literal> 這行改為 <literal>The FreeBSD <replaceable>language</replaceable> Documentation Project</literal>。</para> | ||||
<para>此外,還必須加上第三行來指出你所翻譯的,到底是以英文版原稿的哪一版本為母本所做的翻譯。</para> | <para>此外,還必須加上第三行來指出你所翻譯的,到底是以英文版原稿的哪一版本為母本所做的翻譯。</para> | ||||
Context not available. | |||||
<sect1 xml:id="po-translations-introduction"> | <sect1 xml:id="po-translations-introduction"> | ||||
<title>簡介</title> | <title>簡介</title> | ||||
<para><link xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym> <application>gettext</application></link> 系統提供翻譯者一個簡單的方法來建立和維護文件的翻譯。翻譯的字串從原始文件題取出來到 <acronym>PO</acronym> (Portable Object) 檔。字串的翻譯用另外的編輯器輸入。翻譯的字串可以直接使用,或是編譯成原始文件的完整翻譯版本。</para> | <para><link xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym> <application>gettext</application></link> 系統提供翻譯者一個簡單的方法來建立和維護文件的翻譯。翻譯的字串從原始文件題取出來到 <acronym>PO</acronym> (Portable Object) 檔。字串的翻譯用另外的編輯器輸入。翻譯的字串可以直接使用,或是編譯成原始文件的完整翻譯版本。</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="po-translations-quick-start"> | <sect1 xml:id="po-translations-quick-start"> | ||||
Context not available. | |||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>從原始文件處將 <filename>Makefile</filename> 複製到翻譯目錄。</para> | <para>從原始文件處將 <filename>Makefile</filename> 複製到翻譯目錄。</para> | ||||
<screen><prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \ | <screen xml:lang="en"><prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \ | ||||
~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen> | ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen> | ||||
</step> | </step> | ||||
</procedure> | </procedure> | ||||
Context not available. | |||||
<step> | <step> | ||||
<para>使用 <acronym>PO</acronym> 編輯器將翻譯輸入 <acronym>PO</acronym> 檔。有幾個不同的編輯器可以使用。這裡用的是 <package role="port">editors/poedit</package> 的 <filename>poedit</filename> 。</para> | <para>使用 <acronym>PO</acronym> 編輯器將翻譯輸入 <acronym>PO</acronym> 檔。有幾個不同的編輯器可以使用。這裡用的是 <package role="port">editors/poedit</package> 的 <filename>poedit</filename> 。</para> | ||||
<para><acronym>PO</acronym> 檔名是兩個字元的語系碼後面接底線和兩個字元的區域碼。以西班牙語來說,檔名是 <filename>es_ES.po</filename> 。</para> | <para><acronym>PO</acronym> 檔名是兩個字元的語系碼後面接底線和兩個字元的區域碼。以西班牙語來說,檔名是 <filename>es_ES.po</filename> 。</para> | ||||
<screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> | <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> | ||||
</step> | </step> | ||||
Context not available. | |||||
<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> | <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> | ||||
<prompt>%</prompt> <userinput>make tran</userinput></screen> | <prompt>%</prompt> <userinput>make tran</userinput></screen> | ||||
<para>產生的文件名稱與英文原始文件名稱相符,文章通常是 <filename>article.xml</filename> ,書籍是 <filename>book.xml</filename> 。</para> | <para>產生的文件名稱與英文原始文件名稱相符,文章通常是 <filename>article.xml</filename>,書籍是 <filename>book.xml</filename> 。</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
Context not available. | |||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>翻譯位於主要說明文件目錄的子目錄,這裡假設如 <xref linkend="overview-quick-start"/> 所示,是 <filename>~/doc/</filename>。例如德文位於 <filename>~/doc/de_DE.ISO8859-1/</filename>, 法文位於 <filename>~/doc/fr_FR.ISO8859-1/</filename>。</para> | <para>翻譯位於主要說明文件目錄的子目錄,這裡假設如 <xref linkend="overview-quick-start"/> 所示,是 <filename>~/doc/</filename>。例如德文位於 <filename>~/doc/de_DE.ISO8859-1/</filename>,法文位於 <filename>~/doc/fr_FR.ISO8859-1/</filename>。</para> | ||||
<para>每個語系目錄包含不同文件類型的子目錄,通常是 <filename>articles/</filename> 和 <filename>books/</filename>。</para> | <para>每個語系目錄包含不同文件類型的子目錄,通常是 <filename>articles/</filename> 和 <filename>books/</filename>。</para> | ||||
Context not available. | |||||
<para>當翻譯到一個新語系時必須建立一個新的語系目錄。如果語系目錄已經存在,那只需要有 <filename>articles/</filename> 或 <filename>books/</filename> 的子目錄。</para> | <para>當翻譯到一個新語系時必須建立一個新的語系目錄。如果語系目錄已經存在,那只需要有 <filename>articles/</filename> 或 <filename>books/</filename> 的子目錄。</para> | ||||
<para>FreeBSD 說明文件的編譯是由同一個目錄的 <filename>Makefile</filename> 控制。簡單的文章可以從原始的英語目錄直接複製 <filename>Makefile</filename> 過來。書籍的翻譯流程結合多個獨立的 <filename>book.xml</filename> 和 <filename>chapter.xml</filename> 成為一個檔案, 所以書籍翻譯的 <filename>Makefile</filename> 必須複製並修改。</para> | <para>FreeBSD 說明文件的編譯是由同一個目錄的 <filename>Makefile</filename> 控制。簡單的文章可以從原始的英語目錄直接複製 <filename>Makefile</filename> 過來。書籍的翻譯流程結合多個獨立的 <filename>book.xml</filename> 和 <filename>chapter.xml</filename> 成為一個檔案,所以書籍翻譯的 <filename>Makefile</filename> 必須複製並修改。</para> | ||||
<example xml:id="po-translations-creating-example"> | <example xml:id="po-translations-creating-example"> | ||||
<title>建立 Porter 手冊的西班牙語翻譯</title> | <title>建立 Porter 手冊的西班牙語翻譯</title> | ||||
<para>建立 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook">Porter 手冊</link> 的西班牙文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename> 的書籍。</para> | <para>建立 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook">Porter 手冊</link> 的西班牙文翻譯。原文是位於 <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename> 的書籍。</para> | ||||
<procedure> | <procedure> | ||||
<step> | <step> | ||||
<para>西班牙文 books 目錄 <filename>~/doc/es_ES.ISO8859-1/books/</filename> 已經存在,所以只要建立 Porter 手冊的子目錄:</para> | <para>西班牙文 books 目錄 <filename>~/doc/es_ES.ISO8859-1/books/</filename> 已經存在,所以只要建立 Porter 手冊的子目錄:</para> | ||||
<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput> | <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput> | ||||
<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput> | <prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput> | ||||
A porters-handbook</screen> | A porters-handbook</screen> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>從原始文件的目錄複製 <filename>Makefile</filename> :</para> | <para>從原始文件的目錄複製 <filename>Makefile</filename>:</para> | ||||
<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> | <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> | ||||
<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput> | <prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput> | ||||
A Makefile</screen> | A Makefile</screen> | ||||
Context not available. | |||||
<procedure> | <procedure> | ||||
<step> | <step> | ||||
<para>法文文章目錄 <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> 已經存在,所以只要建立 <acronym>PGP</acronym> 金鑰文章的子目錄:</para> | <para>法文文章目錄 <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> 已經存在,所以只要建立 <acronym>PGP</acronym> 金鑰文章的子目錄:</para> | ||||
<screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput> | <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput> | ||||
<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput> | <prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput> | ||||
A pgpkeys</screen> | A pgpkeys</screen> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>從原始文件的目錄複製 <filename>Makefile</filename> :</para> | <para>從原始文件的目錄複製 <filename>Makefile</filename>:</para> | ||||
<screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput> | <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput> | ||||
<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput> | <prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput> | ||||
A Makefile</screen> | A Makefile</screen> | ||||
<para>檢查 <filename>Makefile</filename> 的內容。因為這是簡單的文章,此例的 <filename>Makefile</filename> 不用修改。第二行的 <literal>$FreeBSD...$</literal> 版本字串將會在檔案提交時被版本控制系統替換掉。</para> | <para>檢查 <filename>Makefile</filename> 的內容。因為這是簡單的文章,此例的 <filename>Makefile</filename> 不用修改。第二行的 <literal>$FreeBSD...$</literal> 版本字串將會在檔案提交時被版本控制系統替換掉。</para> | ||||
<programlisting xml:lang="en"># | <programlisting xml:lang="en"># | ||||
# $FreeBSD$ | # $FreeBSD$ | ||||
Context not available. | |||||
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> | .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> | ||||
<para>文章結構處理好後, 可以執行建立 <command>make po</command> 建立 <acronym>PO</acronym> 檔。</para> | <para>文章結構處理好後,可以執行建立 <command>make po</command> 建立 <acronym>PO</acronym> 檔。</para> | ||||
</step> | </step> | ||||
</procedure> | </procedure> | ||||
</example> | </example> | ||||
Context not available. | |||||
<sect1 xml:id="po-translations-translating"> | <sect1 xml:id="po-translations-translating"> | ||||
<title>翻譯</title> | <title>翻譯</title> | ||||
<para><application>gettext</application> 系統大幅減少翻譯者要追蹤的事情。 字串從原始文件提取到 <acronym>PO</acronym> 檔。再用 <acronym>PO</acronym> 檔編輯器輸入字串的翻譯。</para> | <para><application>gettext</application> 系統大幅減少翻譯者要追蹤的事情。字串從原始文件提取到 <acronym>PO</acronym> 檔。再用 <acronym>PO</acronym> 檔編輯器輸入字串的翻譯。</para> | ||||
<para>FreeBSD <acronym>PO</acronym> 翻譯系統不會覆蓋掉 <acronym>PO</acronym> 檔。所以提取步驟可以在任何時候重複執行來更新 <acronym>PO</acronym> 檔。</para> | <para>FreeBSD <acronym>PO</acronym> 翻譯系統不會覆蓋掉 <acronym>PO</acronym> 檔。所以提取步驟可以在任何時候重複執行來更新 <acronym>PO</acronym> 檔。</para> | ||||
<para>用 <acronym>PO</acronym> 檔編輯器來編輯檔案。此例是用 <package role="port">editors/poedit</package>,因為它很簡單而且系統需求低。其他的 <acronym>PO</acronym> 檔編輯器提供一些特點,能使翻譯工作更輕鬆。Port 套件集裡有數個編輯器,包括 <package role="port">devel/gtranslator</package> 。</para> | <para>用 <acronym>PO</acronym> 檔編輯器來編輯檔案。此例是用 <package role="port">editors/poedit</package>,因為它很簡單而且系統需求低。其他的 <acronym>PO</acronym> 檔編輯器提供一些特點,能使翻譯工作更輕鬆。Port 套件集裡有數個編輯器,包括 <package role="port">devel/gtranslator</package> 。</para> | ||||
<para>保留 <acronym>PO</acronym> 檔是很重要的。它包含所有的翻譯成果。</para> | <para>保留 <acronym>PO</acronym> 檔是很重要的。它包含所有的翻譯成果。</para> | ||||
Context not available. | |||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>使用 <acronym>PO</acronym> 檔編輯器輸入翻譯:</para> | <para>使用 <acronym>PO</acronym> 檔編輯器輸入翻譯:</para> | ||||
<screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> | <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> | ||||
</step> | </step> | ||||
Context not available. | |||||
<programlisting>&dollar;FreeBSD&dollar;</programlisting> | <programlisting>&dollar;FreeBSD&dollar;</programlisting> | ||||
<para>版本控制符號不會把 <literal>&dollar;</literal> entities 看成金錢符號,所以不會把字串展開成版本字串。</para> | <para>版本控制符號不會把 <literal>&dollar;</literal> entities 看成金錢符號,所以不會把字串展開成版本字串。</para> | ||||
<para>當 <acronym>PO</acronym> 檔建立之後,在範例中使用到的 <literal>&dollar;</literal> Entity 會被取代成實際的錢字符號,這會使的 <literal>$FreeBSD$</literal> 字串在提交時錯誤的被版本控制系統展開成版本字串。</para> | <para>當 <acronym>PO</acronym> 檔建立之後,在範例中使用到的 <literal>&dollar;</literal> Entity 會被取代成實際的錢字符號,這會使的 <literal>$FreeBSD$</literal> 字串在提交時錯誤的被版本控制系統展開成版本字串。</para> | ||||
<para>在英文文件上使用的方法也可以用在翻譯上,翻譯時在 <acronym>PO</acronym> 編輯器用 <literal>&dollar;</literal> 來取代金錢符號:</para> | <para>在英文文件上使用的方法也可以用在翻譯上,翻譯時在 <acronym>PO</acronym> 編輯器用 <literal>&dollar;</literal> 來取代金錢符號:</para> | ||||
<programlisting>&dollar;FreeBSD&dollar;</programlisting> | <programlisting>&dollar;FreeBSD&dollar;</programlisting> | ||||
</sect2> | </sect2> | ||||
Context not available. | |||||
<example xml:id="po-translations-building-example"> | <example xml:id="po-translations-building-example"> | ||||
<title>編譯西班牙文 Porter 手冊</title> | <title>編譯西班牙文 Porter 手冊</title> | ||||
<para>編譯和預覽之前範例翻譯的西班牙文版 Porter 手冊</para> | <para>編譯和預覽之前範例翻譯的西班牙文版 Porter 手冊</para> | ||||
<procedure> | <procedure> | ||||
<step> | <step> | ||||
Context not available. | |||||
<step> | <step> | ||||
<para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統:</para> | <para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統:</para> | ||||
<screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput> | <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput> | ||||
<prompt>%</prompt> <userinput>ls</userinput> | <prompt>%</prompt> <userinput>ls</userinput> | ||||
Makefile article.xml es_ES.po | Makefile article.xml es_ES.po | ||||
<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput> | <prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput> | ||||
Context not available. | |||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>設定檔案的 <acronym>MIME</acronym> 類型。書籍和文章是 <literal>text/xml</literal> ,<acronym>PO</acronym> 檔是 <literal>text/x-gettext-translation</literal> 。</para> | <para>設定檔案的 <acronym>MIME</acronym> 類型。書籍和文章是 <literal>text/xml</literal>,<acronym>PO</acronym> 檔是 <literal>text/x-gettext-translation</literal> 。</para> | ||||
<screen><prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput> | <screen><prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput> | ||||
property 'svn:mime-type' set on 'es_ES.po' | property 'svn:mime-type' set on 'es_ES.po' | ||||
Context not available. | |||||
<step> | <step> | ||||
<para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統:</para> | <para>增加 <filename>Makefile</filename> 、<acronym>PO</acronym> 檔和產生的 <acronym>XML</acronym> 翻譯到版本控制系統:</para> | ||||
<screen><prompt>%</prompt> <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput> | <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput> | ||||
<prompt>%</prompt> <userinput>ls</userinput> | <prompt>%</prompt> <userinput>ls</userinput> | ||||
Makefile article.xml ko_KR.po | Makefile article.xml ko_KR.po | ||||
<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput> | <prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput> | ||||
Context not available. | |||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>設定檔案的 <acronym>MIME</acronym> 類型。因為這些檔案使用 <acronym>UTF-8</acronym> 字元集,這也需要指定。為了防止版本控制系統將這些檔案誤認為二進位資料,<literal>fbsd:notbinary</literal> 屬性也需要設定。</para> | <para>設定檔案的 <acronym>MIME</acronym> 類型。因為這些檔案使用 <acronym>UTF-8</acronym> 字元集,這也需要指定。為了防止版本控制系統將這些檔案誤認為二進位資料,<literal>fbsd:notbinary</literal> 屬性也需要設定。</para> | ||||
<screen><prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/x-gettext-translation;charset=UTF-8' ko_KR.po</userinput> | <screen><prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/x-gettext-translation;charset=UTF-8' ko_KR.po</userinput> | ||||
property 'svn:mime-type' set on 'ko_KR.po' | property 'svn:mime-type' set on 'ko_KR.po' | ||||
Context not available. | |||||
<sect1 xml:id="writing-style-guide"> | <sect1 xml:id="writing-style-guide"> | ||||
<title>風格指南</title> | <title>風格指南</title> | ||||
<para>由於說明文件是由眾多作者所維護,為了保持寫作風格的一貫性, 請遵守下列撰寫風格慣例。</para> | <para>由於說明文件是由眾多作者所維護,為了保持寫作風格的一貫性,請遵守下列撰寫風格慣例。</para> | ||||
<sect2> | <sect2> | ||||
<title>大小寫</title> | <title>大小寫</title> | ||||
<para>Tag 的部份都是用小寫字母,譬如是用 <tag>para</tag> ,<emphasis>而非</emphasis><tag>PARA</tag>。</para> | <para>Tag 的部份都是用小寫字母,譬如是用 <tag>para</tag>,<emphasis>而非</emphasis><tag>PARA</tag>。</para> | ||||
<para>而 SGML 內文則是用大寫字母表示,像是: <literal><!ENTITY…></literal> 及 <literal><!DOCTYPE…></literal>, <emphasis>而不是</emphasis> <literal><!entity…></literal> 及 <literal><!doctype…></literal>。</para> | <para>而 SGML 內文則是用大寫字母表示,像是: <literal><!ENTITY…></literal> 及 <literal><!DOCTYPE…></literal>,<emphasis>而不是</emphasis> <literal><!entity…></literal> 及 <literal><!doctype…></literal>。</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="writing-style-acronyms"> | <sect2 xml:id="writing-style-acronyms"> | ||||
<title>縮寫</title> | <title>縮寫</title> | ||||
<para>縮寫字(acronym)通常在書中第一次提到時,必須同時列出完整拼法, 比如:<quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>。 定義縮寫字之後,應該儘量只使用該縮寫字(而非完整詞彙, 除非使用完整詞彙可以更能表達語意)來表達即可。 通常每本書只會第一次提到時,才會列出完整詞彙, 但若您高興也可以在每章第一次提到時又列出完整詞彙。</para> | <para>縮寫字 (Acronym) 通常在書中第一次提到時,必須同時列出完整拼法,比如:<quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>。定義縮寫字之後,應該儘量只使用該縮寫字(而非完整詞彙,除非使用完整詞彙可以更能表達語意)來表達即可。通常每本書只會第一次提到時,才會列出完整詞彙,但若您高興也可以在每章第一次提到時又列出完整詞彙。</para> | ||||
<para>所有縮寫要包在<tag>acronym</tag>標籤內。</para> | <para>所有縮寫要包在<tag>acronym</tag>標籤內。</para> | ||||
</sect2> | </sect2> | ||||
Context not available. | |||||
<sect2 xml:id="writing-style-indentation"> | <sect2 xml:id="writing-style-indentation"> | ||||
<title>縮排</title> | <title>縮排</title> | ||||
<para><emphasis>無論</emphasis>檔案縮排設定為何, 每個檔案的第一行都不縮排。</para> | <para><emphasis>無論</emphasis>檔案縮排設定為何,每個檔案的第一行都不縮排。</para> | ||||
<para>未完的標籤會以多兩個空白來增加縮排, 結尾的標籤則少兩個空白來縮減縮排。 若已達 8 個空白,則以 tab 取代之。 此外,在 tab 前面不要再用空白,也不要在每行後面加上空白。 每個 tag 的內文若超過一行的話,則接下來的就多兩個空白以做縮排。</para> | <para>未完的標籤會以多兩個空白來增加縮排,結尾的標籤則少兩個空白來縮減縮排。若已達 8 個空白,則以 tab 取代之。此外,在 tab 前面不要再用空白,也不要在每行後面加上空白。每個 tag 的內文若超過一行的話,則接下來的就多兩個空白以做縮排。</para> | ||||
<para>舉個例子,這節所用的寫法大致是下面這樣:</para> | <para>舉個例子,這節所用的寫法大致是下面這樣:</para> | ||||
<programlisting><tag class="starttag">chapter</tag> | <programlisting xml:lang="en"><tag class="starttag">chapter</tag> | ||||
<tag class="starttag">title</tag>...<tag class="endtag">title</tag> | <tag class="starttag">title</tag>...<tag class="endtag">title</tag> | ||||
<tag class="starttag">sect1</tag> | <tag class="starttag">sect1</tag> | ||||
Context not available. | |||||
<tag class="starttag">para</tag>The first line in each file starts with no indentation, | <tag class="starttag">para</tag>The first line in each file starts with no indentation, | ||||
<tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of | <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of | ||||
the file which might contain the current file。<tag class="endtag">para</tag> | the file which might contain the current file.<tag class="endtag">para</tag> | ||||
... | ... | ||||
<tag class="endtag">sect2</tag> | <tag class="endtag">sect2</tag> | ||||
Context not available. | |||||
<para>有長屬性的標籤也是遵循一樣的原則。遵守縮排規則可以幫助編輯和作者了解哪些內容在標籤內:</para> | <para>有長屬性的標籤也是遵循一樣的原則。遵守縮排規則可以幫助編輯和作者了解哪些內容在標籤內:</para> | ||||
<programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link | <programlisting xml:lang="en"><tag class="starttag">para</tag>See the <tag class="starttag">link | ||||
linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag> | linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag> | ||||
section if there are problems booting. Powering down and | section if there are problems booting. Powering down and | ||||
disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk | disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk | ||||
Context not available. | |||||
<literal>systemitem</literal> element has been moved to the | <literal>systemitem</literal> element has been moved to the | ||||
next line to avoid wrapping and indenting:</para> | next line to avoid wrapping and indenting:</para> | ||||
<programlisting><tag class="starttag">para</tag>With file flags, even | <programlisting xml:lang="en"><tag class="starttag">para</tag>With file flags, even | ||||
<tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be | <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be | ||||
prevented from removing or altering files。<tag class="endtag">para</tag></programlisting> | prevented from removing or altering files.<tag class="endtag">para</tag></programlisting> | ||||
<para xml:lang="en">Configurations to help various text editors conform to | <para xml:lang="en">Configurations to help various text editors conform to | ||||
these guidelines can be found in | these guidelines can be found in | ||||
Context not available. | |||||
<sect3 xml:id="writing-style-tag-style-spacing"> | <sect3 xml:id="writing-style-tag-style-spacing"> | ||||
<title>標籤間距</title> | <title>標籤間距</title> | ||||
<para>同一縮排階層的標籤要以空一行來做區隔,而不同縮排階層的則不必。 比如:</para> | <para>同一縮排階層的標籤要以空一行來做區隔,而不同縮排階層的則不必。比如:</para> | ||||
<informalexample> | <informalexample> | ||||
<programlisting><tag class="starttag">article lang='en'</tag> | <programlisting xml:lang="en"><tag class="starttag">article lang='en'</tag> | ||||
<tag class="starttag">articleinfo</tag> | <tag class="starttag">articleinfo</tag> | ||||
<tag class="starttag">title</tag>NIS<tag class="endtag">title</tag> | <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag> | ||||
Context not available. | |||||
<sect3 xml:id="writing-style-tag-style-separating"> | <sect3 xml:id="writing-style-tag-style-separating"> | ||||
<title>分隔標籤</title> | <title>分隔標籤</title> | ||||
<para>像是 <tag>itemizedlist</tag> 這類的標籤事實上本身不含任何文字資料,必須得由其他標籤來補充內文。 這類的標籤會獨用一整行。</para> | <para>像是 <tag>itemizedlist</tag> 這類的標籤事實上本身不含任何文字資料,必須得由其他標籤來補充內文。這類的標籤會獨用一整行。</para> | ||||
<para>另外,像是 <tag>para</tag> 及 <tag>term</tag> 這類的標籤並不需搭配其他標籤, 就可附上文字資料,並且在標籤後面的<emphasis>同一行</emphasis>內即可立即寫上這些內文。</para> | <para>另外,像是 <tag>para</tag> 及 <tag>term</tag> 這類的標籤並不需搭配其他標籤,就可附上文字資料,並且在標籤後面的<emphasis>同一行</emphasis>內即可立即寫上這些內文。</para> | ||||
<para>當然,這兩類的標籤結尾時也是跟上面道理相同。</para> | <para>當然,這兩類的標籤結尾時也是跟上面道理相同。</para> | ||||
<para>不過,當上述這兩種標籤混用時,會有很明顯的困擾。</para> | <para>不過,當上述這兩種標籤混用時,會有很明顯的困擾。</para> | ||||
<para>當第一類標籤的後面接上第二類標籤的話, 那麼要把這兩類標籤各自分行來寫。 後者標籤的段落, 也是需要做適當縮排調整。</para> | <para>當第一類標籤的後面接上第二類標籤的話,那麼要把這兩類標籤各自分行來寫。後者標籤的段落,也是需要做適當縮排調整。</para> | ||||
<para>而第二類標籤結尾時,可以與第一類標籤的結尾放在同一行。</para> | <para>而第二類標籤結尾時,可以與第一類標籤的結尾放在同一行。</para> | ||||
</sect3> | </sect3> | ||||
Context not available. | |||||
<para><emphasis>在提交修改時,請別在修改內容的同時也一起更改編排格式</emphasis>。</para> | <para><emphasis>在提交修改時,請別在修改內容的同時也一起更改編排格式</emphasis>。</para> | ||||
<para>如此一來,像是翻譯團隊才能迅速找出你改了哪些內容, 而不用費心思去判斷該行的改變,是由於格式重排或者內容異動。</para> | <para>如此一來,像是翻譯團隊才能迅速找出你改了哪些內容,而不用費心思去判斷該行的改變,是由於格式重排或者內容異動。</para> | ||||
<para>舉例說明,若要在某段加上兩個句子,如此一來該段落的某行勢必會超出 80 縱列,這時請先 commmit 修改。 接著,再修飾過長行落的換行,然後再次 commit 之。 而第二次的 commit 紀錄,請明確說明這只是 whitespace-only (修改空白而已) 的更改,如此一來,翻譯團隊就可以忽略第二次 commit 了 。</para> | <para>舉例說明,若要在某段加上兩個句子,如此一來該段落的某行勢必會超出 80 縱列,這時請先 commmit 修改。接著,再修飾過長行落的換行,然後再次 commit 之。而第二次的 commit 紀錄,請明確說明這只是 whitespace-only (修改空白而已) 的更改,如此一來,翻譯團隊就可以忽略第二次 commit 了 。</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="writing-style-nonbreaking-space"> | <sect2 xml:id="writing-style-nonbreaking-space"> | ||||
<title>不斷行空白</title> | <title>不斷行空白</title> | ||||
<para>請避免一些情況下的斷行:造成版面醜醜的、或是須連貫表達的同一句子。 斷行的情況會隨所閱讀的工具不同而有所不同。 尤其是透過純文字瀏覽器來看 HTML 說明文件時會更明顯看到類似下面這樣不好的編排段落:</para> | <para>請避免一些情況下的斷行:造成版面醜醜的、或是須連貫表達的同一句子。斷行的情況會隨所閱讀的工具不同而有所不同。尤其是透過純文字瀏覽器來看 HTML 說明文件時會更明顯看到類似下面這樣不好的編排段落:</para> | ||||
<literallayout class="monospaced">Data capacity ranges from 40 MB to 15 | <literallayout class="monospaced" xml:lang="en">Data capacity ranges from 40 MB to 15 | ||||
GB。 Hardware compression …</literallayout> | GB. Hardware compression …</literallayout> | ||||
<para>請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行, 以下示範如何使用不斷行空白:</para> | <para>請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行,以下示範如何使用不斷行空白:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
Context not available. | |||||
<sect1 xml:id="writing-style-word-list"> | <sect1 xml:id="writing-style-word-list"> | ||||
<title>詞彙表</title> | <title>詞彙表</title> | ||||
<para>以下詞彙表列出使用在 FreeBSD 文件的正確拼法和大小寫。 若找不到要找的詞彙,請詢問 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link> 。</para> | <para>以下詞彙表列出使用在 FreeBSD 文件的正確拼法和大小寫。若找不到要找的詞彙,請詢問 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link> 。</para> | ||||
<informaltable frame="none" pgwide="0"> | <informaltable frame="none" pgwide="0"> | ||||
<tgroup cols="3"> | <tgroup cols="3"> | ||||
Context not available. | |||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para><link xlink:href="http://www.oasis-open.org/docbook/">The DocBook 技術委員會</link>, DocBook DTD的維護者</para> | <para><link xlink:href="http://www.oasis-open.org/docbook/">The DocBook 技術委員會</link>,DocBook DTD的維護者</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><link xlink:href="http://www.docbook.org/">DocBook:The Definitive Guide</link>, DocBook DTD 的線上說明文件。</para> | <para><link xlink:href="http://www.docbook.org/">DocBook:The Definitive Guide</link>,DocBook DTD 的線上說明文件。</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
Context not available. | |||||
<example> | <example> | ||||
<title>DocBook <tag>book</tag></title> | <title>DocBook <tag>book</tag></title> | ||||
<programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" | <programlisting xml:lang="en"><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" | ||||
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> | "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> | ||||
<tag class="starttag">book xmlns="http://docbook.org/ns/docbook" | <tag class="starttag">book xmlns="http://docbook.org/ns/docbook" | ||||
Context not available. | |||||
<tag class="endtag">copyright</tag> | <tag class="endtag">copyright</tag> | ||||
<tag class="starttag">abstract</tag> | <tag class="starttag">abstract</tag> | ||||
<tag class="starttag">para</tag>If your book has an abstract then it should go here。<tag class="endtag">para</tag> | <tag class="starttag">para</tag>If your book has an abstract then it should go here.<tag class="endtag">para</tag> | ||||
<tag class="endtag">abstract</tag> | <tag class="endtag">abstract</tag> | ||||
<tag class="endtag">info</tag> | <tag class="endtag">info</tag> | ||||
Context not available. | |||||
<tag class="starttag">title</tag>Preface<tag class="endtag">title</tag> | <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag> | ||||
<tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed | <tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed | ||||
here。<tag class="endtag">para</tag> | here.<tag class="endtag">para</tag> | ||||
<tag class="endtag">preface</tag> | <tag class="endtag">preface</tag> | ||||
<tag class="starttag">chapter</tag> | <tag class="starttag">chapter</tag> | ||||
<tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag> | <tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag> | ||||
<tag class="starttag">para</tag>This is the first chapter in my book。<tag class="endtag">para</tag> | <tag class="starttag">para</tag>This is the first chapter in my book.<tag class="endtag">para</tag> | ||||
<tag class="starttag">sect1</tag> | <tag class="starttag">sect1</tag> | ||||
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> | <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> | ||||
<tag class="starttag">para</tag>This is the first section in my book。<tag class="endtag">para</tag> | <tag class="starttag">para</tag>This is the first section in my book.<tag class="endtag">para</tag> | ||||
<tag class="endtag">sect1</tag> | <tag class="endtag">sect1</tag> | ||||
<tag class="endtag">chapter</tag> | <tag class="endtag">chapter</tag> | ||||
<tag class="endtag">book</tag></programlisting> | <tag class="endtag">book</tag></programlisting> | ||||
Context not available. | |||||
<example> | <example> | ||||
<title>DocBook <tag>article</tag></title> | <title>DocBook <tag>article</tag></title> | ||||
<programlisting><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" | <programlisting xml:lang="en"><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" | ||||
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> | "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> | ||||
<tag class="starttag">article xmlns="http://docbook.org/ns/docbook" | <tag class="starttag">article xmlns="http://docbook.org/ns/docbook" | ||||
Context not available. | |||||
<tag class="endtag">copyright</tag> | <tag class="endtag">copyright</tag> | ||||
<tag class="starttag">abstract</tag> | <tag class="starttag">abstract</tag> | ||||
<tag class="starttag">para</tag>If your article has an abstract then it should go here。<tag class="endtag">para</tag> | <tag class="starttag">para</tag>If your article has an abstract then it should go here.<tag class="endtag">para</tag> | ||||
<tag class="endtag">abstract</tag> | <tag class="endtag">abstract</tag> | ||||
<tag class="endtag">info</tag> | <tag class="endtag">info</tag> | ||||
Context not available. | |||||
<tag class="starttag">sect1</tag> | <tag class="starttag">sect1</tag> | ||||
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> | <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> | ||||
<tag class="starttag">para</tag>This is the first section in my article。<tag class="endtag">para</tag> | <tag class="starttag">para</tag>This is the first section in my article.<tag class="endtag">para</tag> | ||||
<tag class="starttag">sect2</tag> | <tag class="starttag">sect2</tag> | ||||
<tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag> | <tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag> | ||||
<tag class="starttag">para</tag>This is the first sub-section in my article。<tag class="endtag">para</tag> | <tag class="starttag">para</tag>This is the first sub-section in my article.<tag class="endtag">para</tag> | ||||
<tag class="endtag">sect2</tag> | <tag class="endtag">sect2</tag> | ||||
<tag class="endtag">sect1</tag> | <tag class="endtag">sect1</tag> | ||||
<tag class="endtag">article</tag></programlisting> | <tag class="endtag">article</tag></programlisting> | ||||
Context not available. |