1. 简介

许多主要的开源项目正在汇聚到 DocBook，将其作为文档的标准格式——包括 Linux 内核、GNOME、KDE、Samba 和 Linux 文档项目等项目。“结构化标记”（与 troff、Tex 和 Texinfo 所代表的旧式“表示标记”相对）的倡导者似乎赢得了理论上的战斗。您可以从结构化标记生成表示标记，但反过来则非常困难。

然而，围绕 DocBook 和支持它的程序存在许多困惑。它的拥护者所说的行话密集且令人望而生畏，即使按照计算机科学的标准来看也是如此，他们抛出的首字母缩略词与您需要执行的标记编写以及从中制作 HTML 或 Postscript 的操作之间没有明显的联系。XML 标准和技术论文以晦涩难懂而闻名。

本 HOWTO 将尝试澄清围绕 DocBook 及其在开源文档中的应用的主要谜团——包括技术和政治方面的谜团。我们的目标是使您不仅理解制作文档需要做什么，还要理解为什么这个过程如此复杂——以及随着更新的 DocBook 相关工具的出现，它将如何变化。

2. 为什么要在意 DocBook？

有两种可能性使 DocBook 真正有趣。一种是多模式渲染，另一种是可搜索的文档数据库。

多模式渲染是更容易、更近期的可能性；它指的是以单一主格式编写文档的能力，该格式可以以多种不同的显示模式渲染（特别是，既可以作为用于在线查看的 HTML，也可以作为用于高质量打印输出的 Postscript）。这种能力现在已经得到了很好的实现。

可搜索的文档数据库是速记说法，指的是 DocBook 可能帮助我们进入一个世界，在这个世界中，您的开源操作系统上的所有文档都是一个丰富、可搜索、交叉索引和超链接的数据库（而不是像现在这样分散在多个位置的几种不同格式中）。

理想情况下，每当您在机器上安装软件包时，它都会将其 DocBook 文档注册到系统的目录中。HTML 将被生成，并正确索引和交叉链接到目录中其余部分的 HTML。然后，可以通过浏览器访问新软件包的文档。您的所有文档都可以通过类似于优秀的 Web 搜索引擎的界面进行搜索。

HTML 本身格式不够丰富，无法让我们进入那个世界。仅举一个缺点，您无法在 HTML 中显式声明索引条目。DocBook 确实具有支持结构化文档数据库的语义丰富性。从根本上说，这就是这么多项目采用它的原因。

DocBook 的缺点与其优点并存。有些人觉得它令人不快地笨重，并且过于冗长，难以作为编写格式感到舒适。没关系；只要他们喜欢的标记工具（如 asciidoc 或 Perl POD 或 GNU Texinfo）可以从后端生成 DocBook，我们仍然可以得到我们想要的东西。每个人是否都用 DocBook 编写并不重要——只要它成为每个人都使用的通用文档交换格式，我们仍然可以获得统一的可搜索文档数据库。

3. 结构化标记：入门

较旧的格式化语言（如 Tex、Texinfo 和 Troff）支持 表示标记。在这些系统中，您给出的指令是关于文本的外观和物理布局的（字体更改、缩进更改等等）。

只要您的目标是打印到单一介质或显示设备类型，表示标记就足够了。但是，当您想要标记文档以便 (a) 可以为非常不同的显示介质（如打印与 Web 显示）格式化，或者 (b) 您想要按其逻辑结构支持搜索和索引文档（例如，如果您要将其合并到超文本系统中，则很可能需要这样做）时，您会遇到其限制。

为了正确支持这些功能，您需要一个 结构化标记 系统。在结构化标记中，您描述的不是文档的物理外观，而是其各个部分的逻辑属性。

例如：在表示标记语言中，如果您想强调一个词，您可以指示格式化程序将其设置为粗体。在 troff(1) 中，它看起来像这样

All your base
.B are
belong to us!

在结构化标记语言中，您会告诉格式化程序强调这个词

All your base <emphasis>are</emphasis> belong to us!

上面一行中的“<emphasis>”和 </emphasis>被称为 标记标签，或简称为 标签。它们是给格式化程序的指令。

在结构化标记语言中，最终文档的物理外观将由 样式表 控制。样式表会告诉格式化程序“将强调渲染为字体更改为粗体”。结构化标记语言的一个优点是，通过更改样式表，您可以全局更改文档的表示形式（例如，使用不同的字体），而无需破解文档本身中（例如）.B 的所有单个实例。

