A major revamp of the website build procedure in fdp-primer:

- Added a simple method using csup instead of keeping a local CVS repo
- Introduce working examples of supfiles for use with both csup and CVSup
- Fixed the command line options in 'cvs co' to avoid problems with the build
- Updated the free disk space requirements for a website build
- Clear up use of DESTDIR to avoid problems when installing the build

Reviewed by:    pgj
Approved by:    gabor (mentor)

1 files changed, 265 insertions, 82 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
index 4caa2ef8d4..c6b2af3cfa 100644
--- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
@@ -32,86 +32,264 @@
 
 <chapter id="the-website">
   <title>The Website</title>
-  
+
   <sect1 id="the-website-prep">
     <title>Preparation</title>
-    
-    <para>Get 200MB free disk space. You will need the disk space for the
-      SGML tools, a subset of the CVS tree, temporary build space and the
-      installed web pages. If you already have installed the SGML tools and
-      the CVS tree, you need only ~100MB free disk space.</para>
-    
+
+    <para>Use a disk with sufficient free space.  You may need anything from
+      200&nbsp;MB to over 500&nbsp;MB, depending on the method you choose.
+      This space will hold the SGML tools, a subset of the
+      <application>CVS</application> tree, temporary build space and the
+      installed web pages.</para>
+
     <note>
       <para>Make sure your documentation ports are up to date!  When in
 	doubt, remove the old ports using &man.pkg.delete.1; command before
 	installing the port.  For example, we currently depend on
 	jade-1.2 and if you have installed jade-1.1, please do:</para>
 
-      <screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen>
+      <screen>&prompt.root; <userinput><command>pkg_delete</command> jade-1.1</userinput></screen>
     </note>
 
