DG2.3. 制作文档

在你制作文档之前,你需要象制作程序本身那样 运行 configure 脚本. 检查运行结尾处的输出,应该看起来象这样:

checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V3.1... yes
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl
如果 onsgmlsnsgmls 都没有找到,那么你就看不到最后四行. 如果没有找到 “DocBook V3.1”,那么就是你没有把 DocBook DTD 工具箱装到 jade 可以找到的地方,或者你没有正确设置 目录文件.参阅上面的安装提示.配置脚本会在一些比较标准的位置 寻找 DocBook 风格表,但如果你把它们放在其它位置,那么你就应该 设置环境变量 DOCBOOKSTYLE 为该位置并且在它后面重新运行 configure

一旦你把所有的东西都设置好了,进入目录 doc/src/sgml 然后运行下面其中一条命令: (记得要用 GNU make.)

其它书是用相似的命令制作的,只要把 admin 换成 developerprogrammertutorial,或者 user 之一就行了. 用 postgres 可以制作所有 5 本书的综合版本, 这样可能更实用,因为浏览器接口可以把在所有文档中移动简化成敲击.

DG2.3.1. HTML

当在 doc/src/sgml 里制作 HTML 文档时,有些生成的文件会可能 (或者相当肯定地)在书之间有名字冲突.因此那些文件不会在 正常版本的相应目录中.相反,属于不同书的文件保存在一个 tar 归档文件里,在安装的时候解包. 要创建一套 HTML 文档包,用下面命令

cd doc/src
gmake tutorial.tar.gz
gmake user.tar.gz
gmake admin.tar.gz
gmake programmer.tar.gz
gmake postgres.tar.gz
gmake install
在发布版本里,这些归档保存在doc 目录 并且缺省时用 gmake install 安装.

DG2.3.2. 手册页

我们用 docbook2man 工具把 DocBookREFENTRY 页面转换成适于做 man page 的 *roff 输出. 这些手册页也是以 tar 归档的形式发布的,与 HTML 版本类似.要创建手册页包,用命令

cd doc/src
gmake man
这些命令最后会在 doc/src 目录生成一个 tar 文件.

手册页的制作会生成一堆让人糊涂的输出,而且要想生成 高质量的结果,必须做些特殊处理.在这个地方我们仍然有 改进的余地.

DG2.3.3. 生成硬拷贝

Postscript 文档的硬拷贝是通过把 SGML 源码转换成 RTF,然后输入到 ApplixWare-4.4.1. 经过一些清理(见后面章节)后把输出"打印"到一个 postscript 文件里面去.

在生成 Postscript 硬拷贝时要注意几个地方。 包括 RTF 修复,ToC (目录)生成,以及分页调整.

Applixware RTF 清理

硬拷贝过程中集成的一部分,jade, 忽略了声明文本主体的缺省风格.以前,这个未经查明的问题 导致目录(ToC)生成的长时间处理.不过,在 ApplixWare 的工作人员的全力帮助下,这个病症被诊断出来并且找到了 绕开的办法.

  1. 键入下面命令生成 RTF 输入:

    % cd doc/src/sgml
    % make tutorial.rtf
          

  2. 修复 RTF 文件,以正确声明所有风格, 尤其是缺省风格.这些域可以用 vi 或者下面简单的 sed 过程处理:

    #!/bin/sh
    # fixrtf.sh
    # Utility to repair slight damage in RTF files generated by jade
    # Thomas Lockhart <[email protected]>
    #
    for i in $* ; do
      mv $i $i.orig
      cat $i.orig | sed 's#\\stylesheet#\\stylesheet{\\s0 Normal;}#' > $i
    done
    
    exit
          
    这里该脚本把 {\s0 Normal;} 作为文档的零级风格.根据 ApplixWare, RTF 标准会禁止增加一种隐含的零级风格, 尽管 M$Word 碰巧可以处理这种情况.

  3. Applix Words 里打开新的文档,然后输入该 RTF 文件.

  4. 用 ApplixWare 生成一个新的 ToC.

    1. 选择现有的 ToC 行,从第一行第一个字符到最后一行最后一个字符.

    2. Tools.BookBuilding.CreateToC 制作一个新的 ToC.选择头三层头用于包含在 ToC里. 这将用本地的 ApplixWare ToC 代替从RTF 里输入进来的行.

    3. 使用 Format.Style 调整 ToC 格式,选择每三种 ToC 风格, 然后为 FirstLeft调整边距.使用下面的值:

      Table DG2-1. 目录的边距格式

      风格 第一边距(英寸) 左边距(英寸)
      TOC-Heading 1 0.6 0.6
      TOC-Heading 2 1.0 1.0
      TOC-Heading 3 1.4 1.4

  5. 对文档进行加工:

    • 调整分页符.

    • 调整表列宽.

    • 向文档中插入图片. 用 Applixware 工具条上的居中调整按钮把每幅图片放到中央.

      注意: 不是所有文档都有图片. 你可以 grep SGML 源文件查找字串 "graphic" 以标出那些有图片的文档. 有几幅图片在不同的文档中有重复.

  6. 用正确的值替换 ToC 里例子和图片部分右对齐的页数. 这些对每个文档只需要花几分钟.

  7. 如果出现了参考文献, 把每条目录的short form(短形式) 的引用删除.Norm Walsh 的 DocBook 风格表好象把这些也打印出来了,而不管它们是不是紧跟在后面的信息的子集.

  8. 把该文档保存为 Applix Words 本地文档格式以便于最后的编辑.

  9. 把该文档以 Postscript 格式 "打印" 到一个文件.

  10. gzip压缩 Postscript 文件.把压缩后的文件放到 doc 目录.

DG2.3.4. 纯文本文件

有好几个文件是以纯文本的模式发布的,主要是为了在安装过程中阅读. INSTALL 文件对应管理员手册 里面相应的章节,只有一点用于不同环境的修改.要创建这个文件,进入 目录 doc/src/sgml 然后敲入 gmake INSTALL. 这样就会创建一个叫 INSTALL.html 的文件, 你可以用 Netscape Navigator 把它 另存为一个文本文件,然后把它拷到现存文件的位置. 好象 Netscape 提供了最高的 HTML 到文本的转换质量.(比 lynxw3m好).

文件 HISTORY 可以用类似方法创建,用的命令是 gmake HISTORY.生成的文本文件中的目录 需要手工删除.

因为文件 src/test/regress/README 更新得 不频繁,所以它的生成不是完全自动化的.在制作完 HTML 版本的管理员手册以后, 用 Netscape把生成的文件 regress.htmregress-platform.htm 转换成纯文本,然后把两个文件粘在一起,最后编辑这个文件把 它们变整洁(也就是说,删除导航条,删除对其它章的引用).