ref-manual, dev-manual: Applied migration review edits.

Applied the full set of first draft revision edits for the
new migration section for 1.7.  Comments from Paul Eggleton.

(From yocto-docs rev: 90586addbc719ecaf7c768b267adf0e988e27b74)

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

4 files changed, 73 insertions, 119 deletions

diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 864c489251..dd8c3e00cc 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1710,17 +1710,19 @@
             class changes occurred:
             <itemizedlist>
                 <listitem><para><emphasis>
-                    A separate build directory in Autotools recipes is
-                    handled:</emphasis>
+                    A separate build directory is now used by default:</emphasis>
                     The <filename>autotools</filename> class has been changed
                     to use a directory for building
                     (<link linkend='var-B'><filename>B</filename></link>),
                     which is separate from the source directory
                     (<link linkend='var-S'><filename>S</filename></link>).
-                    If the software being built is already capable of
+                    This is commonly referred to as
+                    <filename>B != S</filename>, or an out-of-tree build.</para>
+                    <para>If the software being built is already capable of
                     building in a directory separate from the source, you
                     do not need to do anything.
-                    However, if this capability does not exist, you will
+                    However, if the software is not capable of being built
+                    in this manner, you will
                     need to either patch the software so that it can build
                     separately, or you will need to change the recipe to
                     inherit the
@@ -1728,25 +1730,24 @@
                     class instead of the <filename>autotools</filename> class.
                     </para></listitem>
                 <listitem><para><emphasis>
-                    Handle "foreign":</emphasis>
-                    The <filename>--foreign</filename> option is no longer
-                    passed to <filename>automake</filename> when running
-                    <filename>autoreconf</filename>.
+                    The <filename>&dash;&dash;foreign</filename> option is
+                    no longer passed to <filename>automake</filename> when
+                    running <filename>autoconf</filename>:</emphasis>
                     This option tells <filename>automake</filename> that a
                     particular software package does not follow the GNU
                     standards and therefore should not be expected
                     to distribute certain files such as
                     <filename>ChangeLog</filename>,
                     <filename>AUTHORS</filename>, and so forth.
-                    The majority of upstream software packages already tell
-                    <filename>automake</filename> these packages are foreign
-                    and thus this option is mostly superfluous.
+                    Because the majority of upstream software packages already
+                    tell <filename>automake</filename> to enable foreign mode
+                    themselves, the option is mostly superfluous.
                     However, some recipes will need patches for this change.
                     You can easily make the change by patching
                     <filename>configure.ac</filename> so that it passes
                     "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>.
                     See
-                    <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'></ulink>
+                    <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink>
                     for an example showing how to make the patch.
                     </para></listitem>
             </itemizedlist>
@@ -1757,12 +1758,12 @@
         <title>Binary Configuration Scripts Disabled</title>
 
         <para>
-            Some of the core recipes that previously packaged binary
-            configuration scripts now disable the scripts instead due to the
+            Some of the core recipes that package binary configuration scripts
+            now disable the scripts instead due to the
             scripts previously requiring error-prone path substitution.
             Software that links against these libraries using these scripts
-            should use the much more robust
-            <filename>pkg-config</filename> instead.
+            should use the much more robust <filename>pkg-config</filename>
+            instead.
             The list of recipes changed in this version (and their
             configuration scripts) is as follows:
             <literallayout class='monospaced'>
@@ -1787,12 +1788,10 @@
      pth (pth-config)
      taglib (taglib-config)
             </literallayout>
-            <note>
-                Support for <filename>pkg-config</filename> has been added to
-                some recipes in the previous list in the rare cases
-                where the upstream software package does not already provide
-                it.
-            </note>
+            Additionally, support for <filename>pkg-config</filename> has been
+            added to some recipes in the previous list in the rare cases
+            where the upstream software package does not already provide
+            it.
         </para>
     </section>
 
@@ -1811,15 +1810,15 @@
         </para>
 
         <para>
