ref-manual: Updated the FILESEXTRAPATHS variable description.

Fixes YOCTO #3662.

Per comments from Paul Eggleton, I updated the description to
include best practices of prepending and from using within
append files.

(From yocto-docs rev: 368055bc046277fe601ff3a64913044be0a15e6d)

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

documentation/ref-manual/ref-variables.xml

@@ -1104,42 +1104,34 @@ 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:
-                    <literallayout class='monospaced'>
-     FILESEXTRAPATHS := "path_1:path_2:path_3:"
-                    </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:
+                    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_prepend := "${THISDIR}/${PN}:"
                     </literallayout>
                 </para>
+
+                <para>
+                    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 := "path_1:path_2:path_3:"
+                    </literallayout>
+                </para>
             </glossdef>
         </glossentry>