Index: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 47277) +++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 47278) @@ -1,144 +1,194 @@ 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. + + Environment Variables - 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. + Several environment variables control which parts of the the + web site are built or installed, and to which + directories. - &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs -&prompt.user; make all - - 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 + + + DESTDIR - 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. + + DESTDIR specifies the path where the web site files + are to be installed. - 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. + 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;. + + + - &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. - - &prompt.root; find /usr/local/www -ctime 3 -delete - - - - Environment Variables - - + 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" WEB_ONLY, WEB_LANG, and ENGLISH_ONLY are &man.make.1; variables and can be set in /etc/make.conf, 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