逐步适应 DocBook XML 方言

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

内容：

创建内容

准备 DocBook DTD

处理指令

创建章节

下次见

参考资料

关于作者

本专栏继续讨论使用 DocBook 来将异构格式的文档转换成单一、标准 XML 格式的好处。还更详细地介绍了某些 DocBook 标记，并讨论如何编写基本的 DocBook 文档。

如果您的文档档案和我的差不多，它们就包含了从 Microsoft Word 3.3、HTML、Word Perfect 7 到 ASCII 文本每种格式的文件。大多数时候，您甚至无法获得创建原始文档所用的软件。幸运的是，DocBook，这种用于创建通用技术文档的 SGML 方言，可以帮助您将文件转移到单一的标准 XML 格式。在本专栏中，我将解释如何使用 XML 版本的 DocBook DTD 来转换现有文档。

DocBook 是具有几百个元素的相当复杂的 DTD。幸运的是，您不必知道所有 DocBook 就可以使用它。您将看到，基本元素是以逻辑方式排列的，大多数元素都遵循类似的模式来嵌套子元素。

创建内容 -- 不同的方法
使用 DocBook 时很容易犯一些小的输入错误。要使用它，关键问题是在工作时手头有一本好的参考资料。我偏向于 O'Reilly 相当不错的硬拷贝文本，但也有相同的联机材料（请参阅参考资料）。通过您现有的参考资料，就可以用以下两种方式之一来创建 DocBook 内容：

• 使用专门的 XML 编辑器
• 使用常规文本编辑器，外加外部确认器

DocBook 非常详尽，以至于您需要一些自动化操作来确保与 DTD 保持一致。使用这两种方法都可以长时间连续工作，并只是偶尔需要确认和改正一些缺陷。

大多数专门的 XML 编辑器可以帮助您输入元素和属性。很多程序都为当前 DTD 中存在的可用标记或标记列表提供与上下文相关的提示（例如 DocBook 的）。不过，要知道专门的编辑器通常没有好的通用文本编辑器灵活，后者可以提供如多个剪贴板、语法突出显示、列标记和节／函数浏览等功能。

不幸的是，我发现 XML 工具的质量仍然不能令人满意。我测试过一些 XML 确认和转换工具，但还没找到一个完全正确的命令行 XML 确认器。实际上，我曾试着在 Win32 下使用 XML Spy，在其它带有 Java 支持的平台上使用 Xeena。这两种工具都可以很好地进行确认，但使用起来又都很麻烦。（有关 XML Spy、Xeena 和常规文本编辑器的评论，请参阅参考资料。）

准备 DocBook DTD
创建 XML DocBook 文档的第一步是准备它的声明。让我们看一下清单 1，一个文档声明示例，然后逐步了解它的不同部分：

清单 1. XML 文档类型声明

<?xml version="1.0"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ <!ENTITY Zizek "&Zcaron;i&zcaron;ek"> <!ENTITY Mocnik "Mo&ccaron;nik"> ]> <?xml-stylesheet type="text/xsl" href="chapter.xsl"?> <chapter> <!-- The actual chapter contents are here --> </chapter>

XML 声明
我们首先包括的是 <?xml> 声明，它表明该文档是 XML。下一个是 <!DOCTYPE> 标记 -- 文档类型声明。值得仔细查看一下文档类型声明的内容。

DOCTYPE 标记元素
<!DOCTYPE> 标记中要注意的第一件事是将用在文档中的根元素 (chapter) 名称。确定要使用哪种根元素类型很重要，因为它说明了（至少大致说明）文档的用途。根元素通常粗略地确定了文档大小。

在最高级别上，可以在包括两个或多个 books（例如整个参考资料集合）时指定根元素 set。在这种情况下，不必将每样东西都放在同一个文件中，而使用“包含”，这在“ XML 问题 #3”中有大致的说明。往往会创建一个 book，它由 parts 或 chapters，再加上其它与部分／章节的相同概念级别上的节组成。更谦虚地说，可以创建 article 或 chapter，如清单 1 中的示例那样。实际上，chapter 或 article 是用于 DocBook 文档的最小根元素。

