From owner-svn-doc-head@freebsd.org Wed Aug 19 02:22:20 2015 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id BCF309BD38E; Wed, 19 Aug 2015 02:22:20 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id A0DE0D67; Wed, 19 Aug 2015 02:22:20 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.70]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id t7J2MK6t065008; Wed, 19 Aug 2015 02:22:20 GMT (envelope-from wblock@FreeBSD.org) Received: (from wblock@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id t7J2MKfl065007; Wed, 19 Aug 2015 02:22:20 GMT (envelope-from wblock@FreeBSD.org) Message-Id: <201508190222.t7J2MKfl065007@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: wblock set sender to wblock@FreeBSD.org using -f From: Warren Block Date: Wed, 19 Aug 2015 02:22:20 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 19 Aug 2015 02:22:20 -0000 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 @@ The Website - - Build the Web Pages + The &os; web site is part of the &os; documents. Files for + the web site are stored in the + en_US.ISO8859-1/htdocs subdirectory of the + document tree directory, ~/doc in this + example. - Having obtained the documentation and web site source files, - the web site can be built. In this example, the build directory - is ~/doc - and all the required files are already in place. - - The web site is built from the - en_US.ISO8859-1/htdocs - subdirectory of the document tree directory, - ~/doc in this example. - Change to the build directory and start the build by executing - make all. + + Environment Variables - &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs -&prompt.user; make all + Several environment variables control which parts of the the + web site are built or installed, and to which + directories. - The web site build uses the INDEX - from the Ports Collection and may fail if that file or - /usr/ports is not - present. The simplest approach is to install the Ports - Collection. + 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. - - - - Install the Web Pages - - Run make install, setting - DESTDIR to the target directory for the web - site files. The files will be installed in - $DESTDIR/data, which is - expected to be the web server's document root. - - This installation is run as the root - 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 - jru in their home directory, /usr/home/jru/doc. - &prompt.root; cd /home/jru/doc/en_US.ISO8859-1/htdocs -&prompt.root; env DESTDIR=/usr/local/www make install - - 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. + + + DESTDIR - &prompt.root; find /usr/local/www -ctime 3 -delete - + + DESTDIR specifies the path where the web site files + are to be installed. - - Environment Variables + This variable is best set with &man.env.1; or the user + shell's method of setting environment variables, + setenv for &man.csh.1; or + export for &man.sh.1;. + + + - + ENGLISH_ONLY - When set, only the English documents will - be built or installed. All translations will be ignored: + Default: undefined. Build and include all + translations. - &prompt.root; make ENGLISH_ONLY=YES all install - - To unset the variable and build all pages, including - translations, set ENGLISH_ONLY to an - empty value: - - &prompt.root; make ENGLISH_ONLY="" all install clean + ENGLISH_ONLY=yes: use only + the English documents and ignore all translations. - + WEB_ONLY - When set, only the HTML - pages from the en_US.ISO8859-1/htdocs - directory will be built or installed. All other - directories within - en_US.ISO8859-1 - (Handbook, FAQ, Tutorials) will be ignored: + Default: undefined. Build both the web site + and all the books and articles. - &prompt.root; make WEB_ONLY=YES all install + WEB_ONLY=yes: build or install + only HTML pages from the + en_US.ISO8859-1/htdocs directory. + Other directories and documents, including books and + articles, will be ignored. - + WEB_LANG - If set, build or install only for the languages - specified: + Default: undefined. Build and include all the + available languages on the web site. - &prompt.root; make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install + 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: + + WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1" @@ -141,4 +123,72 @@ Makefile.inc, as environment variables on the command line, or in dot files. + + + Building and Installing the Web Pages + + Having obtained the documentation and web site source files, + the web site can be built. + + An actual installation of the web site is run as the root + 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. + + In these examples, the web site files are built by user + jru in their home + directory, ~/doc, with a full path of + /usr/home/jru/doc. + + + The web site build uses the INDEX + from the Ports Collection and might fail if that file or + /usr/ports is not + present. The simplest approach is to install the Ports + Collection. + + + + Build the web site and all documents. The resulting files + are left in the document tree: + + &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs/ +&prompt.user; make all + + + + Build the web site only, in English, as user + jru, and install + the resulting files into /tmp/www for + testing: + + &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs/ +&prompt.user; env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install + + + + Build the web site and all documents as user + jru. Install the + resulting files as + root into the + default directory, + /root/public_html: + + &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs +&prompt.user; make all +&prompt.user; su - +Password: +&prompt.root; cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs +&prompt.root; make install + + + 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: + + &prompt.root; find /usr/local/www -ctime 3 -delete +