Date: Wed, 19 Aug 2015 02:22:20 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47278 - head/en_US.ISO8859-1/books/fdp-primer/the-website Message-ID: <201508190222.t7J2MKfl065007@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201508190222.t7J2MKfl065007>