202 lines
8.8 KiB
XML
202 lines
8.8 KiB
XML
<?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 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>
|