ref-manual: Updated the section on devtool upgrade

Provided a bit of rationale on why and when you use this command.
Put in several links to help the reader get to related areas where
command use is explained.

(From yocto-docs rev: 7b30f29bfa15dd15f1388bb856e2047be55e7fb9)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 34 insertions, 7 deletions

diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml
index e29bf89e51..e4d27bfe50 100644
--- a/documentation/ref-manual/ref-devtool-reference.xml
+++ b/documentation/ref-manual/ref-devtool-reference.xml
@@ -426,12 +426,27 @@
         <title>Upgrading a Recipe</title>
 
         <para>
-            Use the <filename>devtool upgrade</filename> command
-            to upgrade an existing recipe to a new upstream version.
-            The command puts the upgraded recipe file into the
-            workspace along with any associated files, and extracts
-            the source tree to a specified location should patches
-            need rebased or added to as a result of the upgrade.
+            As software matures, upstream recipes are upgraded to newer
+            versions.
+            As a developer, you need to keep your local recipes up-to-date
+            with the upstream version releases.
+            Several methods exist by which you can upgrade recipes.
+            You can read about them in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
+            section of the Yocto Project Development Tasks Manual.
+            This section overviews the <filename>devtool upgrade</filename>
+            command.
+        </para>
+
+        <para>
+            The <filename>devtool upgrade</filename> command
+            upgrades an existing recipe to a more recent version of the
+            recipe upstream.
+            The command puts the upgraded recipe file along with any associated
+            files into a "workspace" and, if necessary, extracts the source
+            tree to a specified location.
+            During the upgrade, patches associated with the recipe are
+            rebased or added as needed.
         </para>
 
         <para>
@@ -443,9 +458,21 @@
             the version number to which you want to upgrade (i.e. the
             <link linkend='var-PV'><filename>PV</filename></link>),
             the source revision to which you want to upgrade (i.e. the
-            <link linkend='var-SRCREV'><filename>SRCREV</filename></link>,
+            <link linkend='var-SRCREV'><filename>SRCREV</filename></link>),
             whether or not to apply patches, and so forth.
         </para>
+
+        <para>
+            You can read more on the <filename>devtool upgrade</filename>
+            workflow in the
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>"
+            section in the Yocto Project Application Development and the
+            Extensible Software Development Kit (eSDK) Manual.
+            You can also see an example of how to use
+            <filename>devtool upgrade</filename> in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade'>Using <filename>devtool upgrade</filename></ulink>"
+            section in the Yocto Project Development Tasks Manual.
+        </para>
     </section>
 
     <section id='devtool-resetting-a-recipe'>