dev-manual: Edits to the "Source Directory" term

Fixes [YOCTO #5368]

Partial fix to the tarball removal issue.  I rewrote parts of
this term's definition to slightly de-emphasize tarball expansion
as a method to set up the Source Directory on the local machine.

(From yocto-docs rev: 2fb1e569129e9942ca4a99fe7f73de02ccbd1876)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 50 insertions, 43 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 0ba560854d..0dc4bd58bb 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -662,54 +662,61 @@
                 use the <filename>.bb</filename> file extension.</para></listitem>
             <listitem>
                 <para id='source-directory'><emphasis>Source Directory:</emphasis>
-                This term refers to the directory structure created as a result of either downloading
-                and unpacking a Yocto Project release tarball or creating a local copy of
-                the <filename>poky</filename> Git repository
-                <filename>git://git.yoctoproject.org/poky</filename>.
-                Sometimes you might hear the term "poky directory" used to refer to this
-                directory structure.
+                This term refers to the directory structure created as a result
+                of creating a local copy of the <filename>poky</filename> Git
+                repository <filename>git://git.yoctoproject.org/poky</filename>
+                or expanding a released <filename>poky</filename> tarball.
+                Sometimes you might hear the term "poky directory" used to refer
+                to this directory structure.
                 <note>
-                    The OpenEmbedded build system does not support file or directory names that
-                    contain spaces.
-                    Be sure that the Source Directory you use does not contain these types
-                    of names.
+                    The OpenEmbedded build system does not support file or
+                    directory names that contain spaces.
+                    Be sure that the Source Directory you use does not contain
+                    these types of names.
                 </note></para>
-                <para>The Source Directory contains BitBake, Documentation, Metadata and
-                other files that all support the Yocto Project.
-                Consequently, you must have the Source Directory in place on your development
-                system in order to do any development using the Yocto Project.</para>
-
-                <para>For tarball expansion, the name of the top-level directory of the Source Directory
-                is derived from the Yocto Project release tarball.
-                For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename>
-                results in a Source Directory whose top-level folder is named
-                <filename>&YOCTO_POKY;</filename>.
-                If you create a local copy of the Git repository, you can name the repository
-                anything you like.
-                Throughout much of the documentation, <filename>poky</filename> is used as the name of
-                the top-level folder of the local copy of the poky Git repository.
-                So, for example, cloning the <filename>poky</filename> Git repository results in a
-                local Git repository whose top-level folder is also named <filename>poky</filename>.</para>
-
-                <para>It is important to understand the differences between the Source Directory created
-                by unpacking a released tarball as compared to cloning
+
+                <para>The Source Directory contains BitBake, Documentation,
+                Metadata and other files that all support the Yocto Project.
+                Consequently, you must have the Source Directory in place on
+                your development system in order to do any development using
+                the Yocto Project.</para>
+
+                <para>When you create a local copy of the Git repository, you
+                can name the repository anything you like.
+                Throughout much of the documentation, <filename>poky</filename>
+                is used as the name of the top-level folder of the local copy of
+                the poky Git repository.
+                So, for example, cloning the <filename>poky</filename> Git
+                repository results in a local Git repository whose top-level
+                folder is also named <filename>poky</filename>.</para>
+
+                <para>While it is not recommended that you use tarball expansion
+                to setup the Source Directory, if you do, the top-level
+                directory name of the Source Directory is derived from the
+                Yocto Project release tarball.
+                For example, downloading and unpacking
+                <filename>&YOCTO_POKY_TARBALL;</filename> results in a
+                Source Directory whose root folder is named
+                <filename>&YOCTO_POKY;</filename>.</para>
+
+                <para>It is important to understand the differences between the
+                Source Directory created by unpacking a released tarball as
+                compared to cloning
                 <filename>git://git.yoctoproject.org/poky</filename>.
-                When you unpack a tarball, you have an exact copy of the files based on the time of
-                release - a fixed release point.
-                Any changes you make to your local files in the Source Directory are on top of the release.
-                On the other hand, when you clone the <filename>poky</filename> Git repository, you have an
-                active development repository.
-                In this case, any local changes you make to the Source Directory can be later applied
-                to active development branches of the upstream <filename>poky</filename> Git
+                When you unpack a tarball, you have an exact copy of the files
+                based on the time of release - a fixed release point.
+                Any changes you make to your local files in the Source Directory
+                are on top of the release and will remain local only.
+                On the other hand, when you clone the <filename>poky</filename>
+                Git repository, you have an active development repository with
+                access to the upstream repository's branches and tags.
+                In this case, any local changes you make to the local
+                Source Directory can be later applied to active development
+                branches of the upstream <filename>poky</filename> Git
                 repository.</para>
 
-                <para>Finally, if you want to track a set of local changes while starting from the same point
-                as a release tarball, you can create a local Git branch that
-                reflects the exact copy of the files at the time of their release.
-                You do this by using Git tags that are part of the repository.</para>
-
-                <para>For more information on concepts related to Git repositories, branches, and tags,
-                see the
+                <para>For more information on concepts related to Git
+                repositories, branches, and tags, see the
                 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
                 section.</para></listitem>
             <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.