工具集

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

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

Linux RPM 安装

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

    安装 Norm Walsh 的最新风格表。取决于 RPM 的新旧,最新的风格表可能比 RPM 里包含的要改进了一些。

    更新你的 src/Makefile.custom 以包含指向风格表的 HSTYLE 和 PSTYLE 定义。

FreeBSD 安装

在 FreeBSD 上有一整套用于文档工具的移植(ports)。实际上,postgresql.org,其自身的文档每天晚上自动更新,就是一台 FreeBSD 机器。
 
安装 FreeBSD 移植
     
    要在 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
    设置环境变量以访问 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 做调整)。

    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 包

    安装 jade,docbook,和 unzip:
    apt-get install jade
    apt-get install docbook
    apt-get install docbook-stylesheets
    安装最新的风格表。
      确认已经安装了 unzip,或者安装包:
      apt-get install unzip
      从 http://www.nwalsh.com/docbook/dsssl 抓取最新的风格表并且解压缩到一个位置(可能是 /usr/share)。
    编辑 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 是写作的时候最新的版本)
重要的 URL:

安装 Jade

安装 Jade
    阅读上面 URL 列出的安装指导.

    在一个合适的位置 Unzip (解压缩)发布包.做这些的命令看起来象

    unzip -aU jade1_1.zip
    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 里.

    键入 make 制作 Jade 和各种各样 SP 工具.

    一旦完成软件的制作,make install 将完成安装.

安装 DocBook DTD 工具

安装 DocBookDTD 工具
你需要把制作 DocBookDTD 工具的文件放到你制作 Jade 的目录里,如果你按照我们上面建议的话,应该是 /usr/local/share/sgml/。除了 DocBook 文件以外,你还需要有一个就位的 catalog 文件,用于文档类型声明和该目录里实际文件的外部实体参考.你还要有 ISO字符集映射以及可能还需要一个或更多个版本的HTML.
     
    安装多种多样的 DTD 和支持文件的一种方法是设置 catalog 文件,就是收集所有的文件到上面提到的目录里,用一个叫 CATALOG 的文件描述所有这些文件,然后创建文件 catalog 作为指向前者的目录指针 -- 往里面输入下面一行内容:
    CATALOG /usr/local/share/sgml/CATALOG
    文件 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
    当然,一个包含这些的文件和 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 风格表
    阅读上面 URL 列出的安装指导.

    安装 Norman 的风格表,只需要在合适的位置简单的解压缩发布的工具.一个处理这些事情的合适的位置是 /usr/local/share,把工具放到在 /usr/local/share/docbook 目录树下的目录里.处理这些的命令看起来将象

    unzip -aU db119.zip
    测试安装成功与否的一个方法是制作 PostgreSQL用户手册的HTML 和 RTF 形式.
     
      制作 HTML 文件,进入 SGML 源文件目录,doc/src/sgml,键入
      jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
      book1.htm 是输出的顶级节点。

      生成 RTF 输出,为你常用的字处理系统和打印系统做准备,键入:

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

安装 PSGML

安装 PSGML
    阅读上面 URL 列出的安装指导.

    解开发布的压缩文件,运行 configure,make 和 make install 把 byte-compiled(字节编译)文件和信息库就位.

    然后往你的 /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)
    如果你在编辑 HTML 时也需要使用 PSGML,再加一行:
    (setq auto-mode-alist
          (cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
    有一个关于 PSGML 的很重要的问题:它的作者假设你的主 SGMLDTD 目录是 /usr/local/lib/sgml.如果如我们本章例子所说,你用的是 /usr/local/share/sgml,你必须为此做些补偿.
      你可以设置 SGML_CATALOG_FILES 环境变量.
      你可以定制你的 PSGML 安装(其手册告诉你如何做).

      你甚至可以在编译和安装 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 可以编译为大的数据结构尺寸.这些的细节问题根据你的安装不同而异。
