ref-manual, mega-manual: Updates to the Image Generation section

Fixes [YOCTO #2808]

Applied review comments to the section from Paul Eggleton.  I
updated the figure and the text areas.

(From yocto-docs rev: a89b126861e8ee2f43a89afb0a16e56659270fee)

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

1 files changed, 46 insertions, 50 deletions

diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index 5a7d111890..0a6c56c048 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -106,7 +106,7 @@
             configuration files.
             These example files are used as a basis for creating actual
             configuration files when you source the build environment
-            script 
+            script
             (i.e.
             <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
             or
@@ -129,8 +129,8 @@
         <para>
             Because the Poky repository is fundamentally an aggregation of
             existing repositories, some users might be familiar with running
-            the <filename>&OE_INIT_FILE;</filename> or 
-            <filename>oe-init-build-env-memres</filename> script in the context 
+            the <filename>&OE_INIT_FILE;</filename> or
+            <filename>oe-init-build-env-memres</filename> script in the context
             of separate OpenEmbedded-Core and BitBake repositories rather than a
             single Poky repository.
             This discussion assumes the script is executed from within a cloned
@@ -297,7 +297,7 @@
         <para>
             The following figure shows an expanded representation of the
             Metadata, Machine Configuration, and Policy Configuration input
-            (layers) boxes of the 
+            (layers) boxes of the
             <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
         </para>
 
@@ -452,7 +452,7 @@
         <para>
             In order for the OpenEmbedded build system to create an image or
             any target, it must be able to access source files.
-            The 
+            The
             <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
             represents source files using the "Upstream Project Releases",
             "Local Projects", and "SCMs (optional)" boxes.
@@ -608,7 +608,7 @@
             When the OpenEmbedded build system generates an image or an SDK,
             it gets the packages from a package feed area located in the
             <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
-            The 
+            The
             <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
             shows this package feeds area in the upper-right corner.
         </para>
@@ -887,84 +887,80 @@
             <title>Image Generation</title>
 
             <para>
-                Once packages are split and stored in the Package Feeds area, 
-                the OpenEmbedded build system uses BitBake to generate the 
+                Once packages are split and stored in the Package Feeds area,
+                the OpenEmbedded build system uses BitBake to generate the
                 root filesystem image:
                 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
             </para>
 
             <para>
-                The image generation process consists of several stages and 
+                The image generation process consists of several stages and
                 depends on many variables.
                 The <filename>do_rootfs</filename> task uses these key variables
                 to help create the list of packages to actually install:
                 <itemizedlist>
                     <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
-                        Lists out the base set of packages to install from 
-                        the Package Feeds area.</para></listitem>   
+                        Lists out the base set of packages to install from
+                        the Package Feeds area.</para></listitem>
                     <listitem><para><link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>:
                         Specifies packages that should not be installed.
-                        </para></listitem>  
+                        </para></listitem>
                     <listitem><para><link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
-                        Specifies features to include in the image. 
-                        These features map to additional packages for
+                        Specifies features to include in the image.
+                        Most of these features map to additional packages for
                         installation.</para></listitem>
                     <listitem><para><link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>:
-                        Specifies the package manager to use and consequently
-                        helps determine where to locate packages within the 
-                        Package Feeds area.</para></listitem>  
+                        Specifies the package backend to use and consequently
+                        helps determine where to locate packages within the
+                        Package Feeds area.</para></listitem>
                     <listitem><para><link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>:
-                        Determines the language for which packages are being 
-                        installed.</para></listitem>
+                        Determines the language(s) for which additional
+                        language support packages are installed.
+                        </para></listitem>
                 </itemizedlist>
             </para>
 
             <para>
-                Part of the image generation process includes compressing the 
-                root filesystem image. 
-                Compression is accomplished through several optimization 
-                routines designed to reduce the overall size of the image.
-            </para>
-
-            <para>
-                The process runs as many post installation scripts as possible.
-                Any scripts that cannot be run are run when the system is 
-                first booted.
+                The process runs all of the post installation scripts, and
+                any that fail to run on the build host will be run on the
+                target when the target system is first booted.
                 If you are using a read-only root filesystem, all the post
-                installation scripts are run during the package installation
-                phase since the root filesystem cannot be written into.
+                installation scripts must succeed during the package
+                installation phase since the root filesystem cannot be
+                written into.
             </para>
 
             <para>
-                During the Prelink phase, optimization processes are run across
-                the image. 
-                These processes include <filename>mklibs</filename> and 
+                During Optimization, optimizing processes are run across
+                the image.
+                These processes include <filename>mklibs</filename> and
                 <filename>prelink</filename>.
-                The <filename>mklibs</filename> optimizes the size of the 
-                libraries.  
-                The <filename>prelink</filename> process optimizes the dynamic 
-                linking of shared libraries to reduce start up time of the 
+                The <filename>mklibs</filename> optimizes the size of the
+                libraries.
+                A <filename>prelink</filename> process optimizes the dynamic
+                linking of shared libraries to reduce start up time of the
                 executables.
-                See the 
-                <link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>
-                and 
-                <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>
-                variables for additional information.
+            </para>
+
+            <para>
+                Part of the image generation process includes compressing the
+                root filesystem image.
+                Compression is accomplished through several optimization
+                routines designed to reduce the overall size of the image.
             </para>
 
             <para>
                 After the root filesystem has been constructed, the image
-                generation process turns everything into an image file or 
-                a set of image files.  
-                we need to turn into an image file or set of image files.  
-                The formats used for the root filesystem depend on the 
+                generation process turns everything into an image file or
+                a set of image files.
+                The formats used for the root filesystem depend on the
                 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
                 variable.
             </para>
 
             <note>
                 The entire image generation process is run under Pseudo.
-                Running under Pseudo ensures that the files in the root 
+                Running under Pseudo ensures that the files in the root
                 filesystem have correct ownership.
             </note>
         </section>
@@ -977,7 +973,7 @@
             The images produced by the OpenEmbedded build system
             are compressed forms of the
             root filesystems that are ready to boot on a target device.
-            You can see from the 
+            You can see from the
             <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
             that BitBake output in part consists of images.
             This section is going to look more closely at this output:
@@ -1049,7 +1045,7 @@
         <title>Application Development SDK</title>
 
         <para>
-            In the 
+            In the
             <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
             the output labeled "Application Development SDK" represents an
             SDK.