ref-manual: Review comments applied for patch session

Paul Eggleton provided quite a series of patches that I previously
applied.  These changes represent the edits from an interactive
review he conducted with me.  The series of changes represents
his review for the entire set of changes in the original patch
series.

(From yocto-docs rev: e26f615a01de2b101e97eb6fd7175b813f74295e)

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

documentation/ref-manual/migration.xml

@@ -351,15 +351,34 @@
         <title>Variables</title>
 
         <para>
-            The <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
+            The following variables have changed:
-            variable now uses a
+            <itemizedlist>
-            distribution ID, which is composed of the host distributor ID 
+                <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
-            followed by the release.
+                    This variable now uses a distribution ID, which is composed 
-            Previously, it was composed of the description field.
+                    of the host distributor ID followed by the release.
-            For example, "Ubuntu 12.10" becomes "Ubuntu-12.10". 
+                    Previously, 
-            You do not need to worry about this change if you are not 
+                    <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
-            specifically setting this variable, or if you are
+                    was composed of the description field.
-            specifically setting it to "".
+                    For example, "Ubuntu 12.10" becomes "Ubuntu-12.10". 
+                    You do not need to worry about this change if you are not 
+                    specifically setting this variable, or if you are
+                    specifically setting it to "".
+                    </para></listitem>
+                <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
+                    The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>, 
+                    <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>, 
+                    and <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
+                    directories have been dropped from the default value of the 
+                    <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
+                    variable, which is used as the search path for finding files 
+                    referred to in 
+                    <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>. 
+                    If you have a recipe that relied upon these directories, 
+                    which would be unusual, then you will need to add the 
+                    appropriate paths to 
+                    <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>.
+                    </para></listitem>
+            </itemizedlist>           
         </para>
     </section>
 

documentation/ref-manual/ref-classes.xml

@@ -632,7 +632,7 @@
         To exclude some recipes from having their work directories deleted by
         <filename>rm_work</filename>, you can add the names of the recipe or 
         recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename> 
-        variable, which is also found in your <filename>local.conf</filename>
+        variable, which can also be set in your <filename>local.conf</filename>
         file.
         Here is an example:
         <literallayout class='monospaced'>

documentation/ref-manual/ref-variables.xml

@@ -600,10 +600,11 @@ Core layer for images cannot be removed
 
         <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
             <glossdef>
-                <para>A regular expression matched against
+                <para>A regular expression that resolves to one or more hosts 
-                    <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>
+                    (when the recipe is native) or one or more targets (when 
-                    that the OpenEmbedded build system evaluates against
+                    the recipe is non-native) with which a recipe is compatible.
-                    systems with which the recipe works.
+                    The regular expression is matched against
+                    <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
                     You can use the variable to stop recipes from being built
                     for classes of systems with which the recipes are not 
                     compatible.
@@ -616,10 +617,10 @@ Core layer for images cannot be removed
 
         <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
             <glossdef>
-                <para>A regular expression matched against
+                <para>A regular expression that resolves to one or more 
-                    <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>
+                    target machines with which a recipe is compatible.
-                    that the OpenEmbedded build system evaluates against
+                    The regular expression is matched against
-                    machines with which the recipe works.
+                    <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
                     You can use the variable to stop recipes from being built
                     for machines with which the recipes are not compatible.
                     Stopping these builds is particularly useful with kernels.
@@ -743,8 +744,6 @@ Core layer for images cannot be removed
             <glossdef>
                 <para>
                     Specifies a weak bias for recipe selection priority.
-                    Use this variable when more than one provider/version 
-                    satisfies a dependency.
                 </para>
                 <para>
                     The most common usage of this is variable is to set 
@@ -759,7 +758,7 @@ Core layer for images cannot be removed
                     The bias provided by <filename>DEFAULT_PREFERENCE</filename> 
                     is weak and is overridden by 
                     <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
-                    if the selection priority is different between two layers 
+                    if the that variable is different between two layers 
                     that contain different versions of the same recipe.
                 </note>
             </glossdef>
@@ -1279,7 +1278,8 @@ Core layer for images cannot be removed
             <glossdef>
                 <para>
                     Specifies the system, including the architecture and the 
