下面的工具用于处理此文档。如标注所示,有些工具可能是可选的。
这是 DocBook 本身的定义。我们目前使用版本 4.2;你不能使用更新或者更早的版本。 你需要相同版本 DocBook DTD 的SGML和XML变体。 这些通常在单独的包中。
这是 DocBook SGML需要的,但是被独立发布,因为它们由 ISO 维护。
这些包含了将 DocBook 源码转换到其他格式(如HTML)所要用的处理指令。
目前所需的最低版本为1.77.0,但建议使用最新版本以获得最佳效果。
这是SGML处理的基础包。请注意,我们不再需要OpenJade、 DSSSL处理器,只有将SGML转换为XML的OpenSP包。
xmllint
的Libxml2 这个库和它所包含的xmllint
工具被用来处理 XML。
很多开发者将已经安装了Libxml2,因为在编译
PostgreSQL 代码时就已经用到它了。不过要注意,可能需要从一个独立的包中
安装xmllint
。
xsltproc
的Libxslt xsltproc
是一个XSLT处理器,
也就是使用XSLT样式表将XML转换为其他格式的程序。
这是一个将XML等转换为PDF的程序。
我们已经在文档中记录了几种安装处理此文档所需的各种工具的方法。它们将在下文中描述。也可能有这些工具的其他打包发布。请向文档邮件列表报告那些包的状态,我们就会在这里包括它们的信息。
您可以避免在本地安装DocBook XML和DocBook XSLT样式表,
因为所需文件将从网络下载并在本地缓存。事实上,
如果您的操作系统软件包仅提供旧版本,尤其是样式表,或者根本没有可用软件包,
则这可能是首选解决方案。有关更多信息,请参阅xmllint
和xsltproc
的--nonet
选项。
要安装所需的包,可使用:
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
FreeBSD 文档计划本身就是 DocBook 的重度使用者,所以在 FreeBSD 中有一整套文档工具的“移植”可用也就不足为奇。要在 FreeBSD 中编译文档,你必须安装下面的移植。
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 文档工具的信息。
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 源代码包里找到详细内容。在一个 nutshell 中:
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install
确保记住你放置“default catalog”的位置,后面将需要它。
你也可以不用在意这一点,但是后面任何时候使用来自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 能找到它的地方,
或者你还没有正确地设置目录文件。见上文的安装提示。