dev-manual: More work on the new wic section.

I am working through the raw text.  Not clear through yet but
needed to commit this.

(From yocto-docs rev: 4da28c311443ad31a0a36b07b39aa7ce4180b49c)

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

1 files changed, 374 insertions, 395 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 1d2d74927c..305dc316b4 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1926,18 +1926,16 @@
             that image as is on your device.
             Physical devices accept and boot images in various ways depending
             on the specifics of the device.
-            Usually information about the hardware can tell you what image
+            Usually, information about the hardware can tell you what image
             format the device requires.
             Should your device require multiple partitions on an SD card, flash,
             or an HDD, you can use the OpenEmbedded Image Creator
-            (<filename>wic</filename>) to create the properly partitioned image.
+            () to create the properly partitioned image.
         </para>
 
         <para>
-            Using the <filename>wic</filename> command, you can also describe
-            your desired final image and have BitBake assemble the image.
-            The 'wic' command generates partitioned images from existing
-            OpenEmbedded build artifacts.
+            The <filename>wic</filename> command generates partitioned images
+            from existing OpenEmbedded build artifacts.
             Image generation is driven by partitioning commands contained
             in an Openembedded kickstart file (<filename>.wks</filename>)
             specified either directly on the command-line or as one of a
@@ -1949,28 +1947,53 @@
         </para>
 
         <para>
-            'wic' is based loosely on the 'mic' (Meego Image Creator) framework,
-but heavily modified to make direct use of OpenEmbedded build
-artifacts instead of package installation and configuration, things
-already incorporated in the OE artifacts.
+            This section provides some background information on
+            <filename>wic</filename>, describes what you need to have in
+            place to run the tool, provides instruction on how to use
+            <filename>wic</filename>, and provides several examples.
         </para>
 
-        <note>
-The name 'wic' comes from 'oeic', which stands for 'OpenEmbedded
-Image Creator'. The 'oe' diphthong in 'oeic' has been promoted to the
-letter 'w', because 'oeic' is impossible to remember or pronounce.
-        </note>
+        <section id='wic-background'>
+            <title>Background</title>
 
-        <note>
-This is a completely independent standalone utility that
-initially provides easier-to-use and more flexible replacements for a
-couple bits of existing functionality in oe-core: directdisk.bbclass
-and mkefidisk.sh. The replaced scripts are implemented by a
-general-purpose partitioning 'language' based on Red Hat kickstart
-syntax (with the underlying code borrowed from Tizen mic, which in
-turn was borrowed from Meego mic, in turn borrowed from Fedora livecd,
-etc.).
-        </note>
+            <para>
+                This section provides some background on the
+                <filename>wic</filename> utility.
+                While none of this information is required to use
+                <filename>wic</filename>, you might find it interesting.
+                <itemizedlist>
+                    <listitem><para>
+                        The name "wic" is derived from OpenEmbedded
+                        Image Creator (oeic).
+                        The "oe" diphthong in "oeic" was promoted to the
+                        letter "w", because "oeic" is both difficult to remember and
+                        pronounce.</para></listitem>
+                    <listitem><para>
+                        <filename>wic</filename> is loosely based on the
+                        Meego Image Creator (<filename>mic</filename>)
+                        framework.
+                        The <filename>wic</filename> implementation has been
+                        heavily modified to make direct use of OpenEmbedded
+                        build artifacts instead of package installation and
+                        configuration, which are already incorporated within
+                        the OpenEmbedded artifacts.</para></listitem>
+                    <listitem><para>
+                        <filename>wic</filename> is a completely independent
+                        standalone utility that initially provides
+                        easier-to-use and more flexible replacements for a
+                        couple bits of existing functionality in OE Core's
+                        <filename>directdisk.bbclass</filename> and
+                        <filename>mkefidisk.sh</filename> script.
+                        The replaced scripts are implemented by a
+                        general-purpose partitioning language based on Red Hat
+                        kickstart syntax.
+                        Underlying code for <filename>wic</filename> succeeded
+                        from several projects over time.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+<!--
 
         <para>
             This section covers the mechanics of invoking and providing help for
@@ -1996,310 +2019,233 @@ or missing feature of the tool, please file a bug report describing
 the details.
         </note>
 
-        <section id='requirements'>
-            <title>Requirements</title>
+-->
 
-            <para>
-                wic has only been tested on and is only designed to work on the
-distros officially supported by Yocto.
-            </para>
+        <section id='wic-requirements'>
+            <title>Requirements</title>
 
             <para>
-                Aside from the standard system utilities, such as 'cp', wic expects the
-following utilities to be installed on the host machine:
+                In order to use the <filename>wic</filename> utility with the
+                OpenEmbedded Build system, you need to meet the following
+                requirements:
                 <itemizedlist>
-                    <listitem><para><emphasis>parted:</emphasis>
-                        GNU Parted - a partition manipulation program
+                    <listitem><para>The Linux distribution on your
+                        development host must support the Yocto Project.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
+                        section in the Yocto Project Reference Manual for this
+                        list of distributions.</para></listitem>
+                    <listitem><para>
+                        The standard system utilities, such as
+                        <filename>cp</filename>, must be installed on your
+                        development host system.
+                        </para></listitem>
+                    <listitem><para>
+                        The
+                        <ulink url='http://www.gnu.org/software/parted/'>GNU Parted</ulink>
+                        package must be installed on your development host
+                        system.
+                        </para></listitem>
+                    <listitem><para>
+                        Have the build artifacts already available.
+                        You must already have created an image using the
+                        Openembedded build system (e.g.
+                        <filename>core-image-minimal</filename>.
+                        It might seem redundant to generate an image in order
+                        to create an image using <filename>wic</filename>,
+                        but the artifacts are needed and they are generated
+                        with the build system.</para></listitem>
+                    <listitem><para>
+                        You must have sourced one of the build environment
+                        setup scripts (i.e.
+                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                        or
+                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+                        found in the
+                        <link linkend='build-directory'>Build Directory</link>.
                         </para></listitem>
                 </itemizedlist>
             </para>
         </section>
 
-        <section id='raw-vs-cooked-mode'>
-            <title>Raw Vs. Cooked Mode</title>
+        <section id='wic-getting-help'>
+            <title>Getting Help</title>
 
             <para>
-                'wic' can be used in 'raw' mode, where artifacts are explicitly
-specified via command-line arguments (see the command documentation
-and examples below), or it can be used in a more easily usable
-'cooked' mode which uses the current MACHINE setting and a specified
-image name to automatically locate the artifacts used to create the
-image.
+                You can get general help for the <filename>wic</filename>
+                by entering the <filename>wic</filename> command by itself
+                or by entering the command with a help argument as follows:
+                <literallayout class='monospaced'>
+     $ wic -h
+     $ wic --help
+                </literallayout>
             </para>
 
-            <note>
-                The prerequisite for generating any image is to have the build
-artifacts already available. For example, to create a 'wic' image
-using the build artifacts from a core-image-minimal build, you must
-already have created a core-image-minimal OpenembeddedCore image. It
-may seem redundant to generate an OpenEmbedded image in order to
-create a 'wic' image, and in fact to some degree it is. At the
-moment, however, that's typically how build artifacts are generated,
-and future versions will likely be more integrated into the build
-system and will be able to skip that step. There is a benefit
-however, in that 'wic' images are created more quickly and without the
-need for root access.
-            </note>
-        </section>
-
-        <section id='command-summary'>
-            <title>Command Summary</title>
-
             <para>
-                The general form of the 'wic' command in raw mode is:
+                Currently, <filename>wic</filename> supports two commands:
+                <filename>create</filename> and <filename>list</filename>.
+                You can get help for these commands as follows:
                 <literallayout class='monospaced'>
-     $ wic create myimage.wks -r &lt;rootfs-dir&gt; -b &lt;bootimg-dir&gt;
-       -k &lt;kernel-dir&gt; -n &lt;native-sysroot&gt;
+     $ wic help &lt;command&gt;
                 </literallayout>
-                <note>
-                    The 'wic' does NOT require root privileges, and in fact should
-not be run as root.
-                </note>
             </para>
 
             <para>
-                The .wks file specified in the command is an OE kickstart file (see
-the OE kickstart syntax section below) and can of course be specified
-directly on the command-line, but the user can also choose from a set
-of 'canned' .wks files available via the 'wic list images' command
-(example below).
+                You can find more out about the images
+                <filename>wic</filename> creates using the provided
+                kickstart files with the following form of the command:
+                <literallayout class='monospaced'>
+     $ wic list &lt;image&gt; help
+                </literallayout>
+                Where <filename>&lt;image&gt;</filename> is either
+                <filename>directdisk</filename> or
+                <filename>mkefidisk</filename>.
             </para>
+        </section>
+
+        <section id='operational-modes'>
+            <title>Operational Modes</title>
 
             <para>
-                The -r, -b, -k, and -n options refer to the corresponding OpenEmbedded
-build artifacts. Using OpenEmbedded terminology:
+                You can run <filename>wic</filename> in two modes: Raw and
+                Cooked:
                 <itemizedlist>
-                    <listitem><para><emphasis>-r option:</emphasis>
-                        Used to specify the path to the /rootfs dir to
-                        use as the .wks rootfs source.</para></listitem>
-                    <listitem><para><emphasis>-b option:</emphasis>
-                        Used to specify the path to the dir containing
-                        the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the
-                        .wks bootimg source.</para></listitem>
-                    <listitem><para><emphasis>-k option:</emphasis>
-                         Used to specify the path to the dir containing
-                         the kernel to use in the .wks bootimg.
-                         </para></listitem>
-                    <listitem><para><emphasis>-n option:</emphasis>
-                         Used to specify the path to the native sysroot
-                         containing the tools to use to build the image.
-                         </para></listitem>
+                    <listitem><para><emphasis>Raw Mode:</emphasis>
+                        You explicitly specify build artifacts through
+                        command-line arguments.</para></listitem>
+                    <listitem><para><emphasis>Cooked Mode:</emphasis>
+                        The current
+                        <ulink url='&YOCTO_DOCS_REF_URL;var-MACHINE'><filename>MACHINE</filename></ulink>
+                        setting and image name are used to automatically locate
+                        and provide the build artifacts.</para></listitem>
                 </itemizedlist>
             </para>
 
-            <para>
-                For more technical detail on the origin and meanings of those
-artifacts, see the Yocto documentation corresponding to those topics
-elsewhere. In most cases, it's not important to know that, because
-'cooked' mode provides a convenient shortcut allowing the user to
-forget about the raw details and simply specify artifacts via a
-high-level OpenEmbedded image name.
-            </para>
+            <section id='raw-mode'>
+                <title>Raw Mode</title>
 
-            <para>
-                If instead of specifying a user-defined .wks file, you prefer to use
-one of the 'canned' wic images, you can simply specify a canned image
-name (without the .wks extension) in place of a .wks file. Use 'wic
-list images' to get a list of 'canned' images:
-            <literallayout class='monospaced'>
-     $ wic list images
-     mkefidisk Create an EFI disk image
-     directdisk Create a 'pcbios' direct disk image
-            </literallayout>
-            To use one of the canned images, simply specify it in the raw command.
-For example:
-            <literallayout class='monospaced'>
-     $ wic create directdisk -r &lt;rootfs-dir&gt; -b &lt;bootimg-dir&gt;
-     -k &lt;kernel-dir&gt; -n &lt;native-sysroot&gt;
-            </literallayout>
-            Finally, the general form of the 'wic' command in cooked mode is:
-            <literallayout class='monospaced'>
-     $ wic create directdisk -e &lt;image-name&gt;
-            </literallayout>
-            This form is the simplest and most user-friendly, as it allows you to
-skip the need for specifying all the parameters individually.
-            </para>
+                <para>
+                    The general form of the 'wic' command in raw mode is:
+                    <literallayout class='monospaced'>
+     $ wic create &lt;image_name&gt;.wks -r &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; /
+           -k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt;
+                    </literallayout>
+                    <note>
+                        You do not need root privileges to run
+                        <filename>wic</filename>.
+                        In fact, you should not run as root when using the
+                        utility.
+                    </note>
+                </para>
 
-            <para>
-                <filename>&lt;image-name&gt;</filename> refers to the Openembedded image name that you've already
-build the artifacts for, for example, 'core-image-minimal'.
-                <note>
-                    In order to use cooked mode, you must have the machine that you
-built the artifacts with selected in local.conf.
-                </note>
-            </para>
-        </section>
+                <para>
+                    Following is a description of the <filename>wic</filename>
+                    parameters and options:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>&lt;image_name&gt;.wks</filename>:</emphasis>
+                            An OpenEmbedded kickstart file.
+                            You can provide your own custom file or use a
+                            file from a set of provided files as described
+                            following this list.</para></listitem>
+                        <listitem><para><emphasis><filename>-r &lt;rootfs_dir&gt;</filename>:</emphasis>
+                            Specifies the path to the root filesystem directory
+                            to be used and the <filename>.wks</filename>
+                            root filesystem source.</para></listitem>
+                        <listitem><para><emphasis><filename>-b &lt;bootimg_dir&gt;</filename>:</emphasis>
+                            Specifies the path to the directory that contains
+                            the boot artifacts (e.g. the
+                            <filename>EFI</filename> or
+                            <filename>syslinux</filename> directories) to use
+                            as the <filename>.wks</filename> boot image source.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>-k &lt;kernel_dir&gt;</filename>:</emphasis>
+                            Specifies the path to the dir containing the kernel
+                            to use in the <filename>.wks</filename> boot
+                            image.</para></listitem>
+                        <listitem><para><emphasis><filename>-n &lt;native_sysroot&gt;</filename>:</emphasis>
+                             Specifies the path to the native sysroot
+                             that contains the tools used to build the image.
+                             </para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
 
-        <section id='wic-usage-examples'>
-            <title>'wic' Usage Examples</title>
+            <section id='cooked-mode'>
+                <title>Cooked Mode</title>
 
-            <para>
-                As mentioned, the main prerequisite for generating any image is to
-have the build artifacts already available. The below examples assume
-the user has already built a 'core-image-minimal' for a specific
-machine (future versions won't require this redundant step, but for
-now that's typically how build artifacts get generated).
-            </para>
+                <para>
+                    The general form of the <filename>wic</filename> command
+                    using Cooked Mode is:
+                    <literallayout class='monospaced'>
+     $ wic create &lt;kickstart_file&gt; -e &lt;image_name&gt;
+                    </literallayout>
+                    This form is the simplest and most user-friendly, as it
+                    does not requre specifying all individual parameters.
+                    All you need to provide is your own
+                    <filename>.wks</filename> file or one provided with the
+                    release.
+                </para>
+
+                <para>
+                    Following is a description of the <filename>wic</filename>
+                    parameters and options:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>&lt;kickstart&gt;</filename>:</emphasis>
+                            An OpenEmbedded kickstart file.
+                            You can provide your own custom file or supplied
+                            file.</para></listitem>
+                        <listitem><para><emphasis><filename>-e &lt;image_name&gt;</filename>:</emphasis>
+                            Specifies the image built using the OpenEmbedded
+                            build system.</para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+        </section>
+
+        <section id='using-a-provided-kickstart_file'>
+            <title>Using a Provided Kickstart File</title>
 
             <para>
-                The other prerequisite is to source the build environment:
-                <literallayout class='monospaced'>
-     $ source oe-init-build-env
-                </literallayout>
-                To start out with, we'll generate an image from one of the canned .wks
-files. The following generates a list of available images:
+                If you do not want to create your own
+                <filename>.wks</filename> file, you can use a provided
+                file.
+                Use the following command to list the available files:
                 <literallayout class='monospaced'>
      $ wic list images
      mkefidisk Create an EFI disk image
      directdisk Create a 'pcbios' direct disk image
+                 </literallayout>
+                 When you use a provided file, you do not have to use the
+                 <filename>.wks</filename> extension.
+                 Here is an example in Raw Mode that uses the
+                 <filename>directdisk</filename> file:
+                 <literallayout class='monospaced'>
+     $ wic create directdisk -r &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; \
+           -k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt;
                 </literallayout>
-                You can get more information about any of the available images by typing
-'wic list xxx help', where 'xxx' is one of the image names.
-            </para>
-
-            <para>
-                For example:
-                <literallayout class='monospaced'>
-     $ wic list mkefidisk help
-                </literallayout>
-                Creates a partitioned EFI disk image that the user
-can directly dd to boot media.
             </para>
+        </section>
 
-            <para>
-                At any time, you can get help on the 'wic' command or any subcommand
-(currently 'list' and 'create'). For instance, to get the description
-of 'wic create' command and its parameters:
-                <literallayout class='monospaced'>
-     $ wic create
-
-     Usage:
-
-      Create a new OpenEmbedded image
-
-      usage: wic create &lt;wks file or image name&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
-      [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY FILE&gt;]
-      [-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir]
-      [-k, --kernel-dir] [-n, --native-sysroot] [-s, --skip-build-check]
-
-      This command creates an OpenEmbedded image based on the 'OE kickstart
-      commands' found in the &lt;wks file&gt;.
-
-      The -o option can be used to place the image in a directory with a
-      different name and location.
-
-      See 'wic help create' for more detailed instructions.
-
-     [...]
-                </literallayout>
-            </para>
+        <section id='wic-usage-examples'>
+            <title>Examples</title>
 
             <para>
-            Continuing further, as mentioned in the command, you can get even more
-detailed information by adding 'help' to the above:
-                <literallayout class='monospaced'>
-     $ wic help create
-
-     NAME
-      wic create - Create a new OpenEmbedded image
-
-     SYNOPSIS
-      wic create &lt;wks file or image name&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
-      [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY FILE&gt;]
-      [-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir]
-      [-k, --kernel-dir] [-n, --native-sysroot] [-s,
-     --skip-build-check]
-
-     DESCRIPTION
-      This command creates an OpenEmbedded image based on the 'OE
-      kickstart commands' found in the &lt;wks file&gt;.
-
-      In order to do this, wic needs to know the locations of the
-      various build artifacts required to build the image.
-
-      Users can explicitly specify the build artifact locations using
-      the -r, -b, -k, and -n options. See below for details on where
-      the corresponding artifacts are typically found in a normal
-      OpenEmbedded build.
-
-      Alternatively, users can use the -e option to have 'mic' determine
-      those locations for a given image. If the -e option is used, the
-      user needs to have set the appropriate MACHINE variable in
-      local.conf, and have sourced the build environment.
-
-      The -e option is used to specify the name of the image to use the
-      artifacts from e.g. core-image-sato.
-
-      The -r option is used to specify the path to the /rootfs dir to
-      use as the .wks rootfs source.
-
-      The -b option is used to specify the path to the dir containing
-      the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the
-      .wks bootimg source.
-
-      The -k option is used to specify the path to the dir containing
-      the kernel to use in the .wks bootimg.
-
-      The -n option is used to specify the path to the native sysroot
-      containing the tools to use to build the image.
-
-      The -s option is used to skip the build check. The build check is
-      a simple sanity check used to determine whether the user has
-      sourced the build environment so that the -e option can operate
-      correctly. If the user has specified the build artifact locations
-      explicitly, 'wic' assumes the user knows what he or she is doing
-      and skips the build check.
-
-      When 'wic -e' is used, the locations for the build artifacts
-      values are determined by 'wic -e' from the output of the 'bitbake
-      -e' command given an image name e.g. 'core-image-minimal' and a
-      given machine set in local.conf. In that case, the image is
-      created as if the following 'bitbake -e' variables were used:
-
-      -r: IMAGE_ROOTFS
-      -k: STAGING_KERNEL_DIR
-      -n: STAGING_DIR_NATIVE
-      -b: HDDDIR and STAGING_DATA_DIR (handlers decide which to use)
-
-      If 'wic -e' is not used, the user needs to select the appropriate
-      value for -b (as well as -r, -k, and -n).
-
-      The -o option can be used to place the image in a directory with a
-      different name and location.
-
-      As an alternative to the wks file, the image-specific properties
-      that define the values that will be used to generate a particular
-      image can be specified on the command-line using the -i option and
-      supplying a JSON object consisting of the set of name:value pairs
-      needed by image creation.
-
-      The set of properties available for a given image type can be
-      listed using the 'wic list' command.
-                </literallayout>
-        So, the easiest way to create an image is to use the -e option with a
-canned .wks file. To use the -e option, you need to specify the image
-used to generate the artifacts and you actually need to have the
-MACHINE used to build them specified in your local.conf (these
-requirements aren't necessary if you aren't using the -e options.
+                This section provides several examples that show how to use
+                the <filename>wic</filename> utility.
+                All the examples assume the list of requirements in the
+                "<link linkend='wic-requirements'>Requirements</link>" section
+                have been met.
+                The examples assume the previously generated image is
+                <filename>core-image-minimal</filename>.
             </para>
 
-            <para>
-            Below, we generate a mkefidisk image, pointing the process at the
-core-image-minimal artifacts for the minnow, selected as our current
-MACHINE in local.conf.
-            </para>
+            <section id='generate-an-image-using-a-provided-kickstart-file'>
+                <title>Generate an Image using a Provided Kickstart File</title>
 
-            <para>
-            First, once we've set the build up, we run a core-image-minimal minnow
-build:
-                <literallayout class='monospaced'>
-     $ bitbake core-image-minimal
-                </literallayout>
-            Once the build is finished, we can then use wic to create an EFI image
-for the minnow to boot. In this case, we'll use the '-e' option to
-have wic discover the appropriate build artifacts and generate the
-image:
-                <literallayout class='monospaced'>
+                <para>
+                    This example runs in Cooked Mode and uses the
+                    <filename>mkefidisk</filename> kickstart file:
+                    <literallayout class='monospaced'>
      $ wic create mkefidisk -e core-image-minimal
      Checking basic build environment...
      Done.
@@ -2318,86 +2264,118 @@ image:
 
      The image(s) were created using OE kickstart file:
       /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
-                </literallayout>
-        The output specifies exactly which image was created and where it was
-created. It also names the artifacts that were used and the exact
-.wks script that was used to generate the image. You should always
-verify the details provided in the output to make sure that the image
-was indeed created exactly as expected.
-            </para>
+                    </literallayout>
+                    This example shows the easiest way to create an image
+                    by running in Cooked Mode and using the
+                    <filename>&lt;-e&gt;</filename> option with a
+                    provided kickstart file.
+                    All that is necessary is to specify the image
+                    used to generate the artifacts.
+                    Your <filename>local.conf</filename> needs to have the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                    variable set to the machine you are using, which is
+                    "minnow" in this example.
+                </para>
 
-            <para>
-            Using the path specified in the output for the image name and
-location, you can now directly dd the image to a USB stick or whatever
-media you built the image for, and boot the resulting media:
-                <literallayout class='monospaced'>
+                <para>
+                    The output specifies exactly which image were
+                    created and where the image was created.
+                    The output also names the artifacts used and the exact
+                    <filename>.wks</filename> script that was used to generate
+                    the image.
+                    <note>
+                        You should always verify the details provided in the
+                        output to make sure that the imagewas indeed created
+                        exactly as expected.
+                    </note>
+                </para>
+
+                <para>
+                    Continuing with the example, you can now directly
+                    <filename>dd</filename> the image to a USB stick, or
+                    whatever media for which you built your image,
+                    and boot the resulting media:
+                    <literallayout class='monospaced'>
      $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
      [sudo] password for trz:
      182274+0 records in
      182274+0 records out
      93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
      [trz@empanada ~]$ sudo eject /dev/sdb
-                </literallayout>
-            The next example uses a modified 'directdisk' script as an example.
-            </para>
-
-            <para>
-            Because wic image creation is driven by .wks files, it's easy to
-change the parameters that drive image creation: simply modify the
-.wks file.
-            </para>
+                    </literallayout>
+                </para>
+            </section>
 
-            <para>
-            As illustrated previously, 'wic list images' provides a list of
-available images. The images displayed are simply the list of .wks
-files in the scripts/lib/image/canned-wks/ directory, minus the .wks
-extension.
-            </para>
+            <section id='using-a-modified-kickstart-file'>
+                <title>Using a Modified Kickstart File</title>
 
-            <para>
-            To add a new image to that list, simply add a new .wks file.
-            </para>
+                <para>
+                    Because <filename>wic</filename> image creation is driven
+                    by the kickstart file, it is easy to drive image creation
+                    by changing the parameters in the file.
+                    This next example demonstrates that through modification
+                    of the <filename>directdisk</filename> kickstart file.
+                </para>
 
-            <para>
-            For this example, we already have a .wks file that already does pretty
-much what we want, but for our particular hardware, we know we'll be
-booting from sdb instead of sda, which is what the directdisk script uses.
-            </para>
+                <para>
+                    As mentioned earlier, you can use the command
+                    <filename>wic list images</filename> to show the list
+                    of provided kickstart files.
+                    The directory in which these files reside is in the
+                    <link linkend='source-directory'>Source Directory</link>
+                    in <filename>scripts/lib/image/canned-wks/</filename>.
+                    Because the available files reside in this directory, you
+                    can create and add your own custom files to the directory.
+                    Subsequent use of the <filename>wic list images</filename>
+                    command would then include your kickstart files.
+                </para>
 
-            <para>
-            What we can do is simply create a copy of the directdisk.wks file in
-the scripts/lib/image/canned-wks/ directory and change the lines that
-specify the target disk to boot from.
-            </para>
+                <para>
+                    In this example, the existing
+                    <filename>directdisk</filename> file already does most
+                    of what is needed.
+                    However, for the hardware in this example, the image will
+                    need to boot from <filename>sdb</filename> instead of
+                    <filename>sda</filename>, which is what the
+                    <filename>directdisk</filename> kickstart file uses.
+                </para>
 
-            <para>
-            First, we copy the directdisk.wks file to directdisksdb.wks:
-                <literallayout class='monospaced'>
+                <para>
+                    The example begins by making a copy of the
+                    <filename>directdisk.wks</filename> file in the
+                    <filename>scripts/lib/image/canned-wks</filename>
+                    directory and then changing the lines that specify the
+                    target disk from which to boot.
+                    <literallayout class='monospaced'>
      $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
-                </literallayout>
-            Then we modify the directdisksdb.wks file and change all instances of
-'--ondisk sda' to '--ondisk sdb'. The following two lines are the
-lines we end up changing (leaving the rest alone):
-                <literallayout class='monospaced'>
+                    </literallayout>
+                    Next, the example modifies the
+                    <filename>directdisksdb.wks</filename> file and changes all
+                    instances of "<filename>--ondisk sda</filename>"
+                    to "<filename>--ondisk sdb</filename>".
+                    The example changes the following two lines and leaves the
+                    remaining lines untouched:
+                    <literallayout class='monospaced'>
      part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024
      part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
-                </literallayout>
-               Once we've made that change, we generate a directdisksdb image,
+                    </literallayout>
+                    (I AM HERE)
+                    Once the lines are changed, Once we've made that change, we generate a directdisksdb image,
 pointing the process at the core-image-minimal artifacts for the nuc
 (Next Unit of Computing), selected as our current MACHINE in
 local.conf.
-            </para>
+                </para>
 
-            <para>
-            Once we've set the build up, we run a core-image-minimal nuc build:
-                <literallayout class='monospaced'>
+                <para>
+                    Once we've set the build up, we run a core-image-minimal nuc build:
+                    <literallayout class='monospaced'>
      $ bitbake core-image-minimal
-                </literallayout>
+                    </literallayout>
             Once the build is finished, we can then use nuc to create our
 directdisk image for the nuc to boot. In this case, we'll use the
 '-e' option to have wic discover the appropriate build artifacts and
 generate the image:
-                <literallayout class='monospaced'>
+                    <literallayout class='monospaced'>
      $ wic create directdisksdb -e core-image-minimal
      Checking basic build environment...
      Done.
@@ -2416,25 +2394,25 @@ generate the image:
 
      The image(s) were created using OE kickstart file:
       /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
-                </literallayout>
+                    </literallayout>
             Using the path specified in the output for the image name and
 location, you can now directly dd the image to a USB stick or whatever
 media you built the image for, and boot the resulting media:
-                <literallayout class='monospaced'>
+                    <literallayout class='monospaced'>
      $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
      86018+0 records in
      86018+0 records out
      44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
      [trz@empanada tmp]$ sudo eject /dev/sdb
-                </literallayout>
+                    </literallayout>
                 Of course, you can just use the directdisk image directly if you don't
 have any special needs.
-            </para>
+                </para>
 
-            <para>
+                <para>
             Here'we're creating a wic image based on core-image-minimal and
 crownbay-noemgd, which works right out of the box.
-                <literallayout class='monospaced'>
+                    <literallayout class='monospaced'>
      $ wic create directdisk -e core-image-minimal
 
      Checking basic build environment...
@@ -2454,12 +2432,12 @@ crownbay-noemgd, which works right out of the box.
 
      The image(s) were created using OE kickstart file:
       /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
-                </literallayout>
+                    </literallayout>
             Finally, here's an example that doesn't take the easy way out and
 manually specifies each build artifact, along with a non-canned .wks
 file, and also uses the -o option to have wic create the output
 somewhere other than the default /var/tmp/wic:
-                <literallayout class='monospaced'>
+                    <literallayout class='monospaced'>
      $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share  --kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel --native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
 
      Creating image(s)...
@@ -2476,17 +2454,17 @@ somewhere other than the default /var/tmp/wic:
 
      The image(s) were created using OE kickstart file:
       /home/trz/test.wks
-                </literallayout>
+                    </literallayout>
             In this case, we didn't need to have the proper machine selected in
 local.conf - we manually specified each artifact and therefore wic
 doesn't need further information from the build system.
-            </para>
+                </para>
 
-            <para>
+                <para>
             Finally, here's an example of the actual partition language commands
 used to generate the mkefidisk image i.e. these are the contents of the
 mkefidisk.wks OE kickstart file:
-                <literallayout class='monospaced'>
+                    <literallayout class='monospaced'>
      # short-description: Create an EFI disk image
      # long-description: Creates a partitioned EFI disk image that the user
      # can directly dd to boot media.
@@ -2498,56 +2476,56 @@ mkefidisk.wks OE kickstart file:
      part swap --ondisk sda --size 44 --label swap1 --fstype=swap
 
      bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-     intel.enable_msi=0"
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
+            </section>
         </section>
-    </section>
 
-    <section id='openembedded-kickstart-wks-reference'>
-        <title>OpenEmbedded Kickstart (.wks) Reference</title>
+        <section id='openembedded-kickstart-wks-reference'>
+            <title>OpenEmbedded Kickstart (.wks) Reference</title>
 
-        <para>
+            <para>
             The current 'wic' implementation supports only the basic kickstart
 partitioning commands: 'partition' (or 'part' for short) and
 'bootloader'.
-        </para>
+            </para>
 
-        <para>
+            <para>
             They are listed below and mostly follow the syntax and meaning of the
 standard kickstart options for those commands. The documentation below
 is based on the Fedora kickstart documentation of the same commands,
 but modified to reflect wic capabilities. For reference:
-            <literallayout class='monospaced'>
+                <literallayout class='monospaced'>
      http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
      http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
-            </literallayout>
-        </para>
+                </literallayout>
+            </para>
 
-        <section id='command-part-or-partition'>
-            <title>Command: part or partition</title>
+            <section id='command-part-or-partition'>
+                <title>Command: part or partition</title>
 
-            <para>
+                <para>
                 Creates a partition on the system.
                 Use the following syntax:
-                <literallayout class='monospaced'>
+                    <literallayout class='monospaced'>
      part &lt;mntpoint&gt;
-                </literallayout>
+                    </literallayout>
                 The &lt;mntpoint&gt; is where the partition will be mounted and must be of
 one of the following forms:
-                <itemizedlist>
-                    <listitem><para><filename>/&lt;path&gt;</filename>:
-                        For example, <filename>/</filename>,
-                        <filename>/usr</filename>, and
-                        <filename>/home</filename></para></listitem>
-                    <listitem><para><filename>swap</filename>:
-                        The partition will be used as swap space.
-                        </para></listitem>
-                </itemizedlist>
-            </para>
+                    <itemizedlist>
+                        <listitem><para><filename>/&lt;path&gt;</filename>:
+                            For example, <filename>/</filename>,
+                            <filename>/usr</filename>, and
+                            <filename>/home</filename></para></listitem>
+                        <listitem><para><filename>swap</filename>:
+                            The partition will be used as swap space.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
 
-            <para>
-                Following are the supported options:
-                <literallayout class='monospaced'>
+                <para>
+                    Following are the supported options:
+                    <literallayout class='monospaced'>
      --size
       The minimum partition size in megabytes. Specify an integer value
       here such as 500. Do not append the number with MB. Not needed if
@@ -2597,20 +2575,20 @@ one of the following forms:
      --align (in kB)
       The '--align' option is a mic-specific option that says to start a
       partition on an x kB boundary.
-                </literallayout>
-            </para>
-        </section>
+                    </literallayout>
+                </para>
+            </section>
 
-        <section id='command-bootloader'>
-            <title>Command: bootloader</title>
+            <section id='command-bootloader'>
+                <title>Command: bootloader</title>
 
-            <para>
-                This command specifies how the boot loader should be installed.
-            </para>
+                <para>
+                    This command specifies how the boot loader should be installed.
+                </para>
 
-            <para>
-                Following are the supported options:
-                <literallayout class='monospaced'>
+                <para>
+                    Following are the supported options:
+                    <literallayout class='monospaced'>
      --timeout
       Specify the number of seconds before the bootloader times out and
       boots the default option.
@@ -2631,8 +2609,9 @@ one of the following forms:
 
      Future updates will implement more options - using anything not
      explicitly supported can result in unpredictable results.
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
+            </section>
         </section>
     </section>