243 lines
9.9 KiB
XML
243 lines
9.9 KiB
XML
<?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>
|