dev-manual: Miscellaneous updates from the wic help text.

(From yocto-docs rev: 99b04623aa47d07970f91e2bdf648f25ab54c59b)

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

1 files changed, 95 insertions, 57 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index bb84dcc1c9..b995371c10 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3471,6 +3471,17 @@
         </para>
 
         <para>
+                The <filename>wic</filename> command and the infrastructure
+                it is based on is by definition incomplete.
+            Its purpose is to allow the generation of customized images,
+            and as such was designed to be completely extensible via a
+            plugin interface.
+            See the
+            "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
+            section for information on these plugins.
+            </para>
+
+        <para>
             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
@@ -3507,12 +3518,13 @@
                         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>
+                        <filename>mkefidisk.sh</filename> scripts.
+                        The difference between
+                        <filename>wic</filename> and those examples is
+                        that with <filename>wic</filename> the
+                        functionality of those scripts is implemented
+                        by a general-purpose partitioning language, which is
+                        based on Redhat kickstart syntax.</para></listitem>
                 </itemizedlist>
             </para>
         </section>
@@ -3587,6 +3599,20 @@
             </para>
 
             <para>
+                You can also get detailed help on a number of topics
+                from the help system.
+                The output of <filename>wic &dash;&dash;help</filename>
+                displays a list of available help
+                topics under a "Help topics" heading.
+                You can have the help system display the help text for
+                a given topic by prefacing the topic with
+                <filename>wic help</filename>:
+                <literallayout class='monospaced'>
+     $ wic help &lt;help topic&gt;
+                </literallayout>
+            </para>
+
+            <para>
                 You can find more out about the images
                 <filename>wic</filename> creates using the provided
                 kickstart files with the following form of the command:
@@ -3603,8 +3629,10 @@
             <title>Operational Modes</title>
 
             <para>
-                You can run <filename>wic</filename> in two modes: Raw and
-                Cooked:
+                    You can use <filename>wic</filename> in two different
+                    modes, depending on how much control you need for
+                    specifying the Openembedded build artifacts that are
+                used for creating the image: Raw and Cooked:
                 <itemizedlist>
                     <listitem><para><emphasis>Raw Mode:</emphasis>
                         You explicitly specify build artifacts through
@@ -3746,7 +3774,7 @@
      # long-description: Creates a partitioned EFI disk image that the user
      # can directly dd to boot media.
 
-     part /boot &dash;&dash;source bootimg-efi &dash;&dash;ondisk sda &dash;&dash;fstype=efi &dash;&dash;active
+     part /boot &dash;&dash;source bootimg-efi &dash;&dash;ondisk sda &dash;&dash;active
 
      part / &dash;&dash;source rootfs &dash;&dash;ondisk sda &dash;&dash;fstype=ext3 &dash;&dash;label platform
 
@@ -3889,7 +3917,7 @@
                     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 /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
      part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
                     </literallayout>
                     Once the lines are changed, the example generates the
@@ -4215,31 +4243,46 @@
                             You do not need this option if you use
                             <filename>--source</filename>.</para></listitem>
                         <listitem><para><emphasis><filename>--source</filename>:</emphasis>
