Index: chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v
retrieving revision 1.233
diff -u -r1.233 chapter.sgml
--- chapter.sgml 24 Dec 2008 21:47:59 -0000 1.233
+++ chapter.sgml 27 Dec 2008 19:58:50 -0000
@@ -79,6 +79,12 @@
+ How to keep your documentation up to date with
+ CVSup and
+ Docsnap.
+
+
+ The difference between the two development
branches: &os.stable; and &os.current;.
@@ -575,6 +581,306 @@
&prompt.root; portsnap fetch update
+
+ Updating the Documentation Set
+
+ Besides the base system and the Ports Collection,
+ documentation is an integral part of the &os; operating system.
+ While an up-to-date version of the &os; Documentation Set is
+ always available on the &os; 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 &os; Documentation Set.
+
+
+ Using CVSup to Update the Documentation
+
+ The sources and the installed copy of the &os; documentation
+ can be updated with CVSup, using a
+ mechanism similar to the one employed for the base system
+ sources (c.f. ). This section
+ describes:
+
+
+
+ How to install the documentation toolchain, the tools
+ that are required to rebuild the &os; documentation from its
+ source.
+
+
+
+ How to download a copy of the documentation source
+ at /usr/doc,
+ using CVSup.
+
+
+
+ How to rebuild the &os; 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.
+
+
+
+
+
+ Installing CVSup and the Documentation Toolchain
+
+ Rebuilding the &os; documentation from source requires a
+ fairly large collection of tools. These tools are not part of
+ the &os; base system, because they need a large amount of disk
+ space and they are not useful to all &os; users; they are only
+ useful to those users that are actively writing new
+ documentation for &os; 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 &os; Documentation Project,
+ to ease the initial installation and future updates of these
+ tools.
+
+
+ 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.
+
+
+
+ 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 &man.cvsup.1; accepts a host name through the command line,
+ so the documentation sources can be fetched from one of
+ the CVSup servers,
+ like cvsup10.FreeBSD.org, by typing:
+
+ &prompt.root; cvsup -h cvsup10.FreeBSD.org -g -L 2 /usr/share/examples/cvsup/doc-supfile
+
+ 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:
+
+ &prompt.root; cd /usr/doc
+&prompt.root; make update
+
+ A typical set of these &man.make.1; options
+ for /etc/make.conf is:
+
+ SUP_UPDATE= yes
+SUPHOST?= cvsup10.freebsd.org
+DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile
+
+
+ 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.
+
+
+
+
+ Tunable Options of the Documentation Sources
+
+ The updating and build system of the &os; 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 &man.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.
+
+
+
+
+ For more make variables supported as system-wide options in
+ &os;, see &man.make.conf.5;.
+
+ For more make variables supported by the build system of the
+ &os; documentation, please refer to
+ the &os;
+ Documentation Project Primer for New Contributors.
+
+
+
+ Installing the &os; 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:
+
+ &prompt.root; cd /usr/doc
+&prompt.root; 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:
+
+ &prompt.root; cd /usr/doc
+&prompt.root; make update install clean
+
+ If an update of only a specific language is desired,
+ &man.make.1; can be invoked in a language specific subdirectory
+ of /usr/doc, i.e.:
+
+ &prompt.root; cd /usr/doc/en_US.ISO8859-1
+&prompt.root; make update install clean
+
+ The output formats that will be installed may be specified
+ by setting the FORMATS make variable,
+ i.e.:
+
+ &prompt.root; cd /usr/doc
+&prompt.root; make FORMATS='html html-split' install clean
+
+
+
+
+
+
+ Pav
+ Lucistnik
+ Based on information provided by
+
+
+
+
+ Using Docsnap
+
+ Docsnap is an &man.rsync.1;
+ repository for updating installed &os; Documentation in a
+ relatively easy and fast way. A
+ Docsnap server tracks
+ the documentation sources, and builds them in HTML format every
+ hour. The textproc/docproj
+ is unneeded with Docsnap as only
+ patches to the built documentation exist.
+
+ The only requirement for using this technique is
+ the net/rsync port or
+ package. To add it, use the following command:
+
+ &prompt.root; pkg_add -r rsync
+
+
+ Docsnap has been originally
+ developed for updating documentation installed
+ to /usr/share/doc, but
+ the following examples could be adapted to other directories
+ as well. For user directories, it does not require
+ root privileges.
+
+
+ To update the documentation set, issue the following
+ command:
+
+ &prompt.root; rsync -rltvz docsnap.sk.FreeBSD.org::docsnap /usr/share/doc
+
+
+ There is only one Docsnap
+ server at the moment;
+ the docsnap.sk.FreeBSD.org shown
+ above.
+
+
+ Do not use the flag here as there
+ are some items installed
+ into /usr/share/doc
+ during make installworld, which would
+ accidentally be removed. To clean up, use this command
+ instead:
+
+ &prompt.root; rsync -rltvz --delete docsnap.sk.FreeBSD.org::docsnap/??_??\.\* /usr/share/doc
+
+ If a subset of documentation needs to be updated, for
+ example, the English documentation only, the following command
+ should be used:
+
+ &prompt.root; rsync -rltvz docsnap.sk.FreeBSD.org::docsnap/en_US.ISO8859-1 /usr/share/doc
+
+
+
Tracking a Development Branch-CURRENT