>From e98d41ecaad9687f03281ee205e52ad3d4ae52d6 Mon Sep 17 00:00:00 2001
From: Theresa Halloran <thallora@linux.vnet.ibm.com>
Date: Mon, 17 Oct 2011 00:27:16 -0400
Subject: [PATCH] s4: samba-tool --help descriptions and documentation
 improvements

Signed-off-by: Theresa Halloran <thallora@linux.vnet.ibm.com>
---
 source4/scripting/python/samba/netcmd/__init__.py |   17 +++++++++++++++--
 source4/scripting/python/samba/netcmd/user.py     |   13 ++++++++++++-
 source4/setup/tests/blackbox_group.sh             |    4 ++--
 source4/setup/tests/blackbox_newuser.sh           |    4 ++--
 source4/setup/tests/blackbox_setpassword.sh       |    2 +-
 testprogs/blackbox/test_export_keytab.sh          |    2 +-
 testprogs/blackbox/test_kinit.sh                  |    2 +-
 testprogs/blackbox/test_passwords.sh              |    2 +-
 8 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/source4/scripting/python/samba/netcmd/__init__.py b/source4/scripting/python/samba/netcmd/__init__.py
index bf08457..1854168 100644
--- a/source4/scripting/python/samba/netcmd/__init__.py
+++ b/source4/scripting/python/samba/netcmd/__init__.py
@@ -28,8 +28,20 @@ import textwrap
 
 class Option(optparse.Option):
     pass
-
-
+# This help formatter does text wrapping and preserves newlines
+class PlainHelpFormatter(optparse.IndentedHelpFormatter):
+    def format_description(self,description=""):
+            desc_width = self.width - self.current_indent
+            indent = " "*self.current_indent
+            paragraphs = description.split('\n')
+            wrapped_paragraphs = [
+            	textwrap.fill(p,
+              		desc_width,
+              		initial_indent=indent,
+              		subsequent_indent=indent)
+            	for p in paragraphs]
+            result = "\n".join(wrapped_paragraphs) + "\n"
+            return result
 
 class Command(object):
     """A samba-tool command."""
@@ -107,6 +119,7 @@ class Command(object):
         parser = optparse.OptionParser(
             usage=self.synopsis,
             description=self.full_description,
+            formatter=PlainHelpFormatter(),
             prog=prog)
         parser.add_options(self.takes_options)
         optiongroups = {}
