HOWTO HOWTO

HOWTO HOWTO 作者: Mark F. Komarinski 译者: 苏江文 v0.13, 19 September 1999 翻译日期: 09 Feb 1998 成为一个新的 LDP 作者，掌握 LDP 使用的工具、思路和约定。概述历史

本文是1999年8月26日 Mark F. Komarinski 在花费了两天找寻工具的代价後开始写作的。如果任何一个 LDP 作者能从中得到帮助，我就达到我的愿望了。

新版本

本文的最新版本可以在我的主页找到 SGML 源文件。其它不同格式的版本可以在 LDP 主页找到。

版本历史

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.

版权和商标

本指南可以被全部或部分复制，不需要付费，必须接受以下限制：

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 .

感谢

感谢所有在我写作过程中给予我帮助的人，包括 Deb Richardson 和 Daniel Barlow 以及 LDP 讨论列表上的其它人。

部分章节我取自 HOWTO Index 和 sgmltools 文档。在本文的其它部分有指明到何处取得 sgmltools 和 LDP。

LDP 和 SGML 背景资料 LDP

Linux 文档计划 (LDP) 是用来提供给新用户以快速取得某个详细主题相关信息。它并不仅仅包含一系列关於管理、网络、编程等的书籍，而是包容了大量的由使用过的人书写的关於某个个别主题的解决方法。如果你想查找关於打印的资料，你可以查阅 Printing HOWTO。如果你想查找关於网络的资料，你可以查阅 Ethernet HOWTO，等等。

刚开始，许多这些文档是文本或 HTML 格式。随著时间的推移，必须找出一个管理这些文档的好方法。一种能让你从 Web 网页上阅读、从光盘的文本文件阅读，甚至从你的个人数字助理上阅读的方法。答案已经有了，就是 SGML。

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 更注重元素的工作性能而不是元素的显示。这是一个显著的特性，有助你更快地书写，因为你不必关心段落的位置、字体大小等等。

工具

在本章节，我将介绍一些用来创建你自已的 LDP 文档的工具。我将先简单介绍，然後详细说明，包括如何安装它们。如果你使用其它的一些工具来书写 LDP，请告诉我，我会在这里为它们做广告的。

sgmltools

必备

sgmltools 包包含用来处理 SGML 成以上所说格式的 SGML 工具。它也包含创建 LDP 文档所需的 LinuxDoc DTD。如果只创建 SGML 文档，这些已经足够了。如果你想处理成比如 TeX 格式，你还需要一些工具包。sgmltools 包在你的 linux 发行版本中可以找到，或者到下载。

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 可以在找到。

在 KDE 中有一个使用 Qt 库的 LyX。你可以从以下地址得到更多信息：。如果你使用 KLyX 来写 SGML ，请通过告诉我你的使用经验。

让我们开始

本章节显示如何获取关於如何书写你自己的 LDP 文档的信息。获取并安装工具，与 LDP 联系，从那里向所有 Linux 用户发布你所掌握的知识。

写给新作者

如果你刚刚了解 LDP 并且想要选择一个没人维护的 HOWTO 或者想写一个新的 HOWTO 或者 mini-HOWTO 文档，请联系。这将让 HOWTO 协调人掌握谁在维护哪篇文档。同时要注意所有的 HOWTO 都使用 SGML 格式(当前使用 LinuxDoc DTD)。mini-HOWTO 使用 SGML 或者 HTML 格式，但只有 SGML 格式将被包含进 HOWTO 的打印版本中。

邮件列表

有一些邮件列表可以订阅以让你了解 LDP 目前工作情况。首先是，这是 LDP 的主要讨论组。如果要订阅，发送主题为 "subscribe" 的邮件到。退订则发送主题为 "unsubscribe" 的邮件到。

下载并安装工具 sgmltools

从下载 sgmltools 包，或者直接从你的 Linux 发行版本中取得。从 sgmltools.org 取得的软件是源码格式，因此你必须在你的机器上编译这些源码。从你的 Linux 发行版本中取得的预建立好的包更容易些，你可以不用编译而直接开始编辑工作。(特别是如果你不是一个程序员)

