FreeBSD 文件計畫入門書
Prev |  | Next

# Chapter 10 文件的撰寫風格

由於 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>

若用 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

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

Prev | Home | Next
翻譯時的常見問題 |  | 詞彙表

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

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