工具集

安装处理文档需要的工具的经验已经文档化了，总共有三种方法。一种是在 Linux 上从 RPM 里安装，第二种是从 FreeBSD 的 port（移植）里安装，最后一种是从独立的工具的最初发布里安装。这些方法将在下面描述。

可能还有一些这些工具的其他发布包．请向文档邮件列表报告包状态，我们将在这里包含那些信息．

Linux RPM 安装

使用 Cygnus 的 Mark Galassi 开发的 RPM 集是对于一个 RedHat 兼容的 Linux 系统最简单的安装方式。也可以通过源代码安装，我们随后的章节将要介绍。

安装 RPM

1. 为 Jade 和相关包安装 RPM。
2. 安装 Norm Walsh 的最新风格表。取决于 RPM 的新旧，最新的风格表可能比 RPM 里包含的要改进了一些。
3. 更新你的 src/Makefile.custom 以包含指向风格表的 HSTYLE 和 PSTYLE 定义。

FreeBSD 安装

在 FreeBSD 上有一整套用于文档工具的移植（ports）。实际上，postgresql.org，其自身的文档每天晚上自动更新，就是一台 FreeBSD 机器。

安装 FreeBSD 移植

1. 要在 FreeBSD 上面制作文档，我们需要安装许多移植包（ports）。

   % cd /usr/ports/devel/gmake && make install
   % cd /usr/ports/textproc/docproj && make install
   % cd /usr/ports/textproc/docbook && make install
   % cd /usr/ports/textproc/dsssl-docbook-modular && make install
         

2. 设置环境变量以访问 jade 工具集。

   注意：这些对于 postgresql.org 那台 FreeBSD 机器是不需要的，因此你也可能不需要做这些事情。

   export SMGL_ROOT=/usr/local/share/sgml                                          
   SGML_CATALOG_FILES=/usr/local/share/sgml/jade/catalog                           
   SGML_CATALOG_FILES=/usr/local/share/sgml/html/catalog:$SGML_CATALOG_FILES       
   SGML_CATALOG_FILES=/usr/local/share/sgml/iso8879/catalog:$SGML_CATALOG_FILES    
   SGML_CATALOG_FILES=/usr/local/share/sgml/transpec/catalog:$SGML_CATALOG_FILES   
   SGML_CATALOG_FILES=/usr/local/share/sgml/docbook/catalog:$SGML_CATALOG_FILES    
   export SGML_CATALOG_FILES
         

   （这是 sh/bash 语法；根据实情为 csh/tcsh 做调整）。

3. Make 需要一些特殊的参数，或者你要把这些加入你的 Makefile.custom 里：

   HSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/html/ 
   PSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/print/
         

   当然，你要用 gmake 而不只是简单的 'make' 来制作。

Debian 安装

Debian 里也有一整套文档工具包。

安装 Debian 包

1. 安装 jade，docbook，和 unzip：

   apt-get install jade
   apt-get install docbook
   apt-get install docbook-stylesheets
         

2. 安装最新的风格表。
   1. 确认已经安装了 unzip，或者安装包：

      apt-get install unzip
      	

   2. 从 http://www.nwalsh.com/docbook/dsssl 抓取最新的风格表并且解压缩到一个位置（可能是 /usr/share）。
3. 编辑 src/Makefile.custom，增加合适的 HSTYLE 和 PSTYLE 定义：

   HSTYLE= /usr/share/docbook/html
   PSTYLE= /usr/share/docbook/print
         

手工安装这些工具

下面是你获取和安装用 Emacs 编辑 DocBook 源文件然后用 Norman Walsh 的 DSSSL 风格表处理并创建 HTML 和 RTF 文件所需要工具的一个简介．

获取 SGML 和 DocBook 工具的最简单方法可能是从 sgmltools 获取 sgmltools。sgmltools 需要 GNU 版本的 m4。要核实你拥有正确的 m4 版本，键入

gnum4 --version
    

如果你安装 GNU m4，把它装成名为 gnum4，这样 sgmltools 将能找到它。在安装过后，你将有 sgmltools，jade 和 Norm Walsh 的 DocBook 风格表。下面的步骤是分别用于安装这些工具的。

前提

你需要的东西：

• 一个可用的 GCC 2.7.2
• 一个可用的 Emacs 19.19 或更新版本
• 一个用于 UNIX 的 unzip 程序, 用以解包

