DocBook XML 方言入门

David Mertz，博士
档案保管专家，Gnosis Software, Inc.
2000 年 10 月

内容：

什么是 DocBook？

语义灵活性

预备，就位，标记！

包含内容

进修教育

参考资料

关于作者

 

在其有关“XML 问题”新专栏的第三部分中，David Mertz 带您开始使用 DocBook，一种描述技术文章和其它文档内容的 SGML/XML 方言。David 讨论了使用 DocBook 的好处，然后描述了如何规划和模块化大型文档转换项目。

 

想象一下一百年后有个历史学家想要查找一个电子文档库，并且必须要译码它们。一个世纪日新月异的技术更新一定给为她带来极大的难题。但到时的情形不一定是这样！

本专栏提出了对我个人来说一个非常实际的忧虑。这些年来，我写了许多有关人类主题的学术论文，并希望将这些论文放在我的网站上。但不幸的是，多年来我曾多次更换过字处理器和平台，保存的许多文档是使用不再拥有或者无法获得的程序编写的。即使我能够得到这些程序，也可能无法在当前的计算机上运行它们。我最多能找到一些转换程序，对我可以运行的程序做一些合适的转换工作。其它情况下，就必须使用原始字处理器格式，大多数都是 ASCII，其中遍布了许多排版错误。

简而言之，我的电子档案一团糟。许多个人和组织都深受比这更糟糕的档案带来的痛苦。随着每次软件升级，大型组织会丢失大量重要的档案文档以适应技术上的更改 -- 一个随时间越变越复杂的问题。

幸运的是，我们可以创建比已有文档更经得起时间考验的文档。XML/SGML 通常，特别是 DocBook，在向创建灵活而持久的文档过程中走了很长一段路。

什么是 DocBook？
DocBook 是由 O'Reilly 和 HaL Computer Systems 于 1991 年开发的一种 SGML 方言。现在由结构化信息标准高级组织 (OASIS) 所维护。DocBook 描述了文章、书籍、技术手册和其它文档的内容。尽管 DocBook 主要集中在技术方面的写作形式，但它对于描述大多数普通写作通常也足够了。在本文中，我将讨论同样可得到的 DocBook DTD 的 XML 变体。

经得起时间考验的文档首要的同时也是最根本的因素是使用具有开放标准的文档格式，例如 XML/SGML。这些开放标准包括两种元素：

语法，或者文档的外观 语义，或者文档的含义

DocBook 文档的语法完全包括在简单的 XML 标记规则和每个 DocBook 文档中固有的 DocBook DTD 中。其语义有略微的不同。例如，DTD 包含特定的语义特性，确定哪些元素可以或必须出现在其它元素内部。应用 DocBook 标记以使它们对至少说英语的人而言具有某种“一般意义”上的语义内容。但其它更详细的语义问题依赖于特定的出版物指南、一般用法规则和编者的判断（例如，控制适合于文本特定地方的列表类型）。请注意，

参考资料里面引证的 DocBook 手册可以提供有关常规语义指南的一些信息，但各个不同的出版物有更具体的指南。

第二个关键从理论上说没怎么重要，但在实践中相当有意义。在正式规范以外解释和使用文档格式有多容易？很难理解使用文本查看器查看旧的二进制流格式。但 XML 文档通常看上去具有相当合理的外观，即使没有正式的确认和处理。当然，简单 ASCII 更容易阅读。

而且，即使没有正式的规范，某些格式也比其它格式更容易重新构造。想象一下我们的历史学家要查找两个文档：一个是 MS Word 97 格式的，伴有 MSDN 文件格式规范 CD，一个是 XML 格式的（即是一个缺少 DTD的文档）。很清楚，这位历史学家重新构造 XML 文档的内容时更轻松。实际上，没有供应商 -- 甚至微软也没有 -- 在编写 Word 97 转换器时下很大工夫，甚至在有格式规范的情况下。就此而言，想象一下 5 年后，在您的雇主将所有工作站“升级”到 MS Office 2005 后必须重新构造您自己的文档会怎么样。

记住可移植性和技术变更的问题后，我开始了将我以前的学术作品转换成 DocBook 格式的项目。我相信这个项目将有助于作品的保存，并使它用于当前和未来的文档格式（通过转换）。

