FreeBSD Handbook
Prev | Chapter 24 Updating and Upgrading FreeBSD | Next

# 24.4 Updating the Documentation Set

Besides the base system and the Ports Collection, documentation is an integral part of the FreeBSD operating system. While an up-to-date version of the FreeBSD Documentation Set is always available on the FreeBSD web site, some users might have slow or no permanent network connectivity at all. Fortunately, there are several ways to update the documentation shipped with each release by maintaining a local copy of the latest FreeBSD Documentation Set.

## 24.4.1 Using CVSup to Update the Documentation

The sources and the installed copy of the FreeBSD documentation can be updated with CVSup, using a mechanism similar to the one employed for the base system sources (c.f. Section 24.7). This section describes:

- How to install the documentation toolchain, the tools that are required to rebuild the FreeBSD documentation from its source.

- How to download a copy of the documentation source at `/usr/doc`, using CVSup.

- How to rebuild the FreeBSD documentation from its source, and install it under `/usr/share/doc`.

- Some of the build options that are supported by the build system of the documentation, i.e. the options that build only some of the different language translations of the documentation or the options that select a specific output format.

## 24.4.2 Installing CVSup and the Documentation Toolchain

Rebuilding the FreeBSD documentation from source requires a fairly large collection of tools. These tools are not part of the FreeBSD base system, because they need a large amount of disk space and they are not useful to all FreeBSD users; they are only useful to those users that are actively writing new documentation for FreeBSD or are frequently updating their documentation from source.

All the required tools are available as part of the Ports Collection. The `textproc/docproj` port is a master port that has been developed by the FreeBSD Documentation Project, to ease the initial installation and future updates of these tools.

> Note: When no PostScript® or PDF documentation required, one might consider installing the `textproc/docproj-nojadetex` port instead. This version of the documentation toolchain includes everything except the teTeX typesetting engine. teTeX is a very large collection of tools, so it may be quite sensible to omit its installation if PDF output is not really necessary.

For more information on installing and using CVSup, see Using CVSup.

## 24.4.3 Updating the Documentation Sources

The CVSup utility can fetch a clean copy of the documentation sources, using the `/usr/share/examples/cvsup/doc-supfile` file as a configuration template. The default update host is set to a placeholder value in `doc-supfile`, but cvsup(1) accepts a host name through the command line, so the documentation sources can be fetched from one of the CVSup servers by typing:

    # cvsup -h cvsup.FreeBSD.org -g -L 2 /usr/share/examples/cvsup/doc-supfile

Change `cvsup.FreeBSD.org` to the nearest CVSup server. See Section A.6.7 for a complete listing of mirror sites.

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 the same command. The CVSup utility downloads and copies only the updates since the last time it ran, so every run of CVSup after the first complete run should be pretty fast.

After checking out the sources, an alternative way of updating the documentation is supported by the `Makefile` of the `/usr/doc` directory. By setting `SUP_UPDATE`, `SUPHOST` and `DOCSUPFILE` in the `/etc/make.conf` file, it is possible to run:

    # cd /usr/doc
    # make update

A typical set of these make(1) options for `/etc/make.conf` is:

    SUP_UPDATE= yes
    SUPHOST?= cvsup.freebsd.org
    DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile

> Note: Setting the `SUPHOST` and `DOCSUPFILE` value with `?=` permits overriding them in the command-line of make. This is the recommended way of adding options to `make.conf`, to avoid having to edit the file every time a different option value has to be tested.

## 24.4.4 Tunable Options of the Documentation Sources

The updating and build system of the FreeBSD documentation supports a few options that 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 the `/etc/make.conf` file, or as command-line options passed to the make(1) utility.

The following options are some of these:

`DOC_LANG`

  The list of languages and encodings to build and install, e.g. `en_US.ISO8859-1` for the English documentation only.

`FORMATS`

  A single format or a list of output formats to be built. Currently, `html`, `html-split`, `txt`, `ps`, `pdf`, and `rtf` are supported.

`SUPHOST`

  The hostname of the CVSup server to use when updating.

`DOCDIR`

  Where to install the documentation. It defaults to `/usr/share/doc`.

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

For more make variables supported by the build system of the FreeBSD documentation, please refer to the FreeBSD Documentation Project Primer for New Contributors.

## 24.4.5 Installing the FreeBSD Documentation from Source

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

A full update of all the languages defined in the `DOC_LANG` makefile option may be done by typing:

    # cd /usr/doc
    # make install clean

If `make.conf` has been set up with the correct `DOCSUPFILE`, `SUPHOST` and `SUP_UPDATE` options, the install step may be combined with an update of the documentation sources by typing:

    # cd /usr/doc
    # make update install clean

If an update of only a specific language is desired, make(1) can be invoked in a language specific subdirectory of `/usr/doc`, i.e.:

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

The output formats that will be installed may be specified by setting the `FORMATS` make variable, i.e.:

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

## 24.4.6 Using Documentation Ports

Based on the work of Marc Fonvieille.

In the previous section, we have presented a method for updating the FreeBSD documentation from sources. Source based updates may not be feasible or practical for all FreeBSD systems though. Building the documentation sources requires a fairly large collection of tools and utilities, the documentation toolchain, a certain level of familiarity with CVS and source checkouts from a repository, and a few manual steps to build the checked out sources. In this section, we describe an alternative way of updating the installed copies of the FreeBSD documentation; one that uses the Ports Collection and makes it possible to:

- Download and install pre-built snaphots of the documentation, without having to locally build anything (eliminating this way the need for an installation of the entire documentation toolchain).

- Download the documentation sources and build them through the ports framework (making the checkout and build steps a bit eaiser).

These two methods of updating the FreeBSD documentation are supported by a set of documentation ports, updated by the Documentation Engineering Team `<doceng@FreeBSD.org>` on a monthly basis. These are listed in the FreeBSD Ports Collection, under the virtual category named docs.

### 24.4.6.1 Building and Installing Documentation Ports

The documentation ports use the ports building framework to make documentation builds easier. They automate the process of checking out the documentation source, running make(1) with the appropriate environment settings and command-line options, and they make the installation or deinstallation of documentation as easy as the installation of any other FreeBSD port or package.

> Note: As an extra feature, when the documentation ports are built locally, they record a dependency to the documentation toolchain ports, so the latter is automatically installed too.

Organization of the documentation ports is as follows:

- There is a “master port”, `misc/freebsd-doc-en`, where the documentation port files can be found. It is the base of all documentation ports. By default, it builds the English documentation only.

- There is an “all in one port”, `misc/freebsd-doc-all`, and it builds and installs all documentation in all available languages.

- Finally, there is a “slave port” for each translation, e.g.: `misc/freebsd-doc-hu` for the Hungarian-language documents. All of them depend on the master port and install the translated documentation of the respective language.

To install a documentation port from source, issue the following commands (as `root`):

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

This will build and install the English documentation in split HTML format (the same as used on http://www.FreeBSD.org) in the `/usr/local/share/doc/freebsd` directory.

#### 24.4.6.1.1 Common Knobs and Options

There are many options for modifying the default behavior of the documentation ports. The following is just a short list:

`WITH_HTML`

  Allows the build of the HTML format: a single HTML file per document. The formatted documentation is saved to a file called `article.html`, or `book.html`, as appropriate, plus images.

`WITH_PDF`

  Allows the build of the Adobe® Portable Document Format, for use with Adobe Acrobat Reader®, Ghostscript or other PDF readers. The formatted documentation is saved to a file called `article.pdf` or `book.pdf`, as appropriate.

`DOCBASE`

  Where to install the documentation. It defaults to `/usr/local/share/doc/freebsd`.

  > Note: Notice that the default target directory differs from the directory used by the CVSup method. This is because we are installing a port, and ports are usually installed under the `/usr/local` directory. This can overriden, by adding the `PREFIX` variable.

Here is a brief example on how to use the variables mentioned above to install the Hungarian documentation in Portable Document Format:

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

### 24.4.6.2 Using Documentation Packages

Building the documentation ports from source, as described in the previous section, requires a local installation of the documentation toolchain and a bit of disk space for the build of the ports. When resources are not available to install the documentation toolchain, or because the build from sources would take too much disk space, it is still possible to install pre-built snapshots of the documentation ports.

The Documentation Engineering Team `<doceng@FreeBSD.org>` prepares monthly snapshots of the FreeBSD documentation packages. These binary packages can be used with any of the bundled package tools, like pkg_add(1), pkg_delete(1), and so on.

> Note: 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 pre-built package of the Hungarian documentation:

    # pkg_add -r hu-freebsd-doc

> Note: Packages have the following name format that differs from the corresponding port's name: ``lang`-freebsd-doc`. Here `lang` is the short format of the language code, i.e. `hu` for Hungarian, or `zh_cn` for Simplified Chinese.

### 24.4.6.3 Updating Documentation Ports

To update a previously installed documentation port, any tool suitable for updating ports is sufficient. For example, the following command updates the installed Hungarian documentation via the `ports-mgmt/portupgrade` tool by using packages only:

    # portupgrade -PP hu-freebsd-doc

Prev | Home | Next
Portsnap: A Ports Collection Update Tool | Up | Tracking a Development Branch