dev-manual, ref-manual: Review edits for new variables.

Applied review changes to the following variables:

IMAGE_NAME
DATETIME
SDK_ARCH
IMAGE_BASENAME
TUNE_PKGARCH
PACKAGE_GROUP
COMPLEMENTARY_GLOB
BUSYBOX_SPLIT_SUID

Also, reformatted some 1.5 package version requirements into a
list rather than a lazy literallayout tag.

Provided some new wording for the "Directory Layout Changes"
section in the Migration chapter.

(From yocto-docs rev: 60c3a905dd9212f1b4f6969341640a0726342d11)

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

2 files changed, 84 insertions, 25 deletions

diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 1b3b9d99dc..9915c3ce02 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -595,16 +595,15 @@
         <para>
             The OpenEmbedded build system now has some additional requirements
             on the host system:
-            <literallayout class='monospaced'>
-     Python 2.7.3+
-
-     tar 1.24+
-
-     git 1.7.5+
-
-     Patched version of make if you are using make version 3.82.  Most
-        distributions that provide make 3.82 have now done this.
-            </literallayout>
+            <itemizedlist>
+                <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 
+                    3.82.
+                    Most distributions that provide Make 3.82 use the patched
+                    version.</para></listitem>
+            </itemizedlist>
             If the Linux distribution you are using on your build host
             does not provide packages for these, you can install and use
             the Buildtools tarball, which provides an SDK-like environment
@@ -733,7 +732,12 @@
                 <listitem><para>
                     The <filename>pkgdata</filename> directory produced as
                     part of the packaging process has been collapsed into a
-                    single machine-specific directory.</para></listitem>
+                    single machine-specific directory.
+                    These directories are located under 
+                    <filename>sysroots</filename> and use a machine-specific
+                    name (i.e. 
+                    <filename>tmp/sysroots/&lt;machine&gt;/pkgdata</filename>).
+                    </para></listitem>
             </itemizedlist>
         </para>
     </section>
@@ -778,7 +782,7 @@
                     Valid <filename>IMAGE_FEATURES</filename> are drawn from
                     <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
                     definitions,
-                    <link linkend='var-COMPLEMENTARY_GLOBS'><filename>COMPLEMENTARY_GLOBS</filename></link>
+                    <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
                     and a new 'validitems' varflag on
                     <filename>IMAGE_FEATURES</filename>.
                     This change allows additional features to be added if they
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index c1e2013f42..cf964c78a7 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -822,7 +822,18 @@ Core layer for images cannot be removed
         <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
             <glossdef>
                 <para>
-                    Need description.
+                    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>). 
+                </para>
+
+                <para>
+                    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.
                 </para>
             </glossdef>
         </glossentry>
@@ -893,10 +904,29 @@ Core layer for images cannot be removed
             </glossdef>
         </glossentry>
 
-        <glossentry id='var-COMPLEMENTARY_GLOBS'><glossterm>COMPLEMENTARY_GLOBS</glossterm>
+        <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
             <glossdef>
                 <para>
-                    Need description.
+                    Defines wildcards you can use 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  
+                    <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
+                    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 
+                    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 
+                    use the value to specify the wildcard.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
+                    </literallayout>
                 </para>
             </glossdef>
         </glossentry>
@@ -1013,10 +1043,8 @@ Core layer for images cannot be removed
         <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
             <glossdef>
                 <para>
-                    The date and time on which the build started:
-                    <literallayout class='monospaced'>
-     date/time
-                    </literallayout>
+                    The date and time on which the current build started.
+                    The format is suitable for timestamps.
                 </para>
             </glossdef>
         </glossentry>
@@ -1883,7 +1911,9 @@ Core layer for images cannot be removed
         <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
             <glossdef>
                 <para>
-                    Need description.
+                    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>
         </glossentry>
@@ -2032,8 +2062,8 @@ Core layer for images cannot be removed
                 <para>
                     The name of the output image files minus the extension.
                     This variable is derived using the
-                    <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>
-                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
+                    <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
+                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
                     and
                     <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
                     variables:
@@ -3675,7 +3705,27 @@ 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>
-                    Need description.
+                    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.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     PACKAGE_GROUP_widget = "package1 package2"
+                    </literallayout>
+                    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 
+                        groups.
+                        While similarly named, you should not confuse the 
+                        <filename>PACKAGE_GROUP</filename> variable with 
+                        package groups, which are discussed elsewhere in the
+                        documentation.
+                    </note>
                 </para>
             </glossdef>
         </glossentry>
@@ -4630,7 +4680,10 @@ PARALLEL_MAKEINST with the description ".
         <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
             <glossdef>
                 <para>
-                    Need description.
+                    The target architecture for the SDK. 
+                    Typically, you do not directly set this variable.
+                    Instead, use
+                    <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
                 </para>
             </glossdef>
         </glossentry>
@@ -5570,7 +5623,9 @@ PARALLEL_MAKEINST with the description ".
         <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
             <glossdef>
                 <para>
-                    Need description.
+                    The package architecture understood by the packaging 
+                    system to define the architecture, ABI, and tuning of 
+                    output packages.
                 </para>
             </glossdef>
         </glossentry>