RedHat 中包含 sgmltools。如果没有，你可以从 ftp.redhat.com 或者其它镜像站点下载。

如果你使用 Debian，在标准发行版本中也包含 sgmltools 。如果你没有已安装的包，你可以使用 apt-get 命令下载并安装：

# apt-get install sgml-tools

要了解更多关於 Debian 包的信息，你可以查阅

如果从源码编译，所有你需要做的是：

# 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.

手工书写 SGML

非常象 HTML，你可以手工书写 SGML , 只要你掌握了所有需要使用的标记代码本章节将讲述尽可能多的这些代码，并为每一个提供例子。开始的最好的地方就是本文的源码，可以从这里看看： . 因为 SGML 的处理方式依赖於文件格式的不同而不同，我将尽可能说明在文件写作中应该知道的事情。

出发

现在开始写作了，首先用你喜爱的编辑器创建一个新文件，文件的开头如下：

<!doctype linuxdoc system>

这将定义 SGML 处理输出文件时使用的文档类型(我们这个例子使用 LinuxDoc)。这个标记本身不产生任何输出。

接下来你需要把你其余的内容包含在标记 <article> 和 </article> 之中。这意味著内容的开始。如果你熟悉 HTML 的话，这类似於将所有内容包含在标记 <html> 和 </html> 之间。

头部信息Header information

内容的第一部分应该包含内容其余部分的概括信息。这类似於一本书的头几页，那里有标题页(书本的标题、作者、出版日期、内容目录等等)。

内容的标题包含在标记 <title> 和 </title> 之间。作者包含在标记 <author> 和 </author> 之间。日期则使用标记 <date> 和 </date> 。

有两个保留的章节是： <abstract> 和 </abstract> 标记描述内容摘要；<toc> 标记指出内容目录的位置。内容目录(TOC)是由 SGML 自动生成的。我们後面将引入章节。

现在我们所做的一切看起来是什麽样子呢？把刚才说过的 SGML 代码组合起来，就象：

<!doctype linuxdoc system>  <article> <title>HOWTO HOWTO </title> <author>Mark F. Komarinski </author> <date>Aug 27, 1999 </date> <abstract>Getting a new LDP author up and running with tools, ideas, and conventions used by the LDP </abstract> <toc>

当你使用 RTF 或 HTML 格式看这段创建主页面的内容时，所有的信息都在一页中。

章节(Sections)

为了建立内容目录，你必须做一些标记。在 SGML 中的章节(Sections)类似於传统出版中的章的概念。你可以有多个章节，每个章节可以有子章节，子章节下还可以有子章节。

在你的文档中使用章节，有助於你建立主题大纲。你可以将主题分隔成多个小章节。我在写本文时就是这样做的。

章节是 SGML 中少数几个不需要成对出现的标记。也就是说，没有 </sect> 标记。你不用关於章节的编号，SGML 在输出成其它格式时会自动处理的。

章节是使用 <sect> 标记作为开始的。每一个新章节开始於一个 <sect> 标记。第一个章节被编号为 1。

创建子章节 (比如 1.1) 可以使用 <sect1> 标记。它也从 1 开始编号。

子章节 (1.1.1) 使用 <sect2> 标记，并且它也从 1 开始编号。

当 SGML 处理器处理到 <toc> 标记时，它开始扫描文档的其余部分，利用其中的章节标记编号创建文档目录。章节被编号排列在内容目录(TOC)中，然後被文档的其余部分使用。子章节 (1.1.1) 并不出现在 TOC 中，但如果可能的话会被置成强调文本格式。

标准段落

写内容段落就象 HTML一样。使用一个 <p> 标记指明一个新行的开始。SGML 会忽略 TAB、空格、空行。当 SGML 检查到 <p> 标记时，它开始一个新行。放置 </p> 标记结束该段落。

增强文本

你偶而会需要让一些文本明显不同於其它文本。可能是重要代码或者命令列表。强调文本可以使用 <em> 和 </em> 标记。斜体字可以使用 <tt> 和 </tt> 标记。

列表

在 SGML 中有两种形式的列表。第一种是列举列表，从1开始为每一个列表项编号。