4. 文档类型定义

（注意：为了保持解释简单，本节的大部分内容将讲述一些谎言，主要是通过省略大量历史。真实性将在后面的章节中完全恢复。）

DocBook 是一种结构级标记语言。具体来说，它是 XML 的一种方言。DocBook 文档是一大块 XML，它使用 XML 标签进行结构化标记。

为了让文档格式化程序将样式表应用于您的文档并使其看起来良好，它需要了解有关文档整体结构的信息。例如，它需要知道书稿通常由前言、一系列章节和后记组成，以便正确地物理格式化章节标题。为了让它知道这类事情，您需要给它一个 文档类型定义 或 DTD。DTD 告诉您的格式化程序文档结构中可以包含哪些类型的元素，以及它们可以出现的顺序。

我们称 DocBook 为 XML 的“应用”的含义实际上是 DocBook 是一个 DTD——一个相当大的 DTD，其中大约有 400 个标签。

潜伏在 DocBook 背后的是一种名为 验证解析器 的程序。当您格式化 DocBook 文档时，第一步是通过验证解析器（DocBook 格式化程序的前端）传递它。此程序根据 DocBook DTD 检查您的文档，以确保您没有违反 DTD 的任何结构规则（否则，格式化程序的后端，即应用样式表的部分，可能会变得非常困惑）。

验证解析器要么崩溃，并向您提供有关文档结构损坏位置的错误消息，要么将文档转换为 格式化事件 流，解析器后端将这些事件与样式表中的信息结合起来，以生成格式化的输出

这是整个过程的图表

虚线框内的部分是您的格式化软件，或 工具链。除了格式化程序的明显可见的输入（文档源）之外，您还需要记住格式化程序的两个“隐藏”输入（DTD 和样式表），以了解后续内容。

5. 其他 DTD

简要介绍其他 DTD 可能有助于明确上一节的哪些部分是 DocBook 特有的，哪些部分是所有结构化标记语言通用的。

TEI（文本编码倡议）是一个大型、精细的 DTD，主要在学术界用于文学文本的计算机转录。TEI 基于 Unix 的工具链使用许多与 DocBook 相关的相同工具，但使用不同的样式表和（当然）不同的 DTD。

XHTML，HTML 的最新版本，也是由 DTD 描述的 XML 应用程序，这解释了 XHTML 和 DocBook 标签之间的家族相似性。XHTML 工具链由 Web 浏览器和许多临时的 HTML 到打印实用程序组成。

维护了许多其他 XML DTD，以帮助人们在生物信息学和银行业等不同领域交换结构化信息。您可以查看 存储库列表，以了解其中的多样性。

6. DocBook 工具链

格式化和渲染 XML-DocBook 文档的最简单方法是使用 xmlto 工具链。这与 Red Hat 一起发布；Debian 用户可以使用命令 apt-get install xmlto 获取它。

通常，您将执行以下操作以从 DocBook 源代码制作 XHTML

bash$ xmlto xhtml foo.xml
bash$ ls *.html
ar01s02.html ar01s03.html ar01s04.html index.html

在此示例中，您转换了一个名为foo.xml的 XML-Docbook 文档，其中包含三个顶级部分，转换为索引页和两个部分。制作一个大的页面同样容易

bash$ xmlto xhtml-nochunks foo.xml
bash$ ls *.html
foo.html

最后，这是制作 PDF 以进行打印的方法

bash$ dblatex foo.xml       # To make PDF
bash$ ls *.pdf
foo.pdf

一些旧版本的 xmlto 可能更冗长，会发出“正在转换为 XHTML”等噪音。

要将您的文档转换为 HTML 或 PDF，您需要一个引擎，该引擎可以将 DocBook DTD 和合适的样式表组合应用于您的文档。以下是用于执行此操作的开源工具的组合方式

解析您的文档并应用样式表转换将由三个程序之一处理。最有可能的是 xsltproc。其他可能性是两个 Java 程序，Saxon 和 Xalan，

从 DocBook 生成高质量的 XHTML 相对容易；XHTML 只是另一个 XML DTD 这一事实很有帮助。转换为 HTML 是通过应用相当简单的样式表来完成的，这就是故事的结局。RTF 也以这种方式很容易生成，并且从 XHTML 或 RTF 很容易生成简陋的纯文本近似值。

