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 @@
       </listitem>
 
       <listitem>
+	<para>How to keep your documentation up to date with
+	  <application>CVSup</application> and
+	  <application>Docsnap</application>.</para>
+      </listitem>
+
+      <listitem>
 	<para>The difference between the two development
 	  branches: &os.stable; and &os.current;.</para>
       </listitem>
@@ -575,6 +581,306 @@
     <screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
   </sect1>
 
+  <sect1 id="updating-upgrading-documentation">
+    <title>Updating the Documentation Set</title>
+
+    <para>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 <ulink
+	url="http://www.freebsd.org/doc/">&os; web site</ulink>, 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.</para>
+
+    <sect2 id="csup-doc">
+      <title>Using CVSup to Update the Documentation</title>
+
+      <para>The sources and the installed copy of the &os; documentation
+        can be updated with <application>CVSup</application>, using a
+        mechanism similar to the one employed for the base system
+        sources (c.f. <xref linkend="makeworld">).  This section
+        describes:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>How to install the documentation toolchain, the tools
+	    that are required to rebuild the &os; documentation from its
+	    source.</para>
+	</listitem>
+
+	<listitem>
+	  <para>How to download a copy of the documentation source
+	    at <filename class="directory">/usr/doc</filename>,
+	    using <application>CVSup</application>.</para>
+	</listitem>
+
+	<listitem>
+	  <para>How to rebuild the &os; documentation from its source,
+	    and install it
+	    under <filename class="directory">/usr/share/doc</filename>.</para>
+	</listitem>
+
+	<listitem>
+	  <para>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.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2 id="installing-documentation-toolchain">
+      <title>Installing CVSup and the Documentation Toolchain</title>
+
+      <para>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.</para>
+
+      <para>All the required tools are available as part of the Ports
+	Collection.  The <filename
+	  role="package">textproc/docproj</filename> 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.</para>
+
+      <note>
+	<para>When no &postscript; or PDF documentation required, one
+	  might consider installing the <filename
+	    role="package">textproc/docproj-nojadetex</filename> port
+	  instead.  This version of the documentation toolchain includes
+	  everything except the <application>teTeX</application>
+	  typesetting engine.  <application>teTeX</application> is a
+	  very large collection of tools, so it may be quite sensible to
+	  omit its installation if PDF output is not really
+	  necessary.</para>
+      </note>
+
+      <para>For more information on installing and using
+	<application>CVSup</application>, see <link
+	  linkend="cvsup">Using CVSup</link>.</para>
+    </sect2>
+
+    <sect2 id="updating-documentation-sources">
+      <title>Updating the Documentation Sources</title>
+
+      <para>The <application>CVSup</application> utility can fetch a
+	clean copy of the documentation sources, using
+	the <filename>/usr/share/examples/cvsup/doc-supfile</filename>
+	file as a configuration template.  The default update host is
+	set to a placeholder value in <filename>doc-supfile</filename>,
+	but &man.cvsup.1; accepts a host name through the command line,
+	so the documentation sources can be fetched from one of
+	the <application>CVSup</application> servers,
+	like <hostid>cvsup10.FreeBSD.org</hostid>, by typing:</para>
+
+      <screen>&prompt.root; <userinput>cvsup -h <replaceable>cvsup10.FreeBSD.org</replaceable> -g -L 2 <filename>/usr/share/examples/cvsup/doc-supfile</filename></userinput></screen>
+
+      <para>The initial download of the documentation sources may take a
+	while.  Let it run until it completes.</para>
+
+      <para>Future updates of the documentation sources may be fetched
+	by running the same command.
+	The <application>CVSup</application> utility downloads and
+	copies only the updates since the last time it ran, so every run
+	of <application>CVSup</application> after the first complete run
+	should be pretty fast.</para>
+
+      <para>After checking out the sources, an alternative way of
+	updating the documentation is supported by the
+	<filename>Makefile</filename> of the <filename
+	  class="directory">/usr/doc</filename> directory.  By setting
+	<makevar>SUP_UPDATE</makevar>, <makevar>SUPHOST</makevar> and
+	<makevar>DOCSUPFILE</makevar> in the
+	<filename>/etc/make.conf</filename> file, it is possible to
+	run:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make update</userinput></screen>
+
+      <para>A typical set of these &man.make.1; options
+	for <filename>/etc/make.conf</filename> is:</para>
+
+      <programlisting>SUP_UPDATE= yes
+SUPHOST?= cvsup10.freebsd.org
+DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
+
+      <note>
+	<para>Setting the <makevar>SUPHOST</makevar>
+	  and <makevar>DOCSUPFILE</makevar> value
+	  with <literal>?=</literal> permits overriding them in the
+	  command-line of make.  This is the recommended way of adding
+	  options to <filename>make.conf</filename>, to avoid having to
+	  edit the file every time a different option value has to be
+	  tested.</para>
+      </note>
+    </sect2>
+
+    <sect2 id="updating-documentation-options">
+      <title>Tunable Options of the Documentation Sources</title>
+
+      <para>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 <filename>/etc/make.conf</filename> file, or as
+	command-line options passed to the &man.make.1; utility.</para>
+
+      <para>The following options are some of these:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><makevar>DOC_LANG</makevar></term>
+
+	  <listitem>
+	    <para>The list of languages and encodings to build and
+	      install, e.g. <literal>en_US.ISO8859-1</literal> for the
+	      English documentation only.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><makevar>FORMATS</makevar></term>
+
+	  <listitem>
+	    <para>A single format or a list of output formats to be
+	      built.  Currently, <literal>html</literal>,
+	      <literal>html-split</literal>, <literal>txt</literal>,
+	      <literal>ps</literal>, <literal>pdf</literal>,
+	      and <literal>rtf</literal> are supported.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><makevar>SUPHOST</makevar></term>
+
+	  <listitem>
+	    <para>The hostname of the <application>CVSup</application>
+	      server to use when updating.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>For more make variables supported as system-wide options in
+	&os;, see &man.make.conf.5;.</para>
+
+      <para>For more make variables supported by the build system of the
+	&os; documentation, please refer to
+	the <ulink url="&url.doc.langbase;/books/fdp-primer">&os;
+	  Documentation Project Primer for New Contributors</ulink>.</para>
+    </sect2>
+
+    <sect2 id="updating-installed-documentation">
+      <title>Installing the &os; Documentation from Source</title>
+
+      <para>When an up-to-date snapshot of the documentation sources has
+	been fetched in <filename class="directory">/usr/doc</filename>,
+	everything is ready for an update of the installed
+	documentation.</para>
+
+      <para>A full update of all the languages defined in
+	the <makevar>DOC_LANG</makevar> makefile option may be done by
+	typing:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <para>If <filename>make.conf</filename> has been set up with the
+	correct <makevar>DOCSUPFILE</makevar>, <makevar>SUPHOST</makevar>
+	and <makevar>SUP_UPDATE</makevar> options, the install step may
+	be combined with an update of the documentation sources by
+	typing:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make update install clean</userinput></screen>
+
+      <para>If an update of only a specific language is desired,
+	&man.make.1; can be invoked in a language specific subdirectory
+	of <filename class="directory">/usr/doc</filename>, i.e.:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
+&prompt.root; <userinput>make update install clean</userinput></screen>
+
+      <para>The output formats that will be installed may be specified
+	by setting the <makevar>FORMATS</makevar> make variable,
+	i.e.:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
+    </sect2>
+
+    <sect2 id="docsnap">
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Pav</firstname>
+	    <surname>Lucistnik</surname>
+	    <contrib>Based on information provided by </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+
+      <title>Using Docsnap</title>
+
+      <para><application>Docsnap</application> is an &man.rsync.1;
+	repository for updating installed &os; Documentation in a
+	relatively easy and fast way.  A
+	<quote><application>Docsnap</application> server</quote> tracks
+	the documentation sources, and builds them in HTML format every
+	hour.  The <filename role="package">textproc/docproj</filename>
+	is unneeded with <application>Docsnap</application> as only
+	patches to the built documentation exist.</para>
+
+      <para>The only requirement for using this technique is
+	the <filename role="package">net/rsync</filename> port or
+	package.  To add it, use the following command:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r rsync</userinput></screen>
+
+      <note>
+	<para><application>Docsnap</application> has been originally
+	  developed for updating documentation installed
+	  to <filename class="directory">/usr/share/doc</filename>, but
+	  the following examples could be adapted to other directories
+	  as well.  For user directories, it does not require
+	  <username>root</username> privileges.</para>
+      </note>
+
+      <para>To update the documentation set, issue the following
+	command:</para>
+
+      <screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap <replaceable>/usr/share/doc</replaceable></userinput></screen>
+
+      <note>
+	<para>There is only one <application>Docsnap</application>
+	  server at the moment;
+	  the <hostid>docsnap.sk.FreeBSD.org</hostid> shown
+	  above.</para>
+      </note>
+
+      <para>Do not use the <option>--delete</option> flag here as there
+	are some items installed
+	into <filename class="directory">/usr/share/doc</filename>
+	during <command>make installworld</command>, which would
+	accidentally be removed.  To clean up, use this command
+	instead:</para>
+
+      <screen>&prompt.root; <userinput>rsync -rltvz --delete <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/??_??\.\* <replaceable>/usr/share/doc</replaceable></userinput></screen>
+
+      <para>If a subset of documentation needs to be updated, for
+	example, the English documentation only, the following command
+	should be used:</para>
+
+      <screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/en_US.ISO8859-1 <replaceable>/usr/share/doc</replaceable></userinput></screen>
+    </sect2>
+  </sect1>
+
   <sect1 id="current-stable">
     <title>Tracking a Development Branch</title>
     <indexterm><primary>-CURRENT</primary></indexterm>