25.4. 更新系统附带的文档

25.4. 更新系统附带的文档
上一页	第 25 章更新与升级 FreeBSD	下一页

除了基本系统和 Ports 套件之外，文档也是 FreeBSD 操作系统的一个组成部分。尽管您总是可以通过 FreeBSD 网站来访问最新的 FreeBSD 文档，一些用户的网络连接可能很慢，甚至完全没有网络连接。幸运的是，有很多方法可以用来更新随发行版本附带的 FreeBSD 文档的本地副本。

25.4.1. 使用 CVSup 来更新文档

FreeBSD 文档的源代码和安装版本都可以通过 CVSup 来以与基本系统 (参考第 25.7 节 “重新编译 “world””) 类似的方法来升级。这一节中将会介绍：

如何安装联编文档所需的工具集，用于从源代码来联编 FreeBSD 文档所需的那些工具。
如何使用 CVSup 将文档下载到 /usr/doc。
如何从源代码联编 FreeBSD 文档，并将其安装到 /usr/share/doc。
联编文档的过程中支持的一些编译选项，例如只联编某些语言的版本，或只联编特定的输出格式。

25.4.2. 安装 CVSup 和文档工具集

从源代码联编 FreeBSD 文档需要大量的工具。这些工具并不是 FreeBSD 基本系统的一部分，因为这些工具需要占用大量的磁盘空间，而且并不是对所有 FreeBSD 用户都有用；只有活跃地撰写 FreeBSD 新文档，或经常从源代码更新文档的用户才需要这些工具。

全部所需的工具，均可通过 Ports 套件来安装。 textproc/docproj port 是由 FreeBSD 文档计划开发的方便安装和更新这些工具的主 port。

注意:

如果不需要 PostScript® 或 PDF 文档的话，也可以考虑安装 textproc/docproj-nojadetex port。这套文档工具集包含除了 teTeX typesetting 引擎之外的其他全部工具。 teTeX 是一个很大的工具集，因此如果不需要 PDF 输出的话，排除它会节省很多时间和磁盘空间。

如欲了解关于安装和使用 CVSup 的进一步信息，请参阅使用 CVSup。

25.4.3. 更新文档源代码

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 工具只下载上次运行之后所发生过的更新，因此在首次运行之后再运行 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 中增加选项时推荐这样做，以避免在测试时反复修改这个文件。

25.4.4. 文档源代码中可调的选项

FreeBSD 文档的更新和联编系统支持一些方便只更新一部分文档，或只联编特定格式及译文的选项。这些选项可以在 /etc/make.conf 文件中配置，也可以通过 make(1) 工具来指定。

这些选项包括：

DOC_LANG: 准备联编和安装的语言列表。例如，指定为 en_US.ISO8859-1 表示只联编英文版的文档。
FORMATS: 准备输出的格式列表。目前，系统支持 html、 html-split、 txt、 ps、 pdf、和 rtf。
SUPHOST: 用于用来更新的 CVSup 服务器的主机名。
DOCDIR: 用于安装文档的目录。默认为 /usr/share/doc。

如欲了解 FreeBSD 中其他可供配置的全局 make 变量，请参阅 make.conf(5)。

关于 FreeBSD 文档联编系统的其他详情，请参阅 FreeBSD 文档计划入门之新手必读部分。

25.4.5. 从源代码安装 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

25.4.6. 使用文档 Ports

原作： Marc Fonvieille.

在之前的章节中，我们已展示了从源代码更新 FreeBSD 文档的方法。基于源代码的更新的方法可能并不是对于所有的 FreeBSD 系统都可行有效。编译文档源代码需要一大堆的工具， 文档工具链，对于 CVS 的一定了解和从仓库中检出源代码，还有一些编译已检出代码的手工步骤。这一章节我们将介绍一种使用 Ports 来更新已安装的 FreeBSD 文档：

下载并安装预编译好的文档快照，而不用在本地编译任何部份 (这样便不再需要安装整个文档工具链了)。
下载文档的源代码并使用 ports 框架编译 (使得检出和编译的步骤更容易些)。

