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>

3 files changed, 190 insertions, 99 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index bc78a08adc..fe34e8ecd8 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3609,10 +3609,9 @@
             <title>Setting Up Runtime Package Management</title>
 
             <para>
-                For RPM, IPK, and DEB package formats, it is possible to set
-                up a repository that is a host-based
-                package feed from which you can install packages on the
-                target system during runtime.
+                For supported package formats, it is possible to set
+                up a repository that is a host-based package feed from which
+                you can install packages on the target system during runtime.
                 Doing so is optional and depends on the following:
                 <itemizedlist>
                     <listitem><para>
@@ -3637,23 +3636,30 @@
                 </itemizedlist>
             </para>
 
-            <section id='runtime-package-management-deb-rpm'>
-                <title>Using DEB and RPM</title>
-
-                <para>
-                    Following are the steps to set up the optional repository.
-                    This example assumes you are using RPM and the Apache 2
-                    server:
-                    <orderedlist>
-                        <listitem><para>
-                            Add the directory to your Apache configuration, which
-                            you can find at
-                            <filename>/etc/httpd/conf/httpd.conf</filename>.
-                            Use commands similar to these on the development system.
-                            These example commands assume a top-level
-                            <link linkend='source-directory'>Source Directory</link>
-                            named <filename>poky</filename> in your home directory:
-                            <literallayout class='monospaced'>
+            <para>
+                The following list provides steps for setting up the optional 
+                repository regardless of the package format.
+                Once you work through these generic steps, see the 
+                "<link linkend='runtime-package-management-deb-rpm'>Using RPM</link>"
+                section or the  
+                "<link linkend='runtime-package-management-ipk'>Using IPK</link>"
+                section for remaining steps specific to the package type.
+                <note>
+                    The example assumes you are using the Apache 2 server:
+                </note>
+                <orderedlist>
+                    <listitem><para>
+                        Add the directory to your Apache configuration, which
+                        you can find at
+                        <filename>/etc/httpd/conf/httpd.conf</filename>.
+                        Use commands similar to these on the development system.
+                        These example commands assume a top-level
+                        <link linkend='source-directory'>Source Directory</link>
+                        named <filename>poky</filename> in your home directory.
+                        The example also assumes an RPM package type. 
+                        If you are using a different package type, such as 
+                        IPK, use "ipk" in the pathnames:
+                        <literallayout class='monospaced'>
      &lt;VirtualHost *:80&gt;
        ....
          Alias /rpm ~/poky/build/tmp/deploy/rpm
@@ -3661,53 +3667,62 @@
            Options +Indexes
          &lt;/Directory&gt;
      &lt;/VirtualHost&gt;
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            Reload the Apache configuration as follows.
-                            For all commands, be sure you have root privileges.
-                            </para>
-                            <para>
-                            If your development system is using Fedora or
-                            CentOS, use the following:
-                            <literallayout class='monospaced'>
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        Reload the Apache configuration as follows.
+                        For all commands, be sure you have root privileges.
+                        </para>
+                        <para>
+                        If your development system is using Fedora or
+                        CentOS, use the following:
+                        <literallayout class='monospaced'>
      service httpd reload
-                            </literallayout>
-                            For Ubuntu and Debian, use the following:
-                            <literallayout class='monospaced'>
+                        </literallayout>
+                        For Ubuntu and Debian, use the following:
+                        <literallayout class='monospaced'>
      /etc/init.d/apache2 reload
