dev-manual, ref-manual: Moved Wic Plug-In section to dev-manual

Fixes [YOCTO #12370]

I had a section on Wick Plug-Ins in the ref-manual in the
"technical details" chapter.  This section has been combined with the
section on using Wic that lives in the dev-manual.  This move creates
a single section on using Wic to create Wic-partitioned images.

The section was moved out of the ref-manual and merged into the
dev-manual Wic section.

(From yocto-docs rev: 8724049141c9a793312dcf5ff5c3425948d1cbd0)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

3 files changed, 212 insertions, 213 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 58bb6012ce..78825c7f1e 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4878,16 +4878,17 @@
             customized images, and as such, was designed to be
             completely extensible through a plug-in interface.
             See the
-            "<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>"
-            section in the Yocto Project Reference Manual for information
-            on these plug-ins.
+            "<link linkend='wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</link>"
+            section for information on these plug-ins.
         </para>
 
         <para>
             This section provides some background information on Wic,
             describes what you need to have in
             place to run the tool, provides instruction on how to use
-            the Wic utility, and provides several examples.
+            the Wic utility, provides information on using the Wic plug-ins
+            interface, and provides several examples that show how to use
+            Wic.
         </para>
 
         <section id='wic-background'>
@@ -5265,6 +5266,210 @@
             </para>
         </section>
 
+        <section id='wic-using-the-wic-plug-ins-interface'>
+            <title>Using the Wic Plug-Ins Interface</title>
+
+            <para>
+                You can extend and specialize Wic functionality by using
+                Wic plug-ins.
+                This section explains the Wic plug-in interface.
+                <note>
+                    Wic plug-ins consist of "source" and "imager" plug-ins.
+                    Imager plug-ins are beyond the scope of this section.
+                </note>
+            </para>
+
+            <para>
+                Source plug-ins provide a mechanism to customize partition
+                content during the Wic image generation process.
+                You can use source plug-ins to map values that you specify
+                using <filename>--source</filename> commands in kickstart
+                files (i.e. <filename>*.wks</filename>) to a plug-in
+                implementation used to populate a given partition.
+                <note>
+                    If you use plug-ins that have build-time dependencies
+                    (e.g. native tools, bootloaders, and so forth)
+                    when building a Wic image, you need to specify those
+                    dependencies using the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink>
+                    variable.
+                </note>
+            </para>
+
+            <para>
+                Source plug-ins are subclasses defined in plug-in files.
+                As shipped, the Yocto Project provides several plug-in
+                files.
+                You can see the source plug-in files that ship with the
+                Yocto Project
+                <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
+                Each of these plug-in files contains source plug-ins that
+                are designed to populate a specific Wic image partition.
+            </para>
+
+            <para>
+                Source plug-ins are subclasses of the
+                <filename>SourcePlugin</filename> class, which is
+                defined in the
+                <filename>poky/scripts/lib/wic/pluginbase.py</filename>
+                file.
+                For example, the <filename>BootimgEFIPlugin</filename>
+                source plug-in found in the
+                <filename>bootimg-efi.py</filename> file is a subclass of
+                the <filename>SourcePlugin</filename> class, which is found
+                in the <filename>pluginbase.py</filename> file.
+            </para>
+
+            <para>
+                You can also implement source plug-ins in a layer outside
+                of the Source Repositories (external layer).
+                To do so, be sure that your plug-in files are located in
+                a directory whose path is
+                <filename>scripts/lib/wic/plugins/source/</filename>
+                within your external layer.
+                When the plug-in files are located there, the source
+                plug-ins they contain are made available to Wic.
+            </para>
+
+            <para>
+                When the Wic implementation needs to invoke a
+                partition-specific implementation, it looks for the plug-in
+                with the same name as the <filename>--source</filename>
+                parameter used in the kickstart file given to that
+                partition.
+                For example, if the partition is set up using the following
+                command in a kickstart file:
+                <literallayout class='monospaced'>
+     part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
+                </literallayout>
+                The methods defined as class members of the matching
+                source plug-in (i.e. <filename>bootimg-pcbios</filename>)
+                in the <filename>bootimg-pcbios.py</filename> plug-in file
+                are used.
+            </para>
+
+            <para>
+                To be more concrete, here is the corresponding plug-in
+                definition from the <filename>bootimg-pcbios.py</filename>
+                file for the previous command along with an example
+                method called by the Wic implementation when it needs to
+                prepare a partition using an implementation-specific
+                function:
+                <literallayout class='monospaced'>
+     bootimg-pcbios.py
+                  .
+                  .
+                  .
+        class BootimgPcbiosPlugin(SourcePlugin):
+        """
+        Create MBR boot partition and install syslinux on it.
+        """
+
+        name = 'bootimg-pcbios'
+                  .
+                  .
+                  .
+        @classmethod
+        def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
+                                 oe_builddir, bootimg_dir, kernel_dir,
+                                 rootfs_dir, native_sysroot):
+            """
+            Called to do the actual content population for a partition i.e. it
+            'prepares' the partition to be incorporated into the image.
+            In this case, prepare content for legacy bios boot partition.
+            """
+                  .
+                  .
+                  .
+                </literallayout>
+                If a subclass (plug-in) itself does not implement a
+                particular function, Wic locates and uses the default
+                version in the superclass.
+                It is for this reason that all source plug-ins are derived
+                from the <filename>SourcePlugin</filename> class.
+            </para>
+
+            <para>
+                The <filename>SourcePlugin</filename> class defined in
+                the <filename>pluginbase.py</filename> file defines
+                a set of methods that source plug-ins can implement or
+                override.
+                Any plug-ins (subclass of
+                <filename>SourcePlugin</filename>) that do not implement
+                a particular method inherit the implementation of the
+                method from the <filename>SourcePlugin</filename> class.
+                For more information, see the
+                <filename>SourcePlugin</filename> class in the
+                <filename>pluginbase.py</filename> file for details:
+            </para>
+
+            <para>
+                The following list describes the methods implemented in the
+                <filename>SourcePlugin</filename> class:
+                <itemizedlist>
+                    <listitem><para>
+                        <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
+                        Called to populate a partition with actual content.
+                        In other words, the method prepares the final
+                        partition image that is incorporated into the
+                        disk image.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis><filename>do_configure_partition()</filename>:</emphasis>
+                        Called before
+                        <filename>do_prepare_partition()</filename> to
+                        create custom configuration files for a partition
+                        (e.g. syslinux or grub configuration files).
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis><filename>do_install_disk()</filename>:</emphasis>
+                        Called after all partitions have been prepared and
+                        assembled into a disk image.
+                        This method provides a hook to allow finalization
+                        of a disk image (e.g. writing an MBR).
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis><filename>do_stage_partition()</filename>:</emphasis>
+                        Special content-staging hook called before
+                        <filename>do_prepare_partition()</filename>.
+                        This method is normally empty.</para>
+
+                        <para>Typically, a partition just uses the passed-in
+                        parameters (e.g. the unmodified value of
+                        <filename>bootimg_dir</filename>).
+                        However, in some cases, things might need to be
+                        more tailored.
+                        As an example, certain files might additionally
+                        need to be taken from
+                        <filename>bootimg_dir + /boot</filename>.
+                        This hook allows those files to be staged in a
+                        customized fashion.
+                        <note>
+                            <filename>get_bitbake_var()</filename>
+                            allows you to access non-standard variables
+                            that you might want to use for this
+                            behavior.
+                        </note>
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                You can extend the source plug-in mechanism.
+                To add more hooks, create more source plug-in methods
+                within <filename>SourcePlugin</filename> and the
+                corresponding derived subclasses.
+                The code that calls the plug-in methods uses the
+                <filename>plugin.get_source_plugin_methods()</filename>
+                function to find the method or methods needed by the call.
+                Retrieval of those methods is accomplished by filling up
+                a dict with keys that contain the method names of interest.
+                On success, these will be filled in with the actual
+                methods.
+                See the Wic implementation for examples and details.
+            </para>
+        </section>
+
         <section id='wic-usage-examples'>
             <title>Examples</title>
 
