用 DITA Open Toolkit 实现简易命令行处理

Document Information Typing Architecture(DITA)是一套用于面向主题的写作的 XML 文档类型。如果您希望定制 DITA DTD 或模式来适应内容的结构,也可以使用 DITA 提供的机制创建这些文档类型的特殊版本。与许多标准一样,必须符合 DITA,才能使用围绕这个标准构建的商业软件和免费软件。

最流行的免费 DITA 软件是 DITA Open Toolkit(或称为 “DITA OT”),这是一种用来处理 DITA 文件的基于 Java 的环境。安装它之后,它可以接受 DITA XML 文档(甚至是符合您定制的 DITA 模式的文档)并创建 HTML、PDF、RTF、troff 、Eclipse Help 和其他格式的版本。

在初次安装它时,我运行了 “Verifying the installation” 下面的安装说明所描述的构建演示(参见 参考资料)。我看到了它能够从 DITA 示例源文件创建的所有输出格式,感到印象深刻。但是不得不承认,我随后觉得有点儿灰心 — 构建演示是由一个 Ant 脚本驱动的,这个脚本的长度超过 800 行并包含另一个 Ant 构建文件,那个文件又包含十几个文件。我的 Ant 技能实在有限,所以根本不知道如何编写脚本来将我的 DITA 文档转换为 XHTML 或 PDF。

最后,我发现只需使用一行命令指示 DITA OT 将特定的 DITA 文档转换为它的任何输出格式,甚至不需要查看 Ant 脚本。

DITA Open Toolkit 自动执行的操作

如果让 XSLT 处理程序(比如 Xalan 或 Saxon)“在 DITA 文档 mydoc.xml 上运行 DITA OT 样式表 whatever.xsl”,不一定会有效果。必须设置几个环境变量并指定其他关系,这样 DITA OT 的各个部分才能正确地配合工作。在使用定制的模式时,这尤其重要。假设您的 recipe 文档类型中的 ingredient 元素是 DITA prereq 元素的定制版本,希望让 DITA OT 创建 recipe 文档的 HTML 版本。如果 DITA OT 无法找到专门针对 ingredients 元素的任何处理,就需要查询是否应该在 ingredients 元素上使用 prereq 处理。

在构建演示所用的 Ant 脚本中,有许多代码用来完成这个设置,需要使用 Ant 脚本将 DITA OT 转换自动化。对于没有时间提高 Ant 技能的 Ant 新手来说,好消息是也可以自动创建 Ant 构建文件。如果把要转换的 DITA 源文件和所需的输出格式告诉 DITA OT 的 dost.jar 文件,它就会完成余下的工作。

使用 dost.jar 文件

与大多数良好的 jar 文件一样,如果用 -jar 选项和 jar 文件名启动 Java 环境,不带其他参数,就会看到 dost.jar 可用的参数列表。它有大约 30 个参数,据说其中只有两个是必需的,但是我发现可以只使用一个参数:输入文件的名称。当在 DITA OT 的主目录中执行以下命令行时,工具包会在默认的 out 子目录中创建 currywurst.xml 的 XHTML 版本:java -jar lib/dost.jar /i:C:/temp/currywurst.xml因为软件文档指出 /i 输入文件参数和 /transtype 转换类型参数都是必需的,所以 XHTML 不一定总是后一个参数的默认值。

如果为这个参数提供其他值,就会出现真正有意思的现象,比如:

java -jar lib/dost.jar /i:C:/temp/currywurst.xml /transtype:pdf

这会根据 DITA 输入文件创建一个 XSL-FO 文件。如果安装了 Apache FOP 并按照 DITA Open Toolkit 安装文档的描述正确地设置了变量,它就会创建 PDF 文件 — 这些操作都只需要一个相当简短的命令行。

我不想重复文档中关于每个命令行选项的信息,但是要告诉您对于全面理解选项非常重要的一些情况:尽管没有哪个 DITA Open Toolkit 文档页面全面解释了所有 DITA OT 命令行选项,但是有两个页面提供的信息加在一起就比较完整了。“Processing from the Java command line” (参见 参考资料)列出了 /i 和 /transtype 等命令行参数和等效的 Ant 脚本参数,“Ant processing parameters”(参见 参考资料)描述了脚本参数的作用及其默认值。

没有 /transtype 有效值的完整列表。但是,如果为 /transtype 提供无效的值,dost.jar 就会显示有效值的列表:

如果设置一个使用 DITA Open Toolkit 的复杂的大型生产环境,那么使用 Ant 提供的所有功能管理复杂性是有意义的。在使用 DITA OT 时必须安装它,所以对于大型项目,有必要学习 Ant 并根据 DITA OT 包含的 Ant 脚本构建一些脚本。但是,如果只是想试试 DITA OT,那么 dost.jar 提供了一种体验所有 DITA OT 特性的好方法。只需在命令行上输入简单的命令,就会看到每个参数的效果。这很有趣!