documentation/adt-manual/adt-prepare.xml: Edits affecting rename and clarity

I made a pass through this chapter and focused on better descriptions for
getting the system ready for application development.  I made adjustments
to better represent what is really being done.  It is not all ADT here
as was being described before.  Miscellaneous edits and improvements
throughout.

(From yocto-docs rev: 3544beda4794005fe139d7620fd13618fab05534)

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

1 files changed, 44 insertions, 34 deletions

diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index 845c783d24..e67487b224 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -4,29 +4,30 @@
 
 <chapter id='adt-prepare'>
 
-<title>Preparing to Use the Application Development Toolkit (ADT)</title>
+<title>Preparing for Application Development</title>
 
 <para>
-    In order to use the ADT, you must install it, <filename>source</filename> a script to set up the 
-    environment, and be sure both the kernel and filesystem image specific to the target architecture 
-    exist. 
-    This chapter describes how to be sure you meet the ADT requirements.
+    In order to develop applications, you need set up your host development system.
+    Several ways exist that allow you to install cross-development tools, QEMU, the  
+    Eclipse Yocto Plug-in, and other tools.
+    This chapter describes how to prepare for application development.
 </para>
 
 <section id='installing-the-adt'>
-    <title>Installing the ADT</title>
+    <title>Installing the ADT and Toolchains</title>
 
     <para>
-        The following list describes how you can install the ADT, which includes the cross-toolchain.
-        Regardless of the installation you choose, you must <filename>source</filename> the cross-toolchain
-        environment setup script before you use the toolchain.
+        The following list describes installation methods that set up varying degrees of tool
+        availabiltiy on your system.
+        Regardless of the installation method you choose,
+        you must <filename>source</filename> the cross-toolchain
+        environment setup script before you use a toolchain.
         See the "<link linkend='setting-up-the-cross-development-environment'>Setting Up the 
-        Cross-Development Environment</link>"
-        section for more information.
+        Cross-Development Environment</link>" section for more information.
     </para>
 
     <note>
-        <para>Avoid mixing installation methods when installing the ADT for different architectures.
+        <para>Avoid mixing installation methods when installing toolchains for different architectures.
         For example, avoid using the ADT Installer to install some toolchains and then hand-installing
         cross-development toolchains from downloaded tarballs to install toolchains
         for different architectures. 
@@ -50,9 +51,10 @@
                 toolchain tarball and then hand-install the toolchain.
                 If you use this method, you just get the cross-toolchain and QEMU - you do not 
                 get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
-            <listitem><para><emphasis>Use the Toolchain from within a Yocto Project Build Tree:</emphasis>
-                If you already have a build directory, you can build the cross-toolchain 
-                within that structure.
+            <listitem><para><emphasis>Use the Toolchain from within the Build Directory:</emphasis>
+                If you already have a 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>, 
+                you can build the cross-toolchain within the directory.
                 However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you 
                 do not get any of the other benefits without taking separate steps.</para></listitem>
         </itemizedlist>
@@ -75,7 +77,8 @@
                 <ulink url='&YOCTO_DL_URL;/releases'>Index of Releases</ulink>, specifically
                 at  
                 <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink>.
-                Or, you can use BitBake to generate the tarball inside the existing build directory.
+                Or, you can use BitBake to generate the tarball inside the existing 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
             </para>
 
             <para>
@@ -87,9 +90,9 @@
             </para>
 
             <para>
-                The following example commands download the Yocto Project release tarball, set up the 
-                source directory, set up the environment while also creating the 
-                default build directory, 
+                The following example commands download the Poky tarball, set up the 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>, 
+                set up the environment while also creating the default build directory, 
                 and run the <filename>bitbake</filename> command that results in the tarball 
                 <filename>~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
                 <literallayout class='monospaced'>
@@ -243,7 +246,7 @@
      poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.tar.bz2
                     </literallayout>
                     <note><para>As an alternative to steps one and two, you can build the toolchain tarball 
-                        if you have a build directory.
+                        if you have a <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
                         If you need GMAE, you should use the <filename>bitbake meta-toolchain-gmae</filename>
                         command. 
                         The resulting tarball will support such development.