语义灵活性
要记住 DocBook 文档注释的是文档的语义而不是排版或外观。它主要集中在文档的语义，而不是集中在字处理器、HTML，甚至 TeX。字处理器通常允许有帮助您标记例如 "Header, Level 2" 这样的概念类别的样式表，但要逐步尝试实现“所见即所得” (WYSIWYG)。即使样式表也很少能在文档之间保持一致。这种方式对例如页面大小和布局、可用的字体以及元素的类型样式这样的事物进行了大量假设。这些假设大部分与文本实际的概念性含义没有什么关系。几乎所有假设都使得文档很难适应其它不同格式 -- 不论它是不同的打印布局、屏幕显示、语音合成器版本还是 Web 机器人的索引。HTML 最初时与 DocBook 很相似（尽管更简单），但它添加了越来越多的排版标记，因此它当前是语义和排版的混合体（例如，

与 ）。

一个比较容易理解的示例是，许多不同的概念元素在印刷的书籍中是以斜体表示的。不同的书籍使用不同的约定，但以下任何 DocBook 标记都可以在实际输出时以斜体表示：

? ? ?

当然，他们中的任何一个可以不用这种方式表示。在给定了文本的概念性含义后，这些元素的表示方式是任意的。实际上，这些决定都应该是出版商和书籍设计者的事情，而不是作者的事。DocBook 提供了文档必不可少的结构而不尝试以 WYSIWYG 风格表示元素。除了分离内容和外观以外，DocBook 样式的概念性标记可以让您系统地使用元素类型。例如，在文档中创建外语短语的词汇表时，只需要搜索所有 标记的出现即可。使用字处理器，就不得不使用不那么有效的搜索方法来查找所有标记为斜体的短语。

预备，就位，标记！
我的第一个项目 -- 将博士论文转换成 DocBook -- 是个大项目，但我会递增进行的。除了论文写作距现在的时间比较长以外，个别文档还造成文档系统的一些难题。包括：

需要罗马发音符号的名称（但非欧洲字符集） 注脚和交叉引用 页编号 多节级别 铭文 书目 附录 献辞和摘要 数学符号说明 对书籍、URL 和电子邮件地址的引用 特定效果的常用布局 图表和图表注释（必须尽量让它与原始的排版近似）

总的说来，我编写了一个文档，提供许多 DocBook 标记的有效测验。论文已经恢复到它原始的 WordPerfect 7 格式，并有两个不同格式的 PDF 版本，但这两个版本都称不上是可移植或灵活的。使用 DocBook 将是对这两方面的改进。目前我只讨论标记，而不讨论到目标格式的处理。

前言到此为止，让我们开始创建文档：

Mertz 论文的 XML 文档

DocBook XML V4.1.2//EN" "http://gnosis.cx/download/docbook/4.12/docbookx.dtd" [ ]> &bookinfo; &chap1; &chap2; &chap3; &chap4; &chap5; &chap6; &chap7; &chap8; &appendix1; &appendix2; &biblio;

您可以看到，第一步主要在规划。创建组件级别元素的内容，例如章节，才是真正的工作。不过，通过创建对这些组件级元素的实体引用，我将创建过程分割成更易于管理的部分。另外，我还简化了个别章节作为单独文档的发布或导出过程。在第一步里，我指定了创建的文档类型是书籍，因此包括一系列组件级的元素引用外部文件。

在顶级定义的某些实体不是直接使用的，而只能放在包括文件中。例如，实体 &abstract; 只插在 bookinfo.sgm 文档中。第 5 章中的各节也是这样。它是判断有关分割内容的调用，但我的评判标准是应该为单独出版的文档创建单独的文件。我在扩展这个 DocBook 项目的时候可能做其它调整。

这时还定义了据我所知在文档中提到的名称，但这不适合 US-ASCII。我不能直接输入发音符号，而输入例如 &Zizek; 这样的符号令人难以察觉地接近了我的实际需要。您还可以使用完整短语的缩写。

包含内容
如样本代码显示的那样，主文档设置中包括的文件由单独一个文档根标记和它们的内容组成。包括文件中不应该有文档类型声明或处理指令。文档类型已经在中央书籍主文档中声明过，因此可以把它放在一个地方。例如，bookinfo.sgm 文件只包含以下内容：

Included XML/SGML subdocument The Politics of Impotent Representation and Non-Representational Terrorism DavidMertz &abstract;

类似地，每个章节文件都以 标记开始，以 标记结束。

再重复一遍，该模块化结构的主要优点在于抽取单独出版物的个别组件很容易。例如，我要先将第 5 章的版本进行转换以单独发布。因此，单独为该节创建了以下一个比较小的封装器：

