General text edits through section 2.4.4 "General Bitbak Problems"

Extensive language and consistency edits being applied to the manual.
During the 0.9 push I did not have time to make a pass through the
document.

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>

1 files changed, 140 insertions, 115 deletions

diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index 70fa5102f5..c2e102ce37 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -13,27 +13,33 @@
     <title>Poky Overview</title>
 
     <para>
-        At the core of Poky is the bitbake task executor together with various types of
-        configuration files. This section gives an overview of bitbake and the
-        configuration files, in particular what they are used for, and how they
-        interact.
+        The bitbake task executor together with various types of configuration files form the core of Poky.
+        This section overviews the bitbake task executor and the
+        configuration files by describing what they are used for and they they interact.
     </para>
     
     <para>  
-        Bitbake handles the parsing and execution of the data
-        files. The data itself is of various types; recipes which give
-        details about particular pieces of software, class data which is an
-        abstraction of common build information (e.g. how to build a Linux kernel)
-        and configuration data for machines, policy decisions, etc., which acts as
-        a glue and binds everything together. Bitbake knows how to combine multiple
-        data sources together, each data source being referred to as a <link
-            linkend='usingpoky-changes-layers'>'layer'</link>.
+        Bitbake handles the parsing and execution of the data files. 
+        The data itself is of various types:
+    <itemizedlist>
+        <listitem><para>Recipes:  Provides details about particular pieces of software</para></listitem>
+        <listitem><para>Class Data:  An abstraction of common build information (e.g. how to build a 
+          Linux kernel).</para></listitem>
+        <listitem><para>Configuration Data:  Defines machine-specific settings, policy decisions, etc.
+          Configuration data acts a the glue to bind everything together.</para></listitem>
+    </itemizedlist>
+    </para>
+
+    <para> 
+        Bitbake knows how to combine multiple data sources together and refers to each data source
+        as a <link linkend='usingpoky-changes-layers'>'layer'</link>.
     </para>
 
     <para>
-        The <link linkend='ref-structure'>directory structure walkthrough</link>
-        section gives details on the meaning of specific directories but some
-        brief details on the core components follows:
+        Following are some brief details on these core components.
+        For more detailed information on these components see the 
+        <link linkend='ref-structure'>'Reference: Directory Structure'</link>
+        appendix.
     </para>
 
     <section id='usingpoky-components-bitbake'>
@@ -42,23 +48,30 @@
         <para>
             Bitbake is the tool at the heart of Poky and is responsible
             for parsing the metadata, generating a list of tasks from it
-            and then executing them. To see a list of the options it
-            supports look at <command>bitbake --help</command>.
+            and then executing them. To see a list of the options bitbake
+            supports look at 'bitbake --help'.
         </para>
 
         <para>
-            The most common usage is <command>bitbake packagename</command> where
-            packagename is the name of the package you wish to build
-            (from now on called the target). This often equates to the first part of a .bb
-            filename, so to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
-            might type <command>bitbake matchbox-desktop</command>.
-            Several different versions of matchbox-desktop might exist and
-            bitbake will choose the one selected by the distribution configuration
-            (more details about how bitbake chooses between different versions
-            and providers is available in the <link linkend='ref-bitbake-providers'>
-            'Preferences and Providers' section</link>). Bitbake will also try to execute any
-            dependent tasks first so before building matchbox-desktop it
-            would build a cross compiler and glibc if not already built.
+            The most common usage for bitbake is <filename>bitbake &lt;packagename&gt;</filename>, where
+            packagename is the name of the package you want to build (referred to as the 'target'
+            in this manual). 
+            The target often equates to the first part of a <filename>.bb</filename> filename.
+            So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
+            might type the following:
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop
+            </literallayout>
+            Several different versions of <filename>matchbox-desktop</filename> might exist.
+            Bitbake chooses the one selected by the distribution configuration.
+            You can get more details about how bitbake chooses between different versions
+            and providers in the <link linkend='ref-bitbake-providers'>
+            'Preferences and Providers' section</link>.
+        </para>
+        <para>
+            Bitbake also tries to execute any dependent tasks first.
+            So for example, before building <filename>matchbox-desktop</filename> bitbake
+            would build a cross compiler and glibc if they had not already been built.
         </para>
 
     </section>
