Chapter 10 文件的撰寫風格

Table of Contents
10.1 Style guide
10.2 詞彙表

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

使用美式英語

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

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

不要用簡寫

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

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

正確使用 serial comma 以及頓號

英文段落通常會逗號(,)作為該句所提到的各項目的語氣區隔。 並且會在最後一個提到的項目時,先加上逗號再接上 “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)方面舉例,比較妥當的用法是第二句的例子:

使用 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>
  <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> 這類的標籤事實上本身不含任何文字資料,必須得由其他標籤來補充內文。 這類的標籤會獨用一整行。

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

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

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

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

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

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>。