由於 FreeBSD 文件是由眾多作者所維護的,為了保持寫作風格的一貫性, 於是就產生較有共識的寫作規則,請各位記得要遵守。
同一個字在不同種類的英語會有著不同的拼法。 遇到拼字不同的情況,請採用美式英語拼法。 像是: 請改用 “color”,而非 “colour”。 請改用 “rationalize”,而非 “rationalise” 等等類似字彙。
注: 若文章採用英式英語也可以接受,但必須全篇文章都採用同一拼法才行 。 而文件的其他部份,像是書、網頁、 manual 說明等則必須採用美式英語。
請不要簡寫(contraction)。 請務必將完整的字寫出來。 比如: “Don't use contractions” 這句有用到簡寫,就要避免。
正式書面寫法避免簡寫的原因,乃是因為如此一來字句意思較精準, 且對譯者會比較輕鬆些。
英文段落通常會逗號(,)作為該句所提到的各項目的語氣區隔。 並且會在最後一個提到的項目時,先加上逗號再接上 “and”, 最後才是最後的項目。
舉個例子,看看下面這句:
This is a list of one, two and three items.
那麼這一句到底是有三個項目(“one”、“two” 、“three”)呢?或者是只有兩個項目(“one”、 “two and three”)呢?
因此較妥的方式是以 serial comma 的方式,才能正確表達語意:
This is a list of one, two, and three items.
然而,在翻譯過程中,建議把逗號(,)部份改為頓號(、),並且 “and” 的部份可略而不翻,以免語意頓塞。
請試著避免使用贅詞(redundant phrase)。 尤其是 “這個指令”、“這個檔案”、“man 指令” 這幾個通常都是不必要的贅詞。
以指令(command)方面舉例,比較妥當的用法是第二句的例子:
以檔案(filename)方面舉例,比較妥當的用法是第二句的例子:
以 man(manual)方面舉例,比較妥當的用法是第二句(有用到 SGML <citerefentry> 標籤):
詳情請參閱 csh(1)。
為了使文章更易閱讀,以及讓 Emacs 之類的工具容易運用,請在每一完整句子後面加上兩個空白。
不過,句號(.)後面有接大寫字母, 並不一定表示前一個句點所在處就是完整句子, 尤其是名字部份常常會有這現象。 像是 “Jordan K. Hubbard” 這人名就是很好的例證:句號後面接空白,然後是大寫的 H,然而這肯定並不是兩段句子。
撰寫風格的相關細節,可參閱 William Strunk 所寫的 Elements of Style。
由於 Handbook 是由眾多作者所維護,為了保持寫作風格的一貫性, 請遵守下列撰寫風格。
Tag 的部份都是用小寫字母,譬如是用 <para> ,而非 <PARA>。
而 SGML 內文則是用大寫字母表示,像是: <!ENTITY…> 及 <!DOCTYPE…>, 而不是 <!entity…> 及 <!doctype…>。
縮寫字(acronym)通常在書中第一次提到時,必須同時列出完整拼法, 比如:"Network Time Protocol (NTP)"。 定義縮寫字之後,應該儘量只使用該縮寫字(而非完整詞彙, 除非使用完整詞彙可以更能表達語意)來表達即可。 通常每本書只會第一次提到時,才會列出完整詞彙, 但若您高興也可以在每章第一次提到時又列出完整詞彙。
此外,同一縮寫字在前三次使用時,須使用 <acronym> 標籤, 並把完整詞彙附在 role 屬性內做說明。 如此一來就會建立詞彙表,並且當滑鼠移至該縮寫字上方時, 就會顯示完整詞彙。
無論 檔案縮排設定為何, 每個檔案一開始的縮排(indentation)都是從 0 縱列開始
未完的標籤會以多兩個空白來增加縮排, 結尾的標籤則少兩個空白來縮減縮排。 若已達 8 個空白,則以 tab 取代之。 此外,在 tab 前面不要再用空白,也不要在每行後面加上空白。 每個 tag 的內文若超過一行的話,則接下來的就多兩個空白以做縮排。
舉個例子,這節所用的寫法大致是下面這樣:
+--- 這是 0 縱列 V <chapter> <title>...</title> <sect1> <title>...</title> <sect2> <title>縮排</title> <para><emphasis>無論</emphasis> 檔案縮排設定為何, 每個檔案一開始的縮排(indentation)都是從 0 縱列開始。</para> ... </sect2> </sect1> </chapter>
若用 Emacs 或 XEmacs 來編輯這檔,那麼會自動進入 sgml-mode 模式, 然後就會強制使用每個檔案最下方的環境設定。
Vim 愛用者也可以用下列設定來調整:
augroup sgmledit autocmd FileType sgml set formatoptions=cq2l " 特殊格式選項 autocmd FileType sgml set textwidth=70 " 在 70 縱列處即自動換行 autocmd FileType sgml set shiftwidth=2 " 自動縮排 2 個空白 autocmd FileType sgml set softtabstop=2 " 按 Tab 會自動轉為兩個空白縮排 autocmd FileType sgml set tabstop=8 " 把 8 個空白轉為 tab autocmd FileType sgml set autoindent " 自動縮排 augroup END
同一縮排等級的標籤要以空一行來做區隔,而不同縮排等級的則不必。 比如:
像是 <itemizedlist> 這類的標籤事實上本身不含任何文字資料,必須得由其他標籤來補充內文。 這類的標籤會獨用一整行。
另外,像是 <para> 及 <term> 這類的標籤並不需搭配其他標籤, 就可附上文字資料,並且在標籤後面的同一行 內即可立即寫上這些內文。
當然,這兩類的標籤結尾時也是跟上面道理相同。
不過,當上述這兩種標籤混用時,會有很明顯的困擾。
當第一類標籤的後面接上第二類標籤的話, 那麼要把這兩類標籤各自分行來寫。 後者標籤的段落, 也是需要做適當縮排調整。
而第二類標籤結尾時,可以與第一類標籤的結尾放在同一行。
在 commit 修改時,請別在修改內容的同時, 也一起更改編排格式。
如此一來,像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容, 而不用費心思去判斷該行的改變,是由於格式重排或者內容異動。
舉例說明,若要在某段加上兩個句子,如此一來該段落的某行勢必會超出 80 縱列,這時請先 commmit 修改。 接著,再修飾過長行落的換行,然後再次 commit 之。 而第二次的 commit 紀錄,請明確說明這只是 whitespace-only (修改空白而已) 的更改,如此一來,翻譯團隊就可以忽略第二次 commit 了 。
請避免一些情況下的斷行:造成版面醜醜的、或是須連貫表達的同一句子。 斷行的情況會隨所閱讀的工具不同而有所不同。 尤其是透過純文字瀏覽器來看 HTML 時會更明顯看到類似下面這樣不好的編排段落:
Data capacity ranges from 40 MB to 15 GB. Hardware compression …
請使用 以避免同句子之間的斷行, 以下示範如何使用 nonbreaking spaces:
在數字與單位之間:
57600 bps
在程式名稱與版號之間:
FreeBSD 4.7
multiword 之間 (使用時請小心,像是 “The FreeBSD Brazilian Portuguese Documentation Project” 這類由三到四個字所組成的, 則不用加。):
Sun Microsystems
本文及其他文件,可由此下載:ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/。
若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢
<questions@FreeBSD.org>。
關於本文件的問題,請洽詢 <doc@FreeBSD.org>。