除了基本系统和 Ports 套件之外, 文档也是 FreeBSD 操作系统的一个组成部分。 尽管您总是可以通过 FreeBSD 网站 来访问最新的 FreeBSD 文档, 一些用户的网络连接可能很慢, 甚至完全没有网络连接。 幸运的是, 有很多方法可以用来更新随发行版本附带的 FreeBSD 文档的本地副本。
FreeBSD 文档的源代码和安装版本都可以通过 CVSup 来以与基本系统 (参考 第 24.7 节) 类似的方法来升级。 这一节中将会介绍:
如何安装联编文档所需的工具集, 用于从源代码来联编 FreeBSD 文档所需的那些工具。
如何使用 CVSup 将文档下载到 /usr/doc。
如何从源代码联编 FreeBSD 文档, 并将其安装到 /usr/share/doc。
联编文档的过程中支持的一些编译选项, 例如只联编某些语言的版本, 或只联编特定的输出格式。
从源代码联编 FreeBSD 文档需要大量的工具。 这些工具并不是 FreeBSD 基本系统的一部分, 因为这些工具需要占用大量的磁盘空间, 而且并不是对所有 FreeBSD 用户都有用; 只有活跃地撰写 FreeBSD 新文档, 或经常从源代码更新文档的用户才需要这些工具。
全部所需的工具, 均可通过 Ports 套件来安装。 textproc/docproj port 是由 FreeBSD 文档计划开发的方便安装和更新这些工具的主 port。
注意: 如果不需要 PostScript® 或 PDF 文档的话, 也可以考虑安装 textproc/docproj-nojadetex port。 这套文档工具集包含除了 teTeX typesetting 引擎之外的其他全部工具。 teTeX 是一个很大的工具集, 因此如果不需要 PDF 输出的话, 排除它会节省很多时间和磁盘空间。
如欲了解关于安装和使用 CVSup 的进一步信息, 请参阅 使用 CVSup。
CVSup 工具能够下载文档源代码的原始副本, 您可使用 /usr/share/examples/cvsup/doc-supfile 文件作为配置模板来修改。 在 doc-supfile 中的默认主机名是一个无效的占位主机名, 但 cvsup(1) 能够通过命令行来指定主机名, 因此文档源代码可以使用下面的命令从 CVSup 服务器获得:
# cvsup -h cvsup.FreeBSD.org -g -L 2 /usr/share/examples/cvsup/doc-supfile
您应将 cvsup.FreeBSD.org 改为最近的 CVSup 服务器。 参见 第 A.6.7 节 关于镜像站点的完整列表。
初始的文档源代码下载需要一些时间, 您需要耐心等待它完成。
后续的更新可以用同样的命令来进行。 由于 CVSup 工具只下载上次运行之后所发生过的更新, 因此在首次运行之后再运行 CVSup 应该是很快的。
在签出源代码之后, 还可以使用另一种由 /usr/doc 目录中的 Makefile 支持的方法来更新它。 通过在 /etc/make.conf 中配置 SUP_UPDATE、 SUPHOST 和 DOCSUPFILE, 可以通过运行:
# cd /usr/doc # make update
来完成更新。 典型的 /etc/make.conf 中的 make(1) 选项是:
SUP_UPDATE= yes SUPHOST?= cvsup.freebsd.org DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile
注意: 将 SUPHOST 和 DOCSUPFILE 的值使用 ?= 来指定的好处是使 make 命令行能够覆盖这些选项。 在向 make.conf 中增加选项时推荐这样做, 以避免在测试时反复修改这个文件。
FreeBSD 文档的更新和联编系统支持一些方便只更新一部分文档, 或只联编特定格式及译文的选项。 这些选项可以在 /etc/make.conf 文件中配置, 也可以通过 make(1) 工具来指定。
这些选项包括:
准备联编和安装的语言列表。 例如, 指定为 en_US.ISO8859-1 表示只联编英文版的文档。
准备输出的格式列表。 目前, 系统支持 html、 html-split、 txt、 ps、 pdf、 和 rtf。
用于用来更新的 CVSup 服务器的主机名。
用于安装文档的目录。 默认为 /usr/share/doc。
如欲了解 FreeBSD 中其他可供配置的全局 make 变量, 请参阅 make.conf(5)。
关于 FreeBSD 文档联编系统的其他详情, 请参阅 FreeBSD 文档计划入门之新手必读部分。
在 /usr/doc 中下载了最新的文档源代码快照之后, 就可以开始动手联编文档了。
要更新全部 DOC_LANG 中定义的语言的文档, 需要执行下面的命令:
# cd /usr/doc # make install clean
如果在 make.conf 中配置了正确的 DOCSUPFILE、 SUPHOST 和 SUP_UPDATE 选项, 则可以将更新源代码和安装一步完成:
# cd /usr/doc # make update install clean
如果只需要更新某个特定语言的文档, 可以在 /usr/doc 中与之对应的目录中运行 make(1):
# cd /usr/doc/en_US.ISO8859-1 # make update install clean
此外, 还可以透过 make 变量 FORMATS 来控制输出格式, 例如:
# cd /usr/doc # make FORMATS='html html-split' install clean
本文档和其它文档可从这里下载:ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
如果对于FreeBSD有问题,请先阅读文档,如不能解决再联系<questions@FreeBSD.org>.
关于本文档的问题请发信联系 <doc@FreeBSD.org>.