棘手的情况是打印。生成高质量的打印输出（实际上，这意味着 Adobe 的 PDF 或可移植文档格式，PostScript 的打包形式）很困难。要正确地完成它，需要算法地复制人类排版员从内容级别移动到表示级别的微妙判断。

因此，首先，样式表将 Docbook 的结构化标记转换为另一种 XML 方言——FO（格式化对象）。FO 标记在很大程度上是表示级别的；您可以将其视为 troff 的某种 XML 功能等效物。它必须转换为 Postscript 才能打包在 PDF 中。

在大多数当前 Linux 发行版附带的工具链中，这项工作最好由名为 dblatex 的程序处理（这取代了旧版本的 tis HOWTO 中描述的旧的 passivetex 包）。

dblatex 将 xsltproc 生成的格式化对象转换为 Donald Knuth 的 TeX 语言。TeX 是最早的开源项目之一，是一种古老但功能强大的表示级格式化语言，深受数学家喜爱（它为描述数学符号提供了特别精细的功能）。TeX 在基本排版任务（如字距调整、行填充和断字）方面也非常出色。然后，TeX 的输出被处理成 PDF。

如果您认为这种从 XML 到 Tex 宏再到 PDF 的桶链听起来像是一个笨拙的补丁，那么您是对的。它哐当、呼哧作响，并且有丑陋的疣。字体是一个重要的问题，因为 XML、TeX 和 PDF 对字体的工作方式有非常不同的模型；此外，处理国际化和本地化是一场噩梦。这种代码路径唯一的好处是它可以工作。

优雅的方式将是 FOP，这是 Apache 项目正在开发的直接 FO 到 Postscript 转换器。使用 FOP，国际化问题即使没有解决，至少也得到了很好的限制；XML 工具将 Unicode 一直处理到 FOP。字形到字体的映射也严格来说是 FOP 的问题。这种方法的唯一问题是它还完全不起作用。截至 2010 年 10 月，FOP 为 1.0 版，可用，但存在粗糙的边缘和缺少的功能。我建议将 dblatex 用于生产用途。

以下是 FOP 工具链的外观

7. asciidoc

有一个相对较新的工具称为 asciidoc，它相当有效地解决了与 DocBook 相关的一些问题。

asciidoc 工具接受类似于 Wiki 标记的简单、轻量级语法，并使用 DocBook 作为中间阶段将其转换为各种输出格式。asciidoc 标记比 DocBook 本身更容易编写，并且在纯文本 ASCII 中可以很好地呈现自身。

asciidoc 中的打印支持是通过实验性的 LaTeX 后端实现的。它最适合编写用于万维网分发的中短篇文档。

8. 项目和参与者有哪些？

DocBook DTD 本身由 DocBook 技术委员会维护，该委员会由 Norman Walsh 领导。Norm 是 DocBook 样式表的主要作者，他多年来将非凡的精力和才华集中在 DocBook 解决的极其复杂的问题上。他在 DocBook 社区中受到的尊重与 Linus Torvalds 在 Linux 世界中受到的尊重一样。

libxslt 是一个 C 库，用于解释 XSLT，将样式表应用于 XML 文档。它包括一个包装程序 xsltproc，可以用作 XML 格式化程序。该代码由 Daniel Veillard 在 GNOME 项目的支持下编写，但不需要任何 GNOME 代码即可运行。我听说它比 Java 替代方案快得惊人，这并不令人惊讶。

xmlto 是大多数 Linux 的 XML 工具链的用户界面。它由 Tim Waugh 编写和维护。

Saxon 和 Xalan 是解释 XSLT 的 Java 程序。Saxon 似乎旨在在 Windows 下工作。Xalan 是 XML Apache 项目的一部分，并且是 Linux 和 BSD 的原生程序；它旨在与 FOP 一起工作。

FOP 将 XML 格式化对象转换为 PDF。它是 Apache XML 项目的一部分，旨在与 Xalan 一起工作。

asciidoc 将其自己的轻量级标记转换为 DocBook，然后转换为各种输出格式。

9. 迁移工具

DocBook 的第二个最大问题是将旧式表示标记转换为 DocBook 标记所需的工作量。人类通常可以自动将文档的表示解析为逻辑结构，因为（例如）他们可以从上下文中判断出斜体字体何时表示“强调”，何时表示其他含义，例如“这是一个外来短语”。

