B.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 本书的综合版本, 这样可能更实用,因为浏览器接口可以把在所有文档中移动简化成敲击.

B.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 安装.

B.3.2. 手册页

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

cd doc/src
gmake man

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

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

B.3.3. 生成硬拷贝

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

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

ApplixwareRTF 清理

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

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

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

  2. 修复 RTF 文件,以正确声明所有风格, 尤其是缺省风格.如果文档包含 REFENTRY 段, 那么我们还必须把和前面的段落与当前段落 绑定的格式化暗示替换为当前的段落和后面的段落绑定. 在 doc/src/sgml 里有一个 fixrtf 用于完成这样的修补∶ 这些域可以用 vi 或者下面简单的 sed 过程处理:

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

    % cd doc/src/sgml
    % fixrtf --refentry reference.rtf
           

    该脚本把 {\s0 Normal;} 增加为文档的零级风格.根据Applixware, RTF 标准会禁止增加一种隐含的零级风格, 尽管 M$Word 碰巧可以处理这种情况.为了修复 REFENTRY 段落,该脚本把 \keepn 标记替换为 \keep

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

  4. Applixware生成一个新的 ToC.

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

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

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

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

      风格 第一边距(英寸) 左边距(英寸)
      TOC-Heading 1 0.4 0.4
      TOC-Heading 2 0.8 0.8
      TOC-Heading 3 1.2 1.2

  5. 对文档进行加工:

    • 调整分页符.

    • 调整表列宽.

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

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

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

  7. 如果索引是空的,那么从文档中删除它.

  8. 重新生成并调整目录.

    1. 选择 ToC 字段.

    2. 选择 Tools->Book Building->Create Table of Contents.

    3. 通过选择 Tools->Field Editing->Unprotect 解除 ToC.

    4. 删除 ToC 中的第一行,它是指向 ToC 本身的一条记录.

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

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

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

B.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 转换成纯文本,然后把两个文件粘在一起,最后编辑这个文件把 它们变整洁(也就是说,删除导航条,删除对其它章的引用).