<!-- 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="../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>Go to 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>www</filename> directory, and
	  run the &man.make.1; <maketarget>links</maketarget> target, to
	  create the necessary symbolic links.</para>
	
	<screen>&prompt.root; <userinput>cd www</userinput>
&prompt.root; <userinput>make links</userinput></screen>
      </step>

      <step>
	<para>Change into the <filename>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 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 (~/.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> or 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:
-->