This is the first entry in the enumerated list. This is the second. Third.

以上的代码如下：

<enum> <item>This is the first entry in the enumerated list. <item>This is the second. <item>Third. </enum>

<enum> 标记指出紧随其後的列表项要开始编号。

另一种形式是逐项列表，每一个列表项前面只放一个星或圆圈或点或其它东西。

This is the first entry in the itemized list This is the second Third

以上的代码如下：

<itemize> <item>This is the first entry in the itemized list <item>This is the second. <item>Third. </itemize>

就象你所看到的，<item> 标记在两种形式列表中都一样。

第三种形式是描述列表，包括被描述的术语以及描述该术语的短语。

LDPThe Linux Documentation Project SGMLStandard Generalized Markup Language

以上的代码如下：

<descrip> <tag>LDP</tag>The Linux Documentation Project <tag>SGML</tag>Standard Generalized Markup Language </descrip>

这种形式不同於前面两种，整个列表包含在标记 <descrip> 和 </descrip> 中，每一行中的每一项，也就是定义的短语，被包含在 <tag> 和 </tag> 中。行的剩余部分是对短语的定义。

逐字文本

有时你需要完全显示你所写的内容，你可以使用 <verb> 和 </verb> 标记来包含段落。在</verb> 标记之前的空格、回车以及其它文本(包括特别字符)都将被保留。

以下就是逐字文本

统一资源定位(URL)

SGML 也允许统一资源定位(URL)。注意这在输出成 HTML 格式时才有用，其它格式可能也有一些用，比如说 RTF 格式。

一个 URL 没有结束标记，所有信息都放在 <url> 标记里面。这是一个指向 LDP 主页的 URL：。以下是代码：

url=&dquot;http://www.linuxdoc.org/&dquot; 告诉浏览器目标地址，而 name=&dquot;http://www.linuxdoc.org/&dquot; 则告诉浏览器如何显示。在本例中两者是一样的，但我可以创建一个如下的 URL 标记：

在页面上的显示就象这样： .

参考(References)

URL 适合於链接到 LDP 文档之外的内容，但不适合於链接到文档内容自身。为实现这一功能，可以使用 <label> 和 <ref> 标记。<label> 标记创建一个将来能跳转回来的记号，非常象一个书签。创建 <label> 很简单。找到以後需要跳转回来的位置，然後插入以下：

你现在已经在文档内容中创建了一个可以跳转回来的记号 "Introduction"。这个标签确实出现在文档的开头。当你以後需要跳转回来时，插入以下：

SGML 就能明白放入一个叫 "here" 的链接可以跳转至 Introduction 章节的位置。

参考的另一部分是索引 (indexing)。由於 LDP 文档经常是大量文档，必须在书的後面建立基於单词和主题的索引。

特殊字符(Special characters)

非常象 HTML，你必须避免许多非文字字符以防止 SGML 将其解释成 SGML 代码。这里有一个 SGML 代码的列表。更多的可以查阅 sgmltools 用户指南：。

