Clarify and simplify the chapter about building the web site.
Reviewed by: gjb
This commit is contained in:
Warren Block
parent
401f216325
commit
444e5eec2f
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=47278
1 changed files with 125 additions and 75 deletions
|
|
@ -33,104 +33,86 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
|
||||
<title>The Website</title>
|
||||
|
||||
<sect1 xml: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 role="directory"><replaceable>~/doc</replaceable></filename>
|
||||
and all the required files are already in place.</para>
|
||||
|
||||
<para>The web site is built from the
|
||||
<filename>en_US.ISO8859-1/htdocs</filename>
|
||||
subdirectory of the document tree directory,
|
||||
<filename>~/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>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
|
||||
&prompt.user; <userinput>make all</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>/usr/ports</filename> is not
|
||||
present. The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
|
||||
Collection</link>.</para>
|
||||
</tip>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="the-website-install">
|
||||
<title>Install the Web Pages</title>
|
||||
|
||||
<para>Run <command>make install</command>, setting
|
||||
<varname>DESTDIR</varname> to the target directory for the web
|
||||
site files. The files will be installed in
|
||||
<filename>$DESTDIR/data</filename>, which is
|
||||
expected to be the web server's document root.</para>
|
||||
|
||||
<para>This installation is run as the <systemitem class="username">root</systemitem>
|
||||
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
|
||||
<systemitem class="username">jru</systemitem> in their home directory, <filename>/usr/home/jru/doc</filename>.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
|
||||
&prompt.root; <userinput>env DESTDIR=<replaceable>/usr/local/www</replaceable> make install</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>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
|
||||
</sect1>
|
||||
<para>The &os; web site is part of the &os; documents. Files for
|
||||
the web site are stored in the
|
||||
<filename>en_US.ISO8859-1/htdocs</filename> subdirectory of the
|
||||
document tree directory, <filename>~/doc</filename> in this
|
||||
example.</para>
|
||||
|
||||
<sect1 xml:id="the-website-env">
|
||||
<title>Environment Variables</title>
|
||||
|
||||
<para>Several environment variables control which parts of the the
|
||||
web site are built or installed, and to which
|
||||
directories.</para>
|
||||
|
||||
<tip>
|
||||
<para>The web build system uses &man.make.1;, and considers
|
||||
variables to be set when they have been defined, even if they
|
||||
are empty. The examples here show the recommended ways of
|
||||
defining and using these variables. Setting or defining these
|
||||
variables with other values or methods might lead to
|
||||
unexpected surprises.</para>
|
||||
</tip>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<varlistentry xml:id="the-website-env-destdir">
|
||||
<term><varname>DESTDIR</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>DESTDIR specifies the path where the web site files
|
||||
are to be installed.</para>
|
||||
|
||||
<para>This variable is best set with &man.env.1; or the user
|
||||
shell's method of setting environment variables,
|
||||
<command>setenv</command> for &man.csh.1; or
|
||||
<command>export</command> for &man.sh.1;.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry xml:id="the-website-env-englishonly">
|
||||
<term><varname>ENGLISH_ONLY</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>When set, only the English documents will
|
||||
be built or installed. All translations will be ignored:</para>
|
||||
<para>Default: undefined. Build and include all
|
||||
translations.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen>
|
||||
|
||||
<para>To unset the variable and build all pages, including
|
||||
translations, set <varname>ENGLISH_ONLY</varname> to an
|
||||
empty value:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
|
||||
<para><userinput>ENGLISH_ONLY=yes</userinput>: use only
|
||||
the English documents and ignore all translations.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<varlistentry xml:id="the-website-env-webonly">
|
||||
<term><varname>WEB_ONLY</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>When set, only the <acronym>HTML</acronym>
|
||||
pages from the <filename>en_US.ISO8859-1/htdocs</filename>
|
||||
directory will be built or installed. All other
|
||||
directories within
|
||||
<filename>en_US.ISO8859-1</filename>
|
||||
(Handbook, FAQ, Tutorials) will be ignored:</para>
|
||||
<para>Default: undefined. Build both the web site
|
||||
and all the books and articles.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen>
|
||||
<para><userinput>WEB_ONLY=yes</userinput>: build or install
|
||||
only <acronym>HTML</acronym> pages from the
|
||||
<filename>en_US.ISO8859-1/htdocs</filename> directory.
|
||||
Other directories and documents, including books and
|
||||
articles, will be ignored.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<varlistentry xml:id="the-website-env-weblang">
|
||||
<term><varname>WEB_LANG</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>If set, build or install only for the languages
|
||||
specified:</para>
|
||||
<para>Default: undefined. Build and include all the
|
||||
available languages on the web site.</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>
|
||||
<para>Set to a space-separated list of languages to be
|
||||
included in the build
|
||||
or install. The formats are the same as the directory
|
||||
names in the document root directory. For example, to
|
||||
include the German and French documents:</para>
|
||||
|
||||
<screen><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
|
@ -141,4 +123,72 @@
|
|||
<filename>Makefile.inc</filename>, as environment variables on
|
||||
the command line, or in dot files.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="the-website-build">
|
||||
<title>Building and Installing the Web Pages</title>
|
||||
|
||||
<para>Having obtained the documentation and web site source files,
|
||||
the web site can be built.</para>
|
||||
|
||||
<para>An actual installation of the web site is run as the <systemitem class="username">root</systemitem>
|
||||
user because the permissions on the web server directory will
|
||||
not allow files to be installed by an unprivileged user.
|
||||
For testing, it can be useful to install the files as a normal
|
||||
user to a temporary directory.</para>
|
||||
|
||||
<para>In these examples, the web site files are built by user
|
||||
<systemitem class="username">jru</systemitem> in their home
|
||||
directory, <filename>~/doc</filename>, with a full path of
|
||||
<filename>/usr/home/jru/doc</filename>.</para>
|
||||
|
||||
<tip>
|
||||
<para>The web site build uses the <filename>INDEX</filename>
|
||||
from the Ports Collection and might fail if that file or
|
||||
<filename>/usr/ports</filename> is not
|
||||
present. The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
|
||||
Collection</link>.</para>
|
||||
</tip>
|
||||
|
||||
<example xml:id="the-website-examples-build">
|
||||
<para>Build the web site and all documents. The resulting files
|
||||
are left in the document tree:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
|
||||
&prompt.user; <userinput>make all</userinput></screen>
|
||||
</example>
|
||||
|
||||
<example xml:id="the-website-examples-buildinstall-englishonly">
|
||||
<para>Build the web site only, in English, as user
|
||||
<systemitem class="username">jru</systemitem>, and install
|
||||
the resulting files into <filename>/tmp/www</filename> for
|
||||
testing:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
|
||||
&prompt.user; <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen>
|
||||
</example>
|
||||
|
||||
<example xml:id="the-website-examples-buildinstall">
|
||||
<para>Build the web site and all documents as user
|
||||
<systemitem class="username">jru</systemitem>. Install the
|
||||
resulting files as
|
||||
<systemitem class="username">root</systemitem> into the
|
||||
default directory,
|
||||
<filename>/root/public_html</filename>:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
|
||||
&prompt.user; <userinput>make all</userinput>
|
||||
&prompt.user; <userinput>su -</userinput>
|
||||
Password:
|
||||
&prompt.root; <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
|
||||
&prompt.root; <userinput>make install</userinput></screen>
|
||||
</example>
|
||||
|
||||
<para>The install process does 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>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue