由於文件是由眾多作者所維護,為了保持寫作風格的一貫性, 請遵守下列撰寫風格慣例。
Tag 的部份都是用小寫字母,譬如是用 para
,而非PARA
。
而 SGML 內文則是用大寫字母表示,像是: <!ENTITY…>
及 <!DOCTYPE…>
, 而不是 <!entity…>
及 <!doctype…>
。
縮寫字(acronym)通常在書中第一次提到時,必須同時列出完整拼法, 比如:“Network Time Protocol (NTP)”。 定義縮寫字之後,應該儘量只使用該縮寫字(而非完整詞彙, 除非使用完整詞彙可以更能表達語意)來表達即可。 通常每本書只會第一次提到時,才會列出完整詞彙, 但若您高興也可以在每章第一次提到時又列出完整詞彙。
所有縮寫要包在acronym
標籤內。
無論檔案縮排設定為何, 每個檔案的第一行都不縮排。
未完的標籤會以多兩個空白來增加縮排, 結尾的標籤則少兩個空白來縮減縮排。 若已達 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>
Tags containing long attributes follow the same rules. Following the indentation rules in this case helps editors and writers see which content is inside the tags:
<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, Editor Configuration.
同一縮排等級的標籤要以空一行來做區隔,而不同縮排等級的則不必。 比如:
<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>
在提交修改時,請別在修改內容的同時, 也一起更改編排格式。。
如此一來,像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容, 而不用費心思去判斷該行的改變,是由於格式重排或者內容異動。
舉例說明,若要在某段加上兩個句子,如此一來該段落的某行勢必會超出 80 縱列,這時請先 commmit 修改。 接著,再修飾過長行落的換行,然後再次 commit 之。 而第二次的 commit 紀錄,請明確說明這只是 whitespace-only (修改空白而已) 的更改,如此一來,翻譯團隊就可以忽略第二次 commit 了 。
請避免一些情況下的斷行:造成版面醜醜的、或是須連貫表達的同一句子。 斷行的情況會隨所閱讀的工具不同而有所不同。 尤其是透過純文字瀏覽器來看 HTML 時會更明顯看到類似下面這樣不好的編排段落:
Data capacity ranges from 40 MB to 15 GB。 Hardware compression …
請使用
以避免同句子之間的斷行, 以下示範如何使用 nonbreaking spaces:
在數字與單位之間:
57600 bps
在程式名稱與版號之間:
&os; 9.2
multiword 之間 (使用時請小心,像是 “The FreeBSD Brazilian Portuguese Documentation Project” 這類由三到四個字所組成的, 則不用加。):
Sun Microsystems
本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/。
若有 FreeBSD 方面疑問,請先閱讀
FreeBSD 相關文件,如不能解決的話,再洽詢
<questions@FreeBSD.org>。
關於本文件的問題,請洽詢
<doc@FreeBSD.org>。