<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<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>
<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>
</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>
</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>
<step>
<para>Checkout the SGML files from the CVS tree.</para>
<screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen>
</step>
<step>
<para>Change into the <filename role="directory">www/en</filename> directory, and run
the &man.make.1; <maketarget>all</maketarget> target, to create
the web pages.</para>
<screen>&prompt.root; <userinput>cd en</userinput>
&prompt.root; <userinput>make all</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>
</step>
<step>
<para>Run the &man.make.1; <maketarget>install</maketarget> target,
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>
</step>
<step>
<para>If you have previously installed the web pages into the same
directory the install process will not have deleted any old or
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>
</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>
</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>
<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>
</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>
</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>
</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
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
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->