documentation/poky-ref-manual/ref-variables.xml: Edits to CONFFILES and FILES

Second editing pass to these glossary entries based on Paul
Eggleton's review.

Reported-by: Paul Eggleton <paul.eggleton@linux.intel.com>
(From yocto-docs rev: 690043a7b239479c948e1219dcb44751570cc624)

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

1 files changed, 30 insertions, 21 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 8da49b2793..81d3f2e8fc 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -228,9 +228,10 @@
             <glossdef>
                 <para>
                     Identifies editable or configurable files that are part of a package.
-                    If the Package Management System (PMS) is updating packages as part of 
-                    the final image packaging, it is possible that files you want unchanged
-                    get overwritten.
+                    If the Package Management System (PMS) is being used to update
+                    packages on the target system, it is possible that 
+                    configuration files you have changed after the original installation
+                    and that you now want to remain unchanged are overwritten.
                     In other words, editable files might exist in the package that you do not 
                     want reset as part of the package update process.
                     You can use the <filename>CONFFILES</filename> variable to list the files in the 
@@ -243,11 +244,11 @@
                 <para>  
                     To use the <filename>CONFFILES</filename> variable, provide a package name
                     override that identifies the package.
-                    Then, provide a list of space-separated files or paths that identify the 
+                    Then, provide a list of space-separated files that identify the 
                     editable files you want the PMS to exclude from the update process.
                     Here is an example:
                     <literallayout class='monospaced'>                       
-     CONFFILES_${PN} += "/dir1/" "dir2/" "file1" "file2"
+  CONFFILES_${PN} += "${bindir}/file1 ${bindir}/file2"
                     </literallayout>
                 </para>
 
@@ -256,17 +257,19 @@
                     <filename><link linkend='var-FILES'>FILES</link></filename> variables.
                     The files listed with <filename>CONFFILES</filename> must be a subset of 
                     the files listed with <filename>FILES</filename>.
-                    Because the files you provide with <filename>CONFFILES</filename> are simply
-                    being identified so that the PMS will not overwrite them, it makes sense that
+                    Because the configuration files you provide with <filename>CONFFILES</filename> 
+                    are simply being identified so that the PMS will not overwrite them, 
+                    it makes sense that
                     the files must already be included as part of the package through the 
                     <filename>FILES</filename> variable.
                 </para>
 
                 <note>
                     When specifying paths as part of the <filename>CONFFILES</filename> variable, 
-                    it is good practice to use the base, architecture-dependant, and 
-                    architecture-independant variables in the pathnames 
-                    rather than hard-coding the pathnames. 
+                    it is good practice to use appropriate path variables. 
+                    For example, <filename>${sysconfdir}</filename> rather than 
+                    <filename>/etc</filename> or <filename>${bindir}</filename> rather 
+                    than <filename>/usr/bin</filename>.
                     You can find a list of these variables at the top of the 
                     <filename>/meta/conf/bitbake.conf</filename> file in the Yocto Project
                     files directory.
@@ -536,34 +539,40 @@
             <glossdef>
                 <para>
                     The list of directories or files that are placed in packages.
-                    If some of these files are editable and you know they should not be 
-                    overwritten during the package update process by the Package Management
-                    System (PMS), you can identify these files so that the PMS will not 
-                    overwrite them. 
-                    See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> 
-                    variable for information on how to identify these files to the PMS.
                 </para>
 
-                <para>  
+                <para>
                     To use the <filename>FILES</filename> variable, provide a package name
                     override that identifies the package.
                     Then, provide a list of space-separated files or paths that identify the 
                     files you want included as part of the package.
                     Here is an example:
                     <literallayout class='monospaced'>                       
-     FILES_${PN} += "/dir1/" "dir2/" "file1" "file2"
+  FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
                     </literallayout>
                 </para>
 
                 <note>
                     When specifying paths as part of the <filename>FILES</filename> variable, 
-                    it is good practice to use the base, architecture-dependant, and 
-                    architecture-independant variables in the pathnames 
-                    rather than hard-coding the pathnames. 
+                    it is good practice to use appropriate path variables. 
+                    For example, <filename>${sysconfdir}</filename> rather than 
+                    <filename>/etc</filename> or <filename>${bindir}</filename> rather 
+                    than <filename>/usr/bin</filename>.
                     You can find a list of these variables at the top of the 
                     <filename>/meta/conf/bitbake.conf</filename> file in the Yocto Project
                     files directory.
                 </note>
+
+                <para>
+                    If some of files you provide with the <filename>FILES</filename> variable
+                    are editable and you know they should not be 
+                    overwritten during the package update process by the Package Management
+                    System (PMS), you can identify these files so that the PMS will not 
+                    overwrite them. 
+                    See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> 
+                    variable for information on how to identify these files to the PMS.
+                </para>
+
             </glossdef>
         </glossentry>