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 4caa2ef8d4..c6b2af3cfa 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,207 +1,390 @@ The Website - + Preparation - - Get 200MB free disk space. You will need the disk space for the - SGML tools, a subset of the CVS tree, temporary build space and the - installed web pages. If you already have installed the SGML tools and - the CVS tree, you need only ~100MB free disk space. - + + 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 + &prompt.root; pkg_delete jade-1.1 - Set up a CVS repository. You need the directories www, doc and - ports in the CVS tree (plus the CVSROOT of course). Please read the - CVSup introduction - on how to mirror a CVS tree or parts of a CVS tree. - - The essential cvsup collections are: www, - doc-all, cvs-base, and - ports-base. - - These collections require ~105MB free disk space. - - A full CVS tree - including src, - doc, www, and - ports - is currently 940MB. + 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> + + 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 + + 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 - - - - Create and change directory into a build directory with at least 60MB of free - space. - - &prompt.root; mkdir /var/tmp/webbuild -&prompt.root; cd /var/tmp/webbuild - + 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. + + - Checkout the SGML files from the CVS tree. - - &prompt.root; cvs -R co www doc + Change into the build directory: + + &prompt.root; cd /usr/build - Change into the www/en directory, and run + 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 + + &prompt.root; cd www/en +&prompt.root; make all - + Install the web pages into your web server - + - If you have moved out of the en - directory, change back to it. - - &prompt.root; cd path/www/en + 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 + setting the DESTDIR variable to the name of the directory you want to install the files to. - - &prompt.root; make DESTDIR=/usr/local/www install + + &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 -ctime 3 -print0 | xargs -0 rm + + &prompt.root; find /usr/local/www 3 | xargs rm - + Environment variables - + CVSROOT - + - Location of the CVS tree. Essential. - - &prompt.root; CVSROOT=/home/ncvs; export 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 + 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 + + &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 - the doc directory (Handbook, FAQ, Tutorials) will be ignored. - E.g.: - - &prompt.root; make WEB_ONLY=YES all 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 - + 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). + cvs repository. Instead, it will copy the files from + /usr/ports (or where the + variable PORTSBASE points to). - - CVSROOT is an environment variable. You must set it - on the command line or in your dot files (e.g., ~/.profile). - + WEB_ONLY, ENGLISH_ONLY and - NOPORTSCVS are makefile variables. You can set the + 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. - +