diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
index bf09ab0468..7352dd49ed 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -80,7 +80,7 @@
How to keep your documentation up to date with
- CVSup.
@@ -959,6 +959,236 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile
&prompt.root; make FORMATS='html html-split' install clean
+
+
+
+
+ Marc
+ Fonvieille
+ Based on the work of
+
+
+
+
+ Using Documentation Ports
+
+ Updating and Upgrading
+
+
+ documentation package
+ Updating and Upgrading
+
+
+ In the previous section, we have presented a method for
+ updating the &os; documentation from sources. Sources based on
+ updates may not be feasible or practical for all &os; 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 &os;
+ 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 &os; documentation are
+ supported by a set of documentation ports,
+ updated by the &a.doceng; on a monthly basis. These are listed
+ in the &os; Ports Collection, under the virtual category
+ named docs.
+
+
+ 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
+ &man.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 &os; port or package.
+
+
+ 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):
+
+ &prompt.root; cd /usr/ports/misc/freebsd-doc-en
+&prompt.root; make install clean
+
+ This will build and install the English documentation in
+ split HTML format (the same as used on ) in the /usr/local/share/doc/freebsd
+ directory.
+
+
+ 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.
+
+
+ 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:
+
+ &prompt.root; cd /usr/ports/misc/freebsd-doc-hu
+&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean
+
+
+
+
+ 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 &a.doceng; prepares monthly snapshots of the &os;
+ documentation packages. These binary packages can be used
+ with any of the bundled package tools, like &man.pkg.add.1;,
+ &man.pkg.delete.1;, and so on.
+
+
+ When binary packages are used, the &os; 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:
+
+ &prompt.root; pkg_add -r hu-freebsd-doc
+
+
+ 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.
+
+
+
+
+ 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:
+
+ &prompt.root; portupgrade -PP hu-freebsd-doc
+
+
+