-            <filename>glibc 2.20</filename> also minimally requires version
-            2.6.32 of the Linux kernel.
+            <filename>glibc 2.20</filename> requires version 2.6.32 or greater
+            of the Linux kernel.
             Thus, older kernels will no longer be usable in conjunction with it.
         </para>
 
         <para>
             For full details on the changes in <filename>glibc 2.20</filename>,
-            see the upstream release notes at
-            <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'></ulink>.
+            see the upstream release notes
+            <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>.
         </para>
     </section>
 
@@ -1829,33 +1828,25 @@
         <para>
             The
             <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link>
-            and
-            <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
-            variables have been replaced with the variables
+            variable is now deprecated and a new
             <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
-            and
-            <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>,
-            respectively.
-            These variables no longer require you to specify the module name
+            variable should be used instead.
+            Also,
+            <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
+            must now be used in conjunction with a new
+            <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
+            variable.
+            The new variables no longer require you to specify the module name
             as part of the variable name.
             This change not only simplifies usage but also allows the values
             of these variables to be appropriately incorporated into task
             signatures and thus trigger the appropriate tasks to re-execute
             when changed.
             You should replace any references to
-            <filename>module_autoload_*</filename> or
-            <filename>module_conf_*</filename> with the new variables.
-            <note>
-                While it is recommended that you replace occurrences of the
-                <filename>module_conf_*</filename> variable with the
-                <filename>KERNEL_MODULE_PROBECONF</filename> variable, the
-                OpenEmbedded build system still recognizes the
-                <filename>module_conf_*</filename> variable.
-                However, you must be sure that any module name used in the
-                override with the <filename>module_conf</filename> variable
-                is included in the <filename>KERNEL_MODULE_PROBECONF</filename>
-                variable.
-            </note>
+            <filename>module_autoload_*</filename> with
+            <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules
+            for which <filename>module_conf_*</filename> is specified to
+            <filename>KERNEL_MODULE_PROBECONF</filename>.
         </para>
 
         <para>
@@ -1863,7 +1854,7 @@
             <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
             and
             <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
-            descriptions in the variable's glossary.
+            variables.
         </para>
     </section>
 
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 3e7662e146..1b01ef61c9 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -102,6 +102,17 @@
     </para>
 
     <para>
+        By default, the <filename>autotools</filename> class supports
+        out-of-tree builds
+        (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
+        <link linkend='var-S'><filename>S</filename></link>).
+        If your recipes do not support out-of-tree builds, you should
+        have them inherit the
+        <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
+        class.
+    </para>
+
+    <para>
         It's useful to have some idea of how the tasks defined by this class work
         and what they do behind the scenes.
         <itemizedlist>
@@ -123,17 +134,6 @@
                 </para></listitem>
         </itemizedlist>
     </para>
-
-    <note>
-        It is planned for future Yocto Project releases that by default, the
-        <filename>autotools</filename> class supports out-of-tree builds
-        (<link linkend='var-B'><filename>B</filename></link> !=
-        <link linkend='var-S'><filename>S</filename></link>).
-        If your recipes do not support out-of-tree builds, you should
-        have them inherit the
-        <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
-        class.
-    </note>
 </section>
 
 <section id='ref-classes-autotools-brokensep'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 1cff5bdfaa..aadae01ac4 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -4458,7 +4458,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     Specify it as follows:
                     <literallayout class='monospaced'>
-     KERNEL_MODULE_AUTOLOAD = "modname1 modname2 modname3"
+     KERNEL_MODULE_AUTOLOAD += "modname1 modname2 modname3"
                     </literallayout>
                 </para>
 
@@ -4470,7 +4470,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     The modules appear one-per-line in the file.
                     Here is an example of the most common use case:
                     <literallayout class='monospaced'>
-     KERNEL_MODULE_AUTOLOAD = "modname"
+     KERNEL_MODULE_AUTOLOAD += "modname"
                     </literallayout>
                 </para>
 
