sdk-manual, dev-manual: Applied SDK review edits.

 * Removed the note box formatting for the cross-reference
   from the sdk-manual and dev-manual sections that
   talk about devtool.  The reference is now non-note
   form and goes to the ref-manual devtool quick ref.

 * Added devtool upgrade as a third item in the list that
   introduces methods to use devtool.

 * Fixed the working on the devtool finish step 5 for both
   the dev-manual and sdk-manual.

 * Renamed the new chapter that describes different projects
   you can use devtool on.  The focus is on using the SDK
   toolchain directly.

 * Scrubbed the entire sdk-manual for the term "toolchain
   installer" and replaced with "SDK installer".

(From yocto-docs rev: 6d4daef49cc6d54a700a8c3965c9e8814f75d20a)

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

6 files changed, 58 insertions, 49 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 1edead3d6b..0b76ad7191 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -646,12 +646,10 @@
 
         <para>
             The remainder of this section presents these workflows.
-            <note>
-                See the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
-                in the Yocto Project Reference Manual for more a
-                <filename>devtool</filename> reference.
-            </note>
+            See the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
+            in the Yocto Project Reference Manual for a
+            <filename>devtool</filename> quick reference.
         </para>
 
         <section id='use-devtool-to-integrate-new-code'>
@@ -1227,11 +1225,13 @@
                         <emphasis>Finish Your Work With the Recipe</emphasis>:
                         The <filename>devtool finish</filename> command creates
                         any patches corresponding to commits in the local
-                        Git repository, updates the recipe to point to them
-                        (or creates a <filename>.bbappend</filename> file to do
-                        so, depending on the specified destination layer), and
-                        then resets the recipe so that the recipe is built normally
-                        rather than from the workspace.
+                        Git repository, moves the new recipe to a more permanent
+                        layer, and then resets the recipe so that the recipe is
+                        built normally rather than from the workspace.
+                        If you specify a destination layer that is the same as
+                        the original source, then the old version of the
+                        recipe and associated files will be removed prior to
+                        adding the new version.
                         <literallayout class='monospaced'>
      $ devtool finish <replaceable>recipe layer</replaceable>
                         </literallayout>
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
index d7df36f827..3156f77258 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -13,7 +13,7 @@
         You can use existing, pre-built toolchains by locating and running
         an SDK installer script that ships with the Yocto Project.
         Using this method, you select and download an architecture-specific
-        toolchain installer and then run the script to hand-install the
+        SDK installer and then run the script to hand-install the
         toolchain.
     </para>
 
@@ -26,7 +26,7 @@
                 (i.e. <filename>i686</filename> for 32-bit machines or
                 <filename>x86_64</filename> for 64-bit machines).</para>
 
-                <para>Go into that folder and download the toolchain installer
+                <para>Go into that folder and download the SDK installer
                 whose name includes the appropriate target architecture.
                 The toolchains provided by the Yocto Project are based off of
                 the <filename>core-image-sato</filename> image and contain
@@ -56,8 +56,8 @@
     <title>Building an SDK Installer</title>
 
     <para>
-        As an alternative to locating and downloading a toolchain installer,
-        you can build the toolchain installer assuming you have first sourced
+        As an alternative to locating and downloading a SDK installer,
+        you can build the SDK installer assuming you have first sourced
         the environment setup script.
         See the
         "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
@@ -74,7 +74,7 @@
     </para>
 
     <para>
-        To build the toolchain installer for a standard SDK and populate
+        To build the SDK installer for a standard SDK and populate
         the SDK image, use the following command:
         <literallayout class='monospaced'>
      $ bitbake <replaceable>image</replaceable> -c populate_sdk
@@ -83,12 +83,12 @@
         <literallayout class='monospaced'>
      $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
         </literallayout>
-        These commands result in a toolchain installer that contains the sysroot
+        These commands result in a SDK installer that contains the sysroot
         that matches your target root filesystem.
     </para>
 
     <para>
-        When the <filename>bitbake</filename> command completes, the toolchain
+        When the <filename>bitbake</filename> command completes, the SDK
         installer will be in
         <filename>tmp/deploy/sdk</filename> in the Build Directory.
         <note><title>Notes</title>
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 8c568a739e..e5231233e8 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -25,10 +25,12 @@
     </para>
 
     <para>
-        You can use an extensible SDK to work on Makefile, Autotools, and
+        In addition to the functionality available through
+        <filename>devtool</filename>, you can alternatively make use of
+        the toolchain directly to work on Makefile, Autotools, and
         Eclipse-based projects.
         See the
-        "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
+        "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
         chapter for more information.
     </para>
 
@@ -102,7 +104,7 @@
 
                     &DISTRO;, &DISTRO;+snapshot
             </literallayout>
-            For example, the following toolchain installer is for a 64-bit
+            For example, the following SDK installer is for a 64-bit
             development host system and a i586-tuned target architecture
             based off the SDK for <filename>core-image-sato</filename> and
             using the current &DISTRO; snapshot:
@@ -111,7 +113,7 @@
             </literallayout>
             <note>
                 As an alternative to downloading an SDK, you can build the
-                toolchain installer.
+                SDK installer.
                 For information on building the installer, see the
                 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
                 section.
@@ -138,7 +140,7 @@
             The following command shows how to run the installer given a
             toolchain tarball for a 64-bit x86 development host system and
             a 64-bit x86 target architecture.