-                    operating system, being built in the context of the current
+                    operating system, for with the build is occurring
+                    in the context of the current
                     recipe. 
                     The OpenEmbedded build system automatically sets this
                     variable.
@@ -1389,7 +1389,7 @@ Core layer for images cannot be removed
             <glossdef>
                 <para>
                     Specifies the list of locales to install into the image
-                    during the packaging process.
+                    during the root filesystem construction process.
                     The OpenEmbedded build system automatically splits locale 
                     files, which are used for localization, into separate 
                     packages. 
@@ -1648,8 +1648,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     For example, to skip the check for symbolic link 
                     <filename>.so</filename> files in the main package of a 
                     recipe, add the following to the recipe.
-                    In this example, the package name override
+                    The package name override must be used, which in this 
-                    <filename>${PN}</filename> must be used:
+                    example is <filename>${PN}</filename>:
                     <literallayout class='monospaced'>
      INSANE_SKIP_${PN} += "dev-so"
                     </literallayout>
@@ -3158,8 +3158,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
         <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
             <glossdef>
                 <para>
-                    A list of additional packages that you can suggest the 
+                    A list of additional packages that you can suggest for 
-                    package manager installs.
+                    installation by the package manager at the time a package 
+                    is installed.
                     Not all package managers support this functionality.
                 </para>
                 <para>
@@ -3214,7 +3215,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     Identifiers consist of the host distributor ID
                     followed by the release, 
                     as reported by the <filename>lsb_release</filename> tool
-                    or as read from <filename>/etc/lsb-release</filename>.) 
+                    or as read from <filename>/etc/lsb-release</filename>. 
                     Separate the list items with explicit newline 
                     characters (<filename>\n</filename>).
                     If <filename>SANITY_TESTED_DISTROS</filename> is not empty 
@@ -3281,9 +3282,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     thus force rebuilds when the recipe changes. 
                     <caution>
                         If you add an inappropriate variable to this list,
-                        other recipes might break when the interface of the 
+                        the software might break at runtime if the 
-                        recipe changes after the other recipes have been
+                        interface of the recipe was changed after the other 
-                        built.
+                        had been built.
                     </caution>
                 </para>
             </glossdef>
@@ -3309,9 +3310,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     recipe changes. 
                     <caution>
                         If you add an inappropriate dependency for a recipe
-                        relationship, the build might break when the interface
+                        relationship, the software might break during 
-                        of the second recipe changes after the first recipe has 
+                        runtime if the interface of the second recipe was 
-                        been built.
+                        changed after the first recipe had been built.
                     </caution>
                 </para>
             </glossdef>
@@ -3387,24 +3388,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                             which are assumed to be a subdirectories of the directory in which the
                             recipe file resides:
                             <itemizedlist>
-                                <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name
-                                    with any special suffix or prefix, if applicable.
-                                    For example, using <filename>bash</filename> to build for the native
-                                    machine, <filename>PN</filename> is <filename>bash-native</filename>.
-                                    Using <filename>bash</filename> to build for the target and for Multilib,
-                                    <link linkend='var-PN'><filename>PN</filename></link>
-                                    would be <filename>bash</filename> and
-                                    <filename>lib64-bash</filename>, respectively.
-                                    </para></listitem>
-                                <listitem><para><emphasis><filename>${PF}</filename> - </emphasis>
-                                    <filename>${PN}-${EXTENDPE}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}</filename>.
-                                    The recipe name including all version and revision numbers
-                                    (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
-                                    <filename>bash-4.2-r1/</filename>).</para></listitem>
-                                <listitem><para><emphasis><filename>${P}</filename> -</emphasis>
-                                    <filename>${PN}-${PV}</filename>.
-                                    The recipe name and version (i.e. <filename>bash-4.2</filename>).
-                                    </para></listitem>
                                 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The
                                     base recipe name without any special suffix or version numbers.
                                     </para></listitem>
@@ -3683,9 +3666,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     A list of functions to execute after files are staged into 
                     the sysroot.
-                    The OpenEmbedded build system usually uses such functions 
+                    These functions are usually used to apply additional 
-                    to apply additional processing on the
+                    processing on the staged files, or to stage additional 
-                    staged files, or to stage additional files.
+                    files.
                 </para>
             </glossdef>
         </glossentry>