svn commit: r47278 - head/en_US.ISO8859-1/books/fdp-primer/the-website
Warren Block <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
Author: wblock
Date: Wed Aug 19 02:22:19 2015
New Revision: 47278
URL: https://svnweb.freebsd.org/changeset/doc/47278
Log:
Clarify and simplify the chapter about building the web site.
Reviewed by: gjb
Modified:
head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml Wed Aug 19 02:01:52 2015 (r47277)
+++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml Wed Aug 19 02:22:19 2015 (r47278)
@@ -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>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>
- <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>
+ <sect1 xml:id="the-website-env">
+ <title>Environment Variables</title>
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
-&prompt.user; <userinput>make all</userinput></screen>
+ <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 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>
+ <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>
- </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>
+ <variablelist>
+ <varlistentry xml:id="the-website-env-destdir">
+ <term><varname>DESTDIR</varname></term>
- <screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
- </sect1>
+ <listitem>
+ <para>DESTDIR specifies the path where the web site files
+ are to be installed.</para>
- <sect1 xml:id="the-website-env">
- <title>Environment Variables</title>
+ <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>
+ <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>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"