13.3. 風格指南

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

13.3.1. 大小寫

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

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

13.3.2. 縮寫

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

所有縮寫要包在acronym標籤內。

13.3.3. 縮排

無論檔案縮排設定為何,每個檔案的第一行都不縮排。

未完的標籤會以多兩個空白來增加縮排,結尾的標籤則少兩個空白來縮減縮排。若已達 8 個空白,則以 tab 取代之。此外,在 tab 前面不要再用空白,也不要在每行後面加上空白。每個 tag 的內文若超過一行的話,則接下來的就多兩個空白以做縮排。

舉個例子,這節所用的寫法大致是下面這樣:

<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Indentation</title>

      <para>The first line in each file starts with no indentation,
	<emphasis>regardless</emphasis> of the indentation level of
	the file which might contain the current file.</para>

      ...
    </sect2>
  </sect1>
</chapter>

有長屬性的標籤也是遵循一樣的原則。遵守縮排規則可以幫助編輯和作者了解哪些內容在標籤內:

<para>See the <link
    linkend="gmirror-troubleshooting">Troubleshooting</link>
  section if there are problems booting.  Powering down and
  disconnecting the original <filename>ada0</filename> disk
  will allow it to be kept as an offline backup.</para>

<para>It is also possible to journal the boot disk of a &os;
  system.  Refer to the article <link
    xlink:href="&url.articles.gjournal-desktop;">Implementing UFS
    Journaling on a Desktop PC</link> for detailed
  instructions.</para>

When an element is too long to fit on the remainder of a line without wrapping, moving the start tag to the next line can make the source easier to read. In this example, the systemitem element has been moved to the next line to avoid wrapping and indenting:

<para>With file flags, even
  <systemitem class="username">root</systemitem> can be
  prevented from removing or altering files.</para>

Configurations to help various text editors conform to these guidelines can be found in 章 14, 編輯器設定.

13.3.4. 標籤風格

13.3.4.1. 標籤間距

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

<article lang='en'>
  <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>

13.3.4.2. 分隔標籤

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

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

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

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

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

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

13.3.5. 空白變更

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

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

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

13.3.6. 不斷行空白

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

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

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

  • 在數字與單位之間:

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

    &os;&nbsp;9.2
  • 多個單字的名稱之間 (在套用到如 The FreeBSD Brazilian Portuguese Documentation Project 這種由三到四個字所組成的名稱時請小心):

    Sun&nbsp;Microsystems

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

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

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