Index: chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v
retrieving revision 1.240
diff -u -r1.240 chapter.sgml
--- chapter.sgml 1 Feb 2009 04:25:22 -0000 1.240
+++ chapter.sgml 14 Apr 2009 15:30:33 -0000
@@ -80,7 +80,7 @@
How to keep your documentation up to date with
- CVSup.
@@ -959,6 +959,207 @@
&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. It required one
+ to install the documentation toolchain, check out the latest
+ source files, and rebuild them. This process is very similar to
+ rebuilding the world, i.e.: the &os; sources, and it can be a
+ bit cumbersome, and unnecessarily difficult.
+
+ An option to ease the process of documentation updating
+ while still staying close to the sources, is to use the
+ documentation ports provided monthly for
+ every supported language by the &a.doceng;. These ports are
+ listed in the &os; Ports Collection, under the virtual
+ category named docs.
+
+ Basically, this technique implements almost the same method
+ as CVSup that we have already seen,
+ but here the entire process can be controlled by a simple
+ command, and compilation of the sources might be omitted as the
+ &os; package building cluster builds packages from the
+ documentation ports. Thus, the user can decide to update
+ documentation from a pre-built binary package.
+
+
+ If building from sources is preferred, the mandatory
+ documentation tools will be automatically installed as a
+ dependency.
+
+
+
+ Building and Installing Documentation Ports
+
+ 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, probably the most requested
+ language for the majority of the users.
+
+
+
+ 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 are present only for the ease of
+ installation.
+
+
+
+ To install a documentation port by 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 other 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 (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; or
+ Ghostscript
+ (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 isolated in the /usr/local directory.
+ This can however be 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 Packages
+
+ If resources are not available for the complete build and
+ installation of the documentation ports, or we simply want to
+ have the documentation installed in a more convenient way,
+ binary packages come handy. They can be managed as normal
+ &os; packages, via &man.pkg.add.1;, &man.pkg.delete.1;, and so
+ on.
+
+
+ When binary packages are used, documentation will be
+ installed in all available formats for
+ the given language.
+
+
+ The following command will install the latest monthly
+ version of the Hungarian documentation from package:
+
+ &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
+
+
+