@@ -67,17 +80,17 @@
         <title>Metadata (Recipes)</title>
 
         <para>
-            The .bb files are usually referred to as 'recipes'. In general, a
-            recipe contains information about a single piece of software such
-            as where to download the source, any patches that are needed,
-            any special configuration options, how to compile the source files
-            and how to package the compiled output.
+            The <filename>.bb</filename> files are usually referred to as 'recipes'. 
+            In general, a recipe contains information about a single piece of software such
+            as from where to download the source patches (if any are needed), which special 
+            configuration options to apply, how to compile the source files, and how to 
+            package the compiled output. 
         </para>
 
         <para>
-            'package' can also be used to describe recipes but since the same
-            word is used for the packaged output from Poky (i.e. .ipk or .deb
-            files), this document will avoid it.
+            The term 'package' can also be used to describe recipes.
+            However, since the same word is used for the packaged output from Poky (i.e. .ipk or .deb
+            files), this document avoids it.
         </para>
 
     </section>
@@ -86,11 +99,12 @@
         <title>Classes</title>
 
         <para>
-            Class (.bbclass) files contain information which is useful to share
-            between metadata files. An example is the autotools class which contains
-            the common settings that any application using autotools would use. The
-            <link linkend='ref-classes'>classes reference section</link> gives details
-            on common classes and how to use them.
+            Class files (<filename>.bbclass</filename>) contain information that is useful to share
+            between metadata files. 
+            An example is the autotools class, which contains
+            common settings for any application that autotools uses.
+            The <link linkend='ref-classes'>Reference: Classes</link> appendix provides details
+            about common classes and how to use them.
         </para>
     </section>
 
@@ -98,18 +112,17 @@
         <title>Configuration</title>
 
         <para>
-            The configuration (.conf) files define various configuration variables
-            which govern what Poky does. These are split into several areas, such
-            as machine configuration options, distribution configuration options,
-            compiler tuning options, general common configuration and user
-            configuration (local.conf).
+            The configuration files (<filename>.conf</filename>) define various configuration variables
+            that govern what Poky does. 
+            These files are split into several areas that define machine configuration options, 
+            distribution configuration options, compiler tuning options, general common configuration
+            options and user configuration options (<filename>local.conf</filename>).
         </para>
     </section>
 
 </section>
 
 
-
 <section id='usingpoky-build'>
     <title>Running a Build</title>
 
@@ -122,14 +135,14 @@ $ source poky-init-build-env [build_dir]
 </literallayout>
     </para>
     <para>
-        The build_dir is the dir containing all the building object files. The default 
-        build dir is poky-dir/build. Multiple build_dir can be used for different targets. 
-        For example, ~/build/x86 for qemux86 target, and ~/build/arm for qemuarm target.
+        The build_dir is the dir containing all the build's object files. The default 
+        build dir is poky-dir/build. A different build_dir can be used for each of the targets. 
+        For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target.
         Please refer to <link linkend="structure-core-script">poky-init-build-env</link>
-        for detail info
+        for more detailed information.
     </para>
     <para>
-        Once the Poky build environment is set up, a target can now be built using:
+        Once the Poky build environment is set up, a target can be built using:
     </para>
     <para>
         <literallayout class='monospaced'>
@@ -137,11 +150,13 @@ $ bitbake &lt;target&gt;
 </literallayout>
     </para>
     <para>
