ref-manual: Updated 1.5 Migration section and COMPLEMENTARY_GLOB variable

Review edits from Paul Egglegon applied to the Migrating to
1.5 section.

Also, part of the review affected the COMPLEMENTARY_GLOB variable
entry in the glossary.

(From yocto-docs rev: 941a388f45c99403f5cb480bf3e5aae55a800994)

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

2 files changed, 138 insertions, 105 deletions

diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 9915c3ce02..4c7af582fa 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -599,7 +599,7 @@
                 <listitem><para>Python 2.7.3+</para></listitem>
                 <listitem><para>Tar 1.24+</para></listitem>
                 <listitem><para>Git 1.7.5+</para></listitem>
-                <listitem><para>Patched version of Make if you are using 
+                <listitem><para>Patched version of Make if you are using
                     3.82.
                     Most distributions that provide Make 3.82 use the patched
                     version.</para></listitem>
@@ -633,15 +633,46 @@
         </para>
     </section>
 
-    <section id='migration-1.5-remove-operator'>
-        <title>BitBake <filename>_remove</filename> Operator</title>
+    <section id='migration-1.5-bitbake'>
+        <title>BitBake</title>
 
         <para>
-            BitBake now supports a <filename>_remove</filename> operator.
-            The addition of this operator means you will have to rename any
-            items in recipe space (functions, variables) whose names currently
-            contain <filename>_remove_</filename> or end with
-            <filename>_remove</filename> to avoid unexpected behavior.
+            The following changes have been made that relate to BitBake:
+            <itemizedlist>
+                <listitem><para>
+                    BitBake now supports a <filename>_remove</filename>
+                    operator.
+                    The addition of this operator means you will have to
+                    rename any items in recipe space (functions, variables)
+                    whose names currently contain
+                    <filename>_remove_</filename> or end with
+                    <filename>_remove</filename> to avoid unexpected behavior.
+                    </para></listitem>
+                <listitem><para>
+                    BitBake's global method pool has been removed.
+                    This method not particularly useful and led to clashes
+                    between recipes containing functions that had the
+                    same name.</para></listitem>
+                <listitem><para>
+                    The "none" server backend has been removed.
+                    The "process" server backend has been serving well as the
+                    default for a long time now.</para></listitem>
+                <listitem><para>
+                    The <filename>bitbake-runtask</filename> script has been
+                    removed.</para></listitem>
+                <listitem><para>
+                    <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
+                    and
+                    <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
+                    are no longer added to
+                    <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
+                    by default.
+                    These version-specific <filename>PROVIDES</filename>
+                    items were seldom used.
+                    Attempting to use them could result in two versions being
+                    built simultaneously rather than just one version due to
+                    the way BitBake resolves dependencies.</para></listitem>
+            </itemizedlist>
         </para>
     </section>
 
@@ -684,7 +715,7 @@
                     other variables depending on how you wish it to be handled.
                     See the documented QA checks in the
                     "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
-                    section. 
+                    section.
                     </para></listitem>
             </itemizedlist>
         </para>
@@ -733,9 +764,9 @@
                     The <filename>pkgdata</filename> directory produced as
                     part of the packaging process has been collapsed into a
                     single machine-specific directory.
