<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!-- 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>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>svn</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><command>pkg_delete</command> jade-1.1</userinput></screen>
</note>
<sect2 id="the-website-svn">
<title>Using <command>svn</command></title>
<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
<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>
</sect1>
<sect1 id="the-website-build">
<title>Build the Web Pages from Scratch</title>
<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>
<procedure>
<step>
<para>Change into the build directory:</para>
<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build</replaceable></userinput></screen>
</step>
<step>
<para>The website build starts from the <filename
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> en_US.ISO8859-1/htdocs</userinput>
&prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>
<tip>
<para>The build requires a few files from the Ports Collection
and may fail without a properly configured Ports CVS
mirror. Set the <makevar>NOPORTSCVS</makevar> environment
variable as described in <xref linkend="the-website-env"/>
to use your local Ports Collection (typically <filename
class="directory">/usr/ports</filename>) instead.</para>
</tip>
</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
class="directory">en_US.ISO8859-1/htdocs</filename>
directory, change back to it.</para>
<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/en_US.ISO8859-1/htdocs</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 directory you want to install the files to.
The actual files are installed under <filename
class="directory">$DESTDIR/data</filename>
which should be configured as your web server's document
root.</para>
<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>
<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><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><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><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><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 <filename
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>
</listitem>
</varlistentry>
<varlistentry>
<term><makevar>WEB_LANG</makevar></term>
<listitem>
<para>If set, the Makefiles will build and install only for
the languages specified by this variable inside the
<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_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" 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 class="directory">/usr/ports</filename> (or
where the variable <envar>PORTSBASE</envar> points
to).</para>
</listitem>
</varlistentry>
</variablelist>
<para><makevar>WEB_ONLY</makevar>, <makevar>WEB_LANG</makevar>,
<makevar>ENGLISH_ONLY</makevar> and
<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>