svn commit: r38856 -
head/en_US.ISO8859-1/books/fdp-primer/the-website
Glen Barber
gjb at FreeBSD.org
Sun May 20 20:07:12 UTC 2012
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 MB to over 500 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 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 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; 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 MB of free
- space to host the repository files. An additional 200 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>
More information about the svn-doc-all
mailing list