diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml index 2bd46eb90d..ecc959a855 100644 --- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml @@ -1,390 +1,403 @@ The Website 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 SGML tools, a subset of the CVS 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 There are two methods to get the files required for the website build: Use csup to get a local copy of the files from a CVSup server. This is the easiest method, and does not require installation of additional software. The supfile presented in the next section will always checkout the latest version of the required files. This is sufficient if you are simply rebuilding the website and do not intend to commit any changes. &man.csup.1; became part of the base system in &os; 6.2-RELEASE. If you are using an earlier version of &os; you will need to install net/csup from the Ports Collection. Use cvsup in cvs mode to create and maintain a local CVS repository with the required files. This will require you to install a program like net/cvsup-without-gui, but it is a more flexible method if you need to have quick access to different revisions of the doc/www files, revision histories, or if you intend to commit changes to the central &os; CVS repository. - Simple method: Using <command>csup</command> + Simple Method: Using <command>csup</command> The csup command is part of the base system and already used extensively by most people for updating the Ports Collection. The following sample supfile can be used to obtain a checkout of the files required for the website build: # # This file checks out all collections required to rebuild # the FreeBSD website # # Use the nearest CVSup mirror # listed at http://www.freebsd.org/doc/handbook/mirrors.html. *default host=cvsup10.FreeBSD.org *default base=/var/db *default prefix=/usr/build *default release=cvs tag=. *default delete use-rel-suffix *default compress # This will retrieve the entire doc branch of the FreeBSD repository. doc-all # This will retrieve the files required for the website www # This will retrieve some basic ports info required for the build ports-base You should, of course, change the default host entry to a CVSup mirror near your location, and the default prefix entry to the location where you intend to store the checked out files. Save this file as e.g. doc-www-supfile, and then execute the following command: &prompt.root; csup doc-www-supfile When this command finishes, you will find the directories doc/, www/ and ports/ under the directory you specified in default prefix (/usr/build in our example). We will use this same directory for the build process itself, so it would be better to use a filesystem with sufficient free space. That's it! You can now proceed with the website build. - Advanced method: Maintaining a local - <application>CVS</application> doc/www repository + Advanced Method: Maintaining a Local + <application>CVS</application> doc/www Repository This method will give you more advanced options, but will require you to install the net/cvsup-without-gui port or package. The net/cvsup-without-gui port has a build dependency on lang/ezm3, a Modula 3 compiler. This compiler takes quite some time to build, and since most people will not need it for anything else, it is perhaps best to use a package to install CVSup. The CVSup utility has a special cvs mode that allows the retrieval of the ,v files that make up a CVS repository. This function is not currently available in csup. For detailed information on CVSup, please read the CVSup introduction in the &os; Handbook. The supfile shown below will fetch the cvs collections required for the website build, and create a local CVS repository: # # This file will create a local CVS repository # with the collections required for a complete # FreeBSD website rebuild. It should be used with # cvsup *only* (csup will not work) *default host=cvsup10.FreeBSD.org *default base=/var/db *default prefix=/usr/dcvs *default release=cvs *default delete use-rel-suffix *default compress # The following collections are needed # for the website build ports-base doc-all www # These collections are needed # for CVS functionality cvsroot-common cvsroot-ports cvsroot-doc You should, of course, change the default host entry to a CVSup mirror near your location, and the default prefix entry to the location where you intend to store the repository files. Save this file as e.g. doc-www-cvsfile, and then execute the following command: &prompt.root; cvsup doc-www-cvsfile It is also advisable to set the CVSROOT environment variable in your shell's startup files. For example, use the following entry in your ~/.cshrc file: setenv CVSROOT /usr/dcvs If you set this variable, you may omit the argument (shown below) when performing repository operations using the cvs command. Currently, you will need more than 400 MB of free space to host the repository files. An additional 200 MB will be needed for the temporary build space. Once the cvsup command completes, you are ready to check out the files to your build directory: &prompt.root; mkdir /usr/build &prompt.root; cd /usr/build &prompt.root; cvs /usr/dcvs co doc www ports The above command is consistent with the way csup checks out the files from the CVSup servers. When it completes, you will have a build directory with similar contents to the one used in the simple csup method. You can continue to use the cvsup command shown above, to update your local CVS repository on a regular basis. After the initial somewhat lengthy download, regular updates will only take a few minutes. - Build the web pages from scratch + Build the Web Pages from Scratch Having completed either of the two methods, you will be ready to start the website build. In our example, the build directory is /usr/build 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 www/en directory by executing the &man.make.1; all target, to create the web pages. &prompt.root; cd www/en &prompt.root; make all - Install the web pages into your web server + Install the Web Pages into Your Web Server If you have moved out of the en directory, change back to it. &prompt.root; cd /usr/build/www/en Run the &man.make.1; install target, setting the DESTDIR variable to the name of the directory you want to install the files to. &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 find and delete all files that have not been updated in three days. &prompt.root; find /usr/local/www 3 | xargs rm - Environment variables + Environment Variables CVSROOT Location of the CVS tree. We suggest you set this variable, if you use the CVSup method: &prompt.root; CVSROOT=/usr/dcvs; export CVSROOT CVSROOT is an environment variable. You must set it on the command line or in your dot files (e.g., ~/.profile). The exact syntax will differ depending on your shell (the above example is for bash and bash-like shells). ENGLISH_ONLY If set and not empty, the makefiles will build and install only the English documents. 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 ENGLISH_ONLY to an empty value: &prompt.root; make ENGLISH_ONLY="" all install clean WEB_ONLY - If set and not empty, the makefiles will build and install - only the HTML pages from the www directory. All documents from + If set and not empty, the Makefiles will build and install + only the HTML pages from the www directory. All documents from the doc directory (Handbook, FAQ, Tutorials) will be ignored. E.g.: &prompt.root; make WEB_ONLY=YES all install + + WEB_LANG + + + If set, the Makefiles will build and install only for + the languages specified by this variable inside the + www directory. All + other languages except English will be ignored. E.g.: + + &prompt.root; make WEB_LANG="el es hu nl" all install + + + NOPORTSCVS - If set, the makefiles will not checkout files from the ports - cvs repository. Instead, it will copy the files from + 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, ENGLISH_ONLY and + WEB_ONLY, WEB_LANG, ENGLISH_ONLY and NOPORTSCVS are make variables. You can set the variables in /etc/make.conf, Makefile.inc, as environment variables on the command line, or in your dot files.