随着 Linux 变得越来越流行，不仅是新手，所有用户都需要大量的文档。想想每个人日常工作所需的 FAQ、HOWTO、手册页和书籍。有些人希望以纯 ASCII 文本格式阅读这些文档，而另一些人则希望通过万维网阅读或在 PostScript 打印机上打印。可以为 Web 制作 ASCII 文档的 HTML 版本，并为打印制作格式良好的 PostScript 版本，但所有不同的格式都必须分别维护。这在理论上是可能的，但在现实生活中并不会发生。

我们需要一个文档系统，它可以从单一来源生成不同的格式。当 HOWTO 项目启动时，Linux 文档项目正面临着这个难题，因此 Matt Welsh 编写了 Linuxdoc-SGML 包来解决这个问题。有了这个包，所有文档都以类似的方式格式化。但是 SGML 非常灵活，因此您可以使用该系统编写许多不同类型的文档；例如，XFree86 项目的所有文档都使用 Linuxdoc-SGML。

<!doctype linuxdoc system>
<article>
<title>The Very Short Story
<author>A. Author
<date>1 Jan 1970
<p>
Once upon a time, they lived happily ever after.
<article>

正如您在此处看到的，Linuxdoc-SGML 语法非常简单。命令用尖括号编写：<command>。当它们应用于文本块时，它们以包围该块的一对出现，因此块之前的 </article> 与块之后的 </article> 相平衡。如果块很短，后一种情况也有一个缩写：<tt/typewriter font/。

文档的第一行指定文档类型。在这里，您将始终指定 linuxdoc system，因为这指的是 Linuxdoc-SGML 包的主要宏。然后，您可以使用 <article> 命令开始您的文档，并在末尾使用相应的“article off”命令 </article> 关闭它。文章本身以标题、作者和日期（可选）开头。之后，您可以开始编写正文。<p> 命令指示第一个段落的开始。编写文本时，您不必担心空格或换行符，因为单词之间的多个空格将被忽略，并且换行符将自动插入到适当的位置。要开始一个新段落，请插入一个空行，它是 <p> 的“同义词”。

Linuxdoc-SGML 实际上是一组协同工作的程序，以提供最终输出。您需要了解如何使用它们中的每一个；几个示例将有所帮助。format 程序创建为 LaTeX、groff 或 makeinfo 设计的文件，并且是创建 HTML 文件过程的一部分，这将在下面更完整地解释。-T 参数告诉 format 它正在为哪个程序编写文件。

有一个实用程序用于运行每个格式化程序（groff 等）。每个实用程序都有一个以 “q” 开头的名称，例如 “qtex”。

要通过 LaTeX 获取 PostScript 文件，只需键入

format -T latex example.sgml > example.tex
qtex example

Linuxdoc-SGML 将创建一个 LaTeX 格式的文件，使用 LaTeX 处理该文件，然后使用 dvips 将其转换为 PostScript 文件 example.ps。请注意，您需要安装 LaTeX 和 dvips 以及 Linuxdoc-SGML 才能使其工作。

如果您喜欢 DVI 文件，您可以使用 qtex 的 -d 开关

format -T latex example.sgml | qtex -d > example.dvi

纯 ASCII 输出是通过类似的过程创建的。只需运行

format -T nroff example.sgml | qroff > example.txt

要获得可以使用 GNU info 程序读取的 texinfo 输出，请使用

format -T info example.sgml

这将在当前目录中自动创建必要的文件。当然，您需要在系统上安装 GNU texinfo 包才能制作 texinfo 文件。

HTML 输出需要稍微注意一些，因为需要两个编译阶段才能构建所有交叉引用。首先，您必须正确设置 LINUXDOC 环境变量；您可能想要添加如下一行

export LINUXDOC=~/linuxdoc-sgml-1.2

在您的 bash 启动文件中，或

setenv LINUXDOC=~/linuxdoc-sgml-1.2

在您的 csh 或 tcsh 启动文件中。

一旦它工作了，您必须运行几个命令才能获得完成的 HTML

format -T html example.sgml | prehtml | \
   fixref > tmp.html
format -T html example.sgml | prehtml >> tmp.html
cat tmp.html | html2html example > example.html
rm tmp.html

将这些命令放在 shell 脚本中是个好主意，因为您会经常调用这些命令。这是一个您可以使用的简单版本

bin/bash
bin/bash
# sgml2html
[ -z -$1- ] && { echo -What file?-; exit 1 }
BASE=`basename $1 .sgml'
[ ! -f $BASE.sgml ] && { echo -No file $BASE.sgml-; exit 2 }
TMP=$$tmp.html
format -T html $1 | prehtml | fixref > $TMP
format -T html $1 | prehtml >> $TMP
cat $TMP | html2html $BASE > $BASE.html
rm $TMP

此脚本要求您的输入文件具有扩展名 .sgml。

必须为该脚本提供完整的文件名，并且它要求该文件具有扩展名 .sgml 才能正常工作。

所有这些都在 Linuxdoc-SGML 提供的优秀、简短的手册中得到了更完整的记录。

既然我们已经解释了必要的“开销”，我们就可以开始编写更大的文档了。因此，您可能想要创建节和小节，以摘要开始文档，并插入目录。您只需在 date 行之后添加以下行

<abstract>
Here is the abstract.
<abstract>
<toc>
<sect>The First Section
<sect1>The First Subsection

根据您要创建的输出格式，目录将具有不同的样式：在 LaTeX 文档中，您将获得标准目录，而在 HTML 文件中，您将获得不同节和小节的交叉引用列表。

从我们的示例中可以看出，<sect> 命令创建一个新节，<sect1> 命令创建一个新的小节。您只需增加命令名称中的数字即可访问五个不同的级别。请注意，在节命令之后，您仍然必须插入 <p> 命令才能开始第一个段落。对于技术文档，通常需要包含“verbatim”文本——SGML 解析器未经解释传递的文本。您可以使用 <verb> 命令来执行此操作

<verb>This text is not interpreted <verb>

但是，即使某些非常特殊的字符出现在 verbatim 环境中，也确实需要进行一些额外的处理。例如，左尖括号和斜杠 (</) 的序列必须写为 &ero;etago;。Linuxdoc-SGML 包附带的手册包括所有特殊字符以及用于将它们作为文字字符输入的命令的列表。

除了普通字体外，Linuxdoc-SGML 包还支持三种不同的字体样式：boldface、italics 和 typewriter。要选择字体，请分别插入命令 bf、em 或 tt。要切换回默认字体，只需使用相应的“slashed”命令，如下例所示

This <em>text</em> is written in italics!

每种的缩写版本有时很有用

This <em/text/ is written in italics!

现在让我们看一下支持的不同列表类型

您只需使用 <list> 命令启动列表“环境”，并使用 </list> 关闭它。要生成一个新项目（项目符号或数字），您可以使用 <item> 命令。在描述环境中，您必须使用带有包含“关键字”的参数的 <tag> 命令，如下例所示

<descrip>
<tag/First./ This is the first point.
<tag>Second.</tag> And this is the second.
</descrip>

如果您想使用此包创建 WWW 页面，您可能需要创建对其他 WWW 页面的交叉引用。这是通过 <url> 命令完成的，如下例所示

<url url=-http://gnus.com/pub/text.html- name=-Text
document->

这会在指定主机上创建指向 WWW 页面 text.html 的链接，并将 Text document 显示为链接的标题。当您创建非 HTML 文档时，名称和 URL 都会显示，以便读者仍然可以找到该文档。