章节级子文档封装器

DocBook XML V4.1.2//EN" "file://g:/articles/scratch/docbook/4.12/docbookx.dtd" [ ]> Gould, 1987b, quoting Gunnar Myrdal, An American Dilemma (1944) But there must be still other countless errors of the same sort that no living man can yet detect, because of the fog within which our type of Western culture envelops us. Cultural influences have set up the assumptions about the mind, the body, and the universe with which we begin; pose the questions we ask; influence the facts we seek; determine the interpretations we give these facts; and direct our reaction to these interpretations and conclusions. &chap5_1; &chap5_2; &chap5_3;

这一大段已标记的内容分成 3 节，每节都有一个顶级 sect1 作为它的根。不过，我可以选择将相同的节内容作为书籍级或章节级封装器的一部分来处理。我还将第 2 节作为单独的文章出版，它的结构与章节的结构相同。

进一步学习
本专栏只提供对 DocBook 一般了解的信息。以后的专栏将更详细地介绍 DocBook 标记，并描述它们是如何构建的。另外，我还将讨论如何将 DocBook 文档转换成更适合直接阅读的格式，如何确认它们，以及如何对它们执行处理操作。请继续关注。

在此其间，最好开始略微地了解一下

参考资料中的一些 DocBook 引用材料。 DocBook 有许多，可能比任何人想象的都要多的可用标记。出于这个原因，使用 DocBook 时准备一些引用材料并不麻烦 -- 即使进行编辑使用的是专门工具。一旦对要查找的标记类型以及如何将它们放在一起有了初步了解，进行起来就更容易了。

参考资料

仔细检查“XML 问题”专栏的前两部分。

 

XML 问题 #1 介绍了 xml_pickle 对象， XML 问题 #2 描述了如何使用 xml_objectify。

• 最好从 DocBook: The Definitive Guide，Norman Walsh & Leonard Muellner，O'Reilly，Cambridge, MA 1999 开始理解有关 DocBook 的更详细信息。有这本书的联机版本可用。
• OASIS 是结构化信息标准提高组织 （Organization for the Advancement of Structured Information Standards），这是一家非赢利性的国际联合会，基于例如 XML 和 SGML 这样的公用标准来创建可以互操作的行业规范。他们的任务是促进这些标准的使用，他们的站点 OASIS 提供了有关组织和标准的额外信息。
• 从某些方面来看，比 DocBook 更可移植和更经得起时间考验的一种格式是纯 ASCII，或“智能 ASCII”，它以从 Usenet 中发展起来的格式合并简单样式注解。当然，ASCII 不能捕捉 DocBook 的所有语义结构，但您很多时侯并不需要它。 项目 Gutenberg 就是尝试以这种中性方式保留和利用文本的一例。
• TeX 是一个重要工具，它的目标与 DocBook 的目标有重叠。TeX 重点更接近与排版，但 TeX 还有许多特定于数学方面的语义标记元素。
• 我自己的文章，包括这一篇的草稿，最初时曾使用类似于“智能 ASCII”格式。使用工具 Txt2Html 来自动化标记。请参考本文的 ASCII 版本或文本版本。
• 我所做的转换一篇晦涩的哲学论文可能对大多数 XML 开发者没有什么吸引力，但所使用的实际格式却很有趣。文档最初是用 WordPerfect 7 编写的，其中有一些部分自另一个字处理器格式导入。通过努力对一些重要的元素使用样式表来使全局更改更容易。在一个早先进行的对 Web 出版物的尝试中，我将文档输出到 PDF 格式，得到的样式在排版方面更接近于印刷的杂志／期刊文章，而非提交的论文。PDF 是个不坏的格式，但它没有将内容与布局分开。请参考我原始的 PDF 格式 或 WordPerfect 7 格式的论文。
• 本文中使用和提到的文件可以在 XML 问题 #3 文件中找到。
• “DocBook gentle 指南”，也在developerWorks 上，它介绍了 DocBook，并描述如何使用 DocBook 创建简单的文档。

关于作者
可能有些用词不当，但将 David Mertz 的兴趣并列描述为兼用法并不可笑。词就是词。可以通过

[email protected] 与 David Mertz 联系，在 http://gnosis.cx/publish/ 上详细介绍了他的生活。非常欢迎对过去的、这一篇或将来的专栏文章提出意见和建议。