From dc857372ed8f8d52b3f0e531d719f6ed1f7e0d67 Mon Sep 17 00:00:00 2001
From: nekral-guest <nekral-guest@5a98b0ae-9ef6-0310-add3-de5d479b70d7>
Date: Fri, 13 Mar 2009 23:12:06 +0000
Subject: [PATCH] 	* man/newusers.8.xml: Document the behavior of
 newusers for each 	field. 	* man/newusers.8.xml: Do not add the note on
 PAM on non-PAM 	enabled configurations.

---
 ChangeLog          |   7 +++
 man/newusers.8.xml | 120 ++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 114 insertions(+), 13 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d3996e9f..9279037a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2009-03-14  Nicolas François  <nicolas.francois@centraliens.net>
+
+	* man/newusers.8.xml: Document the behavior of newusers for each
+	field.
+	* man/newusers.8.xml: Do not add the note on PAM on non-PAM
+	enabled configurations.
+
 2009-03-13  Nicolas François  <nicolas.francois@centraliens.net>
 
 	* src/newusers.c: Make sure the SHA related variables are not
diff --git a/man/newusers.8.xml b/man/newusers.8.xml
index 7ffdfd1f..a043364d 100644
--- a/man/newusers.8.xml
+++ b/man/newusers.8.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
    Copyright (c) 1991 - 1994, Julianne Frances Haugh
-   Copyright (c) 2007 - 2008, Nicolas François
+   Copyright (c) 2007 - 2009, Nicolas François
    All rights reserved.
   
    Redistribution and use in source and binary forms, with or without
@@ -73,10 +73,28 @@
       of existing users or to create new users. Each line is in the same format
       as the standard password file (see
       <citerefentry><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum>
-      </citerefentry>) with the following exceptions:
+      </citerefentry>) with the exceptions explained below:
     </para>
+    <para>pw_name:pw_passwd:pw_uid:pw_gid:pw_gecos:pw_dir:pw_shell</para>
 
     <variablelist remap='IP'>
+      <varlistentry>
+	<term>
+	  <emphasis remap='I'>pw_name</emphasis>
+	</term>
+	<listitem>
+	  <para>
+	    This is the name of the user.
+	  </para>
+	  <para>
+	    It can be the name of a new user or the name of an existing
+	    user (or an user created before by
+	    <command>newusers</command>).  In case of an existing user,
+	    the user's information will be changed, otherwise a new user
+	    will be created.
+	  </para>
+	</listitem>
+      </varlistentry>
       <varlistentry>
 	<term>
 	  <emphasis remap='I'>pw_passwd</emphasis>
@@ -88,17 +106,73 @@
 	  </para>
 	</listitem>
       </varlistentry>
+      <varlistentry>
+	<term>
+	  <emphasis remap='I'>pw_uid</emphasis>
+	</term>
+	<listitem>
+	  <para>
+	    This field is used to define the UID of the user.
+	  </para>
+	  <para>
+	    If the field is empty, an new (unused) UID will be defined
+	    automatically by <command>newusers</command>.
+	  </para>
+	  <para>
+	    If this field contains a number, this number will be used as
+	    the UID.
+	  </para>
+	  <para>
+	    If this field contains the name of an existing user (or the
+	    name of an user created before by
+	    <command>newusers</command>), the UID of the specified user
+	    will be used.
+	  </para>
+	</listitem>
+      </varlistentry>
       <varlistentry>
 	<term>
 	  <emphasis remap='I'>pw_gid</emphasis>
 	</term>
 	<listitem>
 	  <para>
-	    This field must contain the name (or number) of a group. The user
-	    will be added as a member to this group. When a non-existent
-	    group name or number is specified, a new group will be created.
-	    In the case of a non-existent group number, both the name and the
-	    number of the new group will be this number.
+	    This field is used to define the primary group ID for the user.
+	  </para>
+	  <para>
+	    If this field contains the name of an existing group (or a
+	    group created before by <command>newusers</command>), the GID
+	    of this group will be used as the primary group ID for the
+	    user.
+	  </para>
+	  <para>
+	    If this field is a number, this number will be used as the
+	    primary group ID of the user.  If no groups exist with this
+	    GID, a new group will be created with this GID, and the name
+	    of the user.
+	  </para>
+	  <para>
+	    If this field is empty, a new group will be created with the
+	    name of the user and a GID will be automatically defined by
+	    <command>newusers</command> to be used as the primary group ID
+	    for the user and as the GID for the new group.
+	  </para>
+	  <para>
+	    If this field contains the name of a group which does not
+	    exist (and was not created earlier wbefore by
+	    <command>newusers</command>), a new group will be created with
+	    the specified name and a GID will be automatically defined by
+	    <command>newusers</command> to be used as the primary group ID
+	    for the user and Gs the ID for the new group.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>
+	  <emphasis remap='I'>pw_gecos</emphasis>
+	</term>
+	<listitem>
+	  <para>
+	    This field is copied in the GECOS field of the user.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -108,16 +182,36 @@
 	</term>
 	<listitem>
 	  <para>
-	    This field will be checked for existence as a directory, and a
-	    new directory with this name will be created if it does not
-	    already exist. The ownership of the directory will be set to be
-	    that of the user being created or updated.
+	    This field is used to define the home directory of the user.
+	  </para>
+	  <para>
+	    If this field does not specify an existing directory, the
+	    specified directory is created, with ownership set to the
+	    user being created or updated and its primary group.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>
+	  <emphasis remap='I'>pw_shell</emphasis>
+	</term>
+	<listitem>
+	  <para>
+	    This field defines the shell of the user.
+	    No checks are performed on this field.
 	  </para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
-    <para> 
+    <para>
+      <command>newusers</command> first tries to create or change all the
+      specified users, and then write these changes to the user or group
+      databases. If an error occurs (except in the final writes to the
+      databases), no changes are committed to the databases.
+    </para>
+
+    <para>
       This command is intended to be used in a large system environment
       where many accounts are updated at a single time.
     </para>
@@ -191,7 +285,7 @@
       The input file must be protected since it contains unencrypted
       passwords.
     </para>
-    <para>
+    <para condition="pam">
       PAM is not used to update the passwords.
       Only <filename>/etc/passwd</filename> and
       <filename>/etc/shadow</filename> are updated, and the various checks