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	26 Dec 2008 01:38:45 -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,154 @@
     <screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
   </sect1>
 
+  <sect1 id="updating-upgrading-documentation">
+    <title>Documentation Updating</title>
+
+    <para>There are several ways to update the &os; Documentation Set.
+      In this section, some methods for updating documentation shipped
+      with each &os; release are presented.  Each solution has its
+      advantages and disadvantages, one should choose the most suitable
+      for his or her needs.</para>
+
+    <sect2 id="csup-doc">
+      <title>Using <application>CVSup</application></title>
+
+      <para>Similar to the base system and kernel sources (<link
+	  linkend="makeworld">the <quote>world</quote></link>),
+	documentation itself could be also updated by rebuilding it on
+	a regular basis.  To achieve this, one will need
+	<application>CVSup</application> and the tools used in the &os;
+	Documentation Project to be installed:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r docproj</userinput>
+&prompt.root; <userinput>pkg_add -r cvsup-without-gui</userinput></screen>
+
+      <note>
+	<para>When no &postscript; or PDF documentation required, one
+	  might consider installing <filename
+	    role="package">textproc/docproj-nojadetex</filename>
+	  instead.</para>
+      </note>
+
+      <para>For the first time, source for the documentation set need to
+	be checked out:</para>
+
+      <screen>&prompt.root; <userinput>cvsup -h <replaceable>cvsup10.FreeBSD.org</replaceable> -g -L 2 /usr/share/examples/cvsup/doc-supfile</userinput></screen>
+
+      <para>Once <filename class="directory">/usr/doc</filename>
+	has been established, updating documentation is just as easy as
+	the commands below:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make update install clean</userinput></screen>
+
+      <para>The following &man.make.1; variables can be used for
+	controlling the process of update.  Note that their default
+	values can be modified by adding them to
+	<filename>/etc/make.conf</filename>, so they are not needed to
+	be set in the command line every time.</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><makevar>DOC_LANG</makevar></term>
+
+	  <listitem>
+	    <para>The list 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 involved in the process, see
+	&man.make.conf.5;.</para>
+    </sect2>
+
+    <sect2 id="docsnap">
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Pav</firstname>
+	    <surname>Lucistnik</surname>
+	    <contrib>Based on a home page written by </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+
+      <title>Using <application>Docsnap</application></title>
+
+      <para><application>Docsnap</application> is an
+	<application>rsync</application> repository for updating
+	installed &os; Documentation in a relatively easy and fast way.
+	In this method, a <quote><application>Docsnap</application>
+	  server</quote> tracks the documentation sources, and builds
+	them in HTML format every hour.  However, there is no need for
+	installing the port <filename
+	  role="package">textproc/docproj</filename>, because no SGML
+	sources needed to be built and the differences alone are
+	transmitted over the network.</para>
+
+      <para>The only requirement for using technique is the <filename
+	  role="package">net/rsync</filename> port or package:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r rsync</userinput></screen>
+
+      <note>
+	<para>It is originally recommended 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 even 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, given 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 accidentally would
+	get wiped out.  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, 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>