-    <para>Set up a CVS repository. You need the directories www, doc and
-      ports in the CVS tree (plus the CVSROOT of course).  Please read the
-      <ulink url="&url.books.handbook;/synching.html#CVSUP">CVSup introduction</ulink>
-      on how to mirror a CVS tree or parts of a CVS tree.</para>
-    
-    <para>The essential cvsup collections are: <literal>www</literal>,
-      <literal>doc-all</literal>, <literal>cvs-base</literal>, and
-      <literal>ports-base</literal>.</para>
-    
-    <para>These collections require ~105MB free disk space.</para>
-    
-    <para>A full CVS tree - including <literal>src</literal>,
-      <literal>doc</literal>, <literal>www</literal>, and
-      <literal>ports</literal> - is currently 940MB.</para>
+    <para>There are two methods to get the files required for the website
+      build:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Use <command>csup</command> to get a local copy of the files
+	  from a <application>CVSup</application> server.  This is the
+	  easiest method, and does not require installation of additional
+	  software.  The supfile presented in the next section will always
+	  checkout the latest version of the required files.  This is
+	  sufficient if you are simply rebuilding the website and do not
+	  intend to commit any changes.</para>
+
+	<note>
+	  <para>&man.csup.1; became part of the base system in
+	    &os;&nbsp;6.2-RELEASE. If you are using an earlier version of &os;
+	    you will need to install <filename role="port">net/csup</filename>
+	    from the Ports&nbsp;Collection.</para>
+	</note> 	
+      </listitem>
+
+      <listitem>
+	<para>Use <command>cvsup</command> in <quote>cvs</quote> mode to
+	  create and maintain a local <application>CVS</application>
+	  repository with the required files.  This will require you to
+	  install a program like
+	  <filename role="package">net/cvsup-without-gui</filename>, but it is
+	  a more flexible method if you need to have quick access to different
+	  revisions of the doc/www files, revision histories, or if you
+	  intend to commit changes to the central &os;
+	  <application>CVS</application> repository.</para>
+      </listitem>
+    </itemizedlist>
+
+    <sect2 id="the-website-csup">
+      <title>Simple method: Using <command>csup</command></title>
+
+      <para>The <command>csup</command> command is part of the base system and
+	already used extensively by most people for updating the
+	Ports&nbsp;Collection.  The following sample supfile can be used to
+	obtain a checkout of the files required for the website build:</para>
+
+      <programlisting>#
+# This file checks out all collections required to rebuild
+# the FreeBSD website
+#
+# Use the nearest CVSup mirror
+# listed at http://www.freebsd.org/doc/handbook/mirrors.html.
+
+*default host=<replaceable>cvsup10.FreeBSD.org</replaceable>
+*default base=/var/db
+*default prefix=<replaceable>/usr/build</replaceable>
+*default release=cvs tag=.
+*default delete use-rel-suffix
+*default compress
+
+# This will retrieve the entire doc branch of the FreeBSD repository.
+
+doc-all
+
+# This will retrieve the files required for the website
+
+www
+
+# This will retrieve some basic ports info required for the build
+
+ports-base</programlisting>
+
+      <para>You should, of course, change the <literal>default host</literal>
+	entry to a <application>CVSup</application> mirror near your
+	location, and the <literal>default prefix</literal> entry to the
+	location where you intend to store the checked out files.  Save this
+	file as e.g.
+	<filename><replaceable>doc-www-supfile</replaceable></filename>, and
+	then execute the following command:</para>
+
+      <screen>&prompt.root; <userinput><command>csup</command> <option>-g</option> <option>-L2</option> <replaceable>doc-www-supfile</replaceable></userinput></screen>
+
+      <para>When this command finishes, you will find the directories
+	<filename role="directory">doc/</filename>,
+	<filename role="directory">www/</filename> and
+	<filename role="directory">ports/</filename> under the directory you
+	specified in <literal>default prefix</literal>
+	(<filename
+	  role="directory"><replaceable>/usr/build</replaceable></filename>
+	in our example).  We will use this same directory for the build
+	process itself, so it would be better to use a filesystem with
+	sufficient free space.</para>
+
+      <para>That's it! You can now proceed with the
+	<link linkend="the-website-build">website build</link>.</para>
+    </sect2>
+
+    <sect2 id="the-website-cvsup">
+      <title>Advanced method: Maintaining a local
+	<application>CVS</application> doc/www repository</title>
+
+      <para>This method will give you more advanced options, but will require
+	you to install the
+	<filename role="port">net/cvsup-without-gui</filename> port or
+	package.</para>
+
+      <note>
+	<para>The <filename role="port">net/cvsup-without-gui</filename>
+	  port has a build dependency on
+	  <filename role="port">lang/ezm3</filename>, a Modula&nbsp;3
+	  compiler.  This compiler takes quite some time to build, and since
+	  most people will not need it for anything else, it is perhaps best
+	  to use a package to install <application>CVSup</application>.</para>
+      </note>
+
+      <para>The <application>CVSup</application> utility has a special
+	<quote>cvs</quote> mode that allows the retrieval of the
+	<quote>,v</quote> files that make up a <application>CVS</application>
+	repository.  This function is not currently available in
+	<application>csup</application>.  For detailed information on
+	<application>CVSup</application>, please read the <ulink
+	   url="&url.books.handbook;/synching.html#CVSUP">CVSup introduction</ulink> in the &os;&nbsp;Handbook.</para>
+
+      <para>The supfile shown below will fetch the cvs collections required
+	for the website build, and create a local
+	<application>CVS</application> repository:</para>
+
+      <programlisting>#
+# This file will create a local CVS repository
+# with the collections required for a complete
+# FreeBSD website rebuild. It should be used with
+# cvsup *only* (csup will not work)
+
+*default host=<replaceable>cvsup10.FreeBSD.org</replaceable>
+*default base=/var/db
+*default prefix=<replaceable>/usr/dcvs</replaceable>
+*default release=cvs
+*default delete use-rel-suffix
+*default compress
+
+# The following collections are needed
+# for the website build
+
+ports-base
+doc-all
+www
+
+# These collections are needed
+# for CVS functionality
+
+cvsroot-common
+cvsroot-ports
+cvsroot-doc</programlisting>
+
+      <para>You should, of course, change the <literal>default host</literal>
+	entry to a <application>CVSup</application> mirror near your
+	location, and the <literal>default prefix</literal> entry to the
+	location where you intend to store the repository files.  Save this
+	file as e.g.
+	<filename><replaceable>doc-www-cvsfile</replaceable></filename>, and
+	then execute the following command:</para>
+
+      <screen>&prompt.root; <userinput><command>cvsup</command> <option>-g</option> <option>-L2</option> <replaceable>doc-www-cvsfile</replaceable></userinput></screen>
+
+      <para>It is also advisable to set the <envar>CVSROOT</envar> environment
+	variable in your shell's startup files.  For example, use
+	the following entry in your <filename>~/.cshrc</filename> file:</para>
+
+      <programlisting>setenv <envar>CVSROOT</envar> <replaceable>/usr/dcvs</replaceable></programlisting>
+
+      <para>If you set this variable, you may omit the <option>-d</option>
+	argument (shown below) when performing repository operations using
+	the <command>cvs</command> command.</para>
+
+      <para>Currently, you will need more than 400&nbsp;MB of free space to
+	host the repository files.  An additional 200&nbsp;MB will be needed
+	for the temporary build space.  Once the <command>cvsup</command>
+	command completes, you are ready to check out the files to your build
+	directory:</para>
+
+      <screen>&prompt.root; <userinput><command>mkdir</command> <replaceable>/usr/build</replaceable></userinput>
+&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build</replaceable></userinput>
+&prompt.root; <userinput><command>cvs</command> <option>-d</option> <replaceable>/usr/dcvs</replaceable> <option>-R</option> co <option>-AP</option> doc www ports</userinput></screen>
+
+      <para>The above command is consistent with the way
+	<application>csup</application> checks out the files from the
+	<application>CVSup</application> servers.  When it completes, you
+	will have a build directory with similar contents to the one used in
+	the simple <application>csup</application> method.</para>
+
+      <para>You can continue to use the <command>cvsup</command> command
+	shown above, to update your local <application>CVS</application>
+	repository on a regular basis.  After the initial somewhat lengthy
+	download, regular updates will only take a few minutes.</para>
+    </sect2>
   </sect1>