你需要获取的：

• James Clark 的 Jade （在文件 jade1_1.zip 里的版本 1.1 是写作的时候最新的版本）
• DocBook 版本 3.0
• Norman Walsh 的 Modular Stylesheets （最初用于制作这些文档的是版本 1.19）
• Lennart Staflin 的 PSGML （写作的时候可用的最新版本是 psgml-1.0.1.tar.gz 里的 1.0.1）

重要的 URL：

• The Jade web page
• The DocBook web page
• The Modular Stylesheets web page
• The PSGML web page
• Steve Pepper's Whirlwind Guide
• Robin Cover's database of SGML software

安装 Jade

安装 Jade

1. 阅读上面 URL 列出的安装指导．
2. 在一个合适的位置 Unzip （解压缩）发布包．做这些的命令看起来象

   unzip -aU jade1_1.zip
          

3. Jade 不是用 GNU Autoconf 制作的，所以你需要自己编辑 Makefile。因为 James Clark 把他的工具做得很容易处理这些事情，所以你最好在  Jade 发布的主目录下建立一个制作目录（也许用你的机器的体系命名），把主目录的 Makefile 拷贝到这个位置，在这里编辑之，然后在该目录下运行 make。

   不过，可以不编辑 Makefile．在主目录里有一个文件名为 Makefile.jade，其作用是制作 Jade（相对于只是制作 Jade 倚赖的 SGML 分析器工具 SP）时可以用 make -f Makefile.jade．不过我们建议不要这样做，因为这样你需要修改比 Makefile.jade 里更多的东西，所以不管怎样你都要编辑其中之一（译注：Makefile Makefile.jade）。

   编辑 Makefile，阅读 James 的指导并且修改你需要修改的地方．有许多变量需要设置．下面是最重要的一些，以及它们的典型的值：

   prefix = /usr/local
   XDEFINES = -DSGML_CATALOG_FILES_DEFAULT=\"/usr/local/share/sgml/catalog\"
   XLIBS = -lm
   RANLIB = ranlib
   srcdir = ..
   XLIBDIRS = grove spgrove style
   XPROGDIRS = jade
          

   注意 SGML 支持文件缺省路径的声明－－你可能需要针对你自己的安装做一些改动．如果你的系统不需要上面那些关于数学库和 ranlib 命令的设置，仅仅把它们留在 Makefile 里．

4. 键入 make 制作 Jade 和各种各样 SP 工具．
5. 一旦完成软件的制作，make install 将完成安装．

安装 DocBook DTD 工具

安装 DocBook DTD 工具

1. 你需要把制作 DocBook DTD 工具的文件放到你制作 Jade 的目录里，如果你按照我们上面建议的话，应该是 /usr/local/share/sgml/。除了 DocBook 文件以外，你还需要有一个就位的 catalog 文件，用于文档类型声明和该目录里实际文件的外部实体参考．你还要有 ISO字符集映射以及可能还需要一个或更多个版本的 HTML．

   安装多种多样的 DTD 和支持文件的一种方法是设置 catalog 文件，就是收集所有的文件到上面提到的目录里，用一个叫 CATALOG 的文件描述所有这些文件，然后创建文件 catalog 作为指向前者的目录指针 －－ 往里面输入下面一行内容：

   CATALOG /usr/local/share/sgml/CATALOG
          

2. 文件 CATALOG 应该包含三种类型的行．第一种是（可选的）SGML 声明，这样：

   SGMLDECL docbook.dcl
          

   下一种，必须解释各种各样的 DTD 的参考和实体文件．对于 DocBook 文件，这些看起来象下面几行：

   PUBLIC "-//Davenport//DTD DocBook V3.0//EN" docbook.dtd
   PUBLIC "-//USA-DOD//DTD Table Model 951010//EN" cals-tbl.dtd
   PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
   PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
   PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
          

3. 当然，一个包含这些的文件和 DocBook工具一起发布．注意这些行的最后一项都是文件名，这里给出的没有路径．你可以把这些文件放到你的 SGML 目录的子目录里，当然还要修改 CATALOG 文件里的引用．DocBook 还引用了 ISO字符集实体，所以你还要获取和安装这些东西（它们可以通过几种不同途径获取，并且可以在上面列出的 URL 里很容易的找到），以及所有这些东西的目录实体，类似：

   PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" ISO/ISOlat1
          

   注意这里文件名是如何包含一个目录名的，这里显示了我们把 ISO 实体文件放到了一个名为 ISO 的子目录．同样，正确的目录入口应该对应你获取的工具实体．

