sdk-manual: Updated devtool modify workflow section.

I found this section a bit loosely worded and could result in
confusion to a user ramping up with YP.  I have done an extensive
rewrite focusing on exact wordings.

(From yocto-docs rev: af64c07d259e06fb13572fc224636ed240037b57)

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

1 files changed, 125 insertions, 96 deletions

diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 4303054cba..3a99b3791b 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -520,21 +520,20 @@
 
             <para>
                 The <filename>devtool modify</filename> command prepares the
-                way to work on existing code that already has a recipe in
-                place.
-                The command is flexible enough to allow you to extract code,
-                specify the existing recipe, and keep track of and gather any
-                patch files from other developers that are
-                associated with the code.
+                way to work on existing code that already has a local recipe in
+                place that is used to build the software.
+                The command is flexible enough to allow you to extract code
+                from an upstream source, specify the existing recipe, and
+                keep track of and gather any patch files from other developers
+                that are associated with the code.
             </para>
 
             <para>
                 Depending on your particular scenario, the arguments and options
                 you use with <filename>devtool modify</filename> form different
                 combinations.
-                The following diagram shows common development flows
-                you would use with the <filename>devtool modify</filename>
-                command:
+                The following diagram shows common development flows for the
+                <filename>devtool modify</filename> command:
             </para>
 
             <para>
@@ -543,140 +542,165 @@
 
             <para>
                 <orderedlist>
-                    <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
+                    <listitem><para>
+                        <emphasis>Preparing to Modify the Code</emphasis>:
                         The top part of the flow shows three scenarios by which
                         you could use <filename>devtool modify</filename> to
                         prepare to work on source files.
                         Each scenario assumes the following:
                         <itemizedlist>
-                            <listitem><para>The recipe exists in some layer external
+                            <listitem><para>
+                                The recipe exists locally in a layer external
                                 to the <filename>devtool</filename> workspace.
                                 </para></listitem>
-                            <listitem><para>The source files exist upstream in an
+                            <listitem><para>
+                                The source files exist either upstream in an
                                 un-extracted state or locally in a previously
                                 extracted state.
                                 </para></listitem>
                         </itemizedlist>
                         The typical situation is where another developer has
-                        created some layer for use with the Yocto Project and
+                        created a layer for use with the Yocto Project and
                         their recipe already resides in that layer.
                         Furthermore, their source code is readily available
                         either upstream or locally.
                         <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.
+                            <listitem><para>
+                                <emphasis>Left</emphasis>:
+                                The left scenario in the figure represents a
+                                common situation where the source code does
+                                not exist locally and it needs to be extracted
+                                from an upstream source.
                                 In this situation, the source is extracted
-                                into the default workspace location.
+                                into the default <filename>devtool</filename>
+                                workspace location.
                                 The recipe, in this scenario, is in its own
                                 layer outside the workspace
                                 (i.e.
                                 <filename>meta-</filename><replaceable>layername</replaceable>).
                                 </para>
 
-                                <para>The following command identifies the recipe
-                                and by default extracts the source files:
+                                <para>The following command identifies the
+                                recipe and, by default, extracts the source
+                                files:
                                 <literallayout class='monospaced'>
      $ devtool modify <replaceable>recipe</replaceable>
                                 </literallayout>
-                                Once <filename>devtool</filename>locates the recipe,
-                                it uses the
+                                Once <filename>devtool</filename>locates the
+                                recipe, <filename>devtool</filename> uses the
+                                recipe's
                                 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-                                variable to locate the source code and
-                                any local patch files from other developers are
-                                located.
-                                <note>
-                                    You cannot provide an URL for
-                                    <replaceable>srctree</replaceable> when using the
-                                    <filename>devtool modify</filename> command.
-                                </note>
-                                With this scenario, however, since no
-                                <replaceable>srctree</replaceable> argument exists, the
-                                <filename>devtool modify</filename> command by default
-                                extracts the source files to a Git structure.
-                                Furthermore, the location for the extracted source is the
-                                default area within the workspace.
-                                The result is that the command sets up both the source
-                                code and an append file within the workspace with the
-                                recipe remaining in its original location.
+                                statements to locate the source code and any
+                                local patch files from other developers.</para>
+
+                                <para>With this scenario, no
+                                <replaceable>srctree</replaceable> argument
+                                exists.
+                                Consequently, the default behavior of the
+                                <filename>devtool modify</filename> command is
+                                to extract the source files pointed to by the
+                                <filename>SRC_URI</filename> statements into a
+                                local Git structure.
+                                Furthermore, the location for the extracted
+                                source is the default area within the
+                                <filename>devtool</filename> workspace.
+                                The result is that the command sets up both
+                                the source code and an append file within the
+                                workspace while the recipe remains in its
+                                original location.
                                 </para></listitem>
-                            <listitem><para><emphasis>Middle</emphasis>:
-                                The middle scenario represents a situation where
-                                the source code also does not exist locally.
+                            <listitem><para>
+                                <emphasis>Middle</emphasis>:
+                                The middle scenario in the figure represents a
+                                situation where the source code also does not
+                                exist locally.
                                 In this case, the code is again upstream
                                 and needs to be extracted to some
                                 local area as a Git repository.
-                                The recipe, in this scenario, is again in its own
-                                layer outside the workspace.</para>
+                                The recipe, in this scenario, is again local
+                                and in its own layer outside the workspace.
+                                </para>
 
                                 <para>The following command tells
                                 <filename>devtool</filename> what recipe with
-                                which to work and, in this case, identifies a local
-                                area for the extracted source files that is outside
-                                of the default workspace:
+                                which to work and, in this case, identifies a
+                                local area for the extracted source files that
+                                is outside of the default
+                                <filename>devtool</filename> workspace:
                                 <literallayout class='monospaced'>
      $ devtool modify <replaceable>recipe srctree</replaceable>
                                 </literallayout>
+                                <note>
+                                    You cannot provide a URL for
+                                    <replaceable>srctree</replaceable> using
+                                    the <filename>devtool</filename> command.
+                                </note>
                                 As with all extractions, the command uses
-                                the recipe's <filename>SRC_URI</filename> to locate the
-                                source files.
-                                Once the files are located, the command by default
-                                extracts them.
-                                Providing the <replaceable>srctree</replaceable>
-                                argument instructs <filename>devtool</filename> where
-                                to place the extracted source.</para>
-
-                                <para>Within workspace, <filename>devtool</filename>
-                                creates an append file for the recipe.
+                                the recipe's <filename>SRC_URI</filename>
+                                statements to locate the source files and any
+                                associated patch files.
+                                Once the files are located, the command by
+                                default extracts them into
+                                <replaceable>srctree</replaceable>.</para>
+
+                                <para>Within workspace,
+                                <filename>devtool</filename> creates an append
+                                file for the recipe.
                                 The recipe remains in its original location but
-                                the source files are extracted to the location you
-                                provided with <replaceable>srctree</replaceable>.
+                                the source files are extracted to the location
+                                you provide with
+                                <replaceable>srctree</replaceable>.
                                 </para></listitem>
-                            <listitem><para><emphasis>Right</emphasis>:
-                                The right scenario represents a situation
-                                where the source tree
-                                (<replaceable>srctree</replaceable>) exists as a
-                                previously extracted Git structure outside of
-                                the <filename>devtool</filename> workspace.
+                            <listitem><para>
+                                <emphasis>Right</emphasis>:
+                                The right scenario in the figure represents a
+                                situation where the source tree
+                                (<replaceable>srctree</replaceable>) already
+                                exists locally as a previously extracted Git
+                                structure outside of the
+                                <filename>devtool</filename> workspace.
                                 In this example, the recipe also exists
-                                elsewhere in its own layer.
+                                elsewhere locally in its own layer.
                                 </para>
 
                                 <para>The following command tells
                                 <filename>devtool</filename> the recipe
-                                with which to work, uses the "-n" option to indicate
-                                source does not need to be extracted, and uses
-                                <replaceable>srctree</replaceable> to point to the
-                                previously extracted source files:
+                                with which to work, uses the "-n" option to
+                                indicate source does not need to be extracted,
+                                and uses <replaceable>srctree</replaceable> to
+                                point to the previously extracted source files:
                                 <literallayout class='monospaced'>
      $ devtool modify -n <replaceable>recipe srctree</replaceable>
                                 </literallayout>
                                 </para>
 
                                 <para>Once the command finishes, it creates only
-                                an append file for the recipe in the workspace.
+                                an append file for the recipe in the
+                                <filename>devtool</filename> workspace.
                                 The recipe and the source code remain in their
                                 original locations.
                                 </para></listitem>
                             </itemizedlist>
                         </para></listitem>
-                    <listitem><para><emphasis>Edit the Source</emphasis>:
-                        Once you have used the <filename>devtool modify</filename>
-                        command, you are free to make changes to the source
-                        files.
+                    <listitem><para>
+                        <emphasis>Edit the Source</emphasis>:
+                        Once you have used the
+                        <filename>devtool modify</filename> command, you are
+                        free to make changes to the source files.
                         You can use any editor you like to make and save
                         your source code modifications.
                         </para></listitem>
-                    <listitem><para><emphasis>Build the Recipe</emphasis>:
+                    <listitem><para>
+                        <emphasis>Build the Recipe</emphasis>:
                         Once you have updated the source files, you can build
                         the recipe.
                         </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.
+                        command to build out your recipe, you probably want to
+                        see if the resulting build output works as expected
+                        on target hardware.
                         <note>
                             This step assumes you have a previously built
                             image that is already either running in QEMU or
@@ -686,19 +710,22 @@
                             the image is running on real hardware that 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, use other methods to deploy
+                        the image you built using the
+                        <filename>devtool build-image</filename> command to
+                        actual hardware.
+                        <filename>devtool</filename> does not provide
+                        a specific command to deploy the image to actual
+                        hardware.
                         </para></listitem>
                     <listitem><para>
                         <emphasis>Finish Your Work With the Recipe</emphasis>:
@@ -707,28 +734,30 @@
                         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.
+                        then resets the recipe so that the recipe is built
+                        normally rather than from the workspace.
                         <literallayout class='monospaced'>
      $ devtool finish <replaceable>recipe layer</replaceable>
                         </literallayout>
                         <note>
                             Any changes you want to turn into patches must be
-                            committed to the Git repository in the source tree.
+                            staged and committed within the local Git
+                            repository before you use the
+                            <filename>devtool finish</filename> command.
                         </note></para>
 
                         <para>Because there is no need to move the recipe,
                         <filename>devtool finish</filename> either updates the
                         original recipe in the original layer or the command
-                        creates a <filename>.bbappend</filename> in a different
-                        layer as provided by <replaceable>layer</replaceable>.
-                        </para>
+                        creates a <filename>.bbappend</filename> file in a
+                        different layer as provided by
+                        <replaceable>layer</replaceable>.</para>
 
                         <para>As a final process of the
                         <filename>devtool finish</filename> command, the state
                         of the standard layers and the upstream source is
                         restored so that you can build the recipe from those
-                        areas rather than the workspace.
+                        areas rather than from the workspace.
                         <note>
                             You can use the <filename>devtool reset</filename>
                             command to put things back should you decide you