ref-manual: Updated the PREFERRED_VERSION variable description.

Fixes [YOCTO #8595]

Applied some wording changes as part of the review process from
Richard Purdie.

(From yocto-docs rev: 3c4fc3cbdecb7e3c8287a915b82bc5469288d5db)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 13 insertions, 5 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index fa652e57a1..fd15dff9a1 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9592,14 +9592,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
      PREFERRED_VERSION_python = "2.7.3"
      PREFERRED_VERSION_linux-yocto = "3.19%"
                     </literallayout>
-                    If you want to force a particular version of a recipe,
-                    you can use "forcevariable" as follows:
+                    Sometimes the <filename>PREFERRED_VERSION</filename>
+                    variable can be set by configuration files in a way that
+                    is hard to change.
+                    You can use
+                    <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
+                    to set a machine-specific override.
+                    Here is an example:
                     <literallayout class='monospaced'>
-     PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%"
+     PREFERRED_VERSION_linux-yocto_qemux86 = "3.4%"
                     </literallayout>
-                    Another method is to use a machine override:
+                    Although not recommended, worst case, you can also use the
+                    "forcevariable" override, which is the strongest override
+                    possible.
+                    Here is an example:
                     <literallayout class='monospaced'>
-     PREFERRED_VERSION_linux-yocto_qemux86 = "3.4%"
+     PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%"
                     </literallayout>
                 </para>
             </glossdef>