diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
index 5395ce5e3..fd75275bb 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -1558,6 +1558,20 @@ overview of their function and contents.
          PREFERRED_PROVIDER_xxx = "yyy"
          PREFERRED_PROVIDER_aaa = "bbb"
 
+   :term:`PREFERRED_RPROVIDER`
+      Determines which *recipe* should be given preference when
+      multiple packages declare runtime-providing (:term:`RPROVIDES`)
+      the same item. Some examples::
+
+         PREFERRED_RPROVIDER_initd-functions ?= "initscripts"
+         PREFERRED_RPROVIDER_virtual-libegl-icd ?= "mesa"
+
+      The former will select as the package built by the `initscripts`
+      recipe declaring to be runtime-provider for `initd-functions`,
+      which is in this case `initscripts-functions`::
+
+          .../initscripts_1.0.bb:RPROVIDES:${PN}-functions = "initd-functions"
+
    :term:`PREFERRED_VERSION`
       If there are multiple versions of a recipe available, this variable
       determines which version should be given preference. You must always