-        The target is the name of the recipe you want to build. Common targets are the
-        images (in <filename class="directory">meta/packages/images/</filename>)
-        or the name of a recipe for a specific piece of software like 
-        <application>busybox</application>. More details about the standard images 
-        are available in the <link linkend='ref-images'>image reference section</link>.
+        The target is the name of the recipe you want to build. 
+        Common targets are the images in <filename>meta/recipes-core/images</filename>),
+        <filename>/meta/recipes-sato/images</filename>, etc.
+        Or, the target can be the name of a recipe for a specific piece of software such as 
+        <application>busybox</application>. 
+        For more details about the standard images available, see the 
+        <link linkend="ref-images">'Reference: Images'</link> appendix.
     </para>
 </section>
 
@@ -149,11 +164,15 @@ $ bitbake &lt;target&gt;
     <title>Installing and Using the Result</title>
 
     <para>
-        Once an image has been built it often needs to be installed. The images/kernels built
-        by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
-        directory. Running qemux86 and qemuarm images is covered in the <link 
-        linkend='intro-quickstart-qemu'>Running an Image</link> section. See your 
-        board/machine documentation for information about how to install these images.
+        Once an image has been built it often needs to be installed. 
+        The images/kernels built by Poky are placed in the 
+        <filename class="directory">tmp/deploy/images</filename> directory. 
+        Running qemux86 and qemuarm images is described in the
+        'Using Pre-Built Binaries and QEMU' section of the Yocto Project Quick Start.
+        See <ulink url="http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html"></ulink>
+        for the guide. 
+        For information about how to install these images, see the documentation for your
+        particular board/machine.
     </para>
 
 </section>
@@ -163,66 +182,73 @@ $ bitbake &lt;target&gt;
 
     <para>
         The exact method for debugging Poky depends on the nature of the 
-        bug(s) and which part of the system they might be from. Standard 
-        debugging practises such as comparing to the last 
-        known working version and examining the changes, reapplying the 
-        changes in steps to identify the one causing the problem etc. are
-        valid for Poky just like any other system. It's impossible to detail
-        every possible potential failure here but there are some general
-        tips to aid debugging:
+        problem and on the system's area from which the bug originates. 
+        Standard debugging practises such as comparison against the last 
+        known working version with examination of the changes and the reapplication of steps 
+        to identify the one causing the problem are
+        valid for Poky just as they are for any other system. 
+        It's impossible to detail every possible potential failure but here are some general
+        tips to aid in debugging:
     </para>
 
     <section id='usingpoky-debugging-taskfailures'>
         <title>Task Failures</title>
 
         <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 
-            For the compile task of busybox 1.01 on the ARM spitz machine, this 
-            might be <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename> 
-            for example. To see what bitbake ran to generate that log, look at the <filename>run.do_taskname.pid </filename>
-            file in the same directory.
+            For example, the compile task of busybox 1.01 on the ARM spitz machine might be 
+            <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>.
+            To see what bitbake runs to generate that log, look at the corresponding 
+            <filename>run.do_taskname.pid </filename> file located in the same directory.
         </para>
 
-        <para>The output from python tasks is sent directly to the console at present.</para>
+        <para>Presently, the output from python tasks is sent directly to the console.</para>
     </section>
 
     <section id='usingpoky-debugging-taskrunning'>
         <title>Running specific tasks</title>
 
-        <para> Any given package consists of a set of tasks, in most
-            cases the series is fetch, unpack, patch, configure,
-            compile, install, package, package_write and build. The
-            default task is "build" and any tasks this depends on are
-            built first hence the standard bitbake behaviour. There are
-            some tasks such as devshell which are not part of the
-            default build chain.  If you wish to run such a task you can
-            use the "-c" option to bitbake e.g. <command>bitbake
-            matchbox-desktop -c devshell</command>.
+        <para> Any given package consists of a set of tasks.  
+            In most cases the series is: fetch, unpack, patch, configure,
+            compile, install, package, package_write and build. 
+            The default task is "build" and any tasks on which it depends build first - hence, 
+            the standard bitbake behaviour. 
+            Some tasks exist, such as devshell, that are not part of the default build chain.  
+            If you wish to run a task that is not part of the default build chain you can use the 
+            "-c" option in bitbake as follows:
+            <literallayout class='monospaced'>
+$ bitbake matchbox-desktop -c devshell
+            </literallayout>
         </para>
 
         <para>
