Next Previous Contents

3. 使用 SGML-Tools 撰寫文件

使用 SGML-Tools DTD 撰寫文件的過程大部分是非常容易的，而且有點類似 LaTeX． 然而，仍然有些限制要注意．這一節我將介紹 SGML 文件的撰寫． SGML 文件範例(及寫作指引)請參閱 example.sgml 檔案，你可以拿來當作自己文件的範本． 在此我將討論 SGML 的各項功能，但是以原始文件作為範例不是很有可讀性． 因此，印出 example.sgml 的原始碼(編排後的輸出)，如此你就有真實的參考範例。

3.1 基本概念

仔細看範例文件的原始文件，你會注意到裡面有許多以角括號(< 及 >)標示的「標籤(tags)」． 標籤單純地指出某組成元素的起始，這裡所謂的組成元素是一節，一段，一句斜體的文句，列表中的一個項目，以及諸如此類的結構． 使用標籤就像使用 LaTeX 指令如 \item 或是 \section{...} 等一般．

舉個簡單的例子，要產生這一段 粗體文字，我在原始碼中鍵入 

舉個簡單的例子，要產生這一段 <bf>粗體文字</bf>, ...
<bf> 是這段粗體文字的開頭，而 </bf> 是結尾． 你也可以使用這個簡略形式： 
舉個簡單的例子，要產生這一段 <bf/粗體文字/, ...
就是用斜線將粗體文字包住．(當然，如果被包含的文字含有線，你就必須使用長的形式， 例如 Unix 的檔案名稱．)

關於特殊字元還有其它得要注意的問題 (這就是為什麼如果你仔細觀察原始文件就會注意到這些看起來很怪異 "&" 表示式；我將簡短地說明這些符號)．

在某些情況下，特定的組成元素之結尾標籤是可選用的． 例如，你在某一節的開始使用 <sect> 這個標籤，然而，該節的結尾標籤 (可以出現在該節主體本身結束的地方，而不只是該節的名稱後面!) 是可選用的而當你在同一個層次開始另外一節的時候也就暗示著該節的結束． 一般來說你不需要擔心這些細節；只要跟著使用在 example.sgml 指引裡的範例就可以了。

3.2 特殊字元

很明顯的，角括號它們本身就是 SGML 原始文件裡的特殊字元．另外還有其它該注意的字元． 例如，假設你想鍵入由角括號所涵蓋的表示式，像這樣: <foo>． 為了表示左邊的角括號，你必須使用 &lt; 這個組成元素， 這是一個會展開成左括號字元的「巨集」．因此，我在原始文件中鍵入 

angle brackets around it, as so: <tt>&lt;foo></tt>.
一般來說，以結合字元(&)作為開始表示這是一個特殊的巨集． 例如，產生 % 符號的 &percnt; 產生 | 的 &verbar; 等等． 對於所有的「特殊字元」都有結合巨集可以表示它們．

通常，你不需要使用結合巨集表示某特殊字元，然而，在某些情況下這是必須的。最常用的是：

完整的特殊字元列表可以查看其中一個替換檔． 通常 LaTeX 最會抱怨特殊字元，所以查閱 $SGMLTOOLSLIB/rep/latex/general 會是個好的開始． $SGMLTOOLSLIB 定義在 SGML 轉換程序的最前面．

3.3 Verbatim 與 Code 環境

當我們正討論特殊字元這個主題時，我也必須提到「verbatim 環境」， 用來在輸出中含入不加變動的文字(空白字元以及縮排，和諸如此類)． verb 這個組成元素就是做此用途的．它看起來就像這樣： 

<verb>
 Some literal text to include as example output.
</verb>
verb 環境不允許你在其內容中使用任何東西． 特別地，在 verb 環境中你必須： code 環境非常類似 verb 環境，除了在文字周圍加入分隔線 
這是 code 環境的例子．

你應該在任何 verb 環境的周圍使用 tscreen 環境，像這樣： 

