documentation: More information about DL_DIR added.

The information surrounding the central download directory was
pretty scant.  Jim Abernathy pointed this out in an email sent to
me.  As a start, I have added quite a bit more information to
the glossary description for DL_DIR.  Part of that added information
is a pointer to the FAQ entry that describes exactly how the
build system gets source files.  Then, in the YP Development Manual
in the section that introduces the build process, I added several
references to various variables that are set in the local.conf
file prior to kicking off the build.

Reported-by: Jim Abernathy <jim.abernathy@intel.com>
(From yocto-docs rev: 4d7835a3bff5bd054301fa9ab6954c11c88dad58)

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

3 files changed, 47 insertions, 5 deletions

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 0ed69cf501..6d68a088d0 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -240,9 +240,16 @@
                 previous section.</para></listitem>
             <listitem><para>Initialize the build environment by sourcing a build environment 
                 script.</para></listitem>
-            <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file is set 
-                up how you want it.  
-                This file defines the target machine architecture and other build options.</para></listitem>
+            <listitem><para>Optionally ensure the <filename>/conf/local.conf</filename> configuration file, 
+                which is found in the Yocto Project build directory, is set up how you want it.  
+                This file defines many aspects of the build environment including 
+                the target machine architecture through the 
+                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-MACHINE'>MACHINE</ulink></filename> variable, 
+                the development machine's processor use through the 
+                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and 
+                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
+                a centralized tarball download directory through the  
+                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
             <listitem><para>Build the image using the <command>bitbake</command> command.
                 If you want information on BitBake, see the user manual at
                 <ulink url='http://docs.openembedded.org/bitbake/html'></ulink>.</para></listitem>
diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml
index 669b2d5aa5..1f4448d463 100644
--- a/documentation/poky-ref-manual/faq.xml
+++ b/documentation/poky-ref-manual/faq.xml
@@ -493,7 +493,7 @@
 
     <qandaentry>
         <question>
-            <para>
+            <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
                 How does the Yocto Project obtain source code and will it work behind my 
                 firewall or proxy server?
             </para>
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 711a8a97ca..60bf034d19 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -344,7 +344,42 @@
 
         <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
             <glossdef>
-                <para>The directory where all fetched sources will be stored.</para>
+                <para>
+                    The central download directory used by the build process to store downloads.
+                    You can set this directory by defining the <filename>DL_DIR</filename>
+                    variable in the <filename>/conf/local.conf</filename> file.
+                    This directory is self-maintaining and you should not have
+                    to touch it. 
+                    By default, the directory is <filename>downloads</filename> in the 
+                    Yocto Project build directory.
+                    <literallayout class='monospaced'>
+     #DL_DIR ?= "${TOPDIR}/downloads"
+                    </literallayout>
+                    To specify a different download directory, simply uncomment the line
+                    and provide your directory.
+                </para>
+
+                <para>
+                    During a first build, the system downloads many different source code 
+                    tarballs from various upstream projects. 
+                    Downloading can take a while, particularly if your network
+                    connection is slow. 
+                    Tarballs are all stored in the directory defined by 
+                    <filename>DL_DIR</filename> and the build system looks there first 
+                    to find source tarballs. 
+                    <note>
+                        When wiping and rebuilding, you can preserve this directory to speed 
+                        up this part of subsequent builds. 
+                    </note>
+                </para>
+
+                <para>
+                    You can safely share this directory between multiple builds on the 
+                    same development machine.  
+                    For additional information on how the build process gets source files, see
+                    <link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>this entry</link> in
+                    The FAQ appendix of this manual.
+                </para>
             </glossdef>
 
         </glossentry>