在你制作文档之前,你需要象制作程序本身那样 运行 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如果 onsgmls 和 nsgmls 都没有找到,那么你就看不到最后四行. 如果没有找到 “DocBook V3.1”,那么就是你没有把 DocBook DTD 工具箱装到 jade 可以找到的地方,或者你没有正确设置 目录文件.参阅上面的安装提示.配置脚本会在一些比较标准的位置 寻找 DocBook 风格表,但如果你把它们放在其它位置,那么你就应该 设置环境变量 DOCBOOKSTYLE 为该位置并且在它后面重新运行 configure.
一旦你把所有的东西都设置好了,进入目录 doc/src/sgml 然后运行下面其中一条命令: (记得要用 GNU make.)
要制作 HTML 版本的 管理员手册:
doc/src/sgml$ gmake admin.html
同样手册的 RTF 版本:
doc/src/sgml$ gmake admin.rtf
通过JadeTeX 获取一份 DVI 版本:
doc/src/sgml$ gmake admin.dvi
然后从 DVI 得到 Postscript:
doc/src/sgml$ gmake admin.ps
注意: 官方的 Postscript 格式是用不同方法获取的. 参阅下面的 Section DG2.3.3.
当在 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 安装.
我们用 docbook2man 工具把 DocBook 的 REFENTRY 页面转换成适于做 man page 的 *roff 输出. 这些手册页也是以 tar 归档的形式发布的,与 HTML 版本类似.要创建手册页包,用命令
cd doc/src gmake man这些命令最后会在 doc/src 目录生成一个 tar 文件.
手册页的制作会生成一堆让人糊涂的输出,而且要想生成 高质量的结果,必须做些特殊处理.在这个地方我们仍然有 改进的余地.
Postscript 文档的硬拷贝是通过把 SGML 源码转换成 RTF,然后输入到 ApplixWare-4.4.1. 经过一些清理(见后面章节)后把输出"打印"到一个 postscript 文件里面去.
在生成 Postscript 硬拷贝时要注意几个地方。 包括 RTF 修复,ToC (目录)生成,以及分页调整.
Applixware RTF 清理
硬拷贝过程中集成的一部分,jade, 忽略了声明文本主体的缺省风格.以前,这个未经查明的问题 导致目录(ToC)生成的长时间处理.不过,在 ApplixWare 的工作人员的全力帮助下,这个病症被诊断出来并且找到了 绕开的办法.
键入下面命令生成 RTF 输入:
% cd doc/src/sgml % make tutorial.rtf
修复 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 碰巧可以处理这种情况.
在 Applix Words 里打开新的文档,然后输入该 RTF 文件.
用 ApplixWare 生成一个新的 ToC.
选择现有的 ToC 行,从第一行第一个字符到最后一行最后一个字符.
用 Tools.BookBuilding.CreateToC 制作一个新的 ToC.选择头三层头用于包含在 ToC里. 这将用本地的 ApplixWare ToC 代替从RTF 里输入进来的行.
使用 Format.Style 调整 ToC 格式,选择每三种 ToC 风格, 然后为 First 和 Left调整边距.使用下面的值:
Table DG2-1. 目录的边距格式
风格 | 第一边距(英寸) | 左边距(英寸) |
---|---|---|
TOC-Heading 1 | 0.6 | 0.6 |
TOC-Heading 2 | 1.0 | 1.0 |
TOC-Heading 3 | 1.4 | 1.4 |
对文档进行加工:
调整分页符.
调整表列宽.
向文档中插入图片. 用 Applixware 工具条上的居中调整按钮把每幅图片放到中央.
注意: 不是所有文档都有图片. 你可以 grep SGML 源文件查找字串 "graphic" 以标出那些有图片的文档. 有几幅图片在不同的文档中有重复.
用正确的值替换 ToC 里例子和图片部分右对齐的页数. 这些对每个文档只需要花几分钟.
如果出现了参考文献, 把每条目录的short form(短形式) 的引用删除.Norm Walsh 的 DocBook 风格表好象把这些也打印出来了,而不管它们是不是紧跟在后面的信息的子集.
把该文档保存为 Applix Words 本地文档格式以便于最后的编辑.
把该文档以 Postscript 格式 "打印" 到一个文件.
用gzip压缩 Postscript 文件.把压缩后的文件放到 doc 目录.
有好几个文件是以纯文本的模式发布的,主要是为了在安装过程中阅读. INSTALL 文件对应管理员手册 里面相应的章节,只有一点用于不同环境的修改.要创建这个文件,进入 目录 doc/src/sgml 然后敲入 gmake INSTALL. 这样就会创建一个叫 INSTALL.html 的文件, 你可以用 Netscape Navigator 把它 另存为一个文本文件,然后把它拷到现存文件的位置. 好象 Netscape 提供了最高的 HTML 到文本的转换质量.(比 lynx 和 w3m好).
文件 HISTORY 可以用类似方法创建,用的命令是 gmake HISTORY.生成的文本文件中的目录 需要手工删除.
因为文件 src/test/regress/README 更新得 不频繁,所以它的生成不是完全自动化的.在制作完 HTML 版本的管理员手册以后, 用 Netscape把生成的文件 regress.htm 和 regress-platform.htm 转换成纯文本,然后把两个文件粘在一起,最后编辑这个文件把 它们变整洁(也就是说,删除导航条,删除对其它章的引用).