-                    These directories are located under 
-                    <filename>sysroots</filename> and use a machine-specific
-                    name (i.e. 
+                    This directory is located under
+                    <filename>sysroots</filename> and uses a machine-specific
+                    name (i.e.
                     <filename>tmp/sysroots/&lt;machine&gt;/pkgdata</filename>).
                     </para></listitem>
             </itemizedlist>
@@ -753,10 +784,8 @@
             This change should be safe within contexts where these revisions
             are used because the chances of spatially close collisions
             is very low.
-            <note>
-                Distant collisions are not a major issue in the way
-                the values are used.
-            </note>
+            Distant collisions are not a major issue in the way
+            the values are used.
         </para>
     </section>
 
@@ -764,9 +793,8 @@
         <title><filename>IMAGE_FEATURES</filename></title>
 
         <para>
-            These
-            <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
-            exist:
+            The following changes have been made that relate to
+            <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
             <itemizedlist>
                 <listitem><para>
                     The value of
@@ -783,10 +811,11 @@
                     <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
                     definitions,
                     <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
-                    and a new 'validitems' varflag on
+                    and a new "validitems" varflag on
                     <filename>IMAGE_FEATURES</filename>.
-                    This change allows additional features to be added if they
-                    are not provided using the previous two mechanisms.
+                    The "validitems" varflag change allows additional features
+                    to be added if they are not provided using the previous
+                    two mechanisms.
                     </para></listitem>
                 <listitem><para>
                     The previously deprecated "apps-console-core"
@@ -824,9 +853,9 @@
             This addition is now handled automatically when "package-management"
             is not in
             <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
-            If you have custom image recipes that makes this addition,
-            you should remove the lines, as it is not needed and may interfere
-            with correct operation of postinstall scripts.
+            If you have custom image recipes that make this addition,
+            you should remove the lines, as they are not needed and might
+            interfere with correct operation of postinstall scripts.
         </para>
     </section>
 
@@ -849,8 +878,8 @@
         <para>
             The previously deprecated <filename>task.bbclass</filename> has
             now been dropped.
-            You should remove recipes that previously inherited from this task
-            and rename from <filename>task-*</filename> to
+            For recipes that previously inherited from this task, you should
+            rename them from <filename>task-*</filename> to
             <filename>packagegroup-*</filename> and inherit packagegroup
             instead.
         </para>
@@ -930,52 +959,83 @@
                 </para></listitem>
             <listitem><para>
                 <filename>anjuta-remote-run</filename> has been removed.
-                Support for Anjuta IDE integration has not existed for some
+                Anjuta IDE integration has not been officially supported for
                 several releases.</para></listitem>
         </itemizedlist>
     </section>
 
-    <section id='migration-1.5-other-changes'>
-        <title>Other Changes</title>
+    <section id='migration-1.5-build-history'>
+        <title>Build History</title>
 
         <para>
-            Following is a list of short entries describing other changes:
+            Following are changes to Build History:
             <itemizedlist>
                 <listitem><para>
-                    BitBake: <filename>methodpool</filename>: Retire this.
-                    Remove global method scope.</para></listitem>
-                <listitem><para>
-                    BitBake: server: Remove none server.</para></listitem>
+                     Installed package sizes:
+                     <filename>installed-package-sizes.txt</filename> for an
+                     image now records the size of the files installed by each
+                     package instead of the size of each compressed package
+                     archive file.</para></listitem>
                 <listitem><para>
-                    BitBake: Drop <filename>bitbake-runtask</filename>.
+                    The dependency graphs (<filename>depends*.dot</filename>)
+                    now use the actual package names instead of replacing
+                    dashes, dots and plus signs with underscores.
                     </para></listitem>
                 <listitem><para>
-                    Do not recommend <filename>udev-extraconf</filename>
-                    for <filename>udev</filename>.</para></listitem>
-                <listitem><para>
-                    <filename>udev</filename>: Do not recommend
-                    <filename>pciutils/usbutils ids</filename>
+                    The <filename>buildhistory-diff</filename> and
+                    <filename>buildhistory-collect-srcrevs</filename>
+                    utilities have improved command-line handling.
+                    Use the <filename>&dash;&dash;help</filename> option for
+                    each utility for more information on the new syntax.
                     </para></listitem>
+            </itemizedlist>
+            For more information on Build History, see the
+            "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
+            section.
+        </para>
+    </section>
+
+    <section id='migration-1.5-udev'>
+        <title><filename>udev</filename></title>
+
+        <para>
+            Following are changes to <filename>udev</filename>:
+            <itemizedlist>
                 <listitem><para>
-                    <filename>run-postinsts</filename>: Make this generic.
+                    <filename>udev</filename> no longer brings in
+                    <filename>udev-extraconf</filename> automatically
+                    through
+                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
+                    since this was originally intended to be optional.
+                    If you need the extra rules, then add
+                    <filename>udev-extraconf</filename> to your image.
                     </para></listitem>
                 <listitem><para>
-                    <filename>classes/externalsrc</filename>: Enable global
-                    inherit and simplify usage.</para></listitem>
+                    <filename>udev</filename> no longer brings in
+                    <filename>pciutils-ids</filename> or
+                    <filename>usbutils-ids</filename> through
+                    <filename>RRECOMMENDS</filename>.
+                    These are not needed by <filename>udev</filename> itself
+                    and removing them saves around 350KB.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.5-other-changes'>
+        <title>Other Changes</title>
+
+        <para>
+            Following is a list of short entries describing other changes:
+            <itemizedlist>
                 <listitem><para>
-                    BusyBox: Enable to list suid and non-suid app configs.
+                    <filename>run-postinsts</filename>: Make this generic.
                     </para></listitem>
                 <listitem><para>
                     <filename>base-files</filename>: Remove the unnecessary
                     <filename>/media/xxx</filename> directories.
                     </para></listitem>
                 <listitem><para>
-                    <filename>classes/testimage.bbclass</filename>: New class
-                    for image tests.
-                    See the
-                    "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
-                    section for more information.</para></listitem>
-                <listitem><para>
                     <filename>alsa-state</filename>: Provide an empty
                     <filename>asound.conf</filename> by default.
                     </para></listitem>
@@ -990,7 +1050,8 @@
                 <listitem><para>
                     <filename>systemd</filename>: Remove
                     <filename>systemd_unitdir</filename> if
-                    <filename>systemd</filename> is not in distro features.
+                    <filename>systemd</filename> is not in
+                    <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
                     </para></listitem>
                 <listitem><para>
                     <filename>systemd</filename>: Remove
@@ -1003,10 +1064,6 @@
                     <filename>OTHER</filename> entries.
                     </para></listitem>
                 <listitem><para>
-                    Add <filename>libav</filename> and use it in
-                    <filename>gst-ffmpeg</filename> by default.
-                    </para></listitem>
-                <listitem><para>
                     <filename>image.bbclass</filename>: Move
                     <filename>runtime_mapping_rename</filename> to avoid
                     conflict with <filename>multilib</filename>.
@@ -1019,33 +1076,9 @@
                     to generate the <filename>dtb</filename> files.
                     </para></listitem>
                 <listitem><para>
-                    <filename>classes/buildhistory</filename>: Record the
-                    size of the installed package not the compressed archive.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>classes/buildhistory</filename>: Avoid mangling
-                    names in dot graphs for images.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>buildhistory-diff/buildhistory-collect-srcrevs</filename>:
-                    Improved command-line handling.
-                    </para></listitem>
-                <listitem><para>
                     <filename>kern-tools</filename>: Switch from guilt to
                     new <filename>kgit-s2q</filename> tool.
                     </para></listitem>
-                <listitem><para>
-                    <filename>poky.conf</filename>: Do not force the addition
-                    of extra
-                    <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>bitbake.conf</filename>: Stop providing
-                    <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
-                    and
-                    <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
-                    by default.
-                    </para></listitem>
             </itemizedlist>
         </para>
     </section>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index cf964c78a7..8133b9d14b 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -822,15 +822,15 @@ Core layer for images cannot be removed
         <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
             <glossdef>
                 <para>
-                    For the BusyBox recipe, specifies whether to split the 
-                    output executable file into two parts: one for features 
-                    that require <filename>setuid root</filename>, and one for 
+                    For the BusyBox recipe, specifies whether to split the
+                    output executable file into two parts: one for features
+                    that require <filename>setuid root</filename>, and one for
                     the remaining features (i.e. those that do not require
-                    <filename>setuid root</filename>). 
+                    <filename>setuid root</filename>).
                 </para>
 
                 <para>
