ref-manual: Edits to fix up how GID and UIDs are handled.

Some review edits to change the useradd-staticids class and the
related USERADD* variables. Input from Paul Eggleton.

(From yocto-docs rev: 9b94046721a971de41d2062a48d624e06dcf17f0)

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

2 files changed, 42 insertions, 39 deletions

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index df114f4eb2..0031df26d8 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -3137,11 +3137,11 @@
 </section>
 
 <section id='ref-classes-useradd-staticids'>
-    <title><filename>-useradd-staticids.bbclass</filename></title>
+    <title><filename>useradd-staticids.bbclass</filename></title>
 
     <para>
-        The <filename>useradd-staticids</filename> class supports the addition of
-        users or groups that have static user identification
+        The <filename>useradd-staticids</filename> class supports the addition
+        of users or groups that have static user identification
         (<filename>uid</filename>) and group identification
         (<filename>gid</filename>) values.
     </para>
@@ -3150,28 +3150,31 @@
         The default behavior of the OpenEmbedded build system for assigning
         <filename>uid</filename> and <filename>gid</filename> values when
         packages add users and groups during package install time is to
-        look in
-        <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
-        <filename>files/passwd</filename> and <filename>files/group</filename>
-        files for the values.
+        add them dynamically.
         This works fine for programs that do not care what the values of the
         resulting users and groups become.
         In these cases, the order of the installation determines the final
         <filename>uid</filename> and <filename>gid</filename> values.
-    </para>
-
-    <para>
-        If non-deterministic
+        However, if non-deterministic
         <filename>uid</filename> and <filename>gid</filename> values are a
         problem, you can override the default, dynamic application of these
         values by setting static values.
+        When you set static values, the OpenEmbedded build system looks in
+        <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
+        <filename>files/passwd</filename> and <filename>files/group</filename>
+        files for the values.
+    </para>
+
+    <para>
+        To use static <filename>uid</filename> and <filename>gid</filename>
+        values, you need to set some variables.
         See the
         <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
         <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
         <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
         and
         <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
-        variables for more information.
+        variables.
         You can also see the
         <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
         class for additional information.
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 6eae958e58..258ae2c6db 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -7853,26 +7853,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
 
                 <para>
-                    The default behavior for the build system is to look in
+                    When applying static group identification
+                    (<filename>gid</filename>) values, the OpenEmbedded build
+                    system looks in
                     <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
-                    for a <filename>files/group</filename> file and then dynamically
-                    apply <filename>uid</filename> values.
-                    However, you can override this behavior by using the
-                    <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
-                    variable.
-                    When you do use static values, you must also set the
-                    <filename>USERADD_GID_TABLES</filename> variable in your
-                    <filename>local.conf</filename> file as follows:
+                    for a <filename>files/group</filename> file and then applies
+                    those <filename>uid</filename> values.
+                    Set the variable as follows in your
+                    <filename>local.conf</filename> file:
                     <literallayout class='monospaced'>
      USERADD_GID_TABLES = "files/group"
                     </literallayout>
                 </para>
 
                 <note>
-                    When using static information for user adds, you must
-                    also use the
-                    <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
-                    variable.
+                    Setting the
+                    <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
+                    variable to "useradd-staticids" causes the build system
+                    to use static <filename>gid</filename> values.
                 </note>
             </glossdef>
         </glossentry>
@@ -7887,26 +7885,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
 
                 <para>
-                    The default behavior for the build system is to look in
+                    When applying static user identification
+                    (<filename>uid</filename>) values, the OpenEmbedded build
+                    system looks in
                     <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
-                    for the <filename>files/passwd</filename> file and
-                    then dynamically apply <filename>uid</filename> values.
-                    However, you can override this behavior by using the
-                    <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
-                    variable.
-                    When you do use static values, you must also set the
-                    <filename>USERADD_UID_TABLES</filename> variable in your
-                    <filename>local.conf</filename> file as follows:
+                    for a <filename>files/passwd</filename> file and then applies
+                    those <filename>uid</filename> values.
+                    Set the variable as follows in your
+                    <filename>local.conf</filename> file:
                     <literallayout class='monospaced'>
      USERADD_UID_TABLES = "files/passwd"
                     </literallayout>
                 </para>
 
                 <note>
-                    When using static information for group adds, you must
-                    also use the
-                    <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
-                    variable.
+                    Setting the
+                    <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
+                    variable to "useradd-staticids" causes the build system
+                    to use static <filename>uid</filename> values.
                 </note>
             </glossdef>
         </glossentry>
@@ -7976,7 +7972,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     OpenEmbedded build system to base all user and group
                     additions on a static
                     <filename>passwd</filename> and
-                    <filename>group</filename> files.
+                    <filename>group</filename> files found in
+                    <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
+                </para>
+
+                <para>
                     To use static user identification (<filename>uid</filename>)
                     and group identification (<filename>gid</filename>)
                     values, set the variable