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. There are several ways to update the local copy of documentation with the latest FreeBSD Documentation Set.
The FreeBSD documentation sources can be obtained with svn. This section describes how to:
Install the documentation toolchain, the tools that are required to rebuild the FreeBSD documentation from its source.
Download a copy of the documentation source at
/usr/doc
, using
svn.
Rebuild the FreeBSD documentation from its source, and
install it under /usr/share/doc
.
Recognize some of the build options that are supported by the build system of the documentation, such as 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 collection of tools which are not part of the FreeBSD base system due to the amount of disk space these tools use. They are also not useful to all FreeBSD users, only those users that are actively writing new documentation for FreeBSD or are frequently updating their documentation from source.
The required tools, including
svn, are available in the
textproc/docproj
meta-port
developed by the FreeBSD Documentation Project.
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.
In this example, svn is used to fetch a clean copy of the documentation sources from the western US mirror using the HTTPS protocol:
#
svn checkout https://svn0.us-west.FreeBSD.org
/doc/head /usr/doc
Select the closest mirror from the available Subversion 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:
#
svn update /usr/doc
After checking out the sources, an alternative way of
updating the documentation is supported by the
/usr/doc/Makefile
by running the
following commands:
#
cd /usr/doc
#
make update
The updating and build system of the FreeBSD documentation
set 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 /etc/make.conf
, or as
command-line options passed to make(1).
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
, pdf
,
and rtf
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).
For more make
variables supported by
the build system of the FreeBSD documentation, refer to the
FreeBSD
Documentation Project Primer for New
Contributors.
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 the languages defined in
DOC_LANG
may be performed by typing:
#
cd /usr/doc
#
make 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
:
#
cd /usr/doc/en_US.ISO8859-1
#
make update install clean
The output formats that will be installed may be specified
by setting FORMATS
:
#
cd /usr/doc
#
make FORMATS='html html-split' install clean
For information on editing and submitting corrections to the documentation, refer to the FreeBSD Documentation Project Primer for New Contributors.
The previous section presented a method for updating the FreeBSD documentation from sources. Source based updates may not be feasible or practical for all FreeBSD systems as building the documentation sources requires the documentation toolchain, a certain level of familiarity with svn and source checkouts from a repository, and a few manual steps to build the checked out sources. This section describes an alternative method which uses the Ports Collection and makes it possible to:
Download and install pre-built snapshots of the documentation, without having to locally build anything or install the documentation toolchain.
Download the documentation sources and build them through the ports framework, making the checkout and build steps a bit easier.
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 docs
category.
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.
As an extra feature, when the documentation ports are built locally, they record a dependency to the documentation toolchain ports, so that they are also automatically installed.
Organization of the documentation ports is as follows:
The “master port”, misc/freebsd-doc-en
,
which installs all of the English documentation
ports.
The “all in one port”, misc/freebsd-doc-all
,
builds and installs all documentation in all available
languages.
There is a “slave port” for each
translation, such as misc/freebsd-doc-hu
for the
Hungarian-language documents.
For example, to build and install the English
documentation in split HTML format,
similar to the format used on http://www.FreeBSD.org, to
/usr/local/share/doc/freebsd
,
install the following port
#
cd /usr/ports/misc/freebsd-doc-en
#
make install clean
There are many options for modifying the default behavior of the documentation ports, 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
, as appropriate,
plus images.
WITH_PDF
Builds the Adobe® Portable Document Format
(PDF). The formatted documentation is saved to a
file called article.pdf
or
book.pdf
, as
appropriate.
DOCBASE
Specifies where to install the documentation.
It defaults to /usr/local/share/doc/freebsd
.
The default target directory differs from the
directory used svn.
This is because ports are usually installed within
/usr/local
.
This can be overridden by using
PREFIX
.
This example uses variables to install the Hungarian documentation as a PDF:
#
cd /usr/ports/misc/freebsd-doc-hu
#
make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install cleanBuilding 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.
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
Packages use a format that differs from the
corresponding port's name:
,
where lang
-freebsd-doclang
is the short format
of the language code, such as hu
for
Hungarian, or zh_cn
for Simplified
Chinese.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.