在将文档转换为 DocBook 时，需要明确区分这些类型。有时它们存在于旧标记中；通常它们不存在，并且缺失的结构信息必须由巧妙的启发式方法推断出来，或者由人添加。

以下是来自各种其他格式的转换工具的状态摘要

10. 编辑工具

大多数人仍然使用 vi 或 emacs 手动破解 DocBook 标签。Emacs 附带了一个 Nxml 模式，当编辑器识别到 XMl 文档时会自动调用它。它已经变得非常好；虽然它不提供 GUI 表示，但它确实使用其 XML 知识来突出显示不平衡的标签。在 Emacs CategoryXML 页面 上总结了一些替代方案。

已经尝试了许多 DocBook 的 GUI 编辑器，通常旨在成为任何带有 XML 或 SGML 模式的标记的通用编辑器。EuroMath、MLView、Conglomerate、ThotBook 就是其中之一。此类项目往往在 alpha 阶段停滞不前；为此任务设计一个体面的 UI 非常困难。

在 DocBook Authoring Tools 页面 上可以找到一些已进入生产阶段的尝试（即使在许多情况下只是勉强）。我还没有尝试使用其中任何一个。

11. 提示和技巧

可以通过在文档中希望出现索引的点包含一个空的 <index/> 标签来生成索引。请注意，截至 2004 年初，此功能仍然有些原始。它不会合并范围，并且为 PostScript 生成的输出尚未达到生产质量。

此空间保留用于更多提示和技巧。

12. 相关标准和实践

编辑和格式化 DocBook 标记的工具正在缓慢地走到一起。但是 DocBook 本身只是一种手段，而不是目的。除了 DocBook 本身之外，我们还需要其他标准来实现我在本文档开头提出的可搜索文档数据库目标。有两个大问题：文档编目和元数据。

Scrollkeeper 项目直接旨在满足此需求。它提供了一组简单的脚本钩子，软件包安装和卸载产品可以使用这些钩子将其文档注册和注销到共享的、可搜索的系统范围的数据库中。

Scrollkeeper 使用 开放元数据格式。这是一种用于索引开源文档的标准，类似于图书馆卡片目录系统。这个想法是支持丰富的搜索功能，这些功能使用卡片目录元数据以及文档的源文本本身。

13. SGML 和 SGML-Tools

在前面的章节中，我抛弃了 DocBook 的许多历史。XML 有一个哥哥，SGML 或标准通用标记语言。

在 2002 年年中之前，如果没有对 SGML、SGML 和 XML 之间的差异以及 SGML DocBook 工具链的详细描述进行长时间的讨论，那么对 DocBook 的讨论将是不完整的。现在生活可以更简单了；XML DocBook 工具链在开源中可用，与 SGML 工具链一样好用，并且更易于使用。如果您认为您永远不必处理旧的 SGML-Docbook 文档，则可以跳过本节的其余部分。

14. 参考

学习 DocBook 困难的原因之一是，与其相关的站点倾向于用冗长的 W3C 标准列表、大量的标记神学练习以及密集的抽象术语丛林来淹没新手。我们将尝试在此处避免这种情况，方法是仅为您提供一些精选的参考资料供您查看。

Michael Smith 的 听我的建议：不要学习 XML 从类似于本文档的角度调查了 XML 世界。

Norman Walsh 的 DocBook: 权威指南 可以购买印刷版和在线阅读。 这确实是一本权威参考书，但作为入门或教程来说却是一场灾难。 建议阅读以下内容

使用 DocBook 编写文档：速成课程。 这是一个很棒的教程。

有一个很棒的 DocBook FAQ，其中包含大量关于样式化 HTML 输出的资料。 还有一个 DocBook wiki。

如果您正在为 Linux 文档项目编写文档，请阅读 LDP 作者指南。

我个人完整阅读过的关于 SGML 和 XML 的最佳通用入门读物是 David Megginson 的 XML 文档结构 （Prentice-Hall，ISBN：0-13-642299-3）。

仅对于 XML，W. Scott Means 和 Elliotte “Rusty” Harold 的 XML 简明教程 非常好。

XML 圣经 看起来像是关于 XML 和相关标准（包括格式化对象）的非常全面的参考。

最后，如果您真的想深入了解 XML 标准的丛林，XML 封面页 将带您进入。