diff --git a/source4/scripting/python/samba/netcmd/user.py b/source4/scripting/python/samba/netcmd/user.py
index cbac5af..5b26188 100644
--- a/source4/scripting/python/samba/netcmd/user.py
+++ b/source4/scripting/python/samba/netcmd/user.py
@@ -39,6 +39,17 @@ from samba.netcmd import (
 class cmd_user_add(Command):
     """Creates a new user"""
 
+    full_description="""This command creates a new user account in the Active Directory domain.  The username specified on the command is the SAMaccountname.\n
+User accounts may represent physical entities, such as people or may be used as service accounts for applications.  User accounts are also referred to as security principals and are assigned a security identifier (SID).\n
+A user account enables a user to logon to a computer and domain with an identity that can be authenticate.  To maximize security, each user should have their own unique user account and password.  A user's access to domain resources is based on permissions assigned to the user account.\n\n
+The command may be run from the root userid or another authorized userid.\n
+Example1:
+samba-tool user create User1 passw0rd --given-name=John --surname=Smith --must-change-at-next-login -H ldap://samba.samdom.example.com -Uadministrator%passw1rd\n
+Example1 shows how to create a new user in the domain against a remote LDAP server.  The -U option is used to pass the userid and password authorized to issue the command remotely.\n
+Example2:
+sudo samba-tool user create User2 passw2rd --given-name=Jane --surname=Doe --must-change-at-next-login \n
+Example2 shows how to create a new user in the domain against the local server.   sudo is used so an unauthorized user may run the command as root."""
+
     synopsis = "%prog <username> [<password>] [options]"
 
     takes_options = [
@@ -289,7 +300,7 @@ class cmd_user(SuperCommand):
     """User management"""
 
     subcommands = {}
-    subcommands["add"] = cmd_user_add()
+    subcommands["create"] = cmd_user_add()
     subcommands["delete"] = cmd_user_delete()
     subcommands["enable"] = cmd_user_enable()
     subcommands["setexpiry"] = cmd_user_setexpiry()
diff --git a/source4/setup/tests/blackbox_group.sh b/source4/setup/tests/blackbox_group.sh
index 6c58e91..08b8e5b 100755
--- a/source4/setup/tests/blackbox_group.sh
+++ b/source4/setup/tests/blackbox_group.sh
@@ -20,8 +20,8 @@ samba_tool="./bin/samba-tool"
 CONFIG="--configfile=$PREFIX/simple-dc/etc/smb.conf"
 
 #creation of two test subjects
-testit "user add" $samba_tool user add $CONFIG --given-name="User" --surname="Tester" --initial="UT" testuser testp@ssw0Rd
-testit "user add" $samba_tool user add $CONFIG --given-name="User1" --surname="Tester" --initial="UT" testuser1 testp@ssw0Rd
+testit "user add" $samba_tool user create $CONFIG --given-name="User" --surname="Tester" --initial="UT" testuser testp@ssw0Rd
+testit "user add" $samba_tool user create $CONFIG --given-name="User1" --surname="Tester" --initial="UT" testuser1 testp@ssw0Rd
 
 #test creation of six different groups
 testit "group add" $samba_tool group add $CONFIG --group-scope='Domain' --group-type='Security' --description='DomainSecurityGroup' --mail-address='dsg@samba.org' --notes='Notes' dsg
diff --git a/source4/setup/tests/blackbox_newuser.sh b/source4/setup/tests/blackbox_newuser.sh
index c604684..e048dcd 100755
--- a/source4/setup/tests/blackbox_newuser.sh
+++ b/source4/setup/tests/blackbox_newuser.sh
@@ -22,8 +22,8 @@ CONFIG="--configfile=$PREFIX/simple-dc/etc/smb.conf"
 #two test for creating new user
 #newuser  account is created with cn=Given Name Initials. Surname
 #newuser1 account is created using cn=username
-testit "user add" $samba_tool user add $CONFIG --given-name="User" --surname="Tester" --initials="T" --profile-path="\\\\myserver\\my\\profile" --script-path="\\\\myserver\\my\\script" --home-directory="\\\\myserver\\my\\homedir" --job-title="Tester" --department="Testing" --company="Samba.org" --description="Description" --mail-address="tester@samba.org" --internet-address="http://samba.org" --telephone-number="001122334455" --physical-delivery-office="101" --home-drive="H:" NewUser testp@ssw0Rd
-testit "user add" $samba_tool user add $CONFIG --use-username-as-cn --given-name="User1" --surname="Tester1" --initials="UT1" --profile-path="\\\\myserver\\my\\profile" --script-path="\\\\myserver\\my\\script" --home-directory="\\\\myserver\\my\\homedir" --job-title="Tester" --department="Testing" --company="Samba.org" --description="Description" --mail-address="tester@samba.org" --internet-address="http://samba.org" --telephone-number="001122334455" --physical-delivery-office="101" --home-drive="H:" NewUser1 testp@ssw0Rd
+testit "user add" $samba_tool user create $CONFIG --given-name="User" --surname="Tester" --initials="T" --profile-path="\\\\myserver\\my\\profile" --script-path="\\\\myserver\\my\\script" --home-directory="\\\\myserver\\my\\homedir" --job-title="Tester" --department="Testing" --company="Samba.org" --description="Description" --mail-address="tester@samba.org" --internet-address="http://samba.org" --telephone-number="001122334455" --physical-delivery-office="101" --home-drive="H:" NewUser testp@ssw0Rd
+testit "user add" $samba_tool user create $CONFIG --use-username-as-cn --given-name="User1" --surname="Tester1" --initials="UT1" --profile-path="\\\\myserver\\my\\profile" --script-path="\\\\myserver\\my\\script" --home-directory="\\\\myserver\\my\\homedir" --job-title="Tester" --department="Testing" --company="Samba.org" --description="Description" --mail-address="tester@samba.org" --internet-address="http://samba.org" --telephone-number="001122334455" --physical-delivery-office="101" --home-drive="H:" NewUser1 testp@ssw0Rd
 
 # check the enable account script
 testit "enableaccount" $samba_tool user enable $CONFIG NewUser
diff --git a/source4/setup/tests/blackbox_setpassword.sh b/source4/setup/tests/blackbox_setpassword.sh
index 8858767..e99cdcc 100755
--- a/source4/setup/tests/blackbox_setpassword.sh
+++ b/source4/setup/tests/blackbox_setpassword.sh
@@ -17,7 +17,7 @@ samba_tool="./bin/samba-tool"
 rm -rf $PREFIX/simple-dc
 testit "simple-dc" $PYTHON $SRCDIR/source4/setup/provision --server-role="dc" --domain=FOO --realm=foo.example.com --domain-sid=S-1-5-21-4177067393-1453636373-93818738 --targetdir=$PREFIX/simple-dc
 
-testit "user add" $samba_tool user add --configfile=$PREFIX/simple-dc/etc/smb.conf testuser testp@ssw0Rd
+testit "user add" $samba_tool user create --configfile=$PREFIX/simple-dc/etc/smb.conf testuser testp@ssw0Rd
 
 testit "setpassword" $samba_tool user setpassword --configfile=$PREFIX/simple-dc/etc/smb.conf testuser --newpassword=testp@ssw0Rd
 
diff --git a/testprogs/blackbox/test_export_keytab.sh b/testprogs/blackbox/test_export_keytab.sh
index 81db520..9b60b0f 100755
--- a/testprogs/blackbox/test_export_keytab.sh
+++ b/testprogs/blackbox/test_export_keytab.sh
@@ -22,7 +22,7 @@ samba4bindir="$BINDIR"
 smbclient="$samba4bindir/smbclient$EXEEXT"
 samba4kinit="$samba4bindir/samba4kinit$EXEEXT"
 samba_tool="$samba4bindir/samba-tool$EXEEXT"
-newuser="$samba_tool user add"
+newuser="$samba_tool user create"
 
 . `dirname $0`/subunit.sh
 
diff --git a/testprogs/blackbox/test_kinit.sh b/testprogs/blackbox/test_kinit.sh
index d54955d..3cf841e 100755
--- a/testprogs/blackbox/test_kinit.sh
+++ b/testprogs/blackbox/test_kinit.sh
@@ -73,7 +73,7 @@ testit "check time with kerberos ccache" $VALGRIND $samba_tool time $SERVER $CON
 
 USERPASS=testPass@12%
 echo $USERPASS > $PREFIX/tmpuserpassfile
-testit "add user with kerberos ccache" $VALGRIND $samba_tool user add nettestuser $USERPASS $CONFIGURATION  -k yes $@ || failed=`expr $failed + 1`
+testit "add user with kerberos ccache" $VALGRIND $samba_tool user create nettestuser $USERPASS $CONFIGURATION  -k yes $@ || failed=`expr $failed + 1`
 
 echo "Getting defaultNamingContext"
 BASEDN=`$ldbsearch $options --basedn='' -H ldap://$SERVER -s base DUMMY=x defaultNamingContext | grep defaultNamingContext | awk '{print $2}'`
diff --git a/testprogs/blackbox/test_passwords.sh b/testprogs/blackbox/test_passwords.sh
index f7070c0..ab65294 100755
--- a/testprogs/blackbox/test_passwords.sh
+++ b/testprogs/blackbox/test_passwords.sh
@@ -25,7 +25,7 @@ samba4kinit="$samba4bindir/samba4kinit$EXEEXT"
 samba_tool="$samba4bindir/samba-tool$EXEEXT"
 rkpty="$samba4bindir/rkpty$EXEEXT"
 samba4kpasswd="$samba4bindir/samba4kpasswd$EXEEXT"
-newuser="$samba_tool user add"
+newuser="$samba_tool user create"
 
 . `dirname $0`/subunit.sh
 
-- 
1.7.6.4

