os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update the cutting-edge chapter for obtaining/updating the FreeBSD

Browse source 
Documentation Project sources to reflect the CVS->SVN conversion.

Submitted by:	ryusuke (originally)
This commit is contained in:
Glen Barber 2012-08-20 12:08:49 +00:00
parent 421beffdb7
commit e6eb16da67
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=39399
1 changed files with 19 additions and 73 deletions

92
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
View file

@ -736,14 +736,12 @@ Fetching 133 new ports or files... done.</screen>
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>
<sect2 id="dsvn-doc">
<title>Using <application>Subversion</application> 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>
<para>The &os; documentation sources can be obtained with
<application>Subversion</application>. This section
describes:</para>
<itemizedlist>
<listitem>
@ -755,7 +753,7 @@ Fetching 133 new ports or files... done.</screen>
<listitem>
<para>How to download a copy of the documentation source
at <filename class="directory">/usr/doc</filename>,
using <application>CVSup</application>.</para>
using <application>Subversion</application>.</para>
</listitem>
<listitem>
@ -775,7 +773,7 @@ Fetching 133 new ports or files... done.</screen>
</sect2>
<sect2 id="installing-documentation-toolchain">
<title>Installing CVSup and the Documentation Toolchain</title>
<title>Installing <application>Subversion</application> 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
@ -804,68 +802,34 @@ Fetching 133 new ports or files... done.</screen>
necessary.</para>
</note>
<para>For more information on installing and using
<application>CVSup</application>, see <link
linkend="cvsup">Using CVSup</link>.</para>
<para><application>Subversion</application> is installed with
the <filename role="package">textproc/docproj</filename>
port.</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 by typing:</para>
<para>The <application>Subversion</application> program can fetch a
clean copy of the documentation sources by typing:</para>
<screen>&prompt.root; <userinput>cvsup -h <replaceable>cvsup.FreeBSD.org</replaceable> -g -L 2 <filename>/usr/share/examples/cvsup/doc-supfile</filename></userinput></screen>
<para>Change <replaceable>cvsup.FreeBSD.org</replaceable> to the
nearest <application>CVSup</application> server. See <xref
linkend="cvsup-mirrors"> for a complete listing of mirror
sites.</para>
<screen>&prompt.root; <userinput>svn checkout <literal>svn://svn.FreeBSD.org/doc/head</literal> <filename class="directory">/usr/doc</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>
by running:</para>
<screen>&prompt.root; <userinput>svn update <filename class="directory">/usr/doc</filename></userinput></screen>
<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>
class="directory">/usr/doc</filename> directory by running:</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?= cvsup.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">
@ -903,15 +867,6 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
</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>
<varlistentry>
<term><makevar>DOCDIR</makevar></term>
@ -947,15 +902,6 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
<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>
@ -997,7 +943,7 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
though. Building the documentation sources requires a fairly
large collection of tools and utilities, the
<emphasis>documentation toolchain</emphasis>, a certain level of
familiarity with <application>CVS</application> and source
familiarity with <application>Subversion</application> and source
checkouts from a repository, and a few manual steps to build the
checked out sources. In this section, we describe an
alternative way of updating the installed copies of the &os;
@ -1129,7 +1075,7 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
<note>
<para>Notice that the default target directory
differs from the directory used by the
<application>CVSup</application> method. This is
<application>Subversion</application> method. This is
because we are installing a port, and ports are
usually installed under the <filename
class="directory">/usr/local</filename> directory.