24.3. Updating the Documentation Set

24.3. Updating the Documentation Set
Prev	Chapter 24. Updating and Upgrading FreeBSD	Next

Documentation is an integral part of the FreeBSD operating system. While an up-to-date version of the FreeBSD documentation is always available on the FreeBSD web site (http://www.freebsd.org/doc/), it can be handy to have an up-to-date, local copy of the FreeBSD website, handbooks, FAQ, and articles.

This section describes how to use either source or the FreeBSD Ports Collection to keep a local copy of the FreeBSD documentation up-to-date.

For information on editing and submitting corrections to the documentation, refer to the FreeBSD Documentation Project Primer for New Contributors (http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/).

24.3.1. Updating Documentation from Source

Rebuilding the FreeBSD documentation from source requires a collection of tools which are not part of the FreeBSD base system. The required tools, including svn, can be installed from the textproc/docproj package or port developed by the FreeBSD Documentation Project.

Once installed, use svn to fetch a clean copy of the documentation source. Replace https://svn0.us-west.FreeBSD.org with the address of the closest geographic mirror from Section A.4.4, “Subversion Mirror Sites”:

# svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc

The initial download of the documentation sources may take a while. Let it run until it completes.

Future updates of the documentation sources may be fetched by running:

# svn update /usr/doc

Once an up-to-date snapshot of the documentation sources has been fetched to /usr/doc, everything is ready for an update of the installed documentation.

A full update of all available languages may be performed by typing:

# cd /usr/doc
# make install clean

If an update of only a specific language is desired, make can be invoked in a language-specific subdirectory of /usr/doc:

# cd /usr/doc/en_US.ISO8859-1
# make install clean

An alternative way of updating the documentation is to run this command from /usr/doc or the desired language-specific subdirectory:

# make update

The output formats that will be installed may be specified by setting FORMATS:

# cd /usr/doc
# make FORMATS='html html-split' install clean

Several options are available to ease the process of updating only parts of the documentation, or the build of specific translations. These options can be set either as system-wide options in /etc/make.conf, or as command-line options passed to make.

The options include:

DOC_LANG: The list of languages and encodings to build and install, such as en_US.ISO8859-1 for English documentation.
FORMATS: A single format or a list of output formats to be built. Currently, html, html-split, txt, ps, and pdf are supported.
DOCDIR: Where to install the documentation. It defaults to /usr/share/doc.

For more make variables supported as system-wide options in FreeBSD, refer to make.conf(5).

24.3.2. Updating Documentation from Ports

Based on the work of Marc Fonvieille.

The previous section presented a method for updating the FreeBSD documentation from sources. This section describes an alternative method which uses the Ports Collection and makes it possible to:

Install pre-built packages of the documentation, without having to locally build anything or install the documentation toolchain.
Build the documentation sources through the ports framework, making the checkout and build steps a bit easier.

This method of updating the FreeBSD documentation is supported by a set of documentation ports and packages which are updated by the Documentation Engineering Team <[email protected]> on a monthly basis. These are listed in the FreeBSD Ports Collection, under the docs category (http://www.freshports.org/docs/).

Organization of the documentation ports is as follows:

The misc/freebsd-doc-en package or port installs all of the English documentation.
The misc/freebsd-doc-all meta-package or port installs all documentation in all available languages.
There is a package and port for each translation, such as misc/freebsd-doc-hu for the Hungarian documentation.

When binary packages are used, the FreeBSD documentation will be installed in all available formats for the given language. For example, the following command will install the latest package of the Hungarian documentation:

# pkg install hu-freebsd-doc

Note:

Packages use a format that differs from the corresponding port's name: lang-freebsd-doc, where lang is the short format of the language code, such as hu for Hungarian, or zh_cn for Simplified Chinese.

To specify the format of the documentation, build the port instead of installing the package. For example, to build and install the English documentation:

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

The port provides a configuration menu where the format to build and install can be specified. By default, split HTML, similar to the format used on http://www.FreeBSD.org, and PDF are selected.

Alternately, several make options can be specified when building a documentation port, including:

WITH_HTML: Builds the HTML format with a single HTML file per document. The formatted documentation is saved to a file called article.html, or book.html.
WITH_PDF: The formatted documentation is saved to a file called article.pdf or book.pdf.
DOCBASE: Specifies where to install the documentation. It defaults to /usr/local/share/doc/freebsd.

This example uses variables to install the Hungarian documentation as a PDF in the specified directory:

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

Documentation packages or ports can be updated using the instructions in Chapter 5, Installing Applications: Packages and Ports. For example, the following command updates the installed Hungarian documentation using ports-mgmt/portmaster by using packages only:

# portmaster -PP hu-freebsd-doc

Prev	Up	Next
24.2. FreeBSD Update	Home	24.4. Tracking a Development Branch