-  
+
   <sect1 id="the-website-build">
     <title>Build the web pages from scratch</title>
-    
-    <procedure> 
-      <step>
-	<para>Create and change directory into a build directory with at least 60MB of free
-	  space.</para>
-	
-	<screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput>
-&prompt.root; <userinput>cd /var/tmp/webbuild</userinput></screen>
-      </step>
 
+    <para>Having completed either of the two methods, you will be ready to
+      start the website build.  In our example, the build directory is
+      <filename
+	 role="directory"><replaceable>/usr/build</replaceable></filename>
+      and all the required files are already in place.</para>
+
+    <procedure>
       <step>
-	<para>Checkout the SGML files from the CVS tree.</para>
-	
-	<screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen>
+	<para>Change into the build directory:</para>
+
+	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build</replaceable></userinput></screen>
       </step>
 
       <step>
-	<para>Change into the <filename role="directory">www/en</filename> directory, and run
+	<para>The website build starts from the
+	  <filename role="directory">www/en</filename> directory by executing
 	  the &man.make.1; <maketarget>all</maketarget> target, to create
 	  the web pages.</para>
-	
-	<screen>&prompt.root; <userinput>cd www/en</userinput>
-&prompt.root; <userinput>make all</userinput></screen>
+
+	<screen>&prompt.root; <userinput><command>cd</command> www/en</userinput>
+&prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>
       </step>
     </procedure>
   </sect1>
-  
+
   <sect1 id="the-website-install">
     <title>Install the web pages into your web server</title>
-    
+
     <procedure>
       <step>
-	<para>If you have moved out of the <filename>en</filename>
-	  directory, change back to it.</para>
-	
-	  <screen>&prompt.root; <userinput>cd <replaceable>path</replaceable>/www/en</userinput></screen>
+	<para>If you have moved out of the
+	  <filename role="directory">en</filename> directory, change back to
+	  it.</para>
+
+	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/www/en</replaceable></userinput></screen>
       </step>
 
       <step>
 	<para>Run the &man.make.1; <maketarget>install</maketarget> target,
-	  setting the <makevar>DESTDIR</makevar> variable to the name of the 
+	  setting the <makevar>DESTDIR</makevar> variable to the name of the
 	  directory you want to install the files to.</para>
-	
-	<screen>&prompt.root; <userinput>make DESTDIR=<replaceable>/usr/local/www</replaceable> install</userinput></screen>
+
+	<screen>&prompt.root; <userinput><command>env</command> <makevar>DESTDIR</makevar>=<replaceable>/usr/local/www</replaceable> <command>make</command> <maketarget>install</maketarget></userinput></screen>
       </step>
 
       <step>
