sdk-manual: Updated devtool add workflow section.

Had to update the figure to use "Upstream Source" labels and
fix a wrong "devtool edit-recipe" command. That new figure went into
both figures folders for the sdk-manual and mega-manual areas.

Provideds some cleaner wording.

(From yocto-docs rev: 6225d04dd0551a840d929b752225064a222962bc)

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

3 files changed, 121 insertions, 132 deletions

diff --git a/documentation/mega-manual/figures/sdk-devtool-add-flow.png b/documentation/mega-manual/figures/sdk-devtool-add-flow.png
index c09e60e355..745a028729 100644
--- a/documentation/mega-manual/figures/sdk-devtool-add-flow.png
+++ b/documentation/mega-manual/figures/sdk-devtool-add-flow.png
diff --git a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
index 985ac331f1..745a028729 100644
--- a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
+++ b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index f23ecc8043..cde599d682 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -205,51 +205,13 @@
      SDK environment now set up; additionally you may now run devtool to perform development tasks.
      Run devtool --help for further details.
             </literallayout>
-<!--
-            Running the setup script defines many environment variables:
-            <literallayout class='monospaced'>
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
-     ARCH - missing this one.  It gets set in meta/recipes-devtools/python/python3-native_3.5.5.bb (ARCH=${TARGET_ARCH})
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flagsexport CROSS_COMPILE
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink>
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
-     KCFLAGS - missing this one.  It appears once in meta/classes/toolchain-scripts.bbclass
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
-     M4 - missing this one.  It appears once in meta/recipes-devtools/flex/flex_2.6.0.bb
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
-     OE_SKIP_SDK_CHECK - missing this one.  It appears in meta/classes/populate_sdk_ext.bbclass
-     OECORE_ACLOCAL_OPTS - missing this one.  It appears in meta/classes/toolchain-scripts.bbclass
-     OECORE_DISTRO_VERSION - missing this one.  It appears in meta/classes/toolchain-scripts.bbclass
-     OECORE_NATIVE_SYSROOT - missing this one.  It appears in meta/classes/toolchain-scripts.bbclass
-     OECORE_SDK_VERSION - missing this one.  It appears in meta/classes/toolchain-scripts.bbclass
-     OECORE_TARGET_SYSROOT - missing this one.  It appears in meta/classes/toolchain-scripts.bbclass
-     PATH - The Linux variable that specifies the set of directories where executable programs are located.
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
-     PKG_CONFIG_SYSROOT_DIR - missing this one.  It appears in meta/classes/cross-canadian.bbclass:export PKG_CONFIG_SYSROOT_DIR = "${STAGING_DIR_HOST}"
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run strip, which is used to strip symbols.
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
-            </literallayout>
--->
-        Running the setup script defines many environment variables needed in
-        order to use the SDK (e.g. <filename>PATH</filename>,
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
-        and so forth).
-        If you want to see all the environment variables the script exports,
-        examine the installation file itself.
+            Running the setup script defines many environment variables needed
+            in order to use the SDK (e.g. <filename>PATH</filename>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
+            and so forth).
+            If you want to see all the environment variables the script
+            exports, examine the installation file itself.
         </para>
     </section>
 
@@ -268,7 +230,7 @@
                 the extensible SDK.
                 You can use <filename>devtool</filename> to help you easily
                 develop any project whose build output must be part of an
-                image built using the OpenEmbedded build system.
+                image built using the build system.
             </note>
         </para>
 
@@ -288,8 +250,8 @@
         </para>
 
         <para>
-            Three <filename>devtool</filename> subcommands that provide
-            entry-points into development are:
+            Three <filename>devtool</filename> subcommands exist that provide
+            entry-points into development:
             <itemizedlist>
                 <listitem><para>
                     <emphasis><filename>devtool add</filename></emphasis>:
@@ -306,17 +268,17 @@
                     an updated set of source files.
                     </para></listitem>
             </itemizedlist>
-            As with the OpenEmbedded build system, "recipes" represent software
-            packages within <filename>devtool</filename>.
+            As with the build system, "recipes" represent software packages
+            within <filename>devtool</filename>.
             When you use <filename>devtool add</filename>, a recipe is
             automatically created.
             When you use <filename>devtool modify</filename>, the specified
-            existing recipe is used in order to determine where to get the source
-            code and how to patch it.
+            existing recipe is used in order to determine where to get the
+            source code and how to patch it.
             In both cases, an environment is set up so that when you build the
             recipe a source tree that is under your control is used in order to
             allow you to make changes to the source as desired.
-            By default, both new recipes and the source go into a "workspace"
+            By default, new recipes and the source go into a "workspace"
             directory under the SDK.
         </para>
 
@@ -363,10 +325,10 @@
                         generate a recipe based on existing source code.</para>
 
                         <para>In a shared development environment, it is
-                        typical where other developers are responsible for
+                        typical for other developers to be responsible for
                         various areas of source code.
                         As a developer, you are probably interested in using