在 <!DOCTYPE> 声明中，我们接下来看到的是 PUBLIC 和系统标识。PUBLIC 后面的部分是 SGML 特性，实际上在 XML 文档中并不需要它。如果将它包括在内，要确保它的拼写与在 DTD 中的拼写完全一样。DTD 在系统标识中由 URL 表明，后者是所有 DocBook 定义所在的地方。如果希望查看 DTD， 可以下载 URL。还要确保正确地拼写 URL，否则确认程序将无法找到 DTD。

最后，在 <!DOCTYPE> 标记方括号中的是“内部子集”，它只是声明文档中特殊特性的一种方法。在本例中，我为难以在美式键盘上输入的名称创建了别名。

处理指令
清单 1 中文档类型声明标记之后是处理指令 <?xml-stylesheet...>。我将在下一个“XML 问题”专栏中详细讨论可扩展样式表语言转换 (XSLT)。不过，处理指令与 HTML 文档的级联样式表 (CSS) 类似。在本例中，我添加了一个对 XSL 文档的引用，该文档包含某些用于转换 DocBook 文档的规则。与级联样式表相似，这种类型的处理指令是可选的，甚至对于转换工具来说也是这样。根据不同的工具，可以使用任何所需的 XSLT 来指定转换。处理指令只是一种执行的手段。

最后，我们看到在声明根元素中引用的 <chapter> 标记。章节内容都放在这个标记中。

创建章节
章节、文章、前言和书目等都是文档的组成部分。也就是说，各组成部分对同一主题作适当详细的描述。通常，元素名反映了它们的英文含义。

<chapter>、<appendix>、 或 <preface> 元素的结构是相似的。<article> 与这些元素在结构上几乎一样，但前置内容通常包括在 <artheader> 元素中。类似 <chapter> 的组成部分所包括的前部内容有 <title>，后面跟着节和／或块元素（例如 <p>）。

<title> 元素通常需要作为组成部分和节的前部内容。大多数其它前部内容是可选的，但可以包括作者信息、摘要、图形或其它与 描述组成部分而非建立组成部分相关的信息。让我们看一下清单 2，一个有效、高度精简的章节（假设文档类型声明是在清单 1 中描述的）的示例：

清单 2. DocBook chapter 标记

<chapter> <title>Hegemony, and Other Passing Fads</title> <epigraph> <attribution> Gould, 1987b, quoting Gunnar Myrdal, <citetitle>An American Dilemma</citetitle> (1944) </attribution> <para> 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. </para> </epigraph> <sect1> <title>Day-Care Devil Worshipers</title> <!-- para's, sect2's, epigraph's, and other block elements --> </sect1> <sect1> <!-- more blocks --> </sect1> </chapter>

如该例所示，您需要将一个比较长的章节分为几节 <sect1>。这是有关节有多大的判断问题，但在创建节方面有许多策略。可以使用 <sect1> 到 <sect5> 这种层次结构，也可以使用递归嵌套的 <section> 元素。出于我自己的目的考虑 -- 编写哲学散文 -- 我觉得明确编号的节级别更好一些。对于每种类型的节将会有多重要我有完全不同的感觉，编号那种方式就相当合适。不过，对于例如技术引用这一类事物，节的内容可以嵌套在不同的地方，具有不同的深度。例如，可以在概述中描述函数调用，稍后在章节的编程示例中再次出现。在这种情况下， <section> 元素更适用，嵌套的层次可以多达 5 层。

节比块元素大，它们就是一系列块。在组成部分比较短的情况下，可以立即开始使用块元素。基本上，块元素是段落或与段落处于相同概念／层次结构级别上的元素（例如列表、方程式或插图）。有其它专门的块类型，但这些是最常用的。