安装 Norman Walsh 的 DSSSL 风格表

安装 Norman Walsh 的 DSSSL 风格表

1. 阅读上面 URL 列出的安装指导．
2. 安装 Norman 的风格表，只需要在合适的位置简单的解压缩发布的工具．一个处理这些事情的合适的位置是 /usr/local/share，把工具放到在 /usr/local/share/docbook 目录树下的目录里．处理这些的命令看起来将象

   unzip -aU db119.zip
          

3. 测试安装成功与否的一个方法是制作 PostgreSQL 用户手册的HTML 和 RTF 形式．
   1. 制作 HTML 文件，进入 SGML 源文件目录，doc/src/sgml，键入

      jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
      	 

      book1.htm 是输出的顶级节点。

   2. 生成 RTF 输出，为你常用的字处理系统和打印系统做准备，键入：

      jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
      	 

安装 PSGML

安装 PSGML

1. 阅读上面 URL 列出的安装指导．
2. 解开发布的压缩文件，运行 configure，make 和 make install 把 byte-compiled（字节编译）文件和信息库就位．

3. 然后往你的 /usr/local/share/emacs/site-lisp/site-start.el 文件里增加下面行让你的 Emacs 在需要时正确装载 PSGML：

   (setq load-path
         (cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
   (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
          

4. 如果你在编辑 HTML 时也需要使用 PSGML，再加一行：

   (setq auto-mode-alist
         (cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
          

5. 有一个关于 PSGML 的很重要的问题：它的作者假设你的主 SGML DTD 目录是 /usr/local/lib/sgml．如果如我们本章例子所说，你用的是 /usr/local/share/sgml，你必须为此做些补偿．
   1. 你可以设置 SGML_CATALOG_FILES 环境变量．
   2. 你可以定制你的 PSGML 安装（其手册告诉你如何做）．
   3. 你甚至可以在编译和安装 PSGML 前编辑源文件 psgml.el，把写死的路径硬代码改成你自己的缺省值．

安装 JadeTeX

如果你需要的话，你还可以安装 JadeTeX 以便于用 TeX 作为 Jade 的格式化后端．注意这个软件还不很成熟，将会生成比你从 RTF 后端得到的差得多的打印输出．不过，它还是工作的很好的，尤其是不用表的简单文档，并且 JadeTeX 和风格表都在不断的改进中，显然以后它会变得更好．

要安装和使用JadeTeX，你需要有一个可用的TeX 和 LaTeX2e 安装，包括支持的工具（tools）和图形（graphics）包，Babel，AMS 字体 和 AMS-LaTeX，PSNFSS －－"35种字体" （"the 35 fonts"）的扩展和伴侣工具，用于生成 PostScript 的 dvips 程序，宏包 fancyhdr，hyperref，minitoc，url 和 ot2enc，当然还有 JadeTeX 本身．所有这些可以在离你最近的 CTAN 站点找到．

JadeTeX 到写作时为止还没有随着一些发布带有安装向导，但是有一个 makefile 显示了需要的东西．它还包括一个目录 cooked，在这里你会发现一些你需要的宏软件包，但不是全部，并且也不完整－－至少我们最后一次看到的是这样的．

在制作 jadetex.fmt 格式文件之前，你可能需要编辑 jadetex.ltx 文件，以便更改 Babel 的配置以适合你的路径．要修改的行看起来象

\RequirePackage[german,french,english]{babel}[1997/01/23]
     

并且很显然你应该只列出你实际上需要的语言，然后把 Babel 配置成那样．

在 JadeTeX 能工作后，你应该可以用下面命令为PostgreSQL手册生成和格式化TeX输出（象上面，在 doc/src/sgml 目录里面）

jade -t tex -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
jadetex postgres.tex
jadetex postgres.tex
dvips postgres.dvi
     

当然，你做这些的时候，TeX会在第二次运行时停下来，并且告诉你超出其容量了．据我们所知，这是由于 JadeTeX 生成交叉引用信息造成的．当然 TeX 可以编译为大的数据结构尺寸．这些的细节问题根据你的安装不同而异。

（译注：我在7.0也要开始用这些东西了，原来怎么没注意呢？:(）