@@ -270,27 +273,29 @@
 
         <para>
             A final way of making the cross-toolchain available is to use BitBake 
-            to generate the toolchain within an existing build directory.
+            to generate the toolchain within an existing 
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
             This method does not install the toolchain into the 
             <filename>/opt</filename> directory.
             As with the previous method, if you need to install the target sysroot, you must 
-            do this separately.
+            do that separately as well.
         </para>
 
         <para>
-            Follow these steps to generate the toolchain into the build tree:
+            Follow these steps to generate the toolchain into the build directory:
             <orderedlist>
                 <listitem><para>Source the environment setup script 
-                    <filename>oe-init-build-env</filename> located in the source directory.
+                    <filename>oe-init-build-env</filename> located in the 
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
                     </para></listitem> 
                 <listitem><para>At this point, you should be sure that the 
-                    <filename>MACHINE</filename> variable 
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable 
                     in the <filename>local.conf</filename> file found in the 
                     <filename>conf</filename> directory of the build directory
                     is set for the target architecture.
                     Comments within the <filename>local.conf</filename> file list the values you 
                     can use for the <filename>MACHINE</filename> variable.  
-                    <note>You can populate the build tree with the cross-toolchains for more 
+                    <note>You can populate the build directory with the cross-toolchains for more 
                         than a single architecture.  
                         You just need to edit the <filename>MACHINE</filename> variable in the 
                         <filename>local.conf</filename> file and re-run the BitBake 
@@ -320,10 +325,12 @@
     <para>
         Before you can develop using the cross-toolchain, you need to set up the 
         cross-development environment by sourcing the toolchain's environment setup script.  
-        If you used the ADT Installer or used an existing ADT tarball to install the ADT,
+        If you used the ADT Installer or hand-installed cross-toolchain,
         then you can find this script in the <filename>&YOCTO_ADTPATH_DIR;</filename>
         directory.  
-        If you installed the toolchain in the build tree, you can find the environment setup 
+        If you installed the toolchain in the 
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>, 
+        you can find the environment setup 
         script for the toolchain in the build directory's <filename>tmp</filename> directory.
     </para>
 
@@ -358,7 +365,7 @@
             pre-built versions.
             You can find examples for both these situations in the 
             "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of   
-            The Yocto Project Quick Start.
+            the Yocto Project Quick Start.
         </para>
 
         <para> 
@@ -372,7 +379,7 @@
             For information on the image types you can build using the OpenEmbedded build system, 
             see the
             "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in  
-            The Yocto Project Reference Manual.
+            the Yocto Project Reference Manual.
         </para>
 
         <para>
@@ -389,8 +396,10 @@
             you can do so one of two ways:
             <itemizedlist>
                 <listitem><para>Modify the <filename>conf/local.conf</filename> configuration in 
-                    the build directory and then rebuild the image.
-                    With this method, you need to modify the <filename>EXTRA_IMAGE_FEATURES</filename>
+                    the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
+                    and then rebuild the image.
+                    With this method, you need to modify the 
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
                     variable to have the value of "tools-debug" before rebuilding the image. 
                     Once the image is rebuilt, the <filename>tcf-agent</filename> will be included
                     in the image and is launched automatically after the boot.</para></listitem>
@@ -398,7 +407,7 @@
                     To build the agent, follow these steps:
                     <orderedlist>
                         <listitem><para>Be sure the ADT is installed as described in the 
-                            "<link linkend='installing-the-adt'>Installing the ADT</link>" section.
+                            "<link linkend='installing-the-adt'>Installing the ADT and Toolchains</link>" section.
                             </para></listitem>
                         <listitem><para>Set up the cross-development environment as described in the 
                             "<link linkend='setting-up-the-cross-development-environment'>Setting 
@@ -411,7 +420,8 @@
                             </literallayout></para></listitem>
                         <listitem><para>Modify the <filename>Makefile.inc</filename> file
                             for the cross-compilation environment by setting the 
-                            <filename>OPSYS</filename> and <filename>MACHINE</filename>
+                            <filename>OPSYS</filename> and 
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
                             variables according to your target.</para></listitem>
                         <listitem><para>Use the cross-development tools to build the 
                             <filename>tcf-agent</filename>.