这两种更新 FreeBSD 文档的方法都由一组文档工程组 <[email protected]> 每月更新的 文档 ports 提供支持。这些都列在了 FreeBSD Ports docs 虚拟分类下面。

25.4.6.1. 编译和安装文档 Ports

文档 ports 使用 ports 的构建框架使得文档的编译变得更加容易。自动化了检出文档源代码，配以适合的环境设置和命令行参数运行 make(1)，它们使得安装或卸载文档变得就像安装 FreeBSD 其他 port 或二进制包那样容易。

注意:

另一个特性便是当在本地编译文档 ports 时， 文档工具链 ports 会被列入依赖关系，并自动安装。

文档 ports 按以下的方式组织：

一个 “主 port”，在 misc/freebsd-doc-en 下可以找到这个文档 port。它是所有文档 ports 的基础。在默认的情况下，它只安装英文版文档。
一个 “合集 port”， misc/freebsd-doc-all，它将构建并安装所有语言版本的所有文档。
最后是各种翻译的 “从属 port”，比如： misc/freebsd-doc-hu 是匈牙利文版的文档。所有这些都基于主 port 并会安装上对应语言的翻译文档。

以 root 用户身份运行如下的命令安装文档：

# cd /usr/ports/misc/freebsd-doc-en
# make install clean

这将会安装分章节的英文版本 HTML 格式文档 (与http://www.FreeBSD.org 上的相同) 到 /usr/local/share/doc/freebsd 目录。

25.4.6.1.1. 常见的调节选项

文档 ports 有许多用来修改默认行为的选项。以下是一段简要列表：

WITH_HTML: 允许构建 HTML 格式：每份文档为一个单一的 HTML 文件。此种文档的文件名视情况而定通常是 article.html，或 book.html，另外附加一些图片。
WITH_PDF: 允许构建 Adobe® Portable Document Format，可使用 Adobe® Acrobat Reader®， Ghostscript 或者其他的 PDF 阅读器查阅。此种文档的文件名视情况而定通常是 article.pdf 或 book.pdf。
DOCBASE: 文档将被安装到的目录。默认值 /usr/local/share/doc/freebsd。
注意:
请注意默认的目录与 CVSup 方法种所使用的目录不同。这是因为我们正在安装的是一个 port，而 ports 通常会被安装到 /usr/local 目录。这可以指定 PREFIX 变量覆盖默认值。

这是一份简短的关于如何使用以上提到变量来安装 PDF 格式的匈牙利文档：

# cd /usr/ports/misc/freebsd-doc-hu
# make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean

25.4.6.2. 使用文档 Packages

正如上文所述，从 ports 构建文档需要在本地安装一份文档工具链和一些编译所需的磁盘空间。当不够资源安装文档工具链，或者从源代码编译需要太多的磁盘空间时，我们仍然可以安装预编译好的文档快照的 ports。

文档工程组 <[email protected]> 每个月都会制作 FreeBSD 文档快照的包。这些二进制包可以通过包工具来操作，比如 pkg_add(1)， pkg_delete(1)，等等。

注意:

当使用二进制包时，将安装所指定语言相关的 FreeBSD 文档的所有可用格式。

举例来说，以下的命令将安装最新预编译的匈牙利语文档：

# pkg_add -r hu-freebsd-doc

注意:

二进制包使用了以下与对应 ports 名称不同的命名格式: lang-freebsd-doc。这里的 lang 是语言代码的简短形式，比如 hu 表示匈牙利语，或者 zh_cn 表示简体中文。

25.4.6.3. 更新文档 Ports

任何用于更新 ports 的工具都可以被用来更新已安装的文档 port。举例来说，下面的命令通过 ports-mgmt/portupgrade 工具来更新已安装的匈牙利语文档二进制包。

# portupgrade -PP hu-freebsd-doc

上一页	上一级	下一页
25.3. Portsnap：一个 Ports Collection 更新工具	起始页	25.5. 追踪开发分支