Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 20 May 2012 20:07:11 +0000 (UTC)
From:      Glen Barber <gjb@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r38856 - head/en_US.ISO8859-1/books/fdp-primer/the-website
Message-ID:  <201205202007.q4KK7BHY013352@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: gjb
Date: Sun May 20 20:07:11 2012
New Revision: 38856
URL: http://svn.freebsd.org/changeset/doc/38856

Log:
  Update the FDP Primer "The Website" chapter for the CVS->SVN
  repository conversion:
  
  - Replace the 'the-website-csup' and 'the-website-cvsup' sections
    with a 'the-website-svn' section
  - Replace 'www/en' with 'en_US.ISO8859-1/htdocs' as the starting
    directory in the website build
  - Remove the documented CVSROOT environment variable
  - Update the WEB_LANG example to reflect the new repository layout
  - Add a 'tip' section, noting that if the initial 'svn checkout'
    command is not run as the root user, be sure that /usr/build is
    writable by the current user, or use a different checkout location

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml

Modified: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml	Sun May 20 19:56:00 2012	(r38855)
+++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml	Sun May 20 20:07:11 2012	(r38856)
@@ -39,7 +39,7 @@
     <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
+      subset of the <application>svn</application> tree, temporary
       build space and the installed web pages.</para>
 
     <note>
@@ -52,205 +52,49 @@
       <screen>&prompt.root; <userinput><command>pkg_delete</command> jade-1.1</userinput></screen>
     </note>
 
-    <para>There are two methods to get the files required for the
-      website build:</para>
+    <sect2 id="the-website-svn">
+      <title>Using <command>svn</command></title>
 
-    <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>
-      </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>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><command>csup</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 class="directory">doc/</filename>, <filename
-	  class="directory">www/</filename> and <filename
-	  class="directory">ports/</filename> under the directory you
-	specified in <literal>default prefix</literal> (<filename
-	  class="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><command>svn</command> is necessary to <quote>check
+	  out</quote> the necessary files from the
+	<literal>doc/</literal> Subversion repository.
+	<command>svn</command> can be installed with &man.pkg.add.1;
+	or from the &os; Ports Collection by running:</para>
+
+      <screen>&prompt.root; <userinput><command>cd /usr/ports/devel/subversion</command></userinput>
+&prompt.root; <userinput><command>make</command> <maketarget>install clean</maketarget></userinput></screen>
+
+      <para>To check out the full source files for the &os; website,
+	run:</para>
+
+      <screen>&prompt.root; <userinput><command>svn checkout svn://svn.FreeBSD.org/doc/head/ <replaceable>/usr/build</replaceable></command></userinput></screen>
+
+      <tip>
+	<para>If <command>svn</command> is not run as the
+	  <username>root</username>, be sure <filename
+	    class="directory">/usr/build</filename> has the proper
+	  permissions for the current user.  If changing the
+	  permissions is not possible, use a different target
+	  directory for the website files.</para>
+      </tip>
+
+      <para>When <command>svn</command> finishes, the current version
+	of the &os; website will exist within <filename
+	  class="directory">/usr/build</filename>.  If a different
+	target directory was used, replace <filename
+	  class="directory">/usr/build</filename> appropriately
+	throughout the remainder of this document.</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> <literal>doc/www</literal>
-	Repository</title>
-
-      <para>This method will give you more advanced options, but will
-	require you to install the
-	<filename>net/cvsup-without-gui</filename> port or
-	package.</para>
-
-      <note>
-	<para>The <filename>net/cvsup-without-gui</filename> port has
-	  a build dependency on <filename
-	    role="package">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
-	<filename>~/.cshrc</filename>:</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 <command>cvs</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
-	<command>cvsup</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 <command>cvsup</command> as 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>
 
-    <para>Having completed either of the two methods, you will be
-      ready to start the website build.  In our example, the build
+    <para>Having completed the necessary steps to obtain the website
+      source files, the website can be built.  In our example, the build
       directory is <filename
 	  class="directory"><replaceable>/usr/build</replaceable></filename>
       and all the required files are already in place.</para>
@@ -264,11 +108,11 @@ cvsroot-doc</programlisting>
 
       <step>
 	<para>The website build starts from the <filename
-	    class="directory">www/en</filename> directory by executing
+	    class="directory">en_US.ISO8859-1/htdocs</filename> directory by executing
 	  the &man.make.1; <maketarget>all</maketarget> target, to
 	  create the web pages.</para>
 
-	<screen>&prompt.root; <userinput><command>cd</command> www/en</userinput>
+	<screen>&prompt.root; <userinput><command>cd</command> en_US.ISO8859-1/htdocs</userinput>
 &prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>
       </step>
     </procedure>
@@ -280,10 +124,10 @@ cvsroot-doc</programlisting>
     <procedure>
       <step>
 	<para>If you have moved out of the <filename
-	    class="directory">en</filename> directory, change back to
+	    class="directory">en_US.ISO8859-1/htdocs</filename> directory, change back to
 	  it.</para>
 
-	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/www/en</replaceable></userinput></screen>
+	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/en_US.ISO8859-1/htdocs</replaceable></userinput></screen>
       </step>
 
       <step>
@@ -316,25 +160,6 @@ cvsroot-doc</programlisting>
 
     <variablelist>
       <varlistentry>
-	<term><envar>CVSROOT</envar></term>
-
-	<listitem>
-	  <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>
@@ -359,10 +184,10 @@ cvsroot-doc</programlisting>
 	<listitem>
 	  <para>If set and not empty, the Makefiles will build and
 	    install only the HTML pages from the <filename
-	      class="directory">www</filename> directory.  All
-	    documents from the <filename
-	      class="directory">doc</filename>
-	    directory (Handbook, FAQ, Tutorials) will be ignored.
+	      class="directory">en_US.ISO8859-1/htdocs</filename> directory.
+	    All other directories within <filename
+	      class="directory">en_US.ISO8859-1</filename>
+	    (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>
@@ -375,11 +200,11 @@ cvsroot-doc</programlisting>
 	<listitem>
 	  <para>If set, the Makefiles will build and install only for
 	    the languages specified by this variable inside the
-	    <filename class="directory">www</filename> directory.  All
+	    <filename class="directory"><replaceable>/usr/build</replaceable></filename> directory.  All
 	    other languages except English will be ignored.
 	    E.g.:</para>
 
-	  <screen>&prompt.root; <userinput>make WEB_LANG="el es hu nl" all install</userinput></screen>
+	  <screen>&prompt.root; <userinput>make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install</userinput></screen>
 	</listitem>
       </varlistentry>
 



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205202007.q4KK7BHY013352>