diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml | 285 |
1 files changed, 0 insertions, 285 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml deleted file mode 100644 index 1c6feb6dbb..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml +++ /dev/null @@ -1,285 +0,0 @@ -<?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. - ---> -<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> - - <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 - 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 xml:id="the-website-env-docdir"> - <term><varname>DOCDIR</varname></term> - - <listitem> - <para>DOCDIR 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>Default: undefined. Build and include all - translations.</para> - - <para><userinput>ENGLISH_ONLY=yes</userinput>: use only - the English documents and ignore all translations.</para> - </listitem> - </varlistentry> - - <varlistentry xml:id="the-website-env-webonly"> - <term><varname>WEB_ONLY</varname></term> - - <listitem> - <para>Default: undefined. Build both the web site - and all the books and articles.</para> - - <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 xml:id="the-website-env-weblang"> - <term><varname>WEB_LANG</varname></term> - - <listitem> - <para>Default: undefined. Build and include all the - available languages on the web site.</para> - - <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> - - <para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>, - and <varname>ENGLISH_ONLY</varname> 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> - - <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"> - <title>Build the Full Web Site and All Documents</title> - - <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"> - <title>Build Only the Web Site in English</title> - - <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 DOCDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen> - - <para>Changes to static files can usually be tested by viewing - the modified files directly with a web browser. If the site - has been built as shown above, a modified main page can be - viewed with:</para> - - <screen>&prompt.user; <userinput>firefox /tmp/www/data/index.html</userinput></screen> - - <para>Modifications to dynamic files can be tested with a web - server running on the local system. After building the site - as shown above, this - <filename>/usr/local/etc/apache24/httpd.conf</filename> can be - used with <package>www/apache24</package>:</para> - - <programlisting># httpd.conf for testing the FreeBSD website -Define TestRoot "/tmp/www/data" - -# directory for configuration files -ServerRoot "/usr/local" - -Listen 80 - -# minimum required modules -LoadModule authz_core_module libexec/apache24/mod_authz_core.so -LoadModule mime_module libexec/apache24/mod_mime.so -LoadModule unixd_module libexec/apache24/mod_unixd.so -LoadModule cgi_module libexec/apache24/mod_cgi.so -LoadModule dir_module libexec/apache24/mod_dir.so - -# run the webserver as user and group -User www -Group www - -ServerAdmin you@example.com -ServerName fbsdtest - -# deny access to all files -<Directory /> - AllowOverride none - Require all denied -</Directory> - -# allow access to the website directory -DocumentRoot "${TestRoot}" -<Directory "${TestRoot}"> - Options Indexes FollowSymLinks - AllowOverride None - Require all granted -</Directory> - -# prevent access to .htaccess and .htpasswd files -<Files ".ht*"> - Require all denied -</Files> - -ErrorLog "/var/log/httpd-error.log" -LogLevel warn - -# set up the CGI script directory -<Directory "${TestRoot}/cgi"> - AllowOverride None - Options None - Require all granted - Options +ExecCGI - AddHandler cgi-script .cgi -</Directory> - -Include etc/apache24/Includes/*.conf</programlisting> - - <para>Start the web server with</para> - - <screen>&prompt.root; <userinput>service apache24 onestart</userinput></screen> - - <para>The web site can be viewed at <link - xlink:href="http://localhost"/>. Be aware that many links - refer to the real &os; site by name, and those links will - still go to the external site instead of the local test - version. Fully testing the local site will require - temporarily setting <acronym>DNS</acronym> so - <literal>www.FreeBSD.org</literal> resolves to - <literal>localhost</literal> or the local - <acronym>IP</acronym> address.</para> - </example> - - <example xml:id="the-website-examples-buildinstall"> - <title>Build and Install the Web Site</title> - - <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> |