章 10. 文件的撰寫風格

內容目錄
10.1. Style guide
10.2. 詞彙表

由於 FreeBSD 文件是由眾多作者所維護的,為了保持寫作風格的一貫性, 於是就產生較有共識的寫作規則,請各位記得要遵守。

使用美式英語

同一個字在不同種類的英語會有著不同的拼法。 遇到拼字不同的情況,請採用美式英語拼法。 像是: 請改用 color,而非 colour。 請改用 rationalize,而非 rationalise 等等類似字彙。

注意:

若文章採用英式英語也可以接受,但必須全篇文章都採用同一拼法才行 。 而文件的其他部份,像是書、網頁、 manual 說明等則必須採用美式英語。

不要用簡寫

請不要簡寫(contraction)。 請務必將完整的字寫出來。 比如: Don't use contractions 這句有用到簡寫,就要避免。

正式書面寫法避免簡寫的原因,乃是因為如此一來字句意思較精準, 且對譯者會比較輕鬆些。

正確使用 serial comma 以及頓號

英文段落通常會逗號(,)作為該句所提到的各項目的語氣區隔。 並且會在最後一個提到的項目時,先加上逗號再接上 and, 最後才是最後的項目。

舉個例子,看看下面這句:

This is a list of one, two and three items.

那麼這一句到底是有三個項目(onetwothree)呢?或者是只有兩個項目(onetwo and three)呢?

因此較妥的方式是以 serial comma 的方式,才能正確表達語意:

This is a list of one, two, and three items.

然而,在翻譯過程中,建議把逗號(,)部份改為頓號(、),並且 and 的部份可略而不翻,以免語意頓塞。

避免使用贅詞

請試著避免使用贅詞(redundant phrase)。 尤其是 這個指令這個檔案man 指令 這幾個通常都是不必要的贅詞。

以指令(command)方面舉例,比較妥當的用法是第二句的例子:

使用 cvsup 指令來更新原始碼。

使用 cvsup 來更新原始碼。

以檔案(filename)方面舉例,比較妥當的用法是第二句的例子:

… 在這個 /etc/rc.local 檔案 …

… 在 /etc/rc.local 檔 …

以 man(manual)方面舉例,比較妥當的用法是第二句(有用到 SGML citerefentry 標籤):

請打 man csh 指令以參閱詳情說明。

詳情請參閱 csh(1)

每句後面加上兩個空白

為了使文章更易閱讀,以及讓 Emacs 之類的工具容易運用,請在每一完整句子後面加上兩個空白。

不過,句號(.)後面有接大寫字母, 並不一定表示前一個句點所在處就是完整句子, 尤其是名字部份常常會有這現象。 像是 Jordan K. Hubbard 這人名就是很好的例證:句號後面接空白,然後是大寫的 H,然而這肯定並不是兩段句子。

撰寫風格的相關細節,可參閱 William Strunk 所寫的 Elements of Style

10.1. Style guide

由於 Handbook 是由眾多作者所維護,為了保持寫作風格的一貫性, 請遵守下列撰寫風格。

10.1.1. 大小寫

Tag 的部份都是用小寫字母,譬如是用 <para>而非 <PARA>

而 SGML 內文則是用大寫字母表示,像是: <!ENTITY…><!DOCTYPE…>而不是 <!entity…><!doctype…>

10.1.2. 縮寫字

縮寫字(acronym)通常在書中第一次提到時,必須同時列出完整拼法, 比如:"Network Time Protocol (NTP)"。 定義縮寫字之後,應該儘量只使用該縮寫字(而非完整詞彙, 除非使用完整詞彙可以更能表達語意)來表達即可。 通常每本書只會第一次提到時,才會列出完整詞彙, 但若您高興也可以在每章第一次提到時又列出完整詞彙。

此外,同一縮寫字在前三次使用時,須使用 <acronym> 標籤, 並把完整詞彙附在 role 屬性內做說明。 如此一來就會建立詞彙表,並且當滑鼠移至該縮寫字上方時, 就會顯示完整詞彙。

10.1.3. 縮排

無論 檔案縮排設定為何, 每個檔案一開始的縮排(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>

若用 EmacsXEmacs 來編輯這檔,那麼會自動進入 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

10.1.4. Tag 風格

10.1.4.1. Tag 空行

同一縮排等級的標籤要以空一行來做區隔,而不同縮排等級的則不必。 比如:

<article lang='zh_tw'> <articleinfo> <title>NIS</title> <pubdate>October 1999</pubdate> <abstract> <para>... ... ...</para> </abstract> </articleinfo> <sect1> <title>...</title> <para>...</para> </sect1> <sect1> <title>...</title> <para>...</para> </sect1> </article>

10.1.4.2. 標籤的分行

像是 itemizedlist 這類的標籤事實上本身不含任何文字資料,必須得由其他標籤來補充內文。 這類的標籤會獨用一整行。

另外,像是 paraterm 這類的標籤並不需搭配其他標籤, 就可附上文字資料,並且在標籤後面的同一行 內即可立即寫上這些內文。

當然,這兩類的標籤結尾時也是跟上面道理相同。

不過,當上述這兩種標籤混用時,會有很明顯的困擾。

當第一類標籤的後面接上第二類標籤的話, 那麼要把這兩類標籤各自分行來寫。 後者標籤的段落, 也是需要做適當縮排調整。

而第二類標籤結尾時,可以與第一類標籤的結尾放在同一行。

10.1.5. 空白的更改

在 commit 修改時,請別在修改內容的同時, 也一起更改編排格式

如此一來,像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容, 而不用費心思去判斷該行的改變,是由於格式重排或者內容異動。

舉例說明,若要在某段加上兩個句子,如此一來該段落的某行勢必會超出 80 縱列,這時請先 commmit 修改。 接著,再修飾過長行落的換行,然後再次 commit 之。 而第二次的 commit 紀錄,請明確說明這只是 whitespace-only (修改空白而已) 的更改,如此一來,翻譯團隊就可以忽略第二次 commit 了 。

10.1.6. Nonbreaking space

請避免一些情況下的斷行:造成版面醜醜的、或是須連貫表達的同一句子。 斷行的情況會隨所閱讀的工具不同而有所不同。 尤其是透過純文字瀏覽器來看 HTML 時會更明顯看到類似下面這樣不好的編排段落:

Data capacity ranges from 40 MB to 15
GB.  Hardware compression …

請使用 &nbsp; 以避免同句子之間的斷行, 以下示範如何使用 nonbreaking spaces:

  • 在數字與單位之間:

    57600&nbsp;bps
  • 在程式名稱與版號之間:

    FreeBSD&nbsp;4.7
  • multiword 之間 (使用時請小心,像是 The FreeBSD Brazilian Portuguese Documentation Project 這類由三到四個字所組成的, 則不用加。):

    Sun&nbsp;Microsystems

本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢 <questions@FreeBSD.org>。

關於本文件的問題,請洽詢 <doc@FreeBSD.org>。