-            The example assumes the toolchain installer is located in
+            The example assumes the SDK installer is located in
             <filename>~/Downloads/</filename>.
             <note>
                 If you do not have write permissions for the directory
@@ -231,36 +233,41 @@
             called <filename>devtool</filename>.
             This tool provides a number of features that help
             you build, test and package software within the extensible SDK, and
-            optionally integrate it into an image built by the OpenEmbedded build
-            system.
+            optionally integrate it into an image built by the OpenEmbedded
+            build system.
         </para>
 
         <para>
-            The <filename>devtool</filename> command line is organized similarly
-            to
+            The <filename>devtool</filename> command line is organized
+            similarly to
             <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
             number of sub-commands for each function.
             You can run <filename>devtool --help</filename> to see all the
             commands.
-            <note>
-                See the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
-                in the Yocto Project Reference Manual for more a
-                <filename>devtool</filename> reference.
-            </note>
+            See the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
+            in the Yocto Project Reference Manual for a
+            <filename>devtool</filename> quick reference.
         </para>
 
         <para>
-            Two <filename>devtool</filename> subcommands that provide
+            Three <filename>devtool</filename> subcommands that provide
             entry-points into development are:
             <itemizedlist>
-                <listitem><para><emphasis><filename>devtool add</filename></emphasis>:
+                <listitem><para>
+                    <emphasis><filename>devtool add</filename></emphasis>:
                     Assists in adding new software to be built.
                     </para></listitem>
-                <listitem><para><emphasis><filename>devtool modify</filename></emphasis>:
+                <listitem><para>
+                    <emphasis><filename>devtool modify</filename></emphasis>:
                     Sets up an environment to enable you to modify the source of
                     an existing component.
                     </para></listitem>
+                <listitem><para>
+                    <emphasis><filename>devtool upgrade</filename></emphasis>:
+                    Updates an existing recipe so that you can build it for
+                    an updated set of source files.
+                    </para></listitem>
             </itemizedlist>
             As with the OpenEmbedded build system, "recipes" represent software
             packages within <filename>devtool</filename>.
@@ -853,11 +860,13 @@
                         <emphasis>Finish Your Work With the Recipe</emphasis>:
                         The <filename>devtool finish</filename> command creates
                         any patches corresponding to commits in the local
-                        Git repository, updates the recipe to point to them
-                        (or creates a <filename>.bbappend</filename> file to do
-                        so, depending on the specified destination layer), and
-                        then resets the recipe so that the recipe is built normally
-                        rather than from the workspace.
+                        Git repository, moves the new recipe to a more permanent
+                        layer, and then resets the recipe so that the recipe is
+                        built normally rather than from the workspace.
+                        If you specify a destination layer that is the same as
+                        the original source, then the old version of the
+                        recipe and associated files will be removed prior to
+                        adding the new version.
                         <literallayout class='monospaced'>
      $ devtool finish <replaceable>recipe layer</replaceable>
                         </literallayout>
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index e0f51e1cf1..68401690de 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -213,7 +213,7 @@
             hardware.
             Additionally, for an extensible SDK, the toolchain also has
             built-in <filename>devtool</filename> functionality.
-            This toolchain is created by running a toolchain installer script
+            This toolchain is created by running a SDK installer script
             or through a
             <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
             that is based on your Metadata configuration or extension for
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index 44cb49c0c8..7281e83ef5 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -97,7 +97,7 @@
 
                     &DISTRO;, &DISTRO;+snapshot
             </literallayout>
-            For example, the following toolchain installer is for a 64-bit
+            For example, the following SDK installer is for a 64-bit
             development host system and a i586-tuned target architecture
             based off the SDK for <filename>core-image-sato</filename> and
             using the current &DISTRO; snapshot:
@@ -106,7 +106,7 @@
             </literallayout>
             <note>
                 As an alternative to downloading an SDK, you can build the
-                toolchain installer.
+                SDK installer.
                 For information on building the installer, see the
                 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
                 section.
@@ -124,7 +124,7 @@
             However, when you run the SDK installer, you can choose an
             installation directory.
             <note>
-                You must change the permissions on the toolchain
+                You must change the permissions on the SDK
                 installer script so that it is executable:
                 <literallayout class='monospaced'>
      $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
@@ -136,7 +136,7 @@
             The following command shows how to run the installer given a
             toolchain tarball for a 64-bit x86 development host system and
             a 32-bit x86 target architecture.
-            The example assumes the toolchain installer is located in
+            The example assumes the SDK installer is located in
             <filename>~/Downloads/</filename>.
             <note>
                 If you do not have write permissions for the directory
diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml
index 15e533000c..9bd6868b2b 100644
--- a/documentation/sdk-manual/sdk-working-projects.xml
+++ b/documentation/sdk-manual/sdk-working-projects.xml
@@ -4,10 +4,10 @@
 
 <chapter id='sdk-working-projects'>
 
-    <title>Working with Different Types of Projects</title>
+    <title>Using the SDK Toolchain Directly</title>
 
     <para>
-        You can use extensible and standard SDKs when working with Makefile,
+        You can use the SDK toolchain directly with Makefile,
         Autotools, and <trademark class='trade'>Eclipse</trademark> based
         projects.
         This chapter covers information specific to each of these types of
@@ -387,7 +387,7 @@
                         section for installation information.
                         <note>
                             As an alternative to downloading an SDK, you can
-                            build the toolchain installer.
+                            build the SDK installer.
                             For information on building the installer, see the
                             "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
                             section.