[gnome-continuous-yocto/gnomeostree-3.28-rocko: 1317/8267] ref-manual: Updated the PR variable description.

[Emmanuele Bassi <ebassi src gnome org>]

commit b66e84e19d087f1f9fd279adc905f3a7bebbe8a1
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Wed Jun 29 08:32:49 2016 -0700

    ref-manual: Updated the PR variable description.
    
    Fixes [YOCTO #9843]
    
    The variable description was very brief.  These changes added some
    substance to the description and how the OpenEmbedded build system
    uses the variable.
    
    (From yocto-docs rev: cc9117d4e16c56dd54f81804fda94561e61d91a7)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/ref-manual/ref-variables.xml |   42 ++++++++++++++++++++++++++-
 1 files changed, 40 insertions(+), 2 deletions(-)
---
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 433893b..ed735a7 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9571,8 +9571,46 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    The revision of the recipe.
-                    The default value for this variable is "r0".
+                    The revision of the recipe. The default value for this
+                    variable is "r0".
+                    Subsequent revisions of the recipe conventionally have the
+                    values "r1", "r2", and so forth.
+                    When
+                    <link linkend='var-PV'><filename>PV</filename></link>
+                    increases, <filename>PR</filename> is conventionally reset
+                    to "r0".
+                    <note>
+                        The OpenEmbedded build system does not need the aid of
+                        <filename>PR</filename> to know when to rebuild a
+                        recipe.
+                        The build system uses
+                        <link linkend='var-STAMP'><filename>STAMP</filename></link>
+                        and the
+                        <link linkend='shared-state-cache'>shared state cache</link>
+                        mechanisms.
+                    </note>
+                    The <filename>PR</filename> variable primarily becomes
+                    significant when a package manager dynamically installs
+                    packages on an already built image.
+                    In this case, <filename>PR</filename>, which is the default
+                    value of
+                    <link linkend='var-PKGR'><filename>PKGR</filename></link>,
+                    helps the package manager distinguish which package is the
+                    most recent one in cases where many packages have the same
+                    <filename>PV</filename> (i.e. <filename>PKGV</filename>).
+                    Packages have the same <filename>PV</filename> usually
+                    when the package manager installs the same upstream version
+                    and some of the packages include packaging fixes.
+                    <note>
+                        <filename>PR</filename> does not need to be increased
+                        for changes that do not change the package contents or
+                        metadata.
+                    </note>
+                    Because, manually managing <filename>PR</filename> can be
+                    cumbersome and error-prone, an automated solution exists.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR 
Service</ulink>"
+                    section for more information.
                 </para>
             </glossdef>
         </glossentry>