@@ -4487,58 +4487,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
         <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
             <glossdef>
                 <para>
-                    Specifies
-                    <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
-                    syntax lines for inclusion in the
-                    <filename>/etc/modprobe.d/modname.conf</filename> file.
-                    <note>
-                        The <filename>KERNEL_MODULE_PROBECONF</filename>
-                        variable behaves the same as the
-                        <link linkend='var-module_conf'><filename>module_conf</filename></link>
-                        variable with the exception of not having to use a
-                        module name override.
-                    </note>
-                </para>
-
-                <para>
-                    You can use the
-                    <filename>KERNEL_MODULE_PROBECONF</filename> variable
-                    anywhere it can be recognized by the kernel recipe or
-                    an out-of-tree kernel module recipe (e.g. a machine
-                    configuration file, a distribution configuration file, an
-                    append file for the recipe, or the recipe itself).
-                </para>
-
-                <para>
-                    Here is the general syntax:
-                    <literallayout class='monospaced'>
-     KERNEL_MODULE_PROBECONF = "&lt;modprobe.d syntax&gt;"
-                    </literallayout>
-                </para>
-
-                <para>
-                    Run <filename>man modprobe.d</filename> in the shell to
-                    find out more information on the exact syntax
-                    you want to provide with <filename>KERNEL_MODULE_PROBECONF</filename>.
-                </para>
-
-                <para>
-                    Including <filename>KERNEL_MODULE_PROBECONF</filename> causes
-                    the OpenEmbedded build system to populate the
-                    <filename>/etc/modprobe.d/modname.conf</filename>
-                    file with <filename>modprobe.d</filename> syntax lines.
-                    Here is an example that adds the options
-                    <filename>arg1</filename> and <filename>arg2</filename>
-                    to a module named <filename>mymodule</filename>:
-                    <literallayout class='monospaced'>
-     KERNEL_MODULE_PROBECONF = "options mymodule arg1=val1 arg2=val2"
-                    </literallayout>
-                </para>
-
-                <para>
-                    For information on how to specify kernel modules to
-                    auto-load on boot, see the
-                    <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
+                    Provides a list of modules for which the OpenEmbedded
+                    build system expects to find
+                    <link linkend='var-module_conf'><filename>module_conf_&lt;modname&gt;</filename></link>
+                    values that specify configuration for each of the modules.
+                    For information on how to provide those module
+                    configurations, see the
+                    <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
+                    variable.
                 </para>
             </glossdef>
         </glossentry>
@@ -5410,12 +5366,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable has been replaced by the
                     <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
-                    You should replace all occurrences of the
-                    <filename>module_autoload</filename> variable with
-                    <filename>KERNEL_MODULE_AUTOLOAD</filename> variables.
+                    You should replace all occurrences of
+                    <filename>module_autoload</filename> with additions to
+                    <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
+                    <literallayout class='monospaced'>
+     module_autoload_rfcomm = "rfcomm"
+                    </literallayout>
+                    should now be replaced with:
+                    <literallayout class='monospaced'>
+     KERNEL_MODULE_AUTOLOAD += "rfcomm"
+                    </literallayout>
                     See the
                     <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
-                    variable for a description of the variable.
+                    variable for more information.
                 </para>
             </glossdef>
         </glossentry>
@@ -5437,7 +5400,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     recipe, or the recipe itself).
                     If you use this variable, you must also be sure to list
                     the module name in the
-                    <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
+                    <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
                     variable.
                 </para>
 
@@ -5471,7 +5434,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     For information on how to specify kernel modules to
                     auto-load on boot, see the
-                    <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
+                    <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
                     variable.
                 </para>
             </glossdef>
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 5a6a4068a7..283fb725ac 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -540,7 +540,7 @@
 
         <para>
             Build history information is kept in
-            <filename>$</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>/buildhistory</filename>
+            <filename>${</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>}/buildhistory</filename>
             in the Build Directory as defined by the
             <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link>
             variable.