@@ -120,81 +298,86 @@
 	  outdated pages.  For example, if you build and install a new copy
 	  of the site every day, this command will find and delete all
 	  files that have not been updated in three days.</para>
-	
-	<screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -print0 | xargs -0 rm</userinput></screen>
+
+	<screen>&prompt.root; <userinput><command>find</command> <replaceable>/usr/local/www</replaceable> <option>-ctime</option> 3 <option>-print0</option> | <command>xargs</command> <option>-0</option> <command>rm</command></userinput></screen>
       </step>
     </procedure>
   </sect1>
-  
+
   <sect1 id="the-website-env">
     <title>Environment variables</title>
-    
+
     <variablelist>
       <varlistentry>
 	<term><envar>CVSROOT</envar></term>
-	
+
 	<listitem>
-	  <para>Location of the CVS tree. Essential.</para>
-	  
-	  <screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen>
+	  <para>Location of the CVS tree.  We suggest you set this
+	    variable, if you use the <application>CVSup</application>
+	    method:</para>
+
+	  <screen><userinput>&prompt.root; <makevar>CVSROOT</makevar>=<replaceable>/usr/dcvs</replaceable>; <command>export</command> <makevar>CVSROOT</makevar></userinput></screen>
+
+	  <para><envar>CVSROOT</envar> is an environment variable.  You must
+	    set it on the command line or in your dot files
+	    (e.g., <filename>~/.profile</filename>).  The exact syntax will
+	    differ depending on your shell (the above example is for
+	    <application>bash</application> and bash-like shells).</para>
 	</listitem>
       </varlistentry>
-	
+
       <varlistentry>
 	<term><makevar>ENGLISH_ONLY</makevar></term>
-	
+
 	<listitem>
 	  <para>If set and not empty, the makefiles will build and
-	    install only the English documents. All translations will be
-	    ignored. E.g.:</para>
-	  
-	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen>
+	    install only the English documents.  All translations will be
+	    ignored.  E.g.:</para>
+
+	  <screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen>
 
 	  <para>If you want to unset the variable
 	    <makevar>ENGLISH_ONLY</makevar> and build all pages, including
 	    translations, set the variable <makevar>ENGLISH_ONLY</makevar>
 	    to an empty value:</para>
-	  
-	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
+
+	  <screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=""</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen>
 	</listitem>
       </varlistentry>
-      
+
       <varlistentry>
 	<term><makevar>WEB_ONLY</makevar></term>
-	
+
 	<listitem>
 	  <para>If set and not empty, the makefiles will build and install
-	    only the HTML pages from the www directory. All documents from
-	    the doc directory (Handbook, FAQ, Tutorials) will be ignored.
-	    E.g.:</para>
-	  
-	  <screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen>
+	    only the HTML pages from the www directory.  All documents from
+	    the <filename role="directory">doc</filename> directory (Handbook,
+	    FAQ, Tutorials) will be ignored.  E.g.:</para>
+
+	  <screen>&prompt.root; <userinput><command>make</command> <makevar>WEB_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen>
 	</listitem>
       </varlistentry>
-	
+
       <varlistentry>
 	<term><makevar>NOPORTSCVS</makevar></term>
-	
+
 	<listitem>
 	  <para>If set, the makefiles will not checkout files from the ports
-	    cvs repository. Instead, it will copy the files from
-	    <filename>/usr/ports</filename> (or where the variable
-	    <envar>PORTSBASE</envar> points to).</para>
+	    cvs repository.  Instead, it will copy the files from
+	    <filename role="directory">/usr/ports</filename> (or where the
+	    variable <envar>PORTSBASE</envar> points to).</para>
 	</listitem>
       </varlistentry>
     </variablelist>
-    
-    <para><envar>CVSROOT</envar> is an environment variable. You must set it
-      on the command line or in your dot files (e.g., ~/.profile).</para>
-    
+
     <para><makevar>WEB_ONLY</makevar>, <makevar>ENGLISH_ONLY</makevar> and
-      <makevar>NOPORTSCVS</makevar> are makefile variables. You can set the
+      <makevar>NOPORTSCVS</makevar> are make variables.  You can set the
       variables in <filename>/etc/make.conf</filename>,
       <filename>Makefile.inc</filename>, as environment variables on the
       command line, or in your dot files.</para>
   </sect1>
 </chapter>
-  
+
 <!--
      Local Variables:
      mode: sgml