1.1 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml	Tue Jan 06 19:33:19 2009 +0200
     1.2 +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml	Tue Jan 06 19:38:38 2009 +0200
     1.3 @@ -79,6 +79,12 @@
     1.4        </listitem>
     1.5  
     1.6        <listitem>
     1.7 +	<para>How to keep your documentation up to date with
     1.8 +	  <application>CVSup</application> and
     1.9 +	  <application>Docsnap</application>.</para>
    1.10 +      </listitem>
    1.11 +
    1.12 +      <listitem>
    1.13  	<para>The difference between the two development
    1.14  	  branches: &os.stable; and &os.current;.</para>
    1.15        </listitem>
    1.16 @@ -698,6 +704,324 @@
    1.17      <screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
    1.18    </sect1>
    1.19  
    1.20 +  <sect1 id="updating-upgrading-documentation">
    1.21 +    <title>Updating the Documentation Set</title>
    1.22 +
    1.23 +    <indexterm><primary>Updating and Upgrading</primary></indexterm>
    1.24 +
    1.25 +    <indexterm>
    1.26 +      <primary>Documentation</primary>
    1.27 +      <see>Updating and Upgrading</see>
    1.28 +    </indexterm>
    1.29 +
    1.30 +    <para>Besides the base system and the Ports Collection,
    1.31 +      documentation is an integral part of the &os; operating system.
    1.32 +      While an up-to-date version of the &os; Documentation Set is
    1.33 +      always available on the <ulink
    1.34 +	url="http://www.freebsd.org/doc/">&os; web site</ulink>, some
    1.35 +      users might have slow or no permanent network connectivity at all.
    1.36 +      Fortunately, there are several ways to update the documentation
    1.37 +      shipped with each release by maintaining a local copy of the
    1.38 +      latest &os; Documentation Set.</para>
    1.39 +
    1.40 +    <sect2 id="csup-doc">
    1.41 +      <title>Using CVSup to Update the Documentation</title>
    1.42 +
    1.43 +      <para>The sources and the installed copy of the &os; documentation
    1.44 +        can be updated with <application>CVSup</application>, using a
    1.45 +        mechanism similar to the one employed for the base system
    1.46 +        sources (c.f. <xref linkend="makeworld">).  This section
    1.47 +        describes:</para>
    1.48 +
    1.49 +      <itemizedlist>
    1.50 +	<listitem>
    1.51 +	  <para>How to install the documentation toolchain, the tools
    1.52 +	    that are required to rebuild the &os; documentation from its
    1.53 +	    source.</para>
    1.54 +	</listitem>
    1.55 +
    1.56 +	<listitem>
    1.57 +	  <para>How to download a copy of the documentation source
    1.58 +	    at <filename class="directory">/usr/doc</filename>,
    1.59 +	    using <application>CVSup</application>.</para>
    1.60 +	</listitem>
    1.61 +
    1.62 +	<listitem>
    1.63 +	  <para>How to rebuild the &os; documentation from its source,
    1.64 +	    and install it
    1.65 +	    under <filename class="directory">/usr/share/doc</filename>.</para>
    1.66 +	</listitem>
    1.67 +
    1.68 +	<listitem>
    1.69 +	  <para>Some of the build options that are supported by the
    1.70 +	    build system of the documentation, i.e. the options that
    1.71 +	    build only some of the different language translations of
    1.72 +	    the documentation or the options that select a specific
    1.73 +	    output format.</para>
    1.74 +	</listitem>
    1.75 +      </itemizedlist>
    1.76 +    </sect2>
    1.77 +
    1.78 +    <sect2 id="installing-documentation-toolchain">
    1.79 +      <title>Installing CVSup and the Documentation Toolchain</title>
    1.80 +
    1.81 +      <para>Rebuilding the &os; documentation from source requires a
    1.82 +	fairly large collection of tools.  These tools are not part of
    1.83 +	the &os; base system, because they need a large amount of disk
    1.84 +	space and they are not useful to all &os; users; they are only
    1.85 +	useful to those users that are actively writing new
    1.86 +	documentation for &os; or are frequently updating their
    1.87 +	documentation from source.</para>
    1.88 +
    1.89 +      <para>All the required tools are available as part of the Ports
    1.90 +	Collection.  The <filename
    1.91 +	  role="package">textproc/docproj</filename> port is a master
    1.92 +	port that has been developed by the &os; Documentation Project,
    1.93 +	to ease the initial installation and future updates of these
    1.94 +	tools.</para>
    1.95 +
    1.96 +      <note>
    1.97 +	<para>When no &postscript; or PDF documentation required, one
    1.98 +	  might consider installing the <filename
    1.99 +	    role="package">textproc/docproj-nojadetex</filename> port
   1.100 +	  instead.  This version of the documentation toolchain includes
   1.101 +	  everything except the <application>teTeX</application>
   1.102 +	  typesetting engine.  <application>teTeX</application> is a
   1.103 +	  very large collection of tools, so it may be quite sensible to
   1.104 +	  omit its installation if PDF output is not really
   1.105 +	  necessary.</para>
   1.106 +      </note>
   1.107 +
   1.108 +      <para>For more information on installing and using
   1.109 +	<application>CVSup</application>, see <link
   1.110 +	  linkend="cvsup">Using CVSup</link>.</para>
   1.111 +    </sect2>
   1.112 +
   1.113 +    <sect2 id="updating-documentation-sources">
   1.114 +      <title>Updating the Documentation Sources</title>
   1.115 +
   1.116 +      <para>The <application>CVSup</application> utility can fetch a
   1.117 +	clean copy of the documentation sources, using
   1.118 +	the <filename>/usr/share/examples/cvsup/doc-supfile</filename>
   1.119 +	file as a configuration template.  The default update host is
   1.120 +	set to a placeholder value in <filename>doc-supfile</filename>,
   1.121 +	but &man.cvsup.1; accepts a host name through the command line,
   1.122 +	so the documentation sources can be fetched from one of the
   1.123 +	<application>CVSup</application> servers by typing:</para>
   1.124 +
   1.125 +      <screen>&prompt.root; <userinput>cvsup -h <replaceable>cvsup.FreeBSD.org</replaceable> -g -L 2 <filename>/usr/share/examples/cvsup/doc-supfile</filename></userinput></screen>
   1.126 +
   1.127 +      <para>Change <replaceable>cvsup.FreeBSD.org</replaceable> to the
   1.128 +	nearest <application>CVSup</application> server.  See <xref
   1.129 +	  linkend="cvsup-mirrors"> for a complete listing of mirror
   1.130 +	sites.</para>
   1.131 +
   1.132 +      <para>The initial download of the documentation sources may take a
   1.133 +	while.  Let it run until it completes.</para>
   1.134 +
   1.135 +      <para>Future updates of the documentation sources may be fetched
   1.136 +	by running the same command.
   1.137 +	The <application>CVSup</application> utility downloads and
   1.138 +	copies only the updates since the last time it ran, so every run
   1.139 +	of <application>CVSup</application> after the first complete run
   1.140 +	should be pretty fast.</para>
   1.141 +
   1.142 +      <para>After checking out the sources, an alternative way of
   1.143 +	updating the documentation is supported by the
   1.144 +	<filename>Makefile</filename> of the <filename
   1.145 +	  class="directory">/usr/doc</filename> directory.  By setting
   1.146 +	<makevar>SUP_UPDATE</makevar>, <makevar>SUPHOST</makevar> and
   1.147 +	<makevar>DOCSUPFILE</makevar> in the
   1.148 +	<filename>/etc/make.conf</filename> file, it is possible to
   1.149 +	run:</para>
   1.150 +
   1.151 +      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
   1.152 +&prompt.root; <userinput>make update</userinput></screen>
   1.153 +
   1.154 +      <para>A typical set of these &man.make.1; options
   1.155 +	for <filename>/etc/make.conf</filename> is:</para>
   1.156 +
   1.157 +      <programlisting>SUP_UPDATE= yes
   1.158 +SUPHOST?= cvsup.freebsd.org
   1.159 +DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
   1.160 +
   1.161 +      <note>
   1.162 +	<para>Setting the <makevar>SUPHOST</makevar>
   1.163 +	  and <makevar>DOCSUPFILE</makevar> value
   1.164 +	  with <literal>?=</literal> permits overriding them in the
   1.165 +	  command-line of make.  This is the recommended way of adding
   1.166 +	  options to <filename>make.conf</filename>, to avoid having to
   1.167 +	  edit the file every time a different option value has to be
   1.168 +	  tested.</para>
   1.169 +      </note>
   1.170 +    </sect2>
   1.171 +
   1.172 +    <sect2 id="updating-documentation-options">
   1.173 +      <title>Tunable Options of the Documentation Sources</title>
   1.174 +
   1.175 +      <para>The updating and build system of the &os; documentation
   1.176 +	supports a few options that ease the process of updating only
   1.177 +	parts of the documentation, or the build of specific
   1.178 +	translations.  These options can be set either as system-wide
   1.179 +	options in the <filename>/etc/make.conf</filename> file, or as
   1.180 +	command-line options passed to the &man.make.1; utility.</para>
   1.181 +
   1.182 +      <para>The following options are some of these:</para>
   1.183 +
   1.184 +      <variablelist>
   1.185 +	<varlistentry>
   1.186 +	  <term><makevar>DOC_LANG</makevar></term>
   1.187 +
   1.188 +	  <listitem>
   1.189 +	    <para>The list of languages and encodings to build and
   1.190 +	      install, e.g. <literal>en_US.ISO8859-1</literal> for the
   1.191 +	      English documentation only.</para>
   1.192 +	  </listitem>
   1.193 +	</varlistentry>
   1.194 +
   1.195 +	<varlistentry>
   1.196 +	  <term><makevar>FORMATS</makevar></term>
   1.197 +
   1.198 +	  <listitem>
   1.199 +	    <para>A single format or a list of output formats to be
   1.200 +	      built.  Currently, <literal>html</literal>,
   1.201 +	      <literal>html-split</literal>, <literal>txt</literal>,
   1.202 +	      <literal>ps</literal>, <literal>pdf</literal>,
   1.203 +	      and <literal>rtf</literal> are supported.</para>
   1.204 +	  </listitem>
   1.205 +	</varlistentry>
   1.206 +
   1.207 +	<varlistentry>
   1.208 +	  <term><makevar>SUPHOST</makevar></term>
   1.209 +
   1.210 +	  <listitem>
   1.211 +	    <para>The hostname of the <application>CVSup</application>
   1.212 +	      server to use when updating.</para>
   1.213 +	  </listitem>
   1.214 +	</varlistentry>
   1.215 +      </variablelist>
   1.216 +
   1.217 +      <para>For more make variables supported as system-wide options in
   1.218 +	&os;, see &man.make.conf.5;.</para>
   1.219 +
   1.220 +      <para>For more make variables supported by the build system of the
   1.221 +	&os; documentation, please refer to
   1.222 +	the <ulink url="&url.doc.langbase;/books/fdp-primer">&os;
   1.223 +	  Documentation Project Primer for New Contributors</ulink>.</para>
   1.224 +    </sect2>
   1.225 +
   1.226 +    <sect2 id="updating-installed-documentation">
   1.227 +      <title>Installing the &os; Documentation from Source</title>
   1.228 +
   1.229 +      <para>When an up-to-date snapshot of the documentation sources has
   1.230 +	been fetched in <filename class="directory">/usr/doc</filename>,
   1.231 +	everything is ready for an update of the installed
   1.232 +	documentation.</para>
   1.233 +
   1.234 +      <para>A full update of all the languages defined in
   1.235 +	the <makevar>DOC_LANG</makevar> makefile option may be done by
   1.236 +	typing:</para>
   1.237 +
   1.238 +      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
   1.239 +&prompt.root; <userinput>make install clean</userinput></screen>
   1.240 +
   1.241 +      <para>If <filename>make.conf</filename> has been set up with the
   1.242 +	correct <makevar>DOCSUPFILE</makevar>, <makevar>SUPHOST</makevar>
   1.243 +	and <makevar>SUP_UPDATE</makevar> options, the install step may
   1.244 +	be combined with an update of the documentation sources by
   1.245 +	typing:</para>
   1.246 +
   1.247 +      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
   1.248 +&prompt.root; <userinput>make update install clean</userinput></screen>
   1.249 +
   1.250 +      <para>If an update of only a specific language is desired,
   1.251 +	&man.make.1; can be invoked in a language specific subdirectory
   1.252 +	of <filename class="directory">/usr/doc</filename>, i.e.:</para>
   1.253 +
   1.254 +      <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
   1.255 +&prompt.root; <userinput>make update install clean</userinput></screen>
   1.256 +
   1.257 +      <para>The output formats that will be installed may be specified
   1.258 +	by setting the <makevar>FORMATS</makevar> make variable,
   1.259 +	i.e.:</para>
   1.260 +
   1.261 +      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
   1.262 +&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
   1.263 +    </sect2>
   1.264 +
   1.265 +    <sect2 id="docsnap">
   1.266 +      <sect2info>
   1.267 +	<authorgroup>
   1.268 +	  <author>
   1.269 +	    <firstname>Pav</firstname>
   1.270 +	    <surname>Lucistnik</surname>
   1.271 +	    <contrib>Based on information provided by </contrib>
   1.272 +	  </author>
   1.273 +	</authorgroup>
   1.274 +      </sect2info>
   1.275 +
   1.276 +      <title>Using Docsnap</title>
   1.277 +
   1.278 +      <indexterm><primary>Updating and Upgrading</primary></indexterm>
   1.279 +
   1.280 +      <indexterm>
   1.281 +	<primary>Docsnap</primary>
   1.282 +	<see>Updating and Upgrading</see>
   1.283 +      </indexterm>
   1.284 +
   1.285 +      <para><application>Docsnap</application> is an &man.rsync.1;
   1.286 +	repository for updating installed &os; Documentation in a
   1.287 +	relatively easy and fast way.  A
   1.288 +	<quote><application>Docsnap</application> server</quote> tracks
   1.289 +	the documentation sources, and builds them in HTML format every
   1.290 +	hour.  The <filename role="package">textproc/docproj</filename>
   1.291 +	is unneeded with <application>Docsnap</application> as only
   1.292 +	patches to the built documentation exist.</para>
   1.293 +
   1.294 +      <para>The only requirement for using this technique is
   1.295 +	the <filename role="package">net/rsync</filename> port or
   1.296 +	package.  To add it, use the following command:</para>
   1.297 +
   1.298 +      <screen>&prompt.root; <userinput>pkg_add -r rsync</userinput></screen>
   1.299 +
   1.300 +      <note>
   1.301 +	<para><application>Docsnap</application> has been originally
   1.302 +	  developed for updating documentation installed
   1.303 +	  to <filename class="directory">/usr/share/doc</filename>, but
   1.304 +	  the following examples could be adapted for other directories
   1.305 +	  as well.  For user directories, it does not require
   1.306 +	  <username>root</username> privileges.</para>
   1.307 +      </note>
   1.308 +
   1.309 +      <para>To update the documentation set, issue the following
   1.310 +	command:</para>
   1.311 +
   1.312 +      <screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap <replaceable>/usr/share/doc</replaceable></userinput></screen>
   1.313 +
   1.314 +      <note>
   1.315 +	<para>There is only one <application>Docsnap</application>
   1.316 +	  server at the moment;
   1.317 +	  the <hostid>docsnap.sk.FreeBSD.org</hostid> shown
   1.318 +	  above.</para>
   1.319 +      </note>
   1.320 +
   1.321 +      <para>Do not use the <option>--delete</option> flag here as there
   1.322 +	are some items installed
   1.323 +	into <filename class="directory">/usr/share/doc</filename>
   1.324 +	during <command>make installworld</command>, which would
   1.325 +	accidentally be removed.  To clean up, use this command
   1.326 +	instead:</para>
   1.327 +
   1.328 +      <screen>&prompt.root; <userinput>rsync -rltvz --delete <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/??_??\.\* <replaceable>/usr/share/doc</replaceable></userinput></screen>
   1.329 +
   1.330 +      <para>If a subset of documentation needs to be updated, for
   1.331 +	example, the English documentation only, the following command
   1.332 +	should be used:</para>
   1.333 +
   1.334 +      <screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/en_US.ISO8859-1 <replaceable>/usr/share/doc</replaceable></userinput></screen>
   1.335 +    </sect2>
   1.336 +  </sect1>
   1.337 +
   1.338    <sect1 id="current-stable">
   1.339      <title>Tracking a Development Branch</title>
   1.340      <indexterm><primary>-CURRENT</primary></indexterm>