diff --git a/documentation/ref-manual/ref-kickstart.xml b/documentation/ref-manual/ref-kickstart.xml
index 1dd36b242c..ab3d1b8ef1 100644
--- a/documentation/ref-manual/ref-kickstart.xml
+++ b/documentation/ref-manual/ref-kickstart.xml
@@ -107,8 +107,9 @@
                     The most common value for this option is "rootfs", but you
                     can use any value that maps to a valid source plug-in.
                     For information on the source plug-ins, see the
-                    "<link linkend='wic-plug-ins-interface'>Wic Plug-Ins Interface</link>"
-                    section.</para>
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</ulink>"
+                    section in the Yocto Project Development Tasks Manual.
+                    </para>
 
                     <para>If you use <filename>--source rootfs</filename>, Wic
                     creates a partition as large as needed and to fill it with
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 1ac020a5cf..5769cd619a 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -1255,213 +1255,6 @@
     </para>
 </section>
 
-<section id='wic-plug-ins-interface'>
-    <title>Wic Plug-Ins Interface</title>
-
-    <para>
-        You can extend and specialize Wic functionality by using
-        Wic plug-ins.
-        This section explains the Wic plug-in interface.
-        For information on using Wic in general, see the
-        "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
-        section in the Yocto Project Development Tasks Manual.
-        <note>
-            Wic plug-ins consist of "source" and "imager" plug-ins.
-            Imager plug-ins are beyond the scope of this section.
-        </note>
-    </para>
-
-    <para>
-        Source plug-ins provide a mechanism to customize partition
-        content during the Wic image generation process.
-        You can use source plug-ins to map values that you specify
-        using <filename>--source</filename> commands in kickstart
-        files (i.e. <filename>*.wks</filename>) to a plug-in
-        implementation used to populate a given partition.
-        <note>
-            If you use plug-ins that have build-time dependencies
-            (e.g. native tools, bootloaders, and so forth)
-            when building a Wic image, you need to specify those
-            dependencies using the
-            <link linkend='var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></link>
-            variable.
-        </note>
-    </para>
-
-    <para>
-        Source plug-ins are subclasses defined in plug-in files.
-        As shipped, the Yocto Project provides several plug-in
-        files.
-        You can see the source plug-in files that ship with the
-        Yocto Project
-        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
-        Each of these plug-in files contain source plug-ins that
-        are designed to populate a specific Wic image partition.
-    </para>
-
-    <para>
-        Source plug-ins are subclasses of the
-        <filename>SourcePlugin</filename> class, which is
-        defined in the
-        <filename>poky/scripts/lib/wic/pluginbase.py</filename>
-        file.
-        For example, the <filename>BootimgEFIPlugin</filename>
-        source plug-in found in the
-        <filename>bootimg-efi.py</filename> file is a subclass of
-        the <filename>SourcePlugin</filename> class, which is found
-        in the <filename>pluginbase.py</filename> file.
-    </para>
-
-    <para>
-        You can also implement source plug-ins in a layer outside
-        of the Source Repositories (external layer).
-        To do so, be sure that your plug-in files are located in
-        a directory whose path is
-        <filename>scripts/lib/wic/plugins/source/</filename>
-        within your external layer.
-        When the plug-in files are located there, the source
-        plug-ins they contain are made available to Wic.
-    </para>
-
-    <para>
-        When the Wic implementation needs to invoke a
-        partition-specific implementation, it looks for the plug-in
-        with the same name as the <filename>--source</filename>
-        parameter used in the kickstart file given to that
-        partition.
-        For example, if the partition is set up using the following
-        command in a kickstart file:
-        <literallayout class='monospaced'>
-     part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
-        </literallayout>
-        The methods defined as class members of the matching
-        source plug-in (i.e. <filename>bootimg-pcbios</filename>)
-        in the <filename>bootimg-pcbios.py</filename> plug-in file
-        are used.
-    </para>
-
-    <para>
-        To be more concrete, here is the corresponding plug-in
-        definition from the <filename>bootimg-pcbios.py</filename>
-        file for the previous command along with an example
-        method called by the Wic implementation when it needs to
-        prepare a partition using an implementation-specific
-        function:
-        <literallayout class='monospaced'>
-     bootimg-pcbios.py
-                  .
-                  .
-                  .
-        class BootimgPcbiosPlugin(SourcePlugin):
-        """
-        Create MBR boot partition and install syslinux on it.
-        """
-
-        name = 'bootimg-pcbios'
-                  .
-                  .
-                  .
-        @classmethod
-        def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
-                                 oe_builddir, bootimg_dir, kernel_dir,
-                                 rootfs_dir, native_sysroot):
-            """
-            Called to do the actual content population for a partition i.e. it
-            'prepares' the partition to be incorporated into the image.
-            In this case, prepare content for legacy bios boot partition.
-            """
-                  .
-                  .
-                  .
-        </literallayout>
-        If a subclass (plug-in) itself does not implement a
-        particular function, Wic locates and uses the default
-        version in the superclass.
-        It is for this reason that all source plug-ins are derived
-        from the <filename>SourcePlugin</filename> class.
-    </para>
-
-    <para>
-        The <filename>SourcePlugin</filename> class defined in
-        the <filename>pluginbase.py</filename> file defines
-        a set of methods that source plug-ins can implement or
-        override.
-        Any plug-ins (subclass of
-        <filename>SourcePlugin</filename>) that do not implement
-        a particular method inherit the implementation of the
-        method from the <filename>SourcePlugin</filename> class.
-        For more information, see the
-        <filename>SourcePlugin</filename> class in the
-        <filename>pluginbase.py</filename> file for details:
-    </para>
-
-    <para>
-        The following list describes the methods implemented in the
-        <filename>SourcePlugin</filename> class:
-        <itemizedlist>
-            <listitem><para>
-                <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
-                Called to populate a partition with actual content.
-                In other words, the method prepares the final
-                partition image that is incorporated into the
-                disk image.
-                </para></listitem>
-            <listitem><para>
-                <emphasis><filename>do_configure_partition()</filename>:</emphasis>
-                Called before
-                <filename>do_prepare_partition()</filename> to
-                create custom configuration files for a partition
-                (e.g. syslinux or grub configuration files).
-                </para></listitem>
-            <listitem><para>
-                <emphasis><filename>do_install_disk()</filename>:</emphasis>
-                Called after all partitions have been prepared and
-                assembled into a disk image.
-                This method provides a hook to allow finalization
-                of a disk image (e.g. writing an MBR).
-                </para></listitem>
-            <listitem><para>
-                <emphasis><filename>do_stage_partition()</filename>:</emphasis>
-                Special content-staging hook called before
-                <filename>do_prepare_partition()</filename>.
-                This method is normally empty.</para>
-
-                <para>Typically, a partition just uses the passed-in
-                parameters (e.g. the unmodified value of
-                <filename>bootimg_dir</filename>).
-                However, in some cases, things might need to be
-                more tailored.
-                As an example, certain files might additionally
-                need to be taken from
-                <filename>bootimg_dir + /boot</filename>.
-                This hook allows those files to be staged in a
-                customized fashion.
-                <note>
-                    <filename>get_bitbake_var()</filename>
-                    allows you to access non-standard variables
-                    that you might want to use for this
-                    behavior.
-                </note>
-                </para></listitem>
-        </itemizedlist>
-    </para>
-
-    <para>
-        You can extend the source plug-in mechanism.
-        To add more hooks, create more source plug-in methods
-        within <filename>SourcePlugin</filename> and the
-        corresponding derived subclasses.
-        The code that calls the plug-in methods uses the
-        <filename>plugin.get_source_plugin_methods()</filename>
-        function to find the method or methods needed by the call.
-        Retrieval of those methods is accomplished by filling up
-        a dict with keys that contain the method names of interest.
-        On success, these will be filled in with the actual
-        methods.
-        See the Wic implementation for examples and details.
-    </para>
-</section>
-
 <section id="wayland">
     <title>Wayland</title>