Next Previous Contents

3. 让我们开始

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

3.1 写给新作者

如果你刚刚了解 LDP 并且想要选择一个没人维护的 HOWTO 或者想写一个新的 HOWTO 或者 mini-HOWTO 文档,请联系 linux-howto@metalab.unc.edu

这将让 HOWTO 协调人掌握谁在维护哪篇文档。同时要注意所有的 HOWTO 都使用 SGML 格式(当前使用 LinuxDoc DTD)。mini-HOWTO 使用 SGML 或者 HTML 格式,但只有 SGML 格式将被包含进 HOWTO 的打印版本中。

3.2 邮件列表

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

3.3 下载并安装工具

sgmltools

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

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

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


# apt-get install sgml-tools
 

要了解更多关於 Debian 包的信息,你可以查阅 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 , 只要你掌握了所有需要使用的标记代码本章节将讲述尽可能多的这些代码,并为每一个提供例子。开始的最好的地方就是本文的源码,可以从这里看看: Introduction. 因为 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>
<!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <markk>
 Fri Aug 27 09:42:28 1999 -->
<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开始为每一个列表项编号。

  1. This is the first entry in the enumerated list.
  2. This is the second.
  3. Third.

以上的代码如下:

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

 

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

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

以上的代码如下:

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

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

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

LDP

The Linux Documentation Project

SGML

Standard 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: http://www.linuxdoc.org/ 。以下是代码:

<url url="http://www.linuxdoc.org/" name="http://www.linuxdoc.org/">
 

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

<url url="http://www.linuxdoc.org/" name="LDP">
 

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

参考(References)

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

<label id="Introduction">
 

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

<ref id="Introduction" name="here">
 

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

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

特殊字符(Special characters)

非常象 HTML,你必须避免许多非文字字符以防止 SGML 将其解释成 SGML 代码。这里有一个 SGML 代码的列表。更多的可以查阅 sgmltools 用户指南: http://www.sgmltools.org/guide/guide.html

3.5 使用其它工具书写 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 文档,请告诉我。

3.6 CVS 基础

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

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

3.7 发布你的文档

发布之前

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

首先,对你的文档做拼写检查。没有什麽比拼写错误更快让人觉得是在互联网世界中说“嘿,我是傻瓜”。许多你可以用来写 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 http://www.linuxdoc.org/COPYRIGHT.html. 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。发送邮件到 ldp-submit@lists.linuxdoc.org 。24小时之内你就可以知道它是否已被接受并送往主要的 LDP 站点。


Next Previous Contents