以下工具用于处理文档。其中一些可能是可选的,具体见说明。
这是 DocBook 自身的定义。我们当前使用 4.2 版;不能使用更高或更低的版本。你需要同一版本 DocBook DTD 的SGML和XML变体。它们通常位于不同的软件包中。
DocBook SGML 需要这些实体,但由于它们由 ISO 维护,因此单独分发。
它们包含将 DocBook 源文件转换成其他格式(例如 HTML)的处理指令。
当前要求的最低版本是 1.77.0,但建议使用最新可用版本以获得最佳效果。
这是处理SGML的基础软件包。注意,我们不再需要DSSSL处理器 OpenJade,只需要 OpenSP 软件包将 SGML 转换为 XML。
xmllint这个库及其所含的xmllint工具用于处理 XML。许多开发者可能已经安装了 Libxml2,因为构建 PostgreSQL 代码时也会用到它。不过请注意, xmllint可能需要通过单独的子包安装。
xsltprocxsltproc是一个 XSLT 处理器,也就是使用 XSLT 样式表把 XML 转换成其他格式的程序。
这是一个可将 XML 转换成 PDF 等格式的程序。
我们已经记录了多种安装处理文档所需工具的方法,下面将加以介绍。 这些工具也可能还有其他打包发行形式。请将软件包状态报告到文档邮件列表, 我们会把这些信息补充到这里。
可以不在本地安装 DocBook XML 和 DocBook XSLT 样式表,因为所需文件会从互联网下载并在本地缓存。如果操作系统软件包只提供旧版本(尤其是旧版样式表),或者根本没有这些软件包,这实际上可能是更好的办法。更多信息见xmllint和xsltproc的--nonet选项。
要安装所需软件包,请使用:
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
FreeBSD Documentation Project 本身就大量使用 DocBook,因此 FreeBSD 提供了完整的文档工具“ports”也就不足为奇了。要在 FreeBSD 上构建文档,需要安装以下 ports。
textproc/docbook-sgml
textproc/docbook-xml
textproc/docbook-xsl
textproc/dsssl-docbook-modular
textproc/libxslt
textproc/fop
textproc/opensp
要安装所需软件包,可以使用pkg,命令如下:
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
从doc目录构建文档时,你需要使用gmake, 因为所提供的 makefile 不适用于 FreeBSD 的make。
更多关于 FreeBSD 文档工具的信息,请参阅FreeBSD Documentation Project 的说明。
完整的文档工具软件包也适用于Debian GNU/Linux。只需使用以下命令即可安装:
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
如果使用 MacPorts,以下命令即可完成配置:
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
手动安装 DocBook 工具的过程有些复杂,因此如果有预构建的软件包,就使用它们。这里只描述一种标准配置,使用合理且标准的安装路径,不使用任何“花哨”功能。有关细节,应查阅各软件包的文档,并阅读SGML入门资料。
OpenSP 的安装采用 GNU 风格的./configure; make; make install构建过程。详细信息可在 OpenSP 源码发行包中找到。简要来说:
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install
务必记住“默认目录文件”的存放位置,后面会用到它。也可以不指定,但这样以后每次使用 OpenSP 中的程序时,都必须设置环境变量SGML_CATALOG_FILES,使其指向该文件。(如果 OpenSP 已经安装,而你希望在本地安装工具链的其余部分,也可以采用这种方法。)
创建目录/usr/local/share/sgml/docbook-4.2并切换到该目录。(具体位置无关紧要,但这个位置在本文所采用的布局中是合理的。)
$mkdir /usr/local/share/sgml/docbook-4.2$cd /usr/local/share/sgml/docbook-4.2
解压归档包:
$unzip -a ...../docbook-4.2.zip
(归档包会将文件解压到当前目录。)
编辑文件/usr/local/share/sgml/catalog(或者安装时告诉 jade 的其他位置),并加入类似下面的一行:
CATALOG "docbook-4.2/docbook.cat"
下载ISO 8879 字符实体归档包,将其解压,然后把文件放入存放 DocBook 文件的同一目录:
$cd /usr/local/share/sgml/docbook-4.2$unzip ...../ISOEnts.zip
在包含 DocBook 和 ISO 文件的目录中运行以下命令:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(这会修正 DocBook 目录文件中使用的名称与 ISO 字符实体文件的实际名称之间的混淆。)
configure检测 #在构建文档之前,需要运行configure脚本,就像构建PostgreSQL程序本身时一样。检查运行即将结束时的输出,它应该类似于:
checking for onsgmls... onsgmls
checking for DocBook V4.2... yes
checking for dbtoepub... dbtoepub
checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for osx... osx
checking for fop... fop
如果onsgmls和nsgmls都没有找到,后续一些测试会被跳过。nsgmls是 OpenSP 软件包的一部分。如果没有自动找到这些程序,可以向 configure 传递环境变量NSGMLS以指明它们的位置。如果没有找到“DocBook V4.2”,则说明 DocBook DTD 工具包没有安装到 OpenSP 能找到的位置,或者目录文件没有正确设置。请参阅上面的安装提示。