-                            </literallayout>
-                            For OpenSUSE, use the following:
-                            <literallayout class='monospaced'>
+                        </literallayout>
+                        For OpenSUSE, use the following:
+                        <literallayout class='monospaced'>
      /etc/init.d/apache2 reload
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            Run BitBake on <filename>package-index</filename>
-                            on the host
-                            <literallayout class='monospaced'>
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        Re-generate the package index:
+                        <literallayout class='monospaced'>
      bitbake package-index
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            Change your working directory to
-                            <filename>tmp/deploy/rpm</filename> in the
-                            <link linkend='build-directory'>Build Directory</link>.
-                            </para></listitem>
-                        <listitem><para>
-                            If you are using Security-Enhanced Linux (SELinux),
-                            you need to label the files as being accessible
-                            through Apache.
-                            Use the following command from the development host:
-                            <literallayout class='monospaced'>
-     chcon -R -h -t httpd_sys_content_t .
-                            </literallayout>
-                            </para></listitem>
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        If you are using Security-Enhanced Linux (SELinux),
+                        you need to label the files as being accessible
+                        through Apache.
+                        Use the following command from the development host.
+                        Again, the example assumes RPM package types:
+                        <literallayout class='monospaced'>
+     chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
+                        </literallayout>
+                        </para></listitem>
+                </orderedlist>
+            </para>
+
+            <section id='runtime-package-management-deb-rpm'>
+                <title>Using RPM</title>
+
+                <para>
+                    Following are RPM-specific steps needed for setting up the 
+                    optional repository.
+                    Perform these steps after working through the common steps
+                    at the start of this section:
+                    <orderedlist>
                         <listitem><para>
                             On the target machine, add the repository to Smart 
                             for every package architecture.
-                            To see the list of package architectures, just list 
-                            the contents of the directory.</para>
+                            To see the list of package architectures, list 
+                            the contents of the 
+                          setting-up-runtime-package-management  <filename>tmp/deploy/rpm</filename> directory
+                            on the host.</para>
                             <para>
                             As an example, suppose you list the contents of the 
                             directory and discover three architectures:
@@ -3715,7 +3730,7 @@
                             and <filename>qemux86</filename>.
                             Given this example, use the following commands:
                             <literallayout class='monospaced'>
-     smart channel &dash;&dash;add all type=rpm-md baseurl=http:server.name/rpm/all
+     smart channel &dash;&dash;add all type=rpm-md baseurl=http://server.name/rpm/all
      smart channel &dash;&dash;add i585 type=rpm-md baseurl=http://server.name/rpm/i586
      smart channel &dash;&dash;add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
                             </literallayout>
@@ -3728,6 +3743,9 @@
                             </literallayout>
                             </para></listitem>
                     </orderedlist>
+                    You can now use the <filename>smart query</filename>
+                    and <filename>smart install</filename> commands to find 
+                    and install packages from the repositories.
                 </para>
             </section>
 
@@ -3735,18 +3753,32 @@
                 <title>Using IPK</title>
 
                 <para>
-                    If your packages are IPK, you can install packages onto an
-                    existing running system by first sharing the
-                    <filename>tmp/deploy/ipk/</filename> directory
-                    through a web server and then by changing
-                    <filename>/etc/opkg/base-feeds.conf</filename>
-                    to point at the shared server.
-                    Following is an example:
-                    <literallayout class='monospaced'>
-     $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
-     $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
-     $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
-                    </literallayout>
+                    Following are IPK-specific steps needed for setting up the 
+                    optional repository.
+                    Perform these steps after working through the common steps
+                    at the start of this section:
+                    <orderedlist>
+                        <listitem><para>Install packages onto an
+                            existing running system by first sharing the
+                            <filename>tmp/deploy/ipk/</filename> directory
+                            through a web server and then by changing
+                            <filename>/etc/opkg/base-feeds.conf</filename>
+                            to point at the shared server.
+                            Following is an example:
+                            <literallayout class='monospaced'>
+     src/gz all http://www.mysite.com/somedir/deploy/ipk/all
+     src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
+     src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
+                            </literallayout></para></listitem>
+                        <listitem><para>From the target machine, fetch the
+                            repository information using this command:
+                            <literallayout class='monospaced'>
+     opkg update
+                            </literallayout></para></listitem>
+                    </orderedlist>
+                    You can now use the <filename>opkg list</filename> and 
+                    <filename>opkg install</filename> commands to find and 
+                    install packages from the repositories.
                 </para>
             </section>
         </section>
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>