svn commit: r40998 - head/en_US.ISO8859-1/books/handbook/cutting-edge

Dru Lavigne dru at FreeBSD.org
Sun Feb 17 17:28:27 UTC 2013


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.</para>
+      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.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
-	<para>What utilities may be used to update the system and
+	<para>Which utilities are available to update the system and
 	  the Ports Collection.</para>
       </listitem>
 
       <listitem>
-	<para>How to keep your system up to date with
+	<para>How to keep a &os; system up-to-date with
 	  <application>freebsd-update</application>,
 	  <application>Subversion</application>, or
 	  <application>CTM</application>.</para>
@@ -80,7 +78,7 @@
       </listitem>
 
       <listitem>
-	<para>How to keep your documentation up to date with
+	<para>How to keep the installed documentation up-to-date with
 	  <application>Subversion</application> or documentation
 	  ports<!--, and <application>Docsnap</application>-->.</para>
       </listitem>
@@ -92,7 +90,7 @@
 
       <listitem>
 	<para>How to rebuild and reinstall the entire base
-	  system with <command>make buildworld</command> (etc).</para>
+	  system.</para>
       </listitem>
     </itemizedlist>
 
@@ -100,7 +98,7 @@
 
     <itemizedlist>
       <listitem>
-	<para>Properly set up your network connection (<xref
+	<para>Properly set up the network connection (<xref
 	    linkend="advanced-networking"/>).</para>
       </listitem>
 
@@ -111,10 +109,10 @@
     </itemizedlist>
 
     <note>
-      <para>Throughout this chapter, the <command>svn</command>
-	command is used to obtain and update &os; sources.  To use it,
-	you will need to install the port or the package for <filename
-	  role="package">devel/subversion</filename>.</para>
+      <para>Throughout this chapter, <command>svn</command> is used to
+	obtain and update &os; sources.  To use it, first install the
+	<filename role="package">devel/subversion</filename> port or
+	package.</para>
     </note>
   </sect1>
 
@@ -135,7 +133,7 @@
 	</author>
       </authorgroup>
     </sect1info>
-    <title>FreeBSD Update</title>
+    <title>&os; Update</title>
 
     <indexterm><primary>Updating and Upgrading</primary></indexterm>
     <indexterm>
@@ -145,13 +143,13 @@
 
     <para>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.</para>
 
     <para>This is no longer the case as &os; now includes a utility
-      simply called <command>freebsd-update</command>.  This utility
+      called <command>freebsd-update</command>.  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 @@
 
     <note>
       <para>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:
-	<ulink url="http://www.FreeBSD.org/releases/"></ulink>.</para>
+	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 <ulink
+	  url="http://www.FreeBSD.org/releases/"></ulink>.</para>
     </note>
 
     <para>If a <command>crontab</command> utilizing the features
@@ -175,39 +172,38 @@
       <title>The Configuration File</title>
 
       <para>Some users may wish to tweak the default configuration
-	file in <filename>/etc/freebsd-update.conf</filename>,
-	allowing better control of the process.  The options are very
-	well documented, but the following few may require a bit more
+	in <filename>/etc/freebsd-update.conf</filename>, allowing
+	better control of the process.  The options are well
+	documented, but the following may require a bit more
 	explanation:</para>
 
       <programlisting># Components of the base system which should be kept updated.
 Components src world kernel</programlisting>
 
-      <para>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
-	<literal>world/games</literal> here would allow game patches
-	to be applied.  Using <literal>src/bin</literal> would allow
-	the source code in
-	<filename class="directory">src/bin</filename> to be
-	updated.</para>
+      <para>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
+	<literal>world/games</literal> would allow game patches to be
+	applied.  Using <literal>src/bin</literal> would allow the
+	source code in <filename class="directory">src/bin</filename>
+	to be updated.</para>
 
       <para>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.</para>
+	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.</para>
 
       <programlisting># Paths which start with anything matching an entry in an IgnorePaths
 # statement will be ignored.
 IgnorePaths</programlisting>
 
-      <para>Add paths, such as
+      <para>To leave specified directories, such as
 	<filename class="directory">/bin</filename> or
-	<filename class="directory">/sbin</filename> to leave these
-	specific directories untouched during the update
-	process.  This option may be used to prevent
+	<filename class="directory">/sbin</filename>, untouched during
+	the update process, add their paths to this statement.  This
+	option may be used to prevent
 	<command>freebsd-update</command> from overwriting local
 	modifications.</para>
 
@@ -216,8 +212,8 @@ IgnorePaths</programlisting>
 # modified by the user (unless changes are merged; see below).
 UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile</programlisting>
 
-      <para>Update configuration files in the specified directories
-	only if they have not been modified.  Any changes made by the
+      <para>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,
 	<literal>KeepModifiedMetadata</literal>, which will instruct
@@ -229,24 +225,23 @@ UpdateIfUnmodified /etc/ /var/ /root/ /.
 MergeChanges /etc/ /var/named/etc/</programlisting>
 
       <para>List of directories with configuration files that
-	<command>freebsd-update</command> should attempt merges in.
+	<command>freebsd-update</command> 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
 	<command>freebsd-update</command> will abort.  When in doubt,
 	backup <filename class="directory">/etc</filename> and just
 	accept the merges.  See <xref linkend="mergemaster"/> for more
-	information about the <command>mergemaster</command>
-	command.</para>
+	information about <command>mergemaster</command>.</para>
 
       <programlisting># Directory in which to store downloaded updates and temporary
 # files used by &os; Update.
 # WorkDir /var/db/freebsd-update</programlisting>
 
-      <para>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.</para>
+      <para>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.</para>
 
       <programlisting># 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/</prog
 # which actually are installed and upgrade those (StrictComponents no)?
 # StrictComponents no</programlisting>
 
-      <para>When set to <literal>yes</literal>,
+      <para>When this option is set to <literal>yes</literal>,
 	<command>freebsd-update</command> will assume that the
 	<literal>Components</literal> list is complete and will not
 	attempt to make changes outside of the list.  Effectively,
@@ -266,32 +261,30 @@ MergeChanges /etc/ /var/named/etc/</prog
     <sect2 id="freebsdupdate-security-patches">
       <title>Security Patches</title>
 
-      <para>Security patches are stored on a remote machine and
-	may be downloaded and installed using the following
-	command:</para>
+      <para>&os; security patches may be downloaded and installed
+	using the following command:</para>
 
       <screen>&prompt.root; <userinput>freebsd-update fetch</userinput>
 &prompt.root; <userinput>freebsd-update install</userinput></screen>
 
-      <para>If any kernel patches have been applied the system will
-	need a reboot.  If all went well the system should be patched
-	and <command>freebsd-update</command> may be run as a nightly
-	&man.cron.8; job.  An entry in
-	<filename>/etc/crontab</filename> would be sufficient to
-	accomplish this task:</para>
+      <para>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
+	<command>freebsd-update</command> may be run as a nightly
+	&man.cron.8; job by adding this entry to
+	<filename>/etc/crontab</filename>:</para>
 
       <programlisting>@daily                                  root    freebsd-update cron</programlisting>
 
-      <para>This entry states that once every day, the
-	<command>freebsd-update</command> utility will be run.  In
-	this way, using the <option>cron</option> argument,
+      <para>This entry states that <command>freebsd-update</command>
+	will run once every day.  When run with <option>cron</option>,
 	<command>freebsd-update</command> will only check if updates
 	exist.  If patches exist, they will automatically be
-	downloaded to the local disk but not applied.  The
-	<username>root</username> user will be sent an email so they
-	may install them manually.</para>
+	downloaded to the local disk but will not be applied.  The
+	<username>root</username> user will be sent an email so that
+	they may be reviewed and manually installed.</para>
 
-      <para>If anything went wrong, <command>freebsd-update</command>
+      <para>If anything goes wrong, <command>freebsd-update</command>
 	has the ability to roll back the last set of changes with
 	the following command:</para>
 
@@ -301,16 +294,15 @@ MergeChanges /etc/ /var/named/etc/</prog
 	kernel or any kernel modules were modified.  This will allow
 	&os; to load the new binaries into memory.</para>
 
-      <para>The <command>freebsd-update</command> utility can
-	automatically update the <filename>GENERIC</filename> kernel
-	only.  If a custom kernel is in use, it will have to be
-	rebuilt and reinstalled after
-	<command>freebsd-update</command> finishes installing the rest
-	of the updates.  However, <command>freebsd-update</command>
-	will detect and update the <filename>GENERIC</filename> kernel
-	in
-	<filename class="directory">/boot/GENERIC</filename> (if it
-	exists), even if it is not the current (running) kernel of the
+      <para>Only the <filename>GENERIC</filename> kernel can be
+	automatically updated by <command>freebsd-update</command>.
+	If a custom kernel is installed, it will have to be rebuilt
+	and reinstalled after <command>freebsd-update</command>
+	finishes installing the rest of the updates.  However,
+	<command>freebsd-update</command> will detect and update the
+	<filename>GENERIC</filename> kernel if
+	<filename class="directory">/boot/GENERIC</filename> exists,
+	even if it is not the current running kernel of the
 	system.</para>
 
       <note>
@@ -327,22 +319,22 @@ MergeChanges /etc/ /var/named/etc/</prog
 	<filename>/etc/freebsd-update.conf</filename> has been
 	changed, <command>freebsd-update</command> 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.</para>
 
       <note>
-	<para>The updates distributed via
-	  <command>freebsd-update</command>, 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 <command>freebsd-update install</command>.
+	<para>The updates distributed by
+	  <command>freebsd-update</command> 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 <command>freebsd-update install</command>.
 	  However, <command>freebsd-update</command> will always
-	  update the <filename>/usr/src/sys/conf/newvers.sh</filename>
-	  file.  The current patch level (as indicated by the
+	  update <filename>/usr/src/sys/conf/newvers.sh</filename>.
+	  The current patch level, as indicated by the
 	  <literal>-p</literal> number reported by
-	  <command>uname -r</command>) is obtained from this file.
-	  Rebuilding your custom kernel, even if nothing else changed,
-	  will allow &man.uname.1; to accurately report the current
+	  <command>uname -r</command>, 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.</para>
@@ -358,18 +350,18 @@ MergeChanges /etc/ /var/named/etc/</prog
 	installed applications will continue to work without problems
 	after minor version upgrades.</para>
 
-      <para><emphasis>Major version</emphasis> 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
-	<filename role="package">ports-mgmt/portupgrade</filename>
-	utility.  A brute-force rebuild of all installed
-	applications can be accomplished with this command:</para>
+      <para><emphasis>Major version</emphasis> 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
+	<filename role="package">ports-mgmt/portmaster</filename>.  A
+	brute-force rebuild of all installed applications can be
+	accomplished with this command:</para>
 
-      <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
+      <screen>&prompt.root; <userinput>portmaster -f</userinput></screen>
 
       <para>This will ensure everything will be re-installed
 	correctly.  Note that setting the
@@ -388,30 +380,28 @@ MergeChanges /etc/ /var/named/etc/</prog
 	<sect4 id="freebsd-update-custom-kernel-8x">
 	  <title>Custom Kernels with &os; 8.X and Earlier</title>
 
-	  <para>A copy of the
-	    <filename>GENERIC</filename> kernel is needed, and it
-	    should be placed in <filename
+	  <para>A copy of the <filename>GENERIC</filename> kernel is
+	    needed, and should be placed in <filename
 	      class="directory">/boot/GENERIC</filename>.  If the
-	    <filename>GENERIC</filename> kernel is not already present
-	    in the system, it may be obtained using one of the
-	    following methods:</para>
+	    <filename>GENERIC</filename> kernel is not present in the
+	    system, it may be obtained using one of the following
+	    methods:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>If a custom kernel has only been built once, the
 		kernel in <filename
 		  class="directory">/boot/kernel.old</filename> is
-		actually the <filename>GENERIC</filename> one.  Simply
-		rename this directory to <filename
+		actually <filename>GENERIC</filename>.  Rename this
+		directory to <filename
 		  class="directory">/boot/GENERIC</filename>.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Assuming physical access to the machine is
 		possible, a copy of the <filename>GENERIC</filename>
-		kernel can be installed from the CD-ROM media.  Insert
-		your installation disc and use the following
-		commands:</para>
+		kernel can be installed from the installation media
+		using the following commands:</para>
 
 	      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
@@ -419,7 +409,7 @@ MergeChanges /etc/ /var/named/etc/</prog
 
 	      <para>Replace <filename
 		  class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
-		with the actual version of the release you are using.
+		with the actual version of the release being used.
 		The <filename>GENERIC</filename> kernel will be
 		installed in <filename
 		  class="directory">/boot/GENERIC</filename> by
@@ -429,7 +419,7 @@ MergeChanges /etc/ /var/named/etc/</prog
 	    <listitem>
 	      <para>Failing all the above, the
 		<filename>GENERIC</filename> kernel may be rebuilt and
-		installed from the sources:</para>
+		installed from source:</para>
 
 	      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput>
@@ -437,8 +427,8 @@ MergeChanges /etc/ /var/named/etc/</prog
 &prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>
 
 	      <para>For this kernel to be picked up as
-		<filename>GENERIC</filename>
-		by <command>freebsd-update</command>, the
+		<filename>GENERIC</filename> by
+		<command>freebsd-update</command>, the
 		<filename>GENERIC</filename> 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/</prog
 	    <listitem>
 	      <para>If physical access to the machine is available, a
 		copy of the <literal>GENERIC</literal> kernel can be
-		installed from the CD-ROM media.  Load the
-		installation disc and use these commands:</para>
+		installed from the installation media using these
+		commands:</para>
 
 	      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput>
@@ -478,7 +468,7 @@ MergeChanges /etc/ /var/named/etc/</prog
 	    <listitem>
 	      <para>If the options above cannot be used, the
 		<literal>GENERIC</literal> kernel may be rebuilt and
-		installed from the sources:</para>
+		installed from source:</para>
 
 	      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput></screen>
@@ -503,21 +493,20 @@ MergeChanges /etc/ /var/named/etc/</prog
 
 	<para>Major and minor version upgrades may be performed by
 	  providing <command>freebsd-update</command> with a release
-	  version target, for example, the following command will
-	  update to &os; 8.1:</para>
+	  version target.  The following command will update to
+	  &os; 9.1:</para>
 
-	<screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen>
+	<screen>&prompt.root; <userinput>freebsd-update -r 9.1-RELEASE upgrade</userinput></screen>
 
 	<para>After the command has been received,
 	  <command>freebsd-update</command> 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:</para>
+	  gather the information necessary to perform the upgrade.  A
+	  screen listing will display which components have and have
+	  not been detected.  For example:</para>
 
 	<screen>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</scre
 	  a warning similar to the following:</para>
 
 	<screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" 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"</screen>
 
@@ -550,57 +539,53 @@ before running "/usr/sbin/freebsd-update
 	  updated <filename>GENERIC</filename> kernel will be used as
 	  an intermediate step in the upgrade process.</para>
 
-	<para>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 <filename
-	    class="directory">/etc</filename> and manually merge
-	  important files, such as
+	<para>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 <filename class="directory">/etc</filename> and
+	  manually merge important files, such as
 	  <filename>master.passwd</filename> or
 	  <filename>group</filename> at a later time.</para>
 
 	<note>
-	  <para>The system is not being altered yet, all patching and
-	    merging is happening in another directory.  When all
+	  <para>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.</para>
-	</note>
-
-	<para>Once this process is complete, the upgrade may be
-	  committed to disk using the following command.</para>
+	    smoothly, the changes can be committed to disk by the
+	    user using the following command:</para>
 
 	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
 
+	</note>
+
 	<para>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
-	  <filename class="directory">/boot/GENERIC</filename> (which
-	  was updated):</para>
+	  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
+	  <filename class="directory">/boot/GENERIC</filename>:</para>
 
 	<screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>
 
 	<warning>
 	  <para>Before rebooting with the <filename>GENERIC</filename>
-	    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 <filename>GENERIC</filename> kernel
-	    using the <filename>/boot/loader.conf</filename> facility.
-	    You may also wish to disable non-essential services, disk
-	    and network mounts, etc. until the upgrade process is
-	    complete.</para>
+	    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
+	    <filename>GENERIC</filename> kernel using the
+	    <filename>/boot/loader.conf</filename> facility.
+	    It is recommended to disable non-essential services as
+	    well as any disk and network mounts until the upgrade
+	    process is complete.</para>
 	</warning>
 
 	<para>The machine should now be restarted with the updated
@@ -608,20 +593,19 @@ before running "/usr/sbin/freebsd-update
 
 	<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
 
-	<para>Once the system has come back online,
-	  <command>freebsd-update</command> will need to be started
-	  again.  The state of the process has been saved and thus,
+	<para>Once the system has come back online, restart
+	  <command>freebsd-update</command> using the following
+	  command.  The state of the process has been saved and thus,
 	  <command>freebsd-update</command> 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:</para>
+	  object files.</para>
 
 	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
 
 	<note>
-	  <para>Depending on whether any libraries version numbers got
-	    bumped, there may only be two install phases instead of
-	    three.</para>
+	  <para>Depending upon whether any library version numbers
+	    were bumped, there may only be two install phases instead
+	    of three.</para>
 	</note>
       </sect3>
 
@@ -629,23 +613,17 @@ before running "/usr/sbin/freebsd-update
 	<title>Rebuilding Ports After a Major Version Upgrade</title>
 
 	<para>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
-	  <filename role="package">ports-mgmt/portupgrade</filename>
-	  command may be used to automate this process.  The following
-	  commands may be used to begin this process:</para>
-
-	<screen>&prompt.root; <userinput>portupgrade -f ruby</userinput>
-&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput>
-&prompt.root; <userinput>portupgrade -f ruby18-bdb</userinput>
-&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput>
-&prompt.root; <userinput>portupgrade -af</userinput></screen>
+	  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 <filename
+	    role="package">ports-mgmt/portmaster</filename>:</para>
+
+	<screen>&prompt.root; <userinput>portmaster -f</userinput></screen>
 
 	<para>Once this has completed, finish the upgrade process with
-	  a final call to <command>freebsd-update</command>.  Issue
-	  the following command to tie up all loose ends in the
-	  upgrade process:</para>
+	  a final call to <command>freebsd-update</command> in order
+	  to tie up all the loose ends in the upgrade process:</para>
 
 	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
 
@@ -661,42 +639,38 @@ before running "/usr/sbin/freebsd-update
     <sect2 id="freebsdupdate-system-comparison">
       <title>System State Comparison</title>
 
-      <para>The <command>freebsd-update</command> 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:</para>
+      <para><command>freebsd-update</command> 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:</para>
 
       <screen>&prompt.root; <userinput>freebsd-update IDS >> outfile.ids</userinput></screen>
 
       <warning>
-	<para>While the command name is <acronym>IDS</acronym> it
-	  should in no way be a replacement for an intrusion detection
-	  system such as
-	  <filename role="package">security/snort</filename>.  As
+	<para>While the command name is <acronym>IDS</acronym> it is
+	  not a replacement for a real intrusion detection system such
+	  as <filename role="package">security/snort</filename>.  As
 	  <command>freebsd-update</command> stores data on disk, the
 	  possibility of tampering is evident.  While this possibility
-	  may be reduced by using the
-	  <varname>kern.securelevel</varname> setting and storing the
-	  <command>freebsd-update</command> 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
-	  <acronym>DVD</acronym> or securely stored external
+	  may be reduced using <varname>kern.securelevel</varname> and
+	  by storing the <command>freebsd-update</command> 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 <acronym>DVD</acronym> or securely stored external
 	  <acronym>USB</acronym> disk device.</para>
       </warning>
 
-      <para>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
-	<filename>outfile.ids</filename> file.  It scrolls by too
-	quickly for eye comparisons, and soon it fills up the console
-	buffer.</para>
-
-      <para>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:</para>
+      <para>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
+	<filename>outfile.ids</filename> file.</para>
+
+      <para>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:</para>
 
       <screen>&prompt.root; <userinput>cat outfile.ids | awk '{ print $1 }' | more</userinput>
 /etc/master.passwd
@@ -704,12 +678,12 @@ before running "/usr/sbin/freebsd-update
 /etc/passwd
 /etc/pf.conf</screen>
 
-      <para>This output has been truncated, many more files exist.
-	Some of these files have natural modifications, the
+      <para>This sample output has been truncated as many more files
+	exist.  Some files have natural modifications.  For example,
 	<filename>/etc/passwd</filename> 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 <command>freebsd-update</command> may have updated them.
+	users have been added to the system.  Other files, such as
+	kernel modules, may differ as
+	<command>freebsd-update</command> may have updated them.
 	To exclude specific files or directories, add them to the
 	<literal>IDSIgnorePaths</literal> option in
 	<filename>/etc/freebsd-update.conf</filename>.</para>
@@ -744,14 +718,12 @@ before running "/usr/sbin/freebsd-update
       <see>Updating and Upgrading</see>
     </indexterm>
 
-    <para>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:</para>
+    <para>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:</para>
 
     <screen>&prompt.root; <userinput>portsnap fetch</userinput>
 Looking up portsnap.FreeBSD.org mirrors... 9 mirrors found.
@@ -767,16 +739,16 @@ Fetching 133 new ports or files... done.
 
     <para>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.</para>
 
     <para>When &man.portsnap.8; successfully completes a
       <command>fetch</command> 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 <command>portsnap</command> is
-      executed, you have to use <literal>extract</literal> to install
-      the downloaded files:</para>
+      executed, use <literal>extract</literal> to install the
+      downloaded files:</para>
 
     <screen>&prompt.root; <userinput>portsnap extract</userinput>
 /usr/ports/.cvsignore
@@ -792,22 +764,22 @@ Fetching 133 new ports or files... done.
 /usr/ports/Mk/bsd.cmake.mk
 <replaceable>...</replaceable></screen>
 
-    <para>To update an already installed Ports Collection use the
-      command <command>portsnap update</command>:</para>
+    <para>To update an already installed Ports Collection, use
+      <command>portsnap update</command>:</para>
 
     <screen>&prompt.root; <userinput>portsnap update</userinput></screen>
 
     <para>The process is now complete, and applications may be
       installed or upgraded using the updated Ports Collection.</para>
 
-    <para>The <literal>fetch</literal> and <literal>extract</literal>
-      or <literal>update</literal> operations may be run
-      consecutively, as shown in the following example:</para>
+    <para>When using <literal>fetch</literal>, the
+      <literal>extract</literal> or the <literal>update</literal>
+      operation may be run consecutively:</para>
 
     <screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
 
-    <para>This command will download the latest version of the
-      Ports Collection and update your local version under
+    <para>This command downloads the latest version of the Ports
+      Collection and updates the local version under
       <filename class="directory">/usr/ports</filename>.</para>
   </sect1>
 
@@ -821,71 +793,66 @@ Fetching 133 new ports or files... done.
       <see>Updating and Upgrading</see>
     </indexterm>
 
-    <para>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
-      <ulink url="http://www.freebsd.org/doc/">&os; web site</ulink>,
-      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.</para>
+    <para>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 <ulink
+	url="http://www.freebsd.org/doc/">&os; web site</ulink>,
+      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.</para>
 
     <sect2 id="dsvn-doc">
       <title>Using <application>Subversion</application> to Update the
 	Documentation</title>
 
       <para>The &os; documentation sources can be obtained with
-	<application>Subversion</application>.  This section
-	describes:</para>
+	<application>svn</application>.  This section
+	describes how to:</para>
 
       <itemizedlist>
 	<listitem>
-	  <para>How to install the documentation toolchain, the tools
-	    that are required to rebuild the &os; documentation from
-	    its source.</para>
+	  <para>Install the documentation toolchain, the tools that
+	    are required to rebuild the &os; documentation from its
+	    source.</para>
 	</listitem>
 
 	<listitem>
-	  <para>How to download a copy of the documentation source
-	    at <filename class="directory">/usr/doc</filename>,
-	    using <application>Subversion</application>.</para>
+	  <para>Download a copy of the documentation source at
+	    <filename class="directory">/usr/doc</filename>, using
+	    <application>svn</application>.</para>
 	</listitem>
 
 	<listitem>
-	  <para>How to rebuild the &os; documentation from its source,
-	    and install it under <filename
+	  <para>Rebuild the &os; documentation from its source, and
+	    install it under <filename
 	      class="directory">/usr/share/doc</filename>.</para>
 	</listitem>
 
 	<listitem>
-	  <para>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.</para>
+	  <para>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.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2 id="installing-documentation-toolchain">
-      <title>Installing <application>Subversion</application> and the
+      <title>Installing <application>svn</application> and the
 	Documentation Toolchain</title>
 
       <para>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.</para>
-
-      <para>All the required tools are available as part of the Ports
-	Collection.  The
-	<filename role="package">textproc/docproj</filename> 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.</para>
+	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.</para>
+
+      <para>The required tools, including
+	<application>svn</application>, are available in the
+	<filename role="package">textproc/docproj</filename> meta-port
+	developed by the &os; Documentation Project.</para>
 
       <note>
 	<para>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.</para>
       </note>
-
-      <para><application>Subversion</application> is installed with
-	the <filename role="package">textproc/docproj</filename>
-	port.</para>
     </sect2>
 
     <sect2 id="updating-documentation-sources">
       <title>Updating the Documentation Sources</title>
 
-      <para>The <application>Subversion</application> program can
+      <para>In this example, <application>svn</application> is used to
 	fetch a clean copy of the documentation sources from the
-	western US mirror using the HTTPS protocol with this
-	command:</para>
+	western US mirror using the HTTPS protocol:</para>
 
       <screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen>
 
-      <para>Please use the closest mirror from the available <link
+      <para>Select the closest mirror from the available <link
 	  linkend="svn-mirrors">Subversion mirror sites</link>.</para>
 
       <para>The initial download of the documentation sources may take
@@ -927,9 +889,8 @@ Fetching 133 new ports or files... done.
 
       <para>After checking out the sources, an alternative way of
 	updating the documentation is supported by the
-	<filename>Makefile</filename> of the
-	<filename class="directory">/usr/doc</filename> directory by
-	running:</para>
+	<filename>/usr/doc/Makefile</filename> by running the
+	following commands:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
 &prompt.root; <userinput>make update</userinput></screen>
@@ -939,14 +900,13 @@ Fetching 133 new ports or files... done.
       <title>Tunable Options of the Documentation Sources</title>
 
       <para>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 <filename>/etc/make.conf</filename> file, or as
-	command-line options passed to the &man.make.1;
-	utility.</para>
+	options in <filename>/etc/make.conf</filename>, or as
+	command-line options passed to &man.make.1;.</para>
 
-      <para>The following options are some of these:</para>
+      <para>The options include:</para>
 
       <variablelist>
 	<varlistentry>
@@ -954,8 +914,8 @@ Fetching 133 new ports or files... done.
 
 	  <listitem>
 	    <para>The list of languages and encodings to build and
-	      install, e.g., <literal>en_US.ISO8859-1</literal> for
-	      the English documentation only.</para>
+	      install, such as <literal>en_US.ISO8859-1</literal> for
+	      English documentation.</para>
 	  </listitem>
 	</varlistentry>
 
@@ -982,11 +942,12 @@ Fetching 133 new ports or files... done.
 	</varlistentry>
       </variablelist>
 
-      <para>For more make variables supported as system-wide options
-	in &os;, see &man.make.conf.5;.</para>
+      <para>For more <command>make</command> variables supported as
+	system-wide options in &os;, refer to
+	&man.make.conf.5;.</para>
 
-      <para>For more make variables supported by the build system of
-	the &os; documentation, please refer to the
+      <para>For more <command>make</command> variables supported by
+	the build system of the &os; documentation, refer to the
 	<ulink url="&url.doc.langbase;/books/fdp-primer">&os;
 	  Documentation Project Primer for New
 	  Contributors</ulink>.</para>
@@ -995,14 +956,13 @@ Fetching 133 new ports or files... done.
     <sect2 id="updating-installed-documentation">
       <title>Installing the &os; Documentation from Source</title>
 
-      <para>When an up-to-date snapshot of the documentation sources
-	has been fetched in
-	<filename class="directory">/usr/doc</filename>, everything is
+      <para>Once an up-to-date snapshot of the documentation sources

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***


More information about the svn-doc-all mailing list