From owner-svn-doc-head@FreeBSD.ORG Wed Jun 26 00:24:47 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 2F1B43A5; Wed, 26 Jun 2013 00:24:47 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 1EE2C1DF1; Wed, 26 Jun 2013 00:24:47 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5Q0Olko012622; Wed, 26 Jun 2013 00:24:47 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5Q0OkB9012621; Wed, 26 Jun 2013 00:24:46 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201306260024.r5Q0OkB9012621@svn.freebsd.org> From: Warren Block Date: Wed, 26 Jun 2013 00:24:46 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42053 - 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.14 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, 26 Jun 2013 00:24:47 -0000 Author: wblock Date: Wed Jun 26 00:24:46 2013 New Revision: 42053 URL: http://svnweb.freebsd.org/changeset/doc/42053 Log: Update "The Website" chapter to reflect current standards and writing style. 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 Tue Jun 25 23:46:46 2013 (r42052) +++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml Wed Jun 26 00:24:46 2013 (r42053) @@ -37,38 +37,37 @@ Preparation - Use a disk with sufficient free space. You may need - anything from 200 MB to over 500 MB, depending on the - method you choose. This space will hold the XML tools, a - subset of the svn tree, temporary + Use a disk with sufficient free space. A full copy of + the documentation and web site files takes over 700 MB. + Allowing a full gigabyte provides some breathing room. + This space will hold the XML tools, the + documentation tree, temporary build space and the installed web pages. - Make sure your documentation ports are up to date! When - in doubt, remove the old ports using &man.pkg.delete.1; - command before installing the port. For example, we currently - depend on jade-1.2 and if you have installed jade-1.1, please - do: - - &prompt.root; pkg_delete jade-1.1 + Make sure the documentation ports are updated to the + latest version. See the + Handbook section on ports + for more information. Using <command>svn</command> - svn is necessary to check - out the necessary files from the - doc/ Subversion repository. + svn is needed to check + out the documentation and web site files from the + doc Subversion repository. svn can be installed with &man.pkg.add.1; or from the &os; Ports Collection by running: &prompt.root; cd /usr/ports/devel/subversion &prompt.root; make install clean - To check out the full source files for the &os; website, + To check out the source files for the &os; web site and the rest of the documentation, run: - &prompt.root; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/ /usr/build + &prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/ ~/doc svn0.us-east.FreeBSD.org @@ -78,100 +77,69 @@ url="&url.books.handbook;/svn-mirrors.html">Subversion mirror sites. - - If svn is not run as - root, be sure /usr/build has the proper - permissions for the current user. If changing the - permissions is not possible, use a different target - directory for the website files. - - - When svn finishes, the current version - of the &os; website will exist within /usr/build. If a different - target directory was used, replace /usr/build appropriately - throughout the remainder of this document. - - That's it! You can now proceed with the - website build. + After the checkout completes, the current version + of the &os; documentation, including the web site files, will be present in ~/doc. - Build the Web Pages from Scratch + Build the Web Pages - Having completed the necessary steps to obtain the website - source files, the website can be built. In our example, the + Having obtained the documentation and web site + source files, the web site can be built. In this example, the build directory is /usr/build + class="directory">~/doc and all the required files are already in place. - - - Change into the build directory: - - &prompt.root; cd /usr/build - - - - The website build starts from the The web site is built from the en_US.ISO8859-1/htdocs - directory by executing the &man.make.1; - all target, to create the web - pages. - - &prompt.root; cd en_US.ISO8859-1/htdocs -&prompt.root; make all - - - The build requires a few files from the Ports Collection - and may fail without a properly configured Ports CVS - mirror. Set the NOPORTSCVS environment - variable as described in - to use your local Ports Collection (typically /usr/ports) instead. - - - + subdirectory of the document tree directory, + ~/doc in this example. + Change to the build directory and start the build by executing make all. + + &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. + - Install the Web Pages into Your Web Server - - - - If you have moved out of the en_US.ISO8859-1/htdocs - directory, change back to it. - - &prompt.root; cd /usr/build/en_US.ISO8859-1/htdocs - + Install the Web Pages - - Run the &man.make.1; install - target, setting the DESTDIR variable to - the name of the directory you want to install the files to. - The actual files are installed under $DESTDIR/data - which should be configured as your web server's document + 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. - &prompt.root; env DESTDIR=/usr/local/www make install - - - - If you have previously installed the web pages into the - same directory the install process will not have deleted any - old or outdated pages. For example, if you build and - install a new copy of the site every day, this command will + 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. - &prompt.root; find /usr/local/www 3 | xargs rm - - + &prompt.root; find /usr/local/www 3 @@ -182,15 +150,15 @@ ENGLISH_ONLY - If set and not empty, the makefiles will build and - install only the English documents. All translations will + If set and not empty, only the English documents will + be built or installed. All translations will be ignored. E.g.: &prompt.root; make ENGLISH_ONLY=YES all install - If you want to unset the variable - ENGLISH_ONLY and build all pages, - including translations, set the variable + 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 @@ -201,10 +169,10 @@ WEB_ONLY - If set and not empty, the Makefiles will build and - install only the HTML pages from the If set and not empty, only the HTML + pages from the en_US.ISO8859-1/htdocs - directory. All other directories within en_US.ISO8859-1 (Handbook, FAQ, Tutorials) will be ignored. E.g.: @@ -217,35 +185,23 @@ WEB_LANG - If set, the Makefiles will build and install only for + If set, build or install only for the languages specified by this variable inside the /usr/build + class="directory">~/doc directory. All other languages except English will be ignored. E.g.: &prompt.root; make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install - - - NOPORTSCVS - - - If set, the Makefiles will not checkout files from the - ports CVS repository. Instead, it will copy the files - from /usr/ports (or - where the variable PORTSBASE points - to). - - WEB_ONLY, WEB_LANG, - ENGLISH_ONLY and - NOPORTSCVS are make variables. You can set - the variables in /etc/make.conf, + 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 your dot files. + the command line, or in dot files.