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 文档之外的内容，但不适合於链接到文档内容自身。为实
现这一功能，可以使用