-            If you wish to rerun a task you can use the force option
-            "-f". A typical usage session might look like: </para>
+            If you wish to rerun a task use the force option "-f". 
+            For example, the following sequence forces recompilation after changing files in the 
+            working directory.
+        </para>
 
         <para>
             <literallayout class='monospaced'>
-% bitbake matchbox-desktop
-[change some source in the WORKDIR for example]
-% bitbake matchbox-desktop -c compile -f
-% bitbake matchbox-desktop</literallayout>
+$ bitbake matchbox-desktop
+[make some changes to the source code in the WORKDIR]
+$ bitbake matchbox-desktop -c compile -f
+$ bitbake matchbox-desktop
+            </literallayout>
         </para>
 
         <para>
-            which would build matchbox-desktop, then recompile it. The
-            final command reruns all tasks after the compile (basically
-            the packaging tasks) since bitbake will notice that the
-            compile has been rerun and hence the other tasks also need
-            to run again.
+            This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it.
+            The last command reruns all tasks, basically the packaging tasks, after the compile.
+            Bitbake recognizes that the compile task was rerun and therefore understands that the other
+            tasks also need to be run again.
         </para>
 
         <para>
-            You can view a list of tasks in a given package by running
-            the listtasks task e.g. <command>bitbake matchbox-desktop -c
-            listtasks</command>, and the result is in file ${WORKDIR}/temp/log.do_listtasks.
+            You can view a list of tasks in a given package by running the listtasks task.
+            For example:
+            <literallayout class='monospaced'>
+$ bitbake matchbox-desktop -c
+            </literallayout>
+            The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
         </para>
     </section>
 
@@ -230,16 +256,13 @@ $ bitbake &lt;target&gt;
         <title>Dependency Graphs</title>
 
         <para>
-            Sometimes it can be hard to see why bitbake wants to build
-            some other packages before a given package you've specified.
-            <command>bitbake -g targetname</command> will create
-            <filename>depends.dot</filename> and
-            <filename>task-depends.dot</filename> files in the current 
-            directory. They show
-            which packages and tasks depend on which other packages and
-            tasks and are useful for debugging purposes.
-            <command>"bitbake -g -u depexp targetname"</command> will show result
-            in more human-readable GUI style.
+            Sometimes it can be hard to see why bitbake wants to build some other packages before a given 
+            package you've specified.
+            The <filename>bitbake -g targetname</filename> command creates the <filename>depends.dot</filename> and
+            <filename>task-depends.dot</filename> files in the current directory. 
+            These files show the package and task dependencies and are useful for debugging problems.
+            You can use the <filename>bitbake -g -u depexp targetname</filename> command to display the results 
+            in a more human-readable form.
         </para>
     </section>
 
@@ -247,17 +270,19 @@ $ bitbake &lt;target&gt;
         <title>General Bitbake Problems</title>
 
         <para>
-            Debug output from bitbake can be seen with the "-D" option.
+            You can see debug output from bitbake by using the "-D" option.
             The debug output gives more information about what bitbake
-            is doing and/or why. Each -D option increases the logging
-            level, the most common usage being "-DDD".
+            is doing and the reason behind it. 
+            Each "-D" option you use increases the logging level.
+            The most common usage is <filename>-DDD</filename>.
         </para>
 
         <para>
-            The output from <command>bitbake -DDD -v targetname</command> can reveal why
-            a certain version of a package might be chosen, why bitbake
-            picked a certain provider or help in other situations where
-            bitbake does something you're not expecting.
+            The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
+            bitbake chose a certain version of a package or why bitbake
+            picked a certain provider.
+            This command could also help you in a situation where you think bitbake did something 
+            unexpected.
         </para>
     </section>