Update the freebsd-update section:

Define minor and major version upgrades at the start of the section.
Mention that installed applications will still run after a minor
upgrade.  Split the custom kernel portion into 8.X and earlier and 9.X
and later.  Make the portupgrade instructions specific to major version
upgrades.

PR:		www/175069
Submitted by:	George Kontostanos <gkontos.mail@gmail.com>
Reviewed by:	freebsd-doc mailing list

en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml

@@ -352,15 +352,23 @@ MergeChanges /etc/ /var/named/etc/</programlisting>
     </sect2>
 
     <sect2 id="freebsdupdate-upgrade">
-      <title>Major and Minor Upgrades</title>
+      <title>Major and Minor Version Upgrades</title>
 
-      <para>This process will remove old object files and
+      <para>Upgrades from one minor version of &os; to another, like
+	from &os;&nbsp;9.0 to &os;&nbsp;9.1, are called
+	<emphasis>minor version</emphasis> upgrades.  Generally,
+	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;&nbsp;8.X to &os;&nbsp;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 later using the
+	and re-installed or upgraded after a major version upgrade by using the
 	<filename role="package">ports-mgmt/portupgrade</filename>
-	utility.  Most users will want to run a test build using
+	utility.  A brute-force rebuild of all installed
-	the following command:</para>
+	applications can be accomplished with this command:</para>
 
       <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
 
@@ -371,8 +379,17 @@ MergeChanges /etc/ /var/named/etc/</programlisting>
 	any prompts during this process, removing the need for
 	manual intervention during the build process.</para>
 
+      <sect3 id="freebsd-update-custom-kernel">
+	<title>Dealing with Custom Kernels</title>
+
 	<para>If a custom kernel is in use, the upgrade process is
-	slightly more involved.  A copy of the
+	  slightly more involved, and the procedure varies depending on
+	  the version of &os;.</para>
+
+	<sect4 id="freebsd-update-custom-kernel-8x">
+	  <title>Custom Kernels with &os;&nbsp;8.X and Earlier</title>
+
+	  <para>A copy of the
 	    <filename>GENERIC</filename> kernel is needed, and it should
 	    be placed in
 	    <filename class="directory">/boot/GENERIC</filename>.  If the
@@ -430,8 +447,60 @@ MergeChanges /etc/ /var/named/etc/</programlisting>
 
 	  <para>Rebooting to the <filename>GENERIC</filename> kernel is
 	    not required at this stage.</para>
+	</sect4>
 
-      <para>Major and minor version updates may be performed by
+	<sect4 id="freebsd-update-custom-kernel-9x">
+	  <title>Custom Kernels with &os;&nbsp;9.X and Later</title>
+
+	  <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 <literal>GENERIC</literal> kernel.
+		Rename this directory to <filename
+		  class="directory">/boot/kernel</filename>.</para>
+	    </listitem>
+
+	    <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>
+
+	      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
+&prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput>
+&prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen>
+	    </listitem>
+
+	    <listitem>
+	      <para>If the options above cannot be used, the
+		<literal>GENERIC</literal> kernel may be rebuilt and
+		installed from the sources:</para>
+
+	      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make kernel</userinput></screen>
+
+	      <para>For this kernel to be identified as the
+		<literal>GENERIC</literal> kernel by
+		<command>freebsd-update</command>, the
+		<filename>GENERIC</filename> configuration file must
+		not have been modified in any way.  It is also
+		suggested that the kernel is built without any other
+		special options, preferably with an empty
+		<filename>/etc/make.conf</filename>.</para>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>Rebooting to the <filename>GENERIC</filename> kernel is
+	    not required at this stage.</para>
+	</sect4>
+      </sect3>
+
+      <sect3 id="freebsdupdate-using">
+	<title>Performing the Upgrade</title>
+
+	<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;&nbsp;8.1:</para>
@@ -551,8 +620,12 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	    bumped, there may only be two install phases instead of
 	    three.</para>
 	</note>
+      </sect3>
 
-      <para>All third party software will now need to be rebuilt and
+      <sect3 id="freebsdupdate-portsrebuild">
+	<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
@@ -579,6 +652,7 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
 	<para>Reboot the machine into the new &os; version.  The process
 	  is complete.</para>
+      </sect3>
     </sect2>
 
     <sect2 id="freebsdupdate-system-comparison">