HOWTO HOWTO
作者: Mark F. Komarinski [1]markk@cgipc.com
譯者: 蘇江文 [2]softsprite@yeah.net
v0.13, 19 September 1999 翻譯日期: 09 Feb 1998
_________________________________________________________________
成為一個新的 LDP 作者，掌握 LDP 使用的工具、思路和約定。
_________________________________________________________________
1. 概述
* 1.1 歷史
* 1.2 新版本
* 1.3 版權和商標
* 1.4 感謝
2. LDP 和 SGML 背景資料
* 2.1 LDP
* 2.2 SGML
* 2.3 工具
3. 讓我們開始
* 3.1 寫給新作者
* 3.2 郵件列表
* 3.3 下載並安裝工具
* 3.4 手工書寫 SGML
* 3.5 使用其它工具書寫 SGML
* 3.6 CVS 基礎
* 3.7 發布你的文檔
4. 風格指南
5. 關於 LDP 的常見問題
* 5.1 我想為 LDP 出一份力，我該如何去作？
* 5.2 我想出版 LDP 文檔。LDP 的文檔許可是怎樣規定的？
* 5.3 我在一個 LDP 文檔中找到一個錯誤。我能修正它嗎？
_________________________________________________________________
1. 概述
1.1 歷史
本文是1999年8月26日 Mark F. Komarinski [3]markk@cgipc.com 在花費了兩天
找尋工具的代價後開始寫作的。如果任何一個 LDP 作者能從中得到幫助，我就達
到我的願望了。
1.2 新版本
本文的最新版本可以在我的主頁 [4]http://www.cgipc.com/~markk 找到 SGML
源文件。 其它不同格式的版本可以在 LDP 主頁 [5]http://www.linuxdoc.org/
找到。
版本歷史
v0.25, 20 September 1999
* 修復了一些斷開的鏈接
* 為新作者增加章節
* 從最初發行版本增加一些雜項修改
* 增加版權說明取代以前的 URL 鏈接
v0.12, 2 September 1999
* 完成大多數章節
* 討論列表的綜合修改
v0.10, 27 August 1999
* Got up to section 3.4 written
* Added to the outline some
* Changed location of LDP mailing list to lists.debian.org from
thepuffingroup.com.
v0.01, 27 August 27 1999
* 初步完成，上傳主頁，簡單大綱寫作
* Take some of what I wrote with a grain of salt. Some things need
to be verified.
1.3 版權和商標
(c) 1999 Mark F. Komarinski
本指南可以被全部或部分復制，不需要付費，必須接受以下限制：
* The copyright notice above and this permission notice must be
preserved complete on all complete or partial copies
* Any translation or derived work must be approved by the author in
writing before distribution.
* If you distribute this work in part, instructions for obtaining
the complete version of this manual must be included, and a means
for obtaining a complete version provided.
* Small portions may be reproduced as illustrations for reviews or
quotes in other works without this permission notice if proper
citation is given.
Exceptions to these rules may be granted for academic purposes: Write
to the author and ask. These restrictions are here to protect us as
authors, not to restrict you as learners and educators. All source
code in this document is placed under the GNU General Public License,
available via anonymous FTP from [6]the GNU archive site.
1.4 感謝
感謝所有在我寫作過程中給予我幫助的人，包括 Deb Richardson 和 Daniel
Barlow 以及 LDP 討論列表上的其它人。
部分章節我取自 HOWTO Index 和 sgmltools 文檔。在本文的其它部分有指明到
何處取得 sgmltools 和 LDP。
2. LDP 和 SGML 背景資料
2.1 LDP
Linux 文檔計劃 (LDP) 是用來提供給新用戶以快速取得某個詳細主題相關信息。
它並不僅僅包含一系列關於管理、網絡、編程等的書籍，而是包容了大量的由使
用過的人書寫的關於某個個別主題的解決方法。如果你想查找關於打印的資料，
你可以查閱 Printing HOWTO。如果你想查找關於網絡的資料，你可以查閱
Ethernet HOWTO，等等。
剛開始，許多這些文檔是文本或 HTML 格式。隨著時間的推移，必須找出一個管
理這些文檔的好方法。一種能讓你從 Web 網頁上閱讀、從光盤的文本文件閱讀，
甚至從你的個人數字助理上閱讀的方法。答案已經有了，就是 SGML。
2.2 SGML
Standard Generalized Markup Language (SGML) 是一種基於記號文本的語言。
在這方面，它類似於 Tex 或者 groff 或者 HTML。 SGML 的強大之在於它不象
WYSIWYG (所見即所得)那樣，你不需要定義象顏色、字體等格式，你只需定義元
素(段落、章節、編號列表)而 讓最終處理程序來處理象位置、顏色、字體等煩心
的事情。HTML 也是這麼做的，實際上它是 SGML 的一個子集。
SGML 包含兩部分。首先是一個稱為 DTD (或稱為文檔類型定義 Document Type
Definition) 的結構。 DTD 定義每一個元素之間的關系。The LinuxDoc DTD,
used to create this document, is an example of this. DTD 為每一個使用
DTD 創建的文檔一個通用的視覺和感覺效果。其次是內容(content)，就是將要由
SGML 處理器處理並被用戶閱讀的部分。本段落就是內容，但也可以包含圖像、表
格、編號列表等等。內容被標記(tag)包圍用來分開不同的元素。
隨著時間的推移，LinuxDoc DTD 將被 DocBook DTD 所取代，為其它的 SGML 文
檔提供一個統一的視覺和感覺效果。 如果實現了這一步，我們將通過本 HOWTO
或者郵件列表為你升級。 LinuxDoc 和 DocBook 之間最大的不同在於 DocBook
分配標記給不同類型的內容(就象命令、文件名、地址目錄等等)，而 LinuxDoc
分配標記基於文本將要顯示的方式(比如你可以分配強調或打字)
為什麼用 SGML 取代 HTML 或其它格式？
SGML 提供的不僅僅是格式。你可以自動建立索引、內容表以及文檔中的鏈接或者
是大綱。sgmltools 包也可以讓你輸出 LaTeX 、 info 、 text 、 HTML 和
RTF。從這些基本格式，你可以創建其它格式文檔(DOC、PostScript等等)。SGML
不會象 HTML 那樣冗長。我不認為你很快會在 SGML 中看到閃亮的標記。這有助
於編碼不僅僅易於處理，而且易於書寫。象 LyX (我至今使用的所見即所得編輯
器)這樣的軟件可以幫助你書寫 TeX格式文檔並輸出成 SGML 格式，然後你就可以
從 SGML 生成任何你需要的格式。
最後，SGML 更注重元素的工作性能而不是元素的顯示。這是一個顯著的特性，有
助你更快地書寫，因為你不必關心段落的位置、字體大小等等。
2.3 工具
在本章節，我將介紹一些用來創建你自已的 LDP 文檔的工具。我將先簡單介紹，
然後詳細說明，包括如何安裝它們。如果你使用其它的一些工具來書寫 LDP，請
告訴我，我會在這裡為它們做廣告的。
sgmltools
必備
sgmltools 包包含用來處理 SGML 成以上所說格式的 SGML 工具。它也包含創建
LDP 文檔所需的 LinuxDoc DTD。如果只創建 SGML 文檔，這些已經足夠了。如果
你想處理成比如 TeX 格式，你還需要一些工具包。sgmltools 包在你的 linux
發行版本中可以找到，或者到 [7]http://www.sgmltools.org/ 下載。
TeX
可選
TeX (rhymes with blech!) 是一種可供廣泛選擇的標記語言，甚至包括那些數學
世界中的人們。 我還記得許多微積分考試是由 TeX 寫成的。它也是至今仍在使
用的最早的標記語言之一。 TeX 實際上和 SGML 具備許多同樣的概念。TeX 處理
它的文件成 DVI (設備無關)從而可能處理成其它格式。 不幸的是，DVI不能容易
地轉換成打印語言(PostScript、PCL)以外的其它格式，很難生成 HTML。 TeX 在
多數 Linux 發行版本中都已安裝或被提供。
LyX
可選
LyX 程序是一個圖形化所見即所得軟件，提供非常必需的易用圖形應用與 SGML
處理器之間的聯系。LyX是用於書寫 TeX 文檔，實現了許多 TeX 規則。舉個例子
，當章節被自動編號，你無法輕易地插入空格。這被 TeX 設計成禁止。而 SGML
通常忽略同樣的空格。LyX能夠讀入 LinuxDoc DTD 並且提供文檔模板以幫助你用
習慣的方式創建你的 LDP 文檔，而不需要象 vi 那樣要記住許多標記。 LyX 可
以在 [8]http://www.lyx.org/ 找到。
在 KDE 中有一個使用 Qt 庫的 LyX。 你可以從以下地址得到更多信息：
[9]http://www.devel.lyx.org/~ettrich/klyx.html。 如果你使用 KLyX 來寫
SGML ，請通過 [10]郵件 告訴我你的使用經驗。
3. 讓我們開始
本章節顯示如何獲取關於如何書寫你自己的 LDP 文檔的信息。獲取並安裝工具，
與 LDP 聯系，從那裡向所有 Linux 用戶發布你所掌握的知識。
3.1 寫給新作者
如果你剛剛了解 LDP 並且想要選擇一個沒人維護的 HOWTO 或者想寫一個新的
HOWTO 或者 mini-HOWTO 文檔，請聯系 [11]linux-howto@metalab.unc.edu 。
這將讓 HOWTO 協調人掌握誰在維護哪篇文檔。同時要注意所有的 HOWTO 都使用
SGML 格式(當前使用 LinuxDoc DTD)。mini-HOWTO 使用 SGML 或者 HTML 格式，
但只有 SGML 格式將被包含進 HOWTO 的打印版本中。
3.2 郵件列表
有一些郵件列表可以訂閱以讓你了解 LDP 目前工作情況。首先是
[12]ldp-discuss@lists.linuxdoc.org，這是 LDP 的主要討論組。如果要訂閱，
發送主題為 "subscribe" 的郵件到
[13]ldp-discuss-request@lists.linuxdoc.org。退訂則發送主題為
"unsubscribe" 的郵件到 [14]ldp-discuss-request@lists.linuxdoc.org。
3.3 下載並安裝工具
sgmltools
從 [15]http://www.sgmltools.org/下載 sgmltools 包，或者直接從你的
Linux 發行版本中取得。從 sgmltools.org 取得的軟件是源碼格式，因此你必須
在你的機器上編譯這些源碼。從你的 Linux 發行版本中取得的預建立好的包更容
易些，你可以不用編譯而直接開始編輯工作。(特別是如果你不是一個程序員)
RedHat 中包含 sgmltools。 如果沒有，你可以從 ftp.redhat.com 或者其它鏡
像站點下載。
如果你使用 Debian，在標準發行版本中也包含 sgmltools 。如果你沒有已安裝
的包，你可以使用 apt-get 命令下載並安裝：
_________________________________________________________________
# apt-get install sgml-tools
_________________________________________________________________
要了解更多關於 Debian 包的信息，你可以查閱
[16]http://www.debian.org/Packages/stable/text/sgml-tools.html
如果從源碼編譯，所有你需要做的是：
# tar -zxvf sgmltools-x.x.x.tar.gz
# cd sgmltools-x.x.x
# ./configure
# make
# make install
替換 sgmltools-x.x.x 成你當前 sgmltools 的版本號。支持 LinuxDoc 的當前
版本號是 1.0.9。支持 DocBook 的當前版本號是 2.0.2。兩者在以上所述站點中
都可以找到。
一旦工具安裝好後，你就可以使用很多命令了。
sgmlcheck file.sgml- 檢查給定文檔的句法。
sgml2html file.sgml- 轉換 SGML 文件成 HTML。 創建一個名為 file.html 的
文件包含內容表，然後創建一系列名為 file-x.html 的文件，這裡 x 是章節號
。
sgml2rtf file.sgml- 轉換 SGML 文件成 Rich Text Format (RTF)。創建兩個文
件，第一個是 file.rtf 包含 TOC，以及 file-0.rtf 包含所有的章節。
sgml2txt file.sgml- 轉換 SGML 文件成 ASCII 文本。所有內容放在 file.txt
中。
sgml2info file.sgml- Blah SGML blah INFO, 能被 info 命令使用。所有的輸
出傳送到 file.info。
sgml2latex file.sgml- Blah SGML blah TeX.
sgml2lyx file.sgml- SGML yadda LyX graphical editor. This is great if
you have pre-generated SGML files and want to convert them for use in
LyX.
3.4 手工書寫 SGML
非常象 HTML，你可以手工書寫 SGML , 只要你掌握了所有需要使用的標記代碼本
章節將講述盡可能多的這些代碼，並為每一個提供例子。開始的最好的地方就是
本文的源碼，可以從這裡看看： [17]Introduction. 因為 SGML 的處理方式依賴
於文件格式的不同而不同，我將盡可能說明在文件寫作中應該知道的事情。
出發
現在開始寫作了，首先用你喜愛的編輯器創建一個新文件，文件的開頭如下：
這將定義 SGML 處理輸出文件時使用的文檔類型(我們這個例子使用 LinuxDoc)。
這個標記本身不產生任何輸出。
接下來你需要把你其余的內容包含在標記 和 之中。這意
味著內容的開始。如果你熟悉 HTML 的話，這類似於將所有內容包含在標記
和 之間。
頭部信息Header information
內容的第一部分應該包含內容其余部分的概括信息。這類似於一本書的頭幾頁，
那裡有標題頁(書本的標題、作者、出版日期、內容目錄等等)。
內容的標題包含在標記 和 之間。作者包含在標記
和 之間。日期則使用標記 和 。
有兩個保留的章節是： 和 標記描述內容摘要；
標記指出內容目錄的位置。內容目錄(TOC)是由 SGML 自動生成的。我們後面將引
入章節。
現在我們所做的一切看起來是什麼樣子呢？把剛才說過的 SGML 代碼組合起來，
就象：
HOWTO HOWTO
Mark F. Komarinski
Aug 27, 1999
Getting a new LDP author up and running with tools, ideas,
and conventions used by the LDP
當你使用 RTF 或 HTML 格式看這段創建主頁面的內容時，所有的信息都在一頁中
。
章節(Sections)
為了建立內容目錄，你必須做一些標記。 在 SGML 中的章節(Sections)類似於傳
統出版中的章的概念。你可以有多個章節，每個章節可以有子章節，子章節下還
可以有子章節。
在你的文檔中使用章節，有助於你建立主題大綱。你可以將主題分隔成多個小章
節。我在寫本文時就是這樣做的。
章節是 SGML 中少數幾個不需要成對出現的標記。也就是說，沒有 標記
。 你不用關於章節的編號，SGML 在輸出成其它格式時會自動處理的。
章節是使用 標記作為開始的。每一個新章節開始於一個 標記。
第一個章節被編號為 1。
創建子章節 (比如 1.1) 可以使用 標記。它也從 1 開始編號。
子章節 (1.1.1) 使用 標記，並且它也從 1 開始編號。
當 SGML 處理器處理到 標記時，它開始掃描文檔的其余部分，利用其中的
章節標記編號創建文檔目錄。章節被編號排列在內容目錄(TOC)中，然後被文檔的
其余部分使用。子章節 (1.1.1) 並不出現在 TOC 中，但如果可能的話會被置成
強調文本格式。
標準段落
寫內容段落就象 HTML一樣。使用一個
標記指明一個新行的開始。SGML 會忽
略 TAB、空格、空行。當 SGML 檢查到
標記時，它開始一個新行。放置
標記結束該段落。
增強文本
你偶而會需要讓一些文本明顯不同於其它文本。可能是重要代碼或者命令列表。
強調文本可以使用 和 標記。斜體字可以使用 和 標記
。
列表
在 SGML 中有兩種形式的列表。第一種是列舉列表，從1開始為每一個列表項編號
。
1. This is the first entry in the enumerated list.
2. This is the second.
3. Third.
以上的代碼如下：
This is the first entry in the enumerated list.
This is the second.
Third.
標記指出緊隨其後的列表項要開始編號。
另一種形式是逐項列表，每一個列表項前面只放一個星或圓圈或點或其它東西。
* This is the first entry in the itemized list
* This is the second
* Third
以上的代碼如下：
This is the first entry in the itemized list
This is the second.
Third.
就象你所看到的， 標記在兩種形式列表中都一樣。
第三種形式是描述列表，包括被描述的術語以及描述該術語的短語。
LDP
The Linux Documentation Project
SGML
Standard Generalized Markup Language
以上的代碼如下：
LDPThe Linux Documentation Project
SGMLStandard
Generalized Markup Language
這種形式不同於前面兩種，整個列表包含在標記 和 中，
每一行中的每一項，也就是定義的短語，被包含在 和 中。行的剩
余部分是對短語的定義。
逐字文本
有時你需要完全顯示你所寫的內容，你可以使用 和 標記來包含
段落。在 標記之前的空格、回車以及其它文本(包括特別字符)都將被保
留。
以下就是逐字文本
統一資源定位(URL)
SGML 也允許統一資源定位(URL)。注意這在輸出成 HTML 格式時才有用，其它格
式可能也有一些用，比如說 RTF 格式。
一個 URL 沒有結束標記，所有信息都放在 標記裡面。這是一個指向 LDP
主頁的 URL： [18]http://www.linuxdoc.org/ 。以下是代碼：
url="http://www.linuxdoc.org/" 告訴瀏覽器目標地址，而
name="http://www.linuxdoc.org/" 則告訴瀏覽器如何顯示。在本例中兩者是一
樣的，但我可以創建一個如下的 URL 標記：
在頁面上的顯示就象這樣： [19]LDP.
參考(References)
URL 適合於鏈接到 LDP 文檔之外的內容，但不適合於鏈接到文檔內容自身。為實
現這一功能，可以使用