-                            This option is a wic-specific option that can
-                            currently have one of two values, "bootimg" or
-                            "rootfs".</para>
-                            <para>If <filename>--source rootfs</filename> is
-                            used, it tells the <filename>wic</filename> command
-                            to create a partition as large as needed to fill
-                            with the contents of the root filesystem
-                            (specified by the <filename>-r</filename>
-                            <filename>wic</filename> option) and to fill it
-                            with the contents of <filename>/rootfs</filename>.
-                            </para>
-                            <para>If <filename>--source bootimg</filename>
-                            is used, it tells the <filename>wic</filename>
-                            command to create a partition as large as needed to
-                            fill with the contents of the boot partition
-                            (specified by the <filename>-b</filename>
-                            <filename>wic</filename> option).
-                            Exactly what those contents are depend on the value
-                            of the <filename>--fstype</filename> option for
-                            that partition.
-                            If <filename>--fstype=efi</filename> is specified,
-                            the boot artifacts contained in HDDDIR are used,
-                            and if <filename>--fstype=msdos</filename> is
-                            specified, the boot artifacts found in
-                            <filename>STAGING_DATADIR</filename> are used.
+                            This option is a
+                            <filename>wic</filename>-specific option that
+                            names the source of the data that populates
+                            the partition.
+                            The most common value for this option is
+                            "rootfs", but you can use any value that maps to
+                            a valid source plugin.
+                            For information on the source plugins, see the
+                            "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
+                            section.</para>
+                            <para>If you use
+                            <filename>&dash;&dash;source rootfs</filename>,
+                            <filename>wic</filename> creates a partition as
+                            large as needed and to fill it with the contents of
+                                        the root filesystem pointed to by the
+                                        <filename>-r</filename> command-line option
+                                        or the equivalent rootfs derived from the
+                                        <filename>-e</filename> command-line
+                                        option.
+                            The filesystem type used to create the
+                            partition is driven by the value of the
+                                        <filename>&dash;&dash;fstype</filename> option
+                                        specified for the partition.
+                            See the entry on
+                            <filename>&dash;&dash;fstype</filename> that
+                            follows for more information.
+                                        </para>
+                            <para>If you use
+                            <filename>&dash;&dash;source &lt;plugin-name&gt;</filename>,
+                            <filename>wic</filename> creates a partition as
+                            large as needed and fills it with the contents of
+                            the partition that is generated by the
+                            specified plugin name using the data pointed
+                            to by the <filename>-r</filename> command-line
+                            option or the equivalent rootfs derived from the
+                                        <filename>-e</filename> command-line
+                                        option.
+                            Exactly what those contents and
+                                        filesystem type end up being are dependent
+                                        on the given plugin implementation.
                             </para></listitem>
                         <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
                             Forces the partition to be created on a particular
@@ -4248,10 +4291,6 @@
                             Sets the file system type for the partition.
                             Valid values are:
                             <itemizedlist>
-                                <listitem><para><filename>msdos</filename>
-                                </para></listitem>
-                                <listitem><para><filename>efi</filename>
-                                </para></listitem>
                                 <listitem><para><filename>ext4</filename>
                                 </para></listitem>
                                 <listitem><para><filename>ext3</filename>
@@ -4267,11 +4306,11 @@
                             </itemizedlist></para></listitem>
                         <listitem><para><emphasis><filename>&dash;&dash;fsoptions</filename>:</emphasis>
                             Specifies a free-form string of options to be
-                            used when mounting the filesystem. 
+                            used when mounting the filesystem.
                             This string will be copied into the
                             <filename>/etc/fstab</filename> file of the
                             installed system and should be enclosed in
-                            quotes.  
+                            quotes.
                             If not specified, the default string
                             is "defaults".
                             </para></listitem>
@@ -4297,6 +4336,21 @@
                 <para>
                     This command specifies how the boot loader should be
                     and supports the following options:
+                    <note>
+                        <para>
+                        Bootloader functionality and boot partitions
+                        are implemented by the various
+                        <filename>&dash;&dash;source</filename>
+                                    plugins that implement bootloader
+                                    functionality.
+                        The bootloader command essentially provides a
+                        means of modifying bootloader configuration.
+                        </para>
+                        <para>
+                        Future updates will implement more options.
+                        If you use anything that is not specifically
+                        supported, results can be unpredictable.</para>
+                    </note>
                     <itemizedlist>
                         <listitem><para><emphasis><filename>--timeout</filename>:</emphasis>
                             Specifies the number of seconds before the
@@ -4307,22 +4361,6 @@
                             These will be added to the syslinux
                             <filename>APPEND</filename> or
                             <filename>grub</filename> kernel command line.
-                            </para>
-                            <para>The boot type is determined by the fstype of
-                            the <filename>/boot</filename> mountpoint.
-                            If the fstype is "msdos" the boot type is
-                            "pcbios", otherwise it is the fstype, which
-                            is currently "efi" (more to be added later).
-                            </para>
-                            <para>If the boot type is "efi", the image will
-                            use <filename>grub</filename> and has one
-                            menuentry: "boot".</para>
-                            <para>If the boot type is "pcbios", the image
-                            will use syslinux and has one menu label: "boot".
-                            </para>
-                            <para>Future updates will implement more options.
-                            If you use anything that is not specifically
-                            supported, results can be unpredictable.
                             </para></listitem>
                     </itemizedlist>
                 </para>