唯一比块元素“更小”的是内联元素。一般来说，使用垂直空格、带框架的框或类似的东西来将块对象与其它块分开。与之相反，内联元素延伸到它周围的字，但由不同的字体、颜色、超链接等标记。在我们的章节示例中，铭文就象是一个包含两个块的短节：属性 <attribution> 和铭文 <para>。属性包含 <citetitle>，但该引用往往在打印时以内联形式表示，可能以斜体或下划线格式表示，也可能作为到书目的热链接出现（如果以 HTML 产生）。

下次见
在此略述的元素和结构已经足以让您开始创建自己的 DocBook 文档了。请参考参考资料部分获得有关我所创建的 DocBook 文档的示例，以及更详细的标记文档。下一专栏将演示如何将我们的 DocBook 源文档转换成其它格式，并熟悉可扩展样式表语言转换，这在 DocBook 应用程序以外是很有用的。

参考资料

• IBM alphaWorks 的 Xeena XML 编辑器（90 天免费许可证）提供了 Xeena 的概述、运行需求、FAQ 和可下载副本。可以通过 alphaWorks 获得 Xeena 的 商业转售许可证。
• webreview.com 上的 David Mertz 的 XML Spy 评论是我对 XML Spy 3.0 的评论，并提供了到其它 XML 文章的链接。
• webreview.com 上的 David Mertz 的文本编辑器评论是我对在不同环境中创建 XML 文档所使用的五种文本编辑器的评论。
• David Mertz 以前的“XML 问题”专栏：
• • XML 问题 #1，有关 使用 Python 的 pickle 模块
  • XML 问题 #2，有关 使用 Python 的 xml_objectify 模块
  • XML 问题 #3， 介绍了 DocBook 可以历经时间的文档归档方法
  另请参阅 David 的 2000 年 6 月 有关 XML 模块的“可爱的 Python”专栏和使用 Python 的 XML 开发者相关资源。
• Altova 的 XML Spy 主页（商业 XML 编辑器）描述了 Altova 的 XML Spy 版本的特性，并提供了示例和可下载的副本。
• Scholarly Technology Group 基于 Web 的 XML 确认（可获得源码，并且特许不受限制）可以让您将 XML 文档粘贴到它们的联机格式，并使用完整的 XML 1.0 功能来确认它。
• 可以从 SoftQuad 访问 SoftQuad 的 XMetal 主页（商业 XML 编辑器）。它提供了 XMetal 2.0 的概述、特性描述、FAQ、产品评论，并可以让您下载和购买产品。
• Extensibility 的 XML instance（商业 XML 编辑器）描述了 XML Instance 1.1，并可以让您下载和购买产品。
• Sablotron XSL 处理器（开放源码）提供了该产品的概述和可下载版本。
• 结构化信息标准高级组织 (OASIS) 是有关 SGML、XML 和 DocBook 的中央信息源。
• OASIS 有关 XML 工具的建议书提供了 DocBook 和 XML 的详尽概述，并提供了已知可用于 DocBook 的工具、文档和样本。
• 最好从 DocBook: The Definitive Guide，Norman Walsh & Leonard Muellner, O'Reilly, Cambridge, MA 1999 开始理解有关 DocBook 的更详细信息。或者，仔细查看它的电子版本。
• 可以获得我所转换的一篇晦涩的哲学论文的 HTML 介绍和 XML/DocBook 源码。对于大多数 XML 开发者来说，文本可能不吸引他们，甚至对他们来说没有太多意义。但标记作为示例可能会引起一些兴趣。
• Robert Stayton 的 DocBook/XML DTD 的超文本版本非常有用。我们必须进行一些实践才能了解 DTD 格式，但无论如何，这也是您使用 XML 所需要做的。

关于作者
David Mertz 不再对学术着迷，而成为一个技术记者：发生于其后者必然是其结果。可以通过 mertz@gnosis.cx 与 David 联系，http://gnosis.cx/publish/ 上详细介绍了他的生活。非常欢迎对过去的、这一篇或将来的专栏文章提出意见和建议。