-                    The <filename>BUSYBOX_SPLIT_SUID</filename> variable 
+                    The <filename>BUSYBOX_SPLIT_SUID</filename> variable
                     defaults to "1", which results in a single output
                     executable file.
                     Set the variable to "0" to split the output file.
@@ -907,21 +907,21 @@ Core layer for images cannot be removed
         <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
             <glossdef>
                 <para>
-                    Defines wildcards you can use when installing a list of 
-                    complementary packages for all the packages explicitly 
+                    Defines wildcards to match when installing a list of
+                    complementary packages for all the packages explicitly
                     (or implicitly) installed in an image.
-                    The resulting list of complementary packages is associated 
-                    with an item that can be added to  
+                    The resulting list of complementary packages is associated
+                    with an item that can be added to
                     <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
-                    An example usage of this is the "dev-pkgs" item that when 
+                    An example usage of this is the "dev-pkgs" item that when
                     added to <filename>IMAGE_FEATURES</filename> will
-                    install -dev packages (containing headers and other 
+                    install -dev packages (containing headers and other
                     development files) for every package in the image.
                 </para>
 
                 <para>
-                    To add a new feature item pointing to a wildcard, use a 
-                    variable flag to specify the feature item name and 
+                    To add a new feature item pointing to a wildcard, use a
+                    variable flag to specify the feature item name and
                     use the value to specify the wildcard.
                     Here is an example:
                     <literallayout class='monospaced'>
@@ -1911,8 +1911,8 @@ Core layer for images cannot be removed
         <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
             <glossdef>
                 <para>
-                    The base name of image output files. 
-                    This variable defaults to the recipe name 
+                    The base name of image output files.
+                    This variable defaults to the recipe name
                     (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
                 </para>
             </glossdef>
@@ -3705,8 +3705,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
         <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
             <glossdef>
                 <para>
-                    Defines one or more packages to include in an image when 
-                    a specific item is included in 
+                    Defines one or more packages to include in an image when
+                    a specific item is included in
                     <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
                     When setting the value, <filename>PACKAGE_GROUP</filename>
                     should have the name of the feature item as an override.
@@ -3714,15 +3714,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     <literallayout class='monospaced'>
      PACKAGE_GROUP_widget = "package1 package2"
                     </literallayout>
-                    In this example, if "widget" were added to 
+                    In this example, if "widget" were added to
                     <filename>IMAGE_FEATURES</filename>, "package1" and
                     "package2" would be included in the image.
                     <note>
-                        Packages installed by features defined through 
-                        <filename>PACKAGE_GROUP</filename> are often package 
+                        Packages installed by features defined through
+                        <filename>PACKAGE_GROUP</filename> are often package
                         groups.
-                        While similarly named, you should not confuse the 
-                        <filename>PACKAGE_GROUP</filename> variable with 
+                        While similarly named, you should not confuse the
+                        <filename>PACKAGE_GROUP</filename> variable with
                         package groups, which are discussed elsewhere in the
                         documentation.
                     </note>
@@ -4680,7 +4680,7 @@ PARALLEL_MAKEINST with the description ".
         <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
             <glossdef>
                 <para>
-                    The target architecture for the SDK. 
+                    The target architecture for the SDK.
                     Typically, you do not directly set this variable.
                     Instead, use
                     <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
@@ -5623,8 +5623,8 @@ PARALLEL_MAKEINST with the description ".
         <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
             <glossdef>
                 <para>
-                    The package architecture understood by the packaging 
-                    system to define the architecture, ABI, and tuning of 
+                    The package architecture understood by the packaging
+                    system to define the architecture, ABI, and tuning of
                     output packages.
                 </para>
             </glossdef>