4 files changed, 33 insertions, 5 deletions

diff --git a/documentation/ref-manual/figures/building-an-image.png b/documentation/ref-manual/figures/building-an-image.png
new file mode 100755
index 0000000000..1fbea5ab00
--- /dev/null
+++ b/documentation/ref-manual/figures/building-an-image.png
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index cc3f6b075c..5250e26be7 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -110,7 +110,7 @@
 <title>System Requirements</title>
     <para>
         For general Yocto Project system requirements, see the
-        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
+        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section
         in the Yocto Project Quick Start.
         The remainder of this section provides details on system requirements
         not covered in the Yocto Project Quick Start.
@@ -212,6 +212,20 @@
             <para>
                 The following list shows the required packages by function
                 given a supported Ubuntu or Debian Linux distribution:
+                <note>
+                    If your build system has the
+                    <filename>oss4-dev</filename> package installed, you
+                    might experience QEMU build failures due to the package
+                    installing its own custom
+                    <filename>/usr/include/linux/soundcard.h</filename> on
+                    the Debian system.
+                    If you run into this situation, either of the following
+                    solutions exist:
+                    <literallayout class='monospaced'>
+     $ sudo apt-get build-dep qemu
+     $ sudo apt-get remove oss4-dev
+                    </literallayout>
+                 </note>
                 <itemizedlist>
                     <listitem><para><emphasis>Essentials:</emphasis>
                         Packages needed to build an image on a headless
diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml
index 30aff6431f..dc402dbffc 100644
--- a/documentation/ref-manual/ref-bitbake.xml
+++ b/documentation/ref-manual/ref-bitbake.xml
@@ -255,7 +255,7 @@
             It is worth noting that you can greatly speed up the build time by properly setting
             the <filename>BB_NUMBER_THREADS</filename> variable.
             See the
-            "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+            "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
             section in the Yocto Project Quick Start for more information.
         </para>
 
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index e2e05b2514..ca87962e24 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -19,7 +19,7 @@
         for less obvious aspects of the build process.
         For general information on how to build an image using the OpenEmbedded build
         system, see the
-        "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+        "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
         section of the Yocto Project Quick Start.
     </para>
 
@@ -27,6 +27,20 @@
         <title>Build Overview</title>
 
         <para>
+            In the development environment you will need to build an image whenever you change hardware
+            support, add or change system libraries, or add or change services that have dependencies.
+        </para>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/>
+            </imageobject>
+            <caption>
+                <para>Building an Image</para>
+            </caption>
+        </mediaobject>
+
+        <para>
             The first thing you need to do is set up the OpenEmbedded build
             environment by sourcing an environment setup script
             (i.e.
@@ -99,8 +113,8 @@
         <filename class="directory">tmp/deploy/images</filename>.
         For information on how to run pre-built images such as <filename>qemux86</filename>
         and <filename>qemuarm</filename>, see the
-        "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
-        section in the Yocto Project Quick Start.
+        "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Example Using Pre-Built Binaries and QEMU</ulink>"
+        section in the Yocto Project Application Developer's Guide.
         For information about how to install these images, see the documentation for your
         particular board or machine.
     </para>