Use & for the ampersand (&) Use < for a left bracket (<) Use > for a right bracket (>) Use &etago; for a left bracket with a slash (</) Use &dollar; for a dollar sign ($) Use &num; for a hash (#) Use &percnt; for a percent (%) Use &tilde; for a tilde (˜) Use `` and '' for quotes, or use &dquot for &dquot; Use  for a soft hyphen (that is, an indication that this is a good place to break a word for horizontal justification).

使用其它工具书写 SGML LyX

我一直十分喜爱 LyX，因此我偏爱这个软件。它提供常规字处理器易於使用的方式书写 SGML。它不是一个所见即所得程序，而是所得即所想应用。

要用 LyX 创建一个 LinuxDoc 文档，下载并安装应用程序。确保你已安装 TeX 和 sgmltools (参见 )。然後启动 LyX 并且选择 "file->new from template..."。选择 "Templates" 然後点击 linuxdoctemplate.lyx ，这样你将得到一个带 LDP 文档头信息的文档模板。更改合适你的数据(也就是，填写标题、作者、日期、摘要等等)，然後开始写作。左上角的下拉菜单可以用来选择内容的类型(标准、列表、章节)。感叹号用来强调文本。你既可以点击它进入强调模式，也可以用鼠标高亮选择文本再点击它，将选择的文本置为强调文本。许多其它的 SGML 特性可以在 Insert 菜单条中找到。你可以插入 URL、交叉参考、索引以及其它类型的数据。当完成你的文档後，你可以保存成 LyX 格式，然後输出到 LinuxDoc 得到 .sgml 後缀的文件。这个文件可以被 sgmlcheck 检查和输出成你想要的格式。

Emacs

我不使用 Emacs，但我并不排斥它。有 Emacs 使用经验的人会觉得它非常有用。

其它 SGML 工具

如果有除此之外的其它 SGML 工具，或者即使是商业版本，只要是能被 LinuxDoc DTD 用来创建 LDP 文档，请告诉我。

CVS 基础

到现在为止，LDP 还没有一个共享仓库可供你在线保存你的文档内容。非常希望改变这种状况。有很多需要使用 CVS 的原因：

CVS 将保存一个你的文档的外部备份。在你将文档传给另外一个作者时，他只需要从 CVS 取得文档就可以继续工作。在你需要取得一个文档的早期版本，你也可以很快得到。在多人维护同一文档时非常有用。你可以从 CVS 得知在你编辑你的拷贝时其他作者做了哪些修改，从而将所有的修改很好地结合在一起。保存修改的记录。在 SGML 处理器处理之前，你可以使用一些特殊的标记，这些记录(以及一个时间戳)会被自动地插入到文档中。提供一个途径，在新文档完成并提交後通过一个程序自动地更新 LDP 站点。

发布你的文档发布之前

在你将文档发布给成千上万的潜在读者之前，我必须做一些事情。

首先，对你的文档做拼写检查。没有什麽比拼写错误更快让人觉得是在互联网世界中说“嘿，我是傻瓜”。许多你可以用来写 SGML 的应用程序(emacs、LyX...)都内置有拼写检查功能。如果没有，就在所有的linux发行版本中都安装了一个 ispell 程序。同样要使用 sgmltools 中的 sgmlcheck 命令检查 SGML 标记。

其次，找一些人评价你的文档。由 LDP 发布的文档应尽可能保证真实、正确，因为有成千上万的Linux用户可能会读它。如果你参加了一个相关主题的较大规模的邮件列表，可以请求列表中的其他人帮助你。

第三，建立一个发布你的文档的网站。这并不是必须的，但有助於人们找到你的文档的原始出处。

版权和许可

In order for an LDP document to be accepted by the LDP, it must be licensed to allow for free (as in beer) distribution and publishing. As an author, you may retain the copyright and add other restrictions (for example, you must approve any translations or derivative works). A sample license is available at . If you choose to use the boilerplate copyright, simply copy it into your source code under a section called "Copyright and Licenses" or similar. Also include a copyright statement of your own (since you still own it). If you are a new maintainer for an already-existing HOWTO, you must include the previous copyright statements of the previous author(s) and the dates they maintained that document.

遵从 LDP

一旦你的文档被一部分人看过并且你已吸收了他们的意见，你就可以将文档送往 LDP。发送邮件到。24小时之内你就可以知道它是否已被接受并送往主要的 LDP 站点。

风格指南

这并不是一个写出色文档的强制和快速的指南，但对你的写作有所帮助。

清晰。所有人需要知道你在说什麽。在可能的地方使用例子。这让所有人看到你在说什麽。组织。不要在同一章节中，在两个不相关主题间跳来跳去。

你可以从以下地址得到更多的 LDP 风格指南： .

关於 LDP 的常见问题我想为 LDP 出一份力，我该如何去作？

最简单的办法就是找出一些东西然後写出来。也可以查找没人维护的 HOWTO 然後看看是否有一个你了解的主题可以继续写下去。

我想出版 LDP 文档。LDP 的文档许可是怎样规定的？

请参阅 .

我在一个 LDP 文档中找到一个错误。我能修正它吗？

联系文档的作者，或者 LDP 组织者，告诉他们存在的问题以及如何修正。