From 4a3a747c77dfb180720b5bc41a41738d96b2db54 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <scott.m.rifenbark@intel.com>
Date: Fri, 28 Mar 2014 15:46:58 -0600
Subject: ref-manual: Edits to the "Using" chapter.

Along with some minor things I did the following:

* Added a brief explanation and reference to the reporting error
  tool.  It seemed like a good chapter to include it.  I put it
  in the debugging section.

* I added a pointer to the BitBake manual right at the top of a
  section that had many usages of the bitbake command.

(From yocto-docs rev: 9317433bc715e9fdac2fc629ed659ac926d67531)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/usingpoky.xml | 38 +++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 8 deletions(-)

(limited to 'documentation/ref-manual/usingpoky.xml')

diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 5799b2b973..a8a6f3b92a 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -48,8 +48,6 @@
             A common practice is to use a different Build Directory for different targets.
             For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
             target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
-            See the "<link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>"
-            section for more information on this script.
         </para>
 
         <para>
@@ -111,16 +109,30 @@
     <title>Debugging Build Failures</title>
 
     <para>
-        The exact method for debugging build failures depends on the nature of the
-        problem and on the system's area from which the bug originates.
+        The exact method for debugging build failures depends on the nature of
+        the problem and on the system's area from which the bug originates.
         Standard debugging practices such as comparison against the last
-        known working version with examination of the changes and the re-application of steps
-        to identify the one causing the problem are
+        known working version with examination of the changes and the
+        re-application of steps to identify the one causing the problem are
         valid for the Yocto Project just as they are for any other system.
         Even though it is impossible to detail every possible potential failure,
         this section provides some general tips to aid in debugging.
     </para>
 
+    <para>
+        A useful feature for debugging is the error reporting tool.
+        Configuring the Yocto Project to use this tool causes the
+        OpenEmbedded build system to produce error reporting commands as
+        part of the console output.
+        You can enter the commands after the build completes
+        to log error information
+        into a common database, that can help you figure out what might be
+        going wrong.
+        For information on how to enable and use this feature, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+
     <para>
         For discussions on debugging, see the
         "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
@@ -129,6 +141,14 @@
         sections in the Yocto Project Development Manual.
     </para>
 
+    <note>
+        The remainder of this section presents many examples of the
+        <filename>bitbake</filename> command.
+        You can learn about BitBake by reading the
+        <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
+    </note>
+
+
     <section id='usingpoky-debugging-taskfailures'>
         <title>Task Failures</title>
 
@@ -137,7 +157,9 @@
             For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
             machine (<filename>qemux86</filename>) might be
             <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
-            To see what BitBake runs to generate that log, look at the corresponding
+            To see what
+            <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
+            runs to generate that log, look at the corresponding
             <filename>run.do_taskname.pid</filename> file located in the same directory.
         </para>
 
@@ -285,7 +307,7 @@
             </literallayout>
             This command form does not check for dependencies.
             Consequently, you should use it
-            only when you know dependencies already exist.
+            only when you know existing dependencies have been met.
             <note>
                 You can also specify fragments of the filename.
                 In this case, BitBake checks for a unique match.
-- 
cgit v1.2.3-54-g00ecf