-                        that source code as part of your development using
+                        that source code as part of your development within
                         the Yocto Project.
                         All you need is access to the code, a recipe, and a
                         controlled area in which to do your work.</para>
@@ -374,138 +336,164 @@
                         <para>Within the diagram, three possible scenarios
                         feed into the <filename>devtool add</filename> workflow:
                         <itemizedlist>
-                            <listitem><para><emphasis>Left</emphasis>:
-                                The left scenario represents a common situation
-                                where the source code does not exist locally
-                                and needs to be extracted.
-                                In this situation, you just let it get
-                                extracted to the default workspace - you do not
-                                want it in some specific location outside of the
-                                workspace.
-                                Thus, everything you need will be located in the
-                                workspace:
+                            <listitem><para>
+                                <emphasis>Left</emphasis>:
+                                The left scenario in the figure represents a
+                                common situation where the source code does not
+                                exist locally and needs to be extracted.
+                                In this situation, the source code is extracted
+                                to the default workspace - you do not
+                                want the files in some specific location
+                                outside of the workspace.
+                                Thus, everything you need will be located in
+                                the workspace:
                                 <literallayout class='monospaced'>
      $ devtool add <replaceable>recipe fetchuri</replaceable>
                                 </literallayout>
                                 With this command, <filename>devtool</filename>
-                                creates a recipe and an append file in the
-                                workspace as well as extracts the upstream
-                                source files into a local Git repository also
-                                within the <filename>sources</filename> folder.
+                                extracts the upstream source files into a local
+                                Git repository within the
+                                <filename>sources</filename> folder.
+                                The command then creates a recipe named
+                                <replaceable>recipe</replaceable> and a
+                                corresponding append file in the workspace.
+                                If you do not provide
+                                <replaceable>recipe</replaceable>, the command
+                                attempts to figure out the recipe name.
                                 </para></listitem>
-                            <listitem><para><emphasis>Middle</emphasis>:
-                                The middle scenario also represents a situation where
-                                the source code does not exist locally.
+                            <listitem><para>
+                                <emphasis>Middle</emphasis>:
+                                The middle scenario in the figure also
+                                represents a situation where the source code
+                                does not exist locally.
                                 In this case, the code is again upstream
                                 and needs to be extracted to some
                                 local area - this time outside of the default
                                 workspace.
-                                If required, <filename>devtool</filename>
-                                always creates
-                                a Git repository locally during the extraction.
+                                <note>
+                                    If required, <filename>devtool</filename>
+                                    always creates
+                                    a Git repository locally during the
+                                    extraction.
+                                </note>
                                 Furthermore, the first positional argument
-                                <replaceable>srctree</replaceable> in this case
-                                identifies where the
+                                <replaceable>srctree</replaceable> in this
+                                case identifies where the
                                 <filename>devtool add</filename> command
                                 will locate the extracted code outside of the
-                                workspace:
+                                workspace.
+                                You need to specify an empty directory:
                                 <literallayout class='monospaced'>
      $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
                                 </literallayout>
                                 In summary, the source code is pulled from
-                                <replaceable>fetchuri</replaceable> and extracted
-                                into the location defined by
+                                <replaceable>fetchuri</replaceable> and
+                                extracted into the location defined by
                                 <replaceable>srctree</replaceable> as a local
                                 Git repository.</para>
 
-                                <para>Within workspace, <filename>devtool</filename>
-                                creates both the recipe and an append file
-                                for the recipe.
+                                <para>Within workspace,
+                                <filename>devtool</filename> creates a
+                                recipe named <replaceable>recipe</replaceable>
+                                along with an associated append file.
                                 </para></listitem>
-                            <listitem><para><emphasis>Right</emphasis>:
-                                The right scenario represents a situation
-                                where the source tree (srctree) has been
+                            <listitem><para>
+                                <emphasis>Right</emphasis>:
+                                The right scenario in the figure represents a
+                                situation where the
+                                <replaceable>srctree</replaceable> has been
                                 previously prepared outside of the
-                                <filename>devtool</filename> workspace.
-                                </para>
+                                <filename>devtool</filename> workspace.</para>
 
-                                <para>The following command names the recipe
-                                and identifies where the existing source tree
-                                is located:
+                                <para>The following command provides a new
+                                recipe name and identifies the existing source
+                                tree location:
                                 <literallayout class='monospaced'>
      $ devtool add <replaceable>recipe srctree</replaceable>
                                 </literallayout>
-                                The command examines the source code and creates
-                                a recipe for it placing the recipe into the
-                                workspace.</para>
+                                The command examines the source code and
+                                creates a recipe named
+                                <replaceable>recipe</replaceable> for the code
+                                and places the recipe into the workspace.
+                                </para>
 
-                                <para>Because the extracted source code already exists,
-                                <filename>devtool</filename> does not try to
-                                relocate it into the workspace - just the new
-                                the recipe is placed in the workspace.</para>
+                                <para>Because the extracted source code already
+                                exists, <filename>devtool</filename> does not
+                                try to relocate the source code into the
+                                workspace - only the new the recipe is placed
+                                in the workspace.</para>
 
                                 <para>Aside from a recipe folder, the command
-                                also creates an append folder and places an initial
-                                <filename>*.bbappend</filename> within.
+                                also creates an associated append folder and
+                                places an initial
+                                <filename>*.bbappend</filename> file within.
                                 </para></listitem>
                         </itemizedlist>
                         </para></listitem>
-                    <listitem><para><emphasis>Edit the Recipe</emphasis>:
-                        At this point, you can use <filename>devtool edit-recipe</filename>
+                    <listitem><para>
+                        <emphasis>Edit the Recipe</emphasis>:
+                        You can use <filename>devtool edit-recipe</filename>
                         to open up the editor as defined by the
                         <filename>$EDITOR</filename> environment variable
                         and modify the file:
                         <literallayout class='monospaced'>
      $ devtool edit-recipe <replaceable>recipe</replaceable>
                         </literallayout>
-                        From within the editor, you can make modifications to the
-                        recipe that take affect when you build it later.
+                        From within the editor, you can make modifications to
+                        the recipe that take affect when you build it later.
                         </para></listitem>
-                    <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
-                        At this point in the flow, the next step you
-                        take depends on what you are going to do with
-                        the new code.</para>
-                        <para>If you need to take the build output and eventually
-                        move it to the target hardware, you would use
-                        <filename>devtool build</filename>:
+                    <listitem><para>
+                        <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+                        The next step you take depends on what you are going
+                        to do with the new code.</para>
+
+                        <para>If you need to eventually move the build output
+                        to the target hardware, use the following
+                        <filename>devtool</filename> command:
                         <literallayout class='monospaced'>
      $ devtool build <replaceable>recipe</replaceable>
                         </literallayout></para>
+
                         <para>On the other hand, if you want an image to
-                        contain the recipe's packages for immediate deployment
-                        onto a device (e.g. for testing purposes), you can use
+                        contain the recipe's packages from the workspace
+                        for immediate deployment onto a device (e.g. for
+                        testing purposes), you can use
                         the <filename>devtool build-image</filename> command:
                         <literallayout class='monospaced'>
      $ devtool build-image <replaceable>image</replaceable>
                         </literallayout>
                         </para></listitem>
-                    <listitem><para><emphasis>Deploy the Build Output</emphasis>:
+                    <listitem><para>
+                        <emphasis>Deploy the Build Output</emphasis>:
                         When you use the <filename>devtool build</filename>
                         command to build out your recipe, you probably want to
-                        see if the resulting build output works as expected on target
-                        hardware.
+                        see if the resulting build output works as expected
+                        on the target hardware.
                         <note>
                             This step assumes you have a previously built
                             image that is already either running in QEMU or
-                            running on actual hardware.
-                            Also, it is assumed that for deployment of the image
-                            to the target, SSH is installed in the image and if
-                            the image is running on real hardware that you have
-                            network access to and from your development machine.
+                            is running on actual hardware.
+                            Also, it is assumed that for deployment of the
+                            image to the target, SSH is installed in the image
+                            and, if the image is running on real hardware,
+                            you have network access to and from your
+                            development machine.
                         </note>
-                        You can deploy your build output to that target hardware by
-                        using the <filename>devtool deploy-target</filename> command:
+                        You can deploy your build output to that target
+                        hardware by using the
+                        <filename>devtool deploy-target</filename> command:
                         <literallayout class='monospaced'>
      $ devtool deploy-target <replaceable>recipe target</replaceable>
                         </literallayout>
-                        The <replaceable>target</replaceable> is a live target machine
-                        running as an SSH server.</para>
+                        The <replaceable>target</replaceable> is a live target
+                        machine running as an SSH server.</para>
 
-                        <para>You can, of course, also deploy the image you build
-                        using the <filename>devtool build-image</filename> command
-                        to actual hardware.
-                        However, <filename>devtool</filename> does not provide a
-                        specific command that allows you to do this.
+                        <para>You can, of course, also deploy the image you
+                        build to actual hardware by using the
+                        <filename>devtool build-image</filename> command.
+                        However, <filename>devtool</filename> does not provide
+                        a specific command that allows you to deploy the
+                        image to actual hardware.
                         </para></listitem>
                     <listitem><para>
                         <emphasis>Finish Your Work With the Recipe</emphasis>:
@@ -522,8 +510,9 @@
                             committed to the Git repository in the source tree.
                         </note></para>
 
-                        <para>As mentioned, the <filename>devtool finish</filename>
-                        command moves the final recipe to its permanent layer.
+                        <para>As mentioned, the
+                        <filename>devtool finish</filename> command moves the
+                        final recipe to its permanent layer.
                         </para>
 
                         <para>As a final process of the