1 files changed, 20 insertions, 28 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index d54b5bcdfc..5b56765cdd 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1104,40 +1104,32 @@ Core layer for images cannot be removed
                 <para>
                     Extends the search path the OpenEmbedded build system uses
                     when looking for files and patches as it processes recipes.
-                    The directories BitBake uses when it processes recipes are
-                    defined by the
-                    <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable.
-                    You can add directories to the search path by defining the
-                    <filename>FILESEXTRAPATHS</filename> variable.
-                </para>
-
-                <para>
-                    To add paths to the front of the search order, prepend
-                    them and use the immediate expansion
-                    (<filename>:=</filename>) operator.
-                    Provide a list of directories and separate
-                    each path using a colon character as follows:
-                    <literallayout class='monospaced'>
-     FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
-                    </literallayout>
-                    You can add paths to the end of the search order by simply
-                    adding them as follows:
+                    Best practices dictate that you accomplish this by using the 
+                    variable from within a <filename>.bbappend</filename> file 
+                    and that you prepend paths as follows:
                     <literallayout class='monospaced'>
-     FILESEXTRAPATHS := "path_1:path_2:path_3:"
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
                     </literallayout>
-                    To maintain the integrity of the
-                    <filename>FILESPATH</filename> variable, you must include
-                    the appropriate beginning or ending (as needed) colon
-                    character.
                 </para>
 
                 <para>
-                    The <filename>FILESEXTRAPATHS</filename> variable is
-                    intended for use in <filename>.bbappend</filename> files
-                    to include any additional files provided in that layer.
-                    You typically accomplish this with the following:
+                    The directories BitBake uses when it processes recipes 
+                    are defined by the 
+                    <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
+                    variable, and can be extended using 
+                    <filename>FILESEXTRAPATHS</filename>.
+                    By prepending paths in <filename>.bbappend</filename>
+                    files, you allow multiple append files that reside in
+                    different layers but are used for the same recipe to 
+                    correctly extend the path.
+                    <note>
+                        Be sure to use the immediate expansion
+                        (<filename>:=</filename>) operator and include 
+                        the trailing separating colon character.
+                    </note>
+                    Here is another example that specifically adds three paths:
                     <literallayout class='monospaced'>
-     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+     FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
                     </literallayout>
                 </para>
             </glossdef>