From owner-svn-doc-all@FreeBSD.ORG Sun Feb 17 17:28:27 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id B8318678; Sun, 17 Feb 2013 17:28:27 +0000 (UTC) (envelope-from dru@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 92F72FE0; Sun, 17 Feb 2013 17:28:27 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.5/8.14.5) with ESMTP id r1HHSRYE009019; Sun, 17 Feb 2013 17:28:27 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.5/8.14.5/Submit) id r1HHSRjC009018; Sun, 17 Feb 2013 17:28:27 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201302171728.r1HHSRjC009018@svn.freebsd.org> From: Dru Lavigne Date: Sun, 17 Feb 2013 17:28:27 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40998 - head/en_US.ISO8859-1/books/handbook/cutting-edge X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 17 Feb 2013 17:28:27 -0000 Author: dru Date: Sun Feb 17 17:28:26 2013 New Revision: 40998 URL: http://svnweb.freebsd.org/changeset/doc/40998 Log: Initial content fix. This patch addresses the following: - missing &os; entities - rewording to address you, we, and general redundancy - adds missing directory tags - replaces portupgrade with portmaster - replaces old version examples with 9.x and 1998 names with 2013 - makes up-to-date consistent Approved by: gjb (mentor) Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sun Feb 17 17:17:14 2013 (r40997) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sun Feb 17 17:28:26 2013 (r40998) @@ -52,23 +52,21 @@ others prefer to keep in sync with the latest developments. However, even official releases are often updated with security and other critical fixes. Regardless of the version used, &os; - provides all necessary tools to keep your system updated, and - also allows for easy upgrades between versions. This chapter - will help you decide if you want to track the development - system, or stick with one of the released versions. The basic - tools for keeping your system up to date are also - presented. + provides all the necessary tools to keep the system updated, and + allows for easy upgrades between versions. This chapter + describes how to track the development system and the basic + tools for keeping a &os; system up-to-date. After reading this chapter, you will know: - What utilities may be used to update the system and + Which utilities are available to update the system and the Ports Collection. - How to keep your system up to date with + How to keep a &os; system up-to-date with freebsd-update, Subversion, or CTM. @@ -80,7 +78,7 @@ - How to keep your documentation up to date with + How to keep the installed documentation up-to-date with Subversion or documentation ports. @@ -92,7 +90,7 @@ How to rebuild and reinstall the entire base - system with make buildworld (etc). + system. @@ -100,7 +98,7 @@ - Properly set up your network connection (Properly set up the network connection (). @@ -111,10 +109,10 @@ - Throughout this chapter, the svn - command is used to obtain and update &os; sources. To use it, - you will need to install the port or the package for devel/subversion. + Throughout this chapter, svn is used to + obtain and update &os; sources. To use it, first install the + devel/subversion port or + package. @@ -135,7 +133,7 @@ - FreeBSD Update + &os; Update Updating and Upgrading @@ -145,13 +143,13 @@ Applying security patches is an important part of maintaining computer software, especially the operating system. - For the longest time on &os; this process was not an easy one. + For the longest time on &os;, this process was not an easy one. Patches had to be applied to the source code, the code rebuilt into binaries, and then the binaries had to be re-installed. This is no longer the case as &os; now includes a utility - simply called freebsd-update. This utility + called freebsd-update. This utility provides two separate functions. First, it allows for binary security and errata updates to be applied to the &os; base system without the build and install requirements. Second, the @@ -159,12 +157,11 @@ Binary updates are available for all architectures and - releases currently supported by the security team. - Before updating to a new release, the current - release announcements should be reviewed as they may contain - important information pertinent to the desired release. These - announcements may be viewed at the following link: - . + releases currently supported by the security team. Before + updating to a new release, its release announcement should be + reviewed as it contains important information pertinent to the + release. Release announcements are available from . If a crontab utilizing the features @@ -175,39 +172,38 @@ The Configuration File Some users may wish to tweak the default configuration - file in /etc/freebsd-update.conf, - allowing better control of the process. The options are very - well documented, but the following few may require a bit more + in /etc/freebsd-update.conf, allowing + better control of the process. The options are well + documented, but the following may require a bit more explanation: # Components of the base system which should be kept updated. Components src world kernel - This parameter controls what parts of &os; will be kept up - to date. The default is to update the source code, the entire - base system, and the kernel. Components are the same as those - available during the install, for instance, adding - world/games here would allow game patches - to be applied. Using src/bin would allow - the source code in - src/bin to be - updated. + This parameter controls which parts of &os; will be kept + up-to-date. The default is to update the source code, the + entire base system, and the kernel. Components are the same + as those available during installation. For instance, adding + world/games would allow game patches to be + applied. Using src/bin would allow the + source code in src/bin + to be updated. The best option is to leave this at the default as - changing it to include specific items will require the user - to list every item they prefer to be updated. This could - have disastrous consequences as source code and binaries may - become out of sync. + changing it to include specific items requires the user to + list every item to be updated. This could have disastrous + consequences as source code and binaries may become out of + sync. # Paths which start with anything matching an entry in an IgnorePaths # statement will be ignored. IgnorePaths - Add paths, such as + To leave specified directories, such as /bin or - /sbin to leave these - specific directories untouched during the update - process. This option may be used to prevent + /sbin, untouched during + the update process, add their paths to this statement. This + option may be used to prevent freebsd-update from overwriting local modifications. @@ -216,8 +212,8 @@ IgnorePaths # modified by the user (unless changes are merged; see below). UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile - Update configuration files in the specified directories - only if they have not been modified. Any changes made by the + This option will only update unmodified configuration + files in the specified directories. Any changes made by the user will invalidate the automatic updating of these files. There is another option, KeepModifiedMetadata, which will instruct @@ -229,24 +225,23 @@ UpdateIfUnmodified /etc/ /var/ /root/ /. MergeChanges /etc/ /var/named/etc/ List of directories with configuration files that - freebsd-update should attempt merges in. + freebsd-update should attempt to merge. The file merge process is a series of &man.diff.1; patches - similar to &man.mergemaster.8; with fewer options, the merges - are either accepted, open an editor, or + similar to &man.mergemaster.8;, but with fewer options. + Merges are either accepted, open an editor, or freebsd-update will abort. When in doubt, backup /etc and just accept the merges. See for more - information about the mergemaster - command. + information about mergemaster. # Directory in which to store downloaded updates and temporary # files used by &os; Update. # WorkDir /var/db/freebsd-update - This directory is where all patches and temporary - files will be placed. In cases where the user is doing - a version upgrade, this location should have a least a - gigabyte of disk space available. + This directory is where all patches and temporary files + are placed. In cases where the user is doing a version + upgrade, this location should have a least a gigabyte of disk + space available. # When upgrading between releases, should the list of Components be # read strictly (StrictComponents yes) or merely as a list of components @@ -254,7 +249,7 @@ MergeChanges /etc/ /var/named/etc/ - When set to yes, + When this option is set to yes, freebsd-update will assume that the Components list is complete and will not attempt to make changes outside of the list. Effectively, @@ -266,32 +261,30 @@ MergeChanges /etc/ /var/named/etc/ Security Patches - Security patches are stored on a remote machine and - may be downloaded and installed using the following - command: + &os; security patches may be downloaded and installed + using the following command: &prompt.root; freebsd-update fetch &prompt.root; freebsd-update install - If any kernel patches have been applied the system will - need a reboot. If all went well the system should be patched - and freebsd-update may be run as a nightly - &man.cron.8; job. An entry in - /etc/crontab would be sufficient to - accomplish this task: + If the update applied any kernel patches, the system will + need a reboot in order to boot into the patched kernel. + Otherwise, the system should be patched and + freebsd-update may be run as a nightly + &man.cron.8; job by adding this entry to + /etc/crontab: @daily root freebsd-update cron - This entry states that once every day, the - freebsd-update utility will be run. In - this way, using the argument, + This entry states that freebsd-update + will run once every day. When run with , freebsd-update will only check if updates exist. If patches exist, they will automatically be - downloaded to the local disk but not applied. The - root user will be sent an email so they - may install them manually. + downloaded to the local disk but will not be applied. The + root user will be sent an email so that + they may be reviewed and manually installed. - If anything went wrong, freebsd-update + If anything goes wrong, freebsd-update has the ability to roll back the last set of changes with the following command: @@ -301,16 +294,15 @@ MergeChanges /etc/ /var/named/etc/ - The freebsd-update utility can - automatically update the GENERIC kernel - only. If a custom kernel is in use, it will have to be - rebuilt and reinstalled after - freebsd-update finishes installing the rest - of the updates. However, freebsd-update - will detect and update the GENERIC kernel - in - /boot/GENERIC (if it - exists), even if it is not the current (running) kernel of the + Only the GENERIC kernel can be + automatically updated by freebsd-update. + If a custom kernel is installed, it will have to be rebuilt + and reinstalled after freebsd-update + finishes installing the rest of the updates. However, + freebsd-update will detect and update the + GENERIC kernel if + /boot/GENERIC exists, + even if it is not the current running kernel of the system. @@ -327,22 +319,22 @@ MergeChanges /etc/ /var/named/etc//etc/freebsd-update.conf has been changed, freebsd-update will install the updated kernel sources along with the rest of the updates. - Rebuilding and reinstalling your new custom kernel can then be + Rebuilding and reinstalling a new custom kernel can then be performed in the usual way. - The updates distributed via - freebsd-update, do not always involve the - kernel. It will not be necessary to rebuild your custom - kernel if the kernel sources have not been modified by the - execution of freebsd-update install. + The updates distributed by + freebsd-update do not always involve the + kernel. It is not necessary to rebuild a custom kernel if + the kernel sources have not been modified by the execution + of freebsd-update install. However, freebsd-update will always - update the /usr/src/sys/conf/newvers.sh - file. The current patch level (as indicated by the + update /usr/src/sys/conf/newvers.sh. + The current patch level, as indicated by the -p number reported by - uname -r) is obtained from this file. - Rebuilding your custom kernel, even if nothing else changed, - will allow &man.uname.1; to accurately report the current + uname -r, is obtained from this file. + Rebuilding a custom kernel, even if nothing else changed, + allows &man.uname.1; to accurately report the current patch level of the system. This is particularly helpful when maintaining multiple systems, as it allows for a quick assessment of the updates installed in each one. @@ -358,18 +350,18 @@ MergeChanges /etc/ /var/named/etc/ - Major version upgrades are when &os; - is upgraded from one major version to another, like from - &os; 8.X to &os; 9.X. Major version upgrades will - remove old object files and libraries which will break most - third party applications. It is recommended that all - installed ports either be removed and re-installed or upgraded - after a major version upgrade by using the - ports-mgmt/portupgrade - utility. A brute-force rebuild of all installed - applications can be accomplished with this command: + Major version upgrades occur when + &os; is upgraded from one major version to another, like from + &os; 8.X to &os; 9.X. Major version upgrades remove + old object files and libraries which will break most third + party applications. It is recommended that all installed + ports either be removed and re-installed or upgraded after a + major version upgrade using a utility such as + ports-mgmt/portmaster. A + brute-force rebuild of all installed applications can be + accomplished with this command: - &prompt.root; portupgrade -af + &prompt.root; portmaster -f This will ensure everything will be re-installed correctly. Note that setting the @@ -388,30 +380,28 @@ MergeChanges /etc/ /var/named/etc/ Custom Kernels with &os; 8.X and Earlier - A copy of the - GENERIC kernel is needed, and it - should be placed in A copy of the GENERIC kernel is + needed, and should be placed in /boot/GENERIC. If the - GENERIC kernel is not already present - in the system, it may be obtained using one of the - following methods: + GENERIC kernel is not present in the + system, it may be obtained using one of the following + methods: If a custom kernel has only been built once, the kernel in /boot/kernel.old is - actually the GENERIC one. Simply - rename this directory to GENERIC. Rename this + directory to /boot/GENERIC. Assuming physical access to the machine is possible, a copy of the GENERIC - kernel can be installed from the CD-ROM media. Insert - your installation disc and use the following - commands: + kernel can be installed from the installation media + using the following commands: &prompt.root; mount /cdrom &prompt.root; cd /cdrom/X.Y-RELEASE/kernels @@ -419,7 +409,7 @@ MergeChanges /etc/ /var/named/etc/Replace X.Y-RELEASE - with the actual version of the release you are using. + with the actual version of the release being used. The GENERIC kernel will be installed in /boot/GENERIC by @@ -429,7 +419,7 @@ MergeChanges /etc/ /var/named/etc/ Failing all the above, the GENERIC kernel may be rebuilt and - installed from the sources: + installed from source: &prompt.root; cd /usr/src &prompt.root; env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null @@ -437,8 +427,8 @@ MergeChanges /etc/ /var/named/etc/rm -rf /boot/GENERIC/boot For this kernel to be picked up as - GENERIC - by freebsd-update, the + GENERIC by + freebsd-update, the GENERIC configuration file must not have been modified in any way. It is also suggested that it is built without any other special @@ -467,8 +457,8 @@ MergeChanges /etc/ /var/named/etc/ If physical access to the machine is available, a copy of the GENERIC kernel can be - installed from the CD-ROM media. Load the - installation disc and use these commands: + installed from the installation media using these + commands: &prompt.root; mount /cdrom &prompt.root; cd /cdrom/usr/freebsd-dist @@ -478,7 +468,7 @@ MergeChanges /etc/ /var/named/etc/ If the options above cannot be used, the GENERIC kernel may be rebuilt and - installed from the sources: + installed from source: &prompt.root; cd /usr/src &prompt.root; make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null @@ -503,21 +493,20 @@ MergeChanges /etc/ /var/named/etc/Major and minor version upgrades may be performed by providing freebsd-update with a release - version target, for example, the following command will - update to &os; 8.1: + version target. The following command will update to + &os; 9.1: - &prompt.root; freebsd-update -r 8.1-RELEASE upgrade + &prompt.root; freebsd-update -r 9.1-RELEASE upgrade After the command has been received, freebsd-update will evaluate the configuration file and current system in an attempt to - gather the information necessary to update the system. A - screen listing will display what components have been - detected and what components have not been detected. For - example: + gather the information necessary to perform the upgrade. A + screen listing will display which components have and have + not been detected. For example: Looking up update.FreeBSD.org mirrors... 1 mirrors found. -Fetching metadata signature for 8.0-RELEASE from update1.FreeBSD.org... done. +Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done. Fetching metadata index... done. Inspecting system... done. @@ -542,7 +531,7 @@ Does this look reasonable (y/n)? y WARNING: This system is running a "MYKERNEL" kernel, which is not a -kernel configuration distributed as part of FreeBSD 8.0-RELEASE. +kernel configuration distributed as part of FreeBSD 9.0-RELEASE. This kernel will not be updated: you MUST update the kernel manually before running "/usr/sbin/freebsd-update install" @@ -550,57 +539,53 @@ before running "/usr/sbin/freebsd-update updated GENERIC kernel will be used as an intermediate step in the upgrade process. - After all patches have been downloaded to the local - system, they will then be applied. This process may take a - while depending on the speed and workload of the machine. - Configuration files will then be merged — this - part of the process requires some user intervention as a - file may be merged or an editor may appear on screen for a - manual merge. The results of every successful merge will be - shown to the user as the process continues. A failed or - ignored merge will cause the process to abort. Users may - wish to make a backup of /etc and manually merge - important files, such as + Once all the patches have been downloaded to the local + system, they will be applied. This process may take a + while, depending on the speed and workload of the machine. + Configuration files will then be merged. The merging + process requires some user intervention as a file may be + merged or an editor may appear on screen for a manual merge. + The results of every successful merge will be shown to the + user as the process continues. A failed or ignored merge + will cause the process to abort. Users may wish to make a + backup of /etc and + manually merge important files, such as master.passwd or group at a later time. - The system is not being altered yet, all patching and - merging is happening in another directory. When all + The system is not being altered yet as all patching + and merging is happening in another directory. Once all patches have been applied successfully, all configuration files have been merged and it seems the process will go - smoothly, the changes will need to be committed by the - user. - - - Once this process is complete, the upgrade may be - committed to disk using the following command. + smoothly, the changes can be committed to disk by the + user using the following command: &prompt.root; freebsd-update install + + The kernel and kernel modules will be patched first. At - this point the machine must be rebooted. If the system was - running with a custom kernel, use the &man.nextboot.8; - command to set the kernel for the next boot to - /boot/GENERIC (which - was updated): + this point, the machine must be rebooted. If the system is + running with a custom kernel, use &man.nextboot.8; to set + the kernel for the next boot to the updated + /boot/GENERIC: &prompt.root; nextboot -k GENERIC Before rebooting with the GENERIC - kernel, make sure it contains all drivers required for - your system to boot properly (and connect to the network, - if the machine that is being updated is accessed - remotely). In particular, if the previously running - custom kernel contained built-in functionality usually - provided by kernel modules, make sure to temporarily load - these modules into the GENERIC kernel - using the /boot/loader.conf facility. - You may also wish to disable non-essential services, disk - and network mounts, etc. until the upgrade process is - complete. + kernel, make sure it contains all the drivers required for + the system to boot properly and connect to the network, + if the machine being updated is accessed remotely. In + particular, if the running custom kernel contains built-in + functionality usually provided by kernel modules, make + sure to temporarily load these modules into the + GENERIC kernel using the + /boot/loader.conf facility. + It is recommended to disable non-essential services as + well as any disk and network mounts until the upgrade + process is complete. The machine should now be restarted with the updated @@ -608,20 +593,19 @@ before running "/usr/sbin/freebsd-update &prompt.root; shutdown -r now - Once the system has come back online, - freebsd-update will need to be started - again. The state of the process has been saved and thus, + Once the system has come back online, restart + freebsd-update using the following + command. The state of the process has been saved and thus, freebsd-update will not start from the beginning, but will remove all old shared libraries and - object files. To continue to this stage, issue the - following command: + object files. &prompt.root; freebsd-update install - Depending on whether any libraries version numbers got - bumped, there may only be two install phases instead of - three. + Depending upon whether any library version numbers + were bumped, there may only be two install phases instead + of three. @@ -629,23 +613,17 @@ before running "/usr/sbin/freebsd-update Rebuilding Ports After a Major Version Upgrade After a major version upgrade, all third party software - will now need to be rebuilt and re-installed. This is - required as installed software may depend on libraries which - have been removed during the upgrade process. The - ports-mgmt/portupgrade - command may be used to automate this process. The following - commands may be used to begin this process: - - &prompt.root; portupgrade -f ruby -&prompt.root; rm /var/db/pkg/pkgdb.db -&prompt.root; portupgrade -f ruby18-bdb -&prompt.root; rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db -&prompt.root; portupgrade -af + needs to be rebuilt and re-installed. This is required as + installed software may depend on libraries which have been + removed during the upgrade process. This process can be + automated using ports-mgmt/portmaster: + + &prompt.root; portmaster -f Once this has completed, finish the upgrade process with - a final call to freebsd-update. Issue - the following command to tie up all loose ends in the - upgrade process: + a final call to freebsd-update in order + to tie up all the loose ends in the upgrade process: &prompt.root; freebsd-update install @@ -661,42 +639,38 @@ before running "/usr/sbin/freebsd-update System State Comparison - The freebsd-update utility may be used - to test the state of the installed &os; version against a - known good copy. This option evaluates the current version - of system utilities, libraries, and configuration files. - To begin the comparison, issue the following command: + freebsd-update can be used to test the + state of the installed &os; version against a known good copy. + This option evaluates the current version of system utilities, + libraries, and configuration files. To begin the comparison, + issue the following command: &prompt.root; freebsd-update IDS >> outfile.ids - While the command name is IDS it - should in no way be a replacement for an intrusion detection - system such as - security/snort. As + While the command name is IDS it is + not a replacement for a real intrusion detection system such + as security/snort. As freebsd-update stores data on disk, the possibility of tampering is evident. While this possibility - may be reduced by using the - kern.securelevel setting and storing the - freebsd-update data on a read only file - system when not in use, a better solution would be to - compare the system against a secure disk, such as a - DVD or securely stored external + may be reduced using kern.securelevel and + by storing the freebsd-update data on a + read only file system when not in use, a better solution + would be to compare the system against a secure disk, such + as a DVD or securely stored external USB disk device. - The system will now be inspected, and a list of files - along with their &man.sha256.1; hash values, both the known - value in the release and the current installed value, will be - printed. This is why the output has been sent to the - outfile.ids file. It scrolls by too - quickly for eye comparisons, and soon it fills up the console - buffer. - - These lines are also extremely long, but the output format - may be parsed quite easily. For instance, to obtain a list of - all files different from those in the release, issue the - following command: + The system will now be inspected, and a lengthy listing of + files, along with the &man.sha256.1; hash values for both the + known value in the release and the current installation, will + be sent to the specified + outfile.ids file. + + The entries in the listing are extremely long, but the + output format may be easily parsed. For instance, to obtain a + list of all files which differ from those in the release, + issue the following command: &prompt.root; cat outfile.ids | awk '{ print $1 }' | more /etc/master.passwd @@ -704,12 +678,12 @@ before running "/usr/sbin/freebsd-update /etc/passwd /etc/pf.conf - This output has been truncated, many more files exist. - Some of these files have natural modifications, the + This sample output has been truncated as many more files + exist. Some files have natural modifications. For example, /etc/passwd has been modified because - users have been added to the system. In some cases, there - may be other files, such as kernel modules, which differ - as freebsd-update may have updated them. + users have been added to the system. Other files, such as + kernel modules, may differ as + freebsd-update may have updated them. To exclude specific files or directories, add them to the IDSIgnorePaths option in /etc/freebsd-update.conf. @@ -744,14 +718,12 @@ before running "/usr/sbin/freebsd-update Updating and Upgrading - The base system of &os; includes a utility for updating - the Ports Collection too: the &man.portsnap.8; utility. Upon - execution, it will connect to a remote site, verify the secure - key, and download a new copy of the Ports Collection. The key - is used to verify the integrity of all downloaded files, - ensuring they have not been modified in-flight. To download the - latest Ports Collection files, issue the following - command: + The base system of &os; includes &man.portsnap.8; for + updating the Ports Collection. This utility connects to a + &os; site, verifies the secure key, and downloads a new copy of + the Ports Collection. The key is used to verify the integrity + of all downloaded files. To download the latest Ports + Collection files, issue the following command: &prompt.root; portsnap fetch Looking up portsnap.FreeBSD.org mirrors... 9 mirrors found. @@ -767,16 +739,16 @@ Fetching 133 new ports or files... done. What this example shows is that &man.portsnap.8; has found and verified several patches to the current ports data. This - also indicates that the utility was run previously, if it was a + also indicates that the utility was run previously; if it was a first time run, the collection would have simply been downloaded. When &man.portsnap.8; successfully completes a fetch operation, the Ports Collection and - subsequent patches exist on the local system that have passed + subsequent patches which exist on the local system have passed verification. The first time portsnap is - executed, you have to use extract to install - the downloaded files: + executed, use extract to install the + downloaded files: &prompt.root; portsnap extract /usr/ports/.cvsignore @@ -792,22 +764,22 @@ Fetching 133 new ports or files... done. /usr/ports/Mk/bsd.cmake.mk ... - To update an already installed Ports Collection use the - command portsnap update: + To update an already installed Ports Collection, use + portsnap update: &prompt.root; portsnap update The process is now complete, and applications may be installed or upgraded using the updated Ports Collection. - The fetch and extract - or update operations may be run - consecutively, as shown in the following example: + When using fetch, the + extract or the update + operation may be run consecutively: &prompt.root; portsnap fetch update - This command will download the latest version of the - Ports Collection and update your local version under + This command downloads the latest version of the Ports + Collection and updates the local version under /usr/ports. @@ -821,71 +793,66 @@ Fetching 133 new ports or files... done. Updating and Upgrading - Besides the base system and the Ports Collection, - documentation is an integral part of the &os; operating system. - While an up-to-date version of the &os; Documentation Set is - always available on the - &os; web site, - some users might have slow or no permanent network connectivity - at all. Fortunately, there are several ways to update the - documentation shipped with each release by maintaining a local - copy of the latest &os; Documentation Set. + Documentation is an integral part of the &os; operating + system. While an up-to-date version of the &os; Documentation + Set is always available on the &os; web site, + some users might have slow or no permanent network connectivity. + There are several ways to update the local copy of documentation + with the latest &os; Documentation Set. Using <application>Subversion</application> to Update the Documentation The &os; documentation sources can be obtained with - Subversion. This section - describes: + svn. This section + describes how to: - How to install the documentation toolchain, the tools - that are required to rebuild the &os; documentation from - its source. + Install the documentation toolchain, the tools that + are required to rebuild the &os; documentation from its + source. - How to download a copy of the documentation source - at /usr/doc, - using Subversion. + Download a copy of the documentation source at + /usr/doc, using + svn. - How to rebuild the &os; documentation from its source, - and install it under Rebuild the &os; documentation from its source, and + install it under /usr/share/doc. - Some of the build options that are supported by the - build system of the documentation, i.e., the options that - build only some of the different language translations of - the documentation or the options that select a specific - output format. + Recognize some of the build options that are + supported by the build system of the documentation, such + as the options that build only some of the different + language translations of the documentation or the options + that select a specific output format. - Installing <application>Subversion</application> and the + <title>Installing <application>svn</application> and the Documentation Toolchain Rebuilding the &os; documentation from source requires a - fairly large collection of tools. These tools are not part of - the &os; base system, because they need a large amount of disk - space and they are not useful to all &os; users; they are only - useful to those users that are actively writing new - documentation for &os; or are frequently updating their - documentation from source. - - All the required tools are available as part of the Ports - Collection. The - textproc/docproj port is a - master port that has been developed by the &os; Documentation - Project, to ease the initial installation and future updates - of these tools. + collection of tools which are not part of the &os; base system + due to the amount of disk space these tools use. They are + also not useful to all &os; users, only those users that are + actively writing new documentation for &os; or are frequently + updating their documentation from source. + + The required tools, including + svn, are available in the + textproc/docproj meta-port + developed by the &os; Documentation Project. When no &postscript; or PDF documentation required, one @@ -898,23 +865,18 @@ Fetching 133 new ports or files... done. of tools, so it may be quite sensible to omit its installation if PDF output is not really necessary. - - Subversion is installed with - the textproc/docproj - port. Updating the Documentation Sources - The Subversion program can + In this example, svn is used to fetch a clean copy of the documentation sources from the - western US mirror using the HTTPS protocol with this - command: + western US mirror using the HTTPS protocol: &prompt.root; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc - Please use the closest mirror from the available Select the closest mirror from the available Subversion mirror sites. The initial download of the documentation sources may take @@ -927,9 +889,8 @@ Fetching 133 new ports or files... done. After checking out the sources, an alternative way of updating the documentation is supported by the - Makefile of the - /usr/doc directory by - running: + /usr/doc/Makefile by running the + following commands: &prompt.root; cd /usr/doc &prompt.root; make update @@ -939,14 +900,13 @@ Fetching 133 new ports or files... done. Tunable Options of the Documentation Sources The updating and build system of the &os; documentation - supports a few options that ease the process of updating only - parts of the documentation, or the build of specific + set supports a few options that ease the process of updating + only parts of the documentation, or the build of specific translations. These options can be set either as system-wide - options in the /etc/make.conf file, or as - command-line options passed to the &man.make.1; - utility. + options in /etc/make.conf, or as + command-line options passed to &man.make.1;. - The following options are some of these: + The options include: @@ -954,8 +914,8 @@ Fetching 133 new ports or files... done. The list of languages and encodings to build and - install, e.g., en_US.ISO8859-1 for - the English documentation only. + install, such as en_US.ISO8859-1 for + English documentation. @@ -982,11 +942,12 @@ Fetching 133 new ports or files... done. - For more make variables supported as system-wide options - in &os;, see &man.make.conf.5;. + For more make variables supported as + system-wide options in &os;, refer to + &man.make.conf.5;. - For more make variables supported by the build system of - the &os; documentation, please refer to the + For more make variables supported by + the build system of the &os; documentation, refer to the &os; Documentation Project Primer for New Contributors. @@ -995,14 +956,13 @@ Fetching 133 new ports or files... done. Installing the &os; Documentation from Source - When an up-to-date snapshot of the documentation sources - has been fetched in - /usr/doc, everything is + Once an up-to-date snapshot of the documentation sources *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***