<tscreen><verb>
這是一段例句．
</verb></tscreen>
tscreen 是一個環境單純地縮排並設定預設字型為 tt． 這使得範例要論在 LaTeX 以及純文字的版本中看起來好多了． 你可以使用 tscreen 而不加 verb，不過，如果你在範例中使用任何的特殊字元那麼你就需要它們兩個． tscreen 與特殊字元無關．範例請參閱 example.sgml．

quote 環境類似 tscreen，除了不將預設字型設為 tt．所以，你可以使用 quote 於與電腦無關的引用，如： 

<quote>
Here is some text to be indented, as in a quote.
</quote>
這會產生：
Here is some text to be indented, as in a quote.

3.4 文件內容概觀

在我們深入研究細節之前，我要開始介紹 linuxdoc DTD 定義的文件概觀．文件如何設立的範例請仔細觀看 example.sgml．

序文

在文件的「序文」中你設立像是標題以及文件型態(style)的東西．Linux HOWTO 文件看起來應該像： 

<!doctype linuxdoc system>

<article>

<title>Linux Foo HOWTO
<author>阿偉, <tt/cwhuang@phys.ntu.edu.tw/
<date>v1.0, 14 August 1997
<abstract>
這份文件說明了如何使用 <tt/foo/ 這個工具．
</abstract>

<toc>

這些組成項目可以酌予增減但須按此順序．第一行告訴 SGML 解析程式使用 linuxdoc DTD． <article> 這個標籤規定文件使用「article」此種文件型態． (原先的 QWERTZ DTD 還定義 「report」以及「book」等型態；我並沒有修改它們以在 SGML-Tools 中使用)．

title, author, 以及 date 這些標籤的意義應該是很明顯的， 在 date 標籤中包含文件的版本編號以及最後修改時間．

abstract 標籤設定文件頂端在內容之前印出的文字． 如果你不想含入內容列表(toc 標籤)，那麼你可能不需要 abstract．

章節與段落

在序文之後，你就可以準備進入文件本身．有下列的分節指令可以使用：

它們相當於 LaTeX 中對應的 section, subsection 等等．

在 sect (或 sect, sect 等等) 標籤之後跟著是該節的名稱． 例如，在文件的頂端，序文之後的是此標籤： 

<sect>簡介
而在此節開始的地方(段落)，有個標籤是： 
<sect2>段落
在一節的標籤之後，你開始文件的主體．然而，你必須以一個 <p> 標籤開始，像這樣： 
<sect>簡介
<p>
這是一份 SGML-Tools 文件處理的使用者指引....
這是告訴解析程式你已完成一節的標題並且準備好開始本文主體． 其後，新的段落是以空白行開始(就如同 TeX)．例如， 
這是第一段的結尾．

而我們從這裡開始新的一段．
沒有什麼理由要在每個段落的前面使用 <p> 標籤；只要在分節指令後面的第一個段落開始處加就行．

文件結尾

在文件結束的地方，你必須使用這個標籤： 

</article>

以告訴解析程式你已經完成 article 這個組成元素(涵蓋整份文件)．

3.5 交互參考

現在我們要進入系統的其它功能．交互參考很容易．例如，如果你想要製作某一節的交互參考，你得像這樣標示該節: 

<sect1>簡介<label id="sec-intro">
接著你就可以在文件中的某個地方式用這個表示式參照該節： 
請參考<ref id="sec-intro" name="簡介">一節的介紹．
這將會以 sec-intro 標記的節號替換掉這個 ref 標籤． 對於 groff 以及 HTML 轉換 name 這個參數是必須的． SGML-Tools 使用的 groff 巨集設定目前並未支援交互參考，而且它常常以名稱取代數字參照某一節．

例如，本節是 交互參考．

在全球資訊網上使用的通用資源定位器，即 URL 也有組成元素 url． 這個元素應該用來參照其它文件，FTP 上的檔案等等．例如： 

你可從此取得 Linux HOWTO 文件
<url url="http://sunsite.unc.edu/mdw/HOWTO/" 
   name="The Linux HOWTO INDEX">．
url 這個參數指定這個 URL 本身．連結會自動加入到 HTML 文件中． 可選用的 name 參數指定應該加上連結的文字(HTML 轉換)或是為 URL 描述命名(LaTeX 或 groff)．如果沒有給 name 參數，會使用這個 URL 本身．

例如，你可以從這裡取得 SGML-Tools 套件
ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-0.99.0.tar.gz.

一個有用的變形是 htmlurl，除了 HTML 文件在其它每種文件中這個 URL 部份將不會出現． 它用在像是個人的電子郵件位址；你可以寫 

<htmlurl url="mailto:esr@snark.thyrsus.com"
      name="esr@snark.thyrsus.com">
而在純文字輸出中獲得「esr@snark.thyrsus.com」 而不是重複的「esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>」 但是在 HTML 文件中仍然保有適當的 URL 部份．

3.6 字型

基本上，SGML-Tools 支援與 LaTeX 相同的字型． 注意，無論如何，純文字的轉換(經由 groff)不理會有關字型的資訊． 所以，你可以盡可能的使用多種字型，這對 LaTeX 的轉換會有好處． 但是在純文字的版本中不要指望能用字型點出重點．

特別是，前面描述過的 tt 這個標籤可以用來獲致寬度固定的「打字機」字型， 這應該用在所有的電子郵遞位址，機器名稱，檔案名稱等等． 例如： 

Here is some <tt>typewriter text</tt> to be included in the document.
相當於： 
Here is some <tt/typewriter text/ to be included in the document.
記得如果被包含的文字不含有斜線你可以使用簡略形式．

其它的字型有 粗體字 用的 bf 以及 斜體字 用的 em． 另外還支援數種字型，但是我不建議你使用它們，因為它們會被轉換成像 HTML 不支援的字型． 粗體，打字機體，以及斜體應該能滿足你的需要．

3.7 列表

此系統支援數種不同的列表．它們是：

在 itemize 或是 enum 裡的項目必須以 item 標籤加以標示． 在 descrip 裡的項目必須以 tag 標示． 例如， 
<itemize>
<item>這是一個項目．
<item>這是第二個項目．
</itemize>
看起來像是這樣： 在 enum 中 
<enum>
<item>這是第一個項目．
<item>這是第二個項目．
</enum>
你應看得出來，列表可以是巢狀的．細節請參閱範例文件．

descrip 列表稍有不同，而且有點難看，但是在某些情況下你可能會想使用它： 

<descrip>
<tag/Gnats./ Annoying little bugs that fly into your cooling fan.
<tag/Gnus./ Annoying little bugs that run on your CPU.
</descrip>
最後看起來像：
Gnats.

Annoying little bugs that fly into your cooling fan.

Gnus.

Annoying little bugs that run on your CPU.

3.8 更進一步的資訊

  1. QWERTZ 使用者指引可以從這裡取得 ftp://ftp.cs.cornell.edu/pub/mdw/SGML. QWERTZ (以及 SGML-Tools) 還支援像是數學公式，表格，圖形等許多特性． 如果你想用 SGML 寫一般的文件，我建議你用原來的 QWERTZ DTD 而不要用修改過的 linuxdoc DTD， 因為這是我特別用來寫 Linux HOWTOs 及其它類似文件用的．
  2. Tom Gordon 的 QWERTZ tools 可在此找到： ftp://ftp.gmd.de/GMD/sgml.
  3. 更多關於 SGML 的資訊可以在下面這些網頁找到：
  4. James Clark 的 sgmls 解析器，及後來的 nsgmls 還有其它工具可在這找到： ftp://ftp.jclark.com 以及 James Clark's WWW Page.
  5. emacs psgml 可在此找到： ftp://ftp.lysator.liu.se/pub/sgml．這個工具提供許多 SGML 的功能．
  6. 你可以寄電子郵件到 majordomo@via.ecp.fr 以參與 SGML-Tools mailing list，內容寫 subscribe sgml-tools． Mailing list 的地址是 sgml-tools@via.ecp.fr．
  7. 關於 LyX 的更多資訊可以在此找到： LyX WWW Page. LyX 是一個給 LaTeX 用的高階文字處理器前端． 具半所見即所得界面，會自動產生許多 LaTeX 的樣式及格局． 可以增快 LaTeX 的學習而且使複雜的格局變簡單且直接．
Next Previous Contents