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.
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.
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.
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.
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:
The list of languages and encodings to build and install, e.g. en_US.ISO8859-1 for the English documentation only.
A single format or a list of output formats to be built. Currently, html, html-split, txt, ps, pdf, and rtf are supported.
The hostname of the CVSup server to use when updating.
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.
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
This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.