<?xml version="1.0" encoding="iso-8859-1"?>
<!-- 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.  A full copy of
      the documentation and web site files takes over 700&nbsp;MB.
      Allowing a full gigabyte provides some breathing room.  This
      space will hold the XML tools, the documentation tree, temporary
      build space and the installed web pages.</para>

    <note>
      <para>Make sure the documentation ports are updated to the
	latest version.  See
	<ulink url="&url.books.handbook;/ports.html#ports-using">the
	  Handbook section on ports</ulink> for more
	information.</para>
    </note>

    <sect2 id="the-website-svn">
      <title>Using <command>svn</command></title>

      <para><command>svn</command> is needed to check out the
	documentation and web site 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 source files for the &os; web site and
	the rest of the documentation, run:</para>

      <screen>&prompt.user; <userinput><command>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/ <replaceable>~/doc</replaceable></command></userinput></screen>

      <para><ulink
	  url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink>
	is a public <literal>SVN</literal> server. Select the closest
	mirror and verify the mirror server certificate from the list
	of
	<ulink url="&url.books.handbook;/svn-mirrors.html">Subversion
	mirror sites</ulink>.</para>

      <para>After the checkout completes, the current version of the
	&os; documentation, including the web site files, will be
	present in
	<filename class="directory">~/doc</filename>.</para>
    </sect2>
  </sect1>

  <sect1 id="the-website-build">
    <title>Build the Web Pages</title>

    <para>Having obtained the documentation and web site source files,
      the web site can be built.  In this example, the build directory
      is <filename
	class="directory"><replaceable>~/doc</replaceable></filename>
      and all the required files are already in place.</para>

    <para>The web site is built from the
      <filename class="directory">en_US.ISO8859-1/htdocs</filename>
      subdirectory of the document tree directory,
      <filename class="directory">~/doc</filename> in this example.
      Change to the build directory and start the build by executing
      <command>make all</command>.</para>

    <screen>&prompt.user; <userinput><command>cd</command> ~/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.user; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>

    <tip>
      <para>The web site build uses the <filename>INDEX</filename>
	from the Ports Collection and may fail if that file or
	<filename class="directory">/usr/ports</filename> is not
	present.  The simplest approach is to install the <ulink
	  url="&url.books.handbook;/ports.html#ports-tree">Ports
	Collection</ulink>.</para>
    </tip>
  </sect1>

  <sect1 id="the-website-install">
    <title>Install the Web Pages</title>

    <para>Run <command>make install</command>, setting
      <makevar>DESTDIR</makevar> to the target directory for the web
      site files.  The files will be installed in
      <filename class="directory">$DESTDIR/data</filename>, which is
      expected to be the web server's document root.</para>

    <para>This installation is run as the <username>root</username>
      user because the permissions on the web server directory will
      not allow files to be installed by an unprivileged user.  In
      this example, the web site files were built by user
      <username>jru</username> in their home directory, <filename
	class="directory">/usr/home/jru/doc</filename>.</para>

    <screen>&prompt.root; <userinput><command>cd</command> /home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.root; <userinput><command>env</command> <makevar>DESTDIR</makevar>=<replaceable>/usr/local/www</replaceable> <command>make</command> <maketarget>install</maketarget></userinput></screen>

    <para>The install process will not delete any old or outdated
      files that existed previously in the same directory.  If a new
      copy of the site is built and installed 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>-delete</option></userinput></screen>
  </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, only the English documents will
	    be built or installed.  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>To unset the variable and build all pages, including
	    translations, set <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, only the <acronym>HTML</acronym>
	    pages from the <filename
	      class="directory">en_US.ISO8859-1/htdocs</filename>
	    directory will be built or installed.  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, build or install only for the languages
	    specified by this variable inside the <filename
	      class="directory"><replaceable>~/doc</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>
    </variablelist>

    <para><makevar>WEB_ONLY</makevar>, <makevar>WEB_LANG</makevar>,
      and <makevar>ENGLISH_ONLY</makevar> are &man.make.1; variables
      and can be set in <filename>/etc/make.conf</filename>,
      <filename>Makefile.inc</filename>, as environment variables on
      the command line, or in dot files.</para>
  </sect1>
</chapter>