©
Ce document utilise Manuel du site Web PHP chinois Libérer
下面的工具用于处理此文档。有些可能是可选的,在文中标注了。
这是 DocBook 本身的定义。目前使用版本 4.2 ;你不能使用 更新或者早些的版本。 你需要SGML,其为DocBook DTD的变体,但是构建手册页还需要同版本的XML变体。
这是 DocBook 需要的,但是独立发布,因为它们是由 ISO 维护的。
These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.
这是另一个将DocBook转化为其它格式的样式表。我们当前使用这来制作手册页和可选的HTM帮助。 你也可以使用这个工具生成HTML或PDF输出,但是官方PostgreSQL发布使用DSSSL样式表做这些事。
这是处理 SGML 的基本包。它包含一个 SGML 分析器,一个 DSSSL (使用 DSSSL 风格表把 SGML 转换成其它格式的程序),还有一系列相关工具。现在 Jade 由 OpenJade 组维护, 而不再是 James Clark 了。
这是个使用XSLT样式表的处理工具。(像jade是对DSSSL样式表的处理工具)
如果你需要,你还可以安装 JadeTeX 把 TeX 用做 Jade 的一种格式化后端。JadeTeX 可以生成 Postscript 或者 PDF 文件(后者带书签)。
不过,JadeTeX 的输出比 RTF 后端稍差一点的打印输出。主要是表的 格式和各种竖直和水平的空白效果。而且,你还没有机会手工润色 输出结果。不过,它运行得很好,尤其是那些不用表格的简单些的文档。
我们已经在文档中记录了几种安装处理此文档所需的各种工具的方法。 它们在下面描述。也可能有其它包发布这些工具。请向 doc 邮件列表报告那些包的状态,就会在这里包括那些信息。
许多供应商在它们的版本里提供了一整套处理 DocBook 的 RPM 包, 请检查一下"SGML"选项,或者下列包之一: sgml-common, docbook, stylesheets, openjade (或 jade)。可能还需要 sgml-tools 。如果你的版本没有提供这些东西, 那么你应该可以使用来自一些其它合理兼容的发行商的包。
FreeBSD 文档计划本身就非常频繁地使用 DocBook ,所以在 FreeBSD 里有一整套可以用的文档工具的"ports" 就一点也不奇怪了。要在 FreeBSD 里制作文档,你必须安装下面的 port。
textproc/sp
textproc/openjade
textproc/iso8879
textproc/dsssl-docbook-modular
textproc/docbook-420
很多东西来自 /usr/ports/print (tex, jadetex) 你也可能会感兴趣。
这些 port 很可能不会更新位于 /usr/local/share/sgml/catalog.ports 的 主目录文件或命令是不正确的。务必在文件的开头有以下几行: 确保你有下面这行:
CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog"
如果你不想编辑文件,还可以把环境变量 SGML_CATALOG_FILES 设置为一个冒号分隔的目录 文件列表(比如上面那样的)。
你可以在 FreeBSD Documentation Project's instructions 里找到更多有关 FreeBSD 文档工具的信息。
Debian GNU/Linux 里面也有一整 套可以用的文档工具的包。安装时, 只需要用下面的命令:
apt-get install docbook docbook-dsssl docbook-xsl openjade xsltproc
DocBook 工具的手工安装过程有些复杂,因此如果你有预先制作好的包, 最好还是用它们。在这里只描述一个标准的安装,而且安装到标准的 路径里,并且没有"fancy"的特性。相关的更多的细节, 你应该学习相关包的文档,并且阅读 SGML介绍性材料。
OpenJade 提供了一个 GNU 风格的 ./configure; make; make install 制作过程。 你可以在 OpenJade 源程序包里找到详细内容。在 shell 里:
./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install
确保你记住这里设置"default catalog"的位置, 后面将需要它。也可以不用注明这句话,但是稍后使用 jade 的时候, 你就不得不把环境变量 SGML_CATALOG_FILES 设置为指向该文件的位置。如果 OpenJade 已经安装, 并且你想在本地安装其它工具的时候,这也是个可选的方法。
另外,你应该从 dsssl 目录里把 dsssl.dtd, fot.dtd, style-sheet.dtd, 和 catalog 文件安装上, 可能是安装到 /usr/local/share/sgml/dsssl 吧。最简单的可能就是复制整个目录:
cp -R dsssl /usr/local/share/sgml
最后,创建文件 /usr/local/share/sgml/catalog 并且把下面行加入其中:
CATALOG "dsssl/catalog"
这是一个相对路径引用安装文件在step 2。 如果你选择不同的安装布局,请你务必调整它。
下载 DocBook V4.2 distribution。
创建目录/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 character entities archive, 解压,然后把文件放到 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 字符实体文件的名字混淆了。
要安装样式表,解开发布的工具包,然后把它挪到一个合适的地方。 (比如 /usr/local/share/sgml)。归档会自动创建子目录)
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
你也可以在 /usr/local/share/sgml/catalog 里制作常用的目录条目:
CATALOG "docbook-dsssl-1.xx/catalog"
因为样式表变化频繁,因此有时候多实验几个版本也挺好, PostgreSQL 并不使用这个表项。 参阅章Section I.2.5获取有 关如何选择样式表的信息。
要安装和使用 JadeTeX ,就需要一套能用的 TeX 和 LaTeX2e , 包括支持的 tools 和 graphics 包 Babel, AMS 字体 和 AMS-LaTeX, PSNFSS 扩展 和 工具箱 "35个字体", dvips 用于生成 PostScript, 宏包 fancyhdr, hyperref, minitoc, url 和 ot2enc。 所有这些你都可以在你最近的 CTAN 网站 镜像站点找到。 基本 TeX 系统的安装远远超出了这份介绍的范围。 你应该可以在任何可以运行 TeX 的系统上找到二进制包。
在你开始使用 JadeTeX 处理 PostgreSQL 文档之前,你需要增大 TeX 的内部数据结构的大小。 关于这些事情的细节可以在 JadeTeX 的安装指导里找到。
一旦完成了这些你就可以安装 JadeTeX 了:
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
最后两步需要以 root 身份处理。
在你制作文档之前,你需要像制作程序本身那样运行 configure 脚本。检查运行结尾处的输出,应该看起来像这样:
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular checking for collateindex.pl... /usr/bin/collateindex.pl checking for xsltproc... xsltproc checking for osx... osx
如果 onsgmls 和 nsgmls 都没有找到,那么你就看不到最后四行。nsgmls 是 JADE 包的一部分。可以通过传递环境变量 JADE 和 NSGMLS 给 configure 来指定这些程序的位置。如果没有找到"DocBook V4.2", 那么就是你没有把 DocBook DTD 工具箱装到 jade 可以找到的地方, 或者你没有正确设置目录文件。参阅上面的安装提示。 配置脚本会在一些比较标准的位置寻找 DocBook 样式表, 但如果你把它们放在其它位置,那么就应该设置环境变量 DOCBOOKSTYLE 为该位置并且重新运行 configure 脚本。