1 files changed, 32 insertions, 10 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 55f135683d..3499b78a20 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1277,18 +1277,40 @@
             <glossdef>
                 <para>
                     The short name of the distribution.
-                    This variable corresponds to a file with the
-                    extension <filename>.conf</filename>
-                    located in a <filename>conf/distro</filename> directory
-                    within the
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
-                    that contains the distribution configuration.
-                    The value must not contain spaces, and is typically all lower-case.
+                    This variable corresponds to a distribution
+                    configuration file whose root name is the same as the
+                    variable's argument and whose filename extension is
+                    <filename>.conf</filename>.
+                    For example, the distribution configuration file for the
+                    Poky distribution is named <filename>poky.conf</filename>
+                    and resides in the
+                    <filename>meta-yocto/conf/distro</filename> directory of
+                    the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+
+                <para>
+                    Within that <filename>poky.conf</filename> file, the
+                    <filename>DISTRO</filename> variable is set as follows:
+                    <literallayout class='monospaced'>
+     DISTRO = "poky"
+                    </literallayout>
                 </para>
+
                 <para>
-                    If the variable is blank, a set of default configuration
-                    will be used, which is specified
-                    within <filename>meta/conf/distro/defaultsetup.conf</filename>.
+                    Distribution configuration files are located in a
+                    <filename>conf/distro</filename> directory within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                    that contains the distribution configuration.
+                    The value for <filename>DISTRO</filename> must not contain
+                    spaces, and is typically all lower-case.
+                    <note>
+                        If the <filename>DISTRO</filename> variable is blank, a set
+                        of default configurations are used, which are specified
+                        within
+                        <filename>meta/conf/distro/defaultsetup.conf</filename>
+                        also in the Source Directory.
+                    </note>
                 </para>
             </glossdef>
         </glossentry>