docs/122476: Misleading doc for adding new users to a group

[Diane Bruce]

>Number:         122476
>Category:       docs
>Synopsis:       Misleading doc for adding new users to a group
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sat Apr 05 22:10:00 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator:     Diane Bruce
>Release:        FreeBSD 7.0-RELEASE i386
>Organization:
Are you kidding?
>Environment:
System: FreeBSD night.db.net 7.0-RELEASE FreeBSD 7.0-RELEASE #13: Thu Feb 28 08:50:37 EST 2008 root at night.db.net:/usr/obj/usr/src/sys/NIGHT i386



>Description:
	3.8 is mis-leading and has resulted in a new user accidentally
	deleting himself from groups, both -M and -m should be shown
	as examples clarifying the difference.
>How-To-Repeat:

>Fix:

See sgml diff

--- en_US.ISO8859-1/books/handbook/users/chapter.sgml.orig	2008-04-04 18:24:51.000000000 -0400
+++ en_US.ISO8859-1/books/handbook/users/chapter.sgml	2008-04-05 16:01:40.000000000 -0400
@@ -982,7 +982,7 @@
       the <groupname>teamtwo</groupname> group.</para>

     <example>
-      <title>Adding Somebody to a Group Using &man.pw.8;</title>
+      <title>Creating the list of members of a Group Using &man.pw.8;</title>

       <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput>
 &prompt.root; <userinput>pw groupshow teamtwo</userinput>
@@ -990,7 +990,7 @@
     </example>

     <para>The argument to the <option>-M</option> option is a
-      comma-delimited list of users who are members of the group.  From the
+      comma-delimited list of users who are to be in the group.  From the
       preceding sections, we know that the password file also contains a
       group for each user.  The latter (the user) is automatically added to
       the group list by the system; the user will not show up as a member
@@ -1000,6 +1000,18 @@
       <filename>/etc/group</filename> file; it will never attempt to read
       additionally data from <filename>/etc/passwd</filename>.</para>

+      <example>
+      <title>Adding a new member to a Group Using &man.pw.8;</title>
+
+      <screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:jru,db</screen>
+    </example>
+    <para>The argument to the <option>-m</option> option is a
+      comma-delimited list of users who are to be added to the group. Unlike
+      the previous example, these users are added to the group and do not
+      replace the list of users in the group.
+    </para>
     <example>
       <title>Using &man.id.1; to Determine Group Membership</title>



>Release-Note:
>Audit-Trail:
>Unformatted: