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 .bb file extension.
Source Directory:
- 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 poky Git repository
- git://git.yoctoproject.org/poky.
- 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 poky Git
+ repository git://git.yoctoproject.org/poky
+ or expanding a released poky tarball.
+ Sometimes you might hear the term "poky directory" used to refer
+ to this directory structure.
- 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.
- 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.
- 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 &YOCTO_POKY_TARBALL;
- results in a Source Directory whose top-level folder is named
- &YOCTO_POKY;.
- If you create a local copy of the Git repository, you can name the repository
- anything you like.
- Throughout much of the documentation, poky is used as the name of
- the top-level folder of the local copy of the poky Git repository.
- So, for example, cloning the poky Git repository results in a
- local Git repository whose top-level folder is also named poky.
+ 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.
- It is important to understand the differences between the Source Directory created
- by unpacking a released tarball as compared to cloning
+ When you create a local copy of the Git repository, you
+ can name the repository anything you like.
+ Throughout much of the documentation, poky
+ is used as the name of the top-level folder of the local copy of
+ the poky Git repository.
+ So, for example, cloning the poky Git
+ repository results in a local Git repository whose top-level
+ folder is also named poky.
+
+ 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
+ &YOCTO_POKY_TARBALL; results in a
+ Source Directory whose root folder is named
+ &YOCTO_POKY;.
+
+ It is important to understand the differences between the
+ Source Directory created by unpacking a released tarball as
+ compared to cloning
git://git.yoctoproject.org/poky.
- 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 poky 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 poky 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 poky
+ 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 poky Git
repository.
- 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.
-
- For more information on concepts related to Git repositories, branches, and tags,
- see the
+ For more information on concepts related to Git
+ repositories, branches, and tags, see the
"Repositories, Tags, and Branches"
section.Tasks: Arbitrary groups of software Recipes.