diff --git a/sbin/changeIobStatus.pl b/sbin/changeIobStatus.pl
index 3f5a790cf..a3152a1d7 100644
--- a/sbin/changeIobStatus.pl
+++ b/sbin/changeIobStatus.pl
@@ -16,6 +16,7 @@ BEGIN {
 }
 
 use Getopt::Long;
+use Pod::Usage;
 use strict;
 use WebGUI::Session;
 use WebGUI::User;
@@ -43,52 +44,8 @@ GetOptions(
 	'newStatus:s'=>\$newStatus
 );
 
-
-
-
-
-unless ($configFile && !$help) {
-	print <<STOP;
-
-
-Usage: perl $0 --configfile=<webguiConfig>
-
-	--configFile	WebGUI config file (with no path info). 
-
-Description:	This utility allows you to automate the switching of status
-		for users in the IOB. For instance, you may wish to
-		automatically mark out all users each night that haven't
-		already marked out.
-
-Options:
-
-	--currentStatus	The status to check for. Defaults to "$currentStatus".
-
-	--help		Display this help message.
-
-	--newStatus	The status to set the user to. Defaults to 
-			"$newStatus".
-
-	--quiet         Disable output unless there's an error.
-
-	--userMessage	A message to be sent to the user upon getting their
-			status changed. Defaults to "$userMessage".
-
-	--userMessageFile	A path to a filename to override the
-			--userMessage with. This option will read the
-			contents of the file and send that as the
-			message.
-
-	--whatsHappening	The message attached to the IOB when 
-			changing status. Defaults to 
-			"$whatsHappening".
-
-STOP
-	exit;
-}
-
-
-
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless $configFile;
 
 print "Starting up...\n" unless ($quiet);
 my $session = WebGUI::Session->open($webguiRoot,$configFile);
@@ -146,3 +103,80 @@ $session->var->end;
 $session->close;
 print "OK\n" unless ($quiet);
 
+__END__
+
+=head1 NAME
+
+changeIobStatus - Automate WebGUI's InOut Board User status switching.
+
+=head1 SYNOPSIS
+
+ changeIobStatus --configFile config.conf
+                 [--currentStatus status]
+                 [--newStatus status]
+                 [--userMessage text|--userMessageFile pathname]
+                 [--whatsHappening text]
+                 [--quiet]
+
+ changeIobStatus --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script helps you switch one or more user status
+in the InOut Board (IOB). For instance, you might want to run it
+from cron each night to automatically mark out all users that haven't
+already marked out.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--currentStatus status>
+
+Check users in the IOB having B<status> status. If left unspecified,
+it will default to C<In>.
+
+=item C<--newStatus status>
+
+Change users status in the IOB to B<status> status. If left unspecified,
+it will default to C<Out>.
+
+=item C<--userMessage msg>
+
+Text of the message to be sent to the user after changing the status.
+If left unspecified it will default to
+
+    You were logged out of the In/Out Board automatically.
+
+=item C<--userMessageFile pathname>
+
+Pathname to a file whose contents will be sent to the user after changing
+the status. Using this option overrides whatever messages is set
+with C<--userMessage> (see above).
+
+=item C<--whatsHappening text>
+
+The message attached to the InOut Board when changing status. If left
+unspecified it defaults to
+
+    Automatically signed out.
+
+=item C<--quiet>
+
+Disable all output unless there's an error.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/diskUsage.pl b/sbin/diskUsage.pl
index 5ba3a6e7a..6351306e0 100644
--- a/sbin/diskUsage.pl
+++ b/sbin/diskUsage.pl
@@ -10,6 +10,7 @@
 
 use lib "../lib";
 use Getopt::Long;
+use Pod::Usage;
 use strict;
 use WebGUI::Session;
 use WebGUI::Asset;
@@ -36,47 +37,8 @@ GetOptions(
     'help!'	  =>\$help,	
 );
 
-if ($help || !$configFile) {
-
-	print <<__EOH;
-
-usage perl $0
-
-Description:	This utility is modeled after the *nix 'du' utility.
-
-		It displays the amount of disk space used by an asset and
-		it's descendants.
-
-Options:
-
-	--assetId	AssetId to use as starting point for calculating
-			disk usage.  Defaults to the WebGUI default page
-			defined in the sites settings.
-	
-	--assetUrl	Relative asset URL to use as starting point for
-			calculating (i.e., /home) disk usage.  Defaults to the
-			WebGUI default page defined in the sites settings.
-	
-	--blockSize	Numeric value to change the unit of measure for
-			the amount of disk space used.  Defaults to 1
-			(bytes)
-			
-	--help		Display this help message
-	
-	--norecurse	Returns the disk space used by the starting asset only.
-	
-	--quiet		Display nothing but the amount of disk space used.
-			This value will respect the blockSize and recurse
-			parameters when calculating it's output.
-			
-	--summary	Display only the total amount of disk space used in a
-			human readable format.
-	
-	--configFile	WebGUI config file to use.  This parameter is required.
-	
-__EOH
-	exit;
-}
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless $configFile;
 
 my $session = start();
 du();
@@ -158,4 +120,82 @@ sub du {
 	}
 }
 
+__END__
 
+=head1 NAME
+
+diskUsage - Display amount of disk space used by a WebGUI asset
+            an its desecendants.
+
+=head1 SYNOPSIS
+
+
+ diskUsage --configFile config.conf
+           [--assetId id]
+	   [--assetUrl url]
+           [--blockSize bytes]
+	   [--norecurse]
+	   [--quiet]
+	   [--summary]
+
+ diskUsage --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script displays the amount of disk space used by
+an asset and it's descendants. It has been modeled after the *nix 'du'
+utility.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--assetId id>
+
+Calculate disk usage starting from WebGUI's Asset identified by C<id>.
+If this parameter is not supplied, calculations will start from
+WebGUI's default page as defined in the Site settings.
+
+=item C<--assetUrl url>
+
+Calculate disk usage starting from the particular URL given by C<url>,
+which must be relative to the server (e.g. C</home> instead of
+C<http://your.server/home>). If this parameter is not supplied, calculations
+will start from WebGUI's default page as defined in the Site settings.
+
+=item C<--blockSize bytes>
+
+Use C<bytes> as scaling factor to change the units in which disk space
+will be reported. If this parameter is not supplied, it defaults to C<1>,
+hence the results will be expressed in bytes. If you want to have kb,
+use C<--blockSize 1024>.
+
+=item C<--norecurse>
+
+Prevent recursive calculation of disk space. This effectively computes
+the used disk space for the starting Asset only, without including
+its descendants.
+
+=item C<--quiet>
+
+Just display the total amount of disk space as a raw value.
+
+=item C<--summary>
+
+Just display the total amount of disk space in a human readable format.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/fileImport.pl b/sbin/fileImport.pl
index 8e6148db2..9bfa8b71e 100644
--- a/sbin/fileImport.pl
+++ b/sbin/fileImport.pl
@@ -24,6 +24,7 @@ use File::stat;
 use FileHandle;
 use Getopt::Long;
 use POSIX;
+use Pod::Usage;
 use strict;
 use WebGUI::Asset::File;
 use WebGUI::Asset::File::Image;
@@ -70,103 +71,9 @@ GetOptions(
 	'ignoreExtInName'  => \$ignoreExtInName
 );
 
-
-if ($configFile eq "" || $pathToFiles eq "" || $parentAssetId eq "") {
-	printHelp();
-	exit 4;
-};
-
-if ($help) {
-	printHelp();
-	exit 1;
-}
-
-sub printHelp {
-	print <<STOP;
-
-
-Usage: perl $0 --pathToFiles=<pathToImportFiles> --configfile=<webguiConfig> --parentAssetId=<assetId>
-
-	--configFile		WebGUI config file.
-
-	--pathToFiles		Folder containing files to import.
-
-	--parentAssetId		The asset ID of the asset you wish
-				to attach these files to.
-
-
-Options:
-
-	--groupToEdit		The group ID of the group that should
-				have the privileges to edit these
-				files. Defaults to '4' (Content Managers).
-
-	--groupToView		The group ID of the group that should
-				have the privileges to view these
-				files. Defaults to '7' (Everybody).
-
-	--help			Display this help message and exit.
-
-	--owner			The user ID of the user that should
-				have the privileges to modify these
-				files. Defaults to '3' (Admin).
-
-	--override		This utility is designed to be run as
-				a privileged user on Linux style systems.
-				If you wish to run this utility without
-				being the super user, then use this flag,
-				but note that it may not work as
-				intended.
-
-	--quiet			Disable output unless there's an error.
-
-	--webUser		The user that your web server runs as.
-				Defaults to 'apache'.
-
-	--skipOlderThan		An interval defined in second to skip file older than.
-				Defaults "nothing skip".
-
-	--findByExt		Import only files files with an extension matching 
-				one of the exensions.
-				Defaults "import all files".
-
-	--recursive		Import the files recursivelly from the folder --pathToFiles
-				Defaults "don't run recursivelly"
-
-	--overwrite		Overwrite any matching file URL with the new file rather
-				than creating a new Asset for the file.
-				Instanciate the existing asset and replace the file.
-
-	--ignoreExtInName	Title and menuTitle database fields should not contain the
-				extension of the filename.
-
-
-EXIT STATUS
-
-  The following exit values are returned:
-
-  0
-	Successful execution.
-
-  1
-	For Windows User, stop the script if not super user.
-
-  2
-	A folder can't be open for reading.
-
-  3
-	In recursive mode, if two files has the same name and are selected to be imported. Return this error.
-
-  4
-	Error during invocation of the command.
-
-  5
-	The parent Asset Id doesn't exists.
-
-
-
-STOP
-}
+pod2usage( verbose => 2 ) if $help;
+pod2usage( exitval => 4)
+  if ($configFile eq "" || $pathToFiles eq "" || $parentAssetId eq "");
 
 my $slash = ($^O =~ /^Win/i) ? "\\" : "/";
 
@@ -405,3 +312,134 @@ sub skipFilter {
 	return 0;
 }
 
+__END__
+
+=head1 NAME
+
+fileImport - Import files into WebGUI's Asset Manager.
+
+=head1 SYNOPSIS
+
+ fileImport --configFile config.conf --pathToFiles path
+            --parentAssetID id
+            [--groupToEdit group]
+            [--groupToView group]
+            [--owner id]
+            [--findByExt ext1,ext2,...]
+            [--ignoreExtInName]
+            [--webUser username]
+            [--recursive]
+            [--overwrite]
+            [--override]
+            [--quiet]
+
+ fileImport --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script imports files into WebGUI's Asset Manager
+attached to a specified parent Asset, helping bulk uploads of content.
+
+This utility is designed to be run as a superuser on Linux systems,
+since it needs to be able to put files into WebGUI's data directories
+and change ownership of files. If you want to run this utility without
+superuser privileges, use the C<--override> option described below.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--pathToFiles path>
+
+Path to a folder containing the files to import. This parameter is required.
+
+=item C<--parentAssetId id>
+
+Attach the imported files to the Asset C<id> in WebGUI's Asset Manager.
+This parameter is required.
+
+=item C<--groupToEdit id>
+
+Make members of WebGUI's group identified by C<id> be able to edit
+the uploaded files. If left unspecified, it defaults to Group ID 4,
+(Content Managers).
+
+=item C<--groupToView id>
+
+Make members of WebGUI's group identified by C<id> be able to view
+the uploaded files. If left unspecified, it defaults to Group ID 7,
+(Everybody).
+
+=item C<--owner id>
+
+Make WebGUI's user identified by C<id> own the uploaded files. If
+left unspecified, it defaults to User ID 3 (Admin).
+
+=item C<--webUser username>
+
+The system user that your web server runs as. If left unspecified
+it will default to C<www-data>.
+
+=item C<--override>
+
+This flag will allow you to run this utility without being the super user,
+but note that it may not work as intended.
+
+=item C<--skipOlderThan interval>
+
+Skip files older than C<interval> seconds. If left unspecified, it
+will default to skip no files.
+
+=item C<--findByExt patterns>
+
+Import only those files with matching file extensions. C<patterns>
+is a list of comma-separated extensions to match. If left unspecified,
+it will default to import all files.
+
+=item C<--recursive>
+
+Import files recursively. If left unspecified, only files in the
+folder will be imported, without following subfolders.
+
+=item C<--overwrite>
+
+Overwrite any matching file URL with the new file rather than
+creating a new Asset for the file. Instantiate the existing asset
+and replace the file.
+
+=item C<--ignoreExtInName>
+
+Do not include the filename extension in the Title and menuTitle
+database fields.
+
+=item C<--quiet>
+
+Disable all output unless there's an error.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 EXIT VALUES
+
+The following exit values are returned upon completion:
+
+  0  Successful execution.
+  1  Stop the script if not super user.
+  2  A folder can't be opened for reading.
+  3  Two files had the same name and were selected to be imported
+     during recursive mode.
+  4  Missing required parameter.
+  5  Specified parent AssetId does not exist.
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/generateContent.pl b/sbin/generateContent.pl
index 57f8209b4..77803eca8 100644
--- a/sbin/generateContent.pl
+++ b/sbin/generateContent.pl
@@ -19,6 +19,7 @@ BEGIN {
 use DBI;
 use FileHandle;
 use Getopt::Long;
+use Pod::Usage;
 use strict qw(subs vars);
 use WebGUI::Session;
 use WebGUI::Asset;
@@ -39,35 +40,8 @@ GetOptions(
 	'url=s'=>\$url
 );
 
-if ($help || $configFile eq '' || !($assetId||$url)) {
-	print <<STOP;
-
-
-Usage: perl $0 --configFile=<webguiConfig> --url=home
-
-Options:
-
-	--configFile    WebGUI config file (with no path info).
-
-
-	--assetId       Set the asset to be generated.
-
-        --help		Displays this message.
-
-	--styleId	Set an alternate style for the page.
-			Defaults to asset's default style.
-
-	--toFile	Set the path and filename to write the
-			content to instead of standard out.
-
-	--url		The URL of the asset to be generated.
-
-	--userId	Set the user that should view the page.
-			Defaults to "1" (Visitor).
-
-STOP
-	exit;
-}
+pod2usage( verbose => 2 ) if $help;
+pod2usage() if ($configFile eq '' || !($assetId||$url) );
 
 # Open WebGUI session
 my $session = WebGUI::Session->open($webguiRoot,$configFile);
@@ -104,3 +78,74 @@ $session->close;
 
 exit;
 
+__END__
+
+=head1 NAME
+
+generateContent - Generate content for a specified Asset
+
+=head1 SYNOPSIS
+
+ generateContent --configFile config.conf {--url home|--assetID id}
+                 [--styleId id]
+                 [--toFile pathname]
+                 [--userId id]
+
+ generateContent --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script generates content for an Asset specified
+either by its URL or its Asset ID. The content is sent to standard
+output or to a filename.
+
+A particular WebGUI UserId can be specified as a viewer, in order
+to check whether the content is correctly generated or not, being
+possible to specify any of the available WebGUI styles to format
+the generated content.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--assetId id>
+
+Generate content for WebGUI's Asset identified by C<id>. Either this
+parameter or C<--url> must be supplied.
+
+=item C<--url url>
+
+Generate content for WebGUI's Asset located at C<url>, which must be
+relative to the server (e.g. C</home> instead of C<http://your.server/home>).
+Either this parameter or C<--assetID> must be supplied.
+
+=item C<--styleId id>
+
+Use the WebGUI style specified by the AssetID C<id>. If left unspecified,
+it defaults to using the Asset's default style.
+
+=item C<--toFile pathname>
+
+Send generated content to the specified filename. If left unspecified,
+content is sent to standard output.
+
+=item C<--userId id>
+
+Set a specific WebGUI user to act as content viewer. If left unspecified,
+defaults to C<1> (Visitor).
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/maintenanceMode.pl b/sbin/maintenanceMode.pl
index c1a5b659c..cb9c4fbc5 100644
--- a/sbin/maintenanceMode.pl
+++ b/sbin/maintenanceMode.pl
@@ -17,6 +17,7 @@ BEGIN {
 }
 
 use Getopt::Long;
+use Pod::Usage;
 use strict;
 use WebGUI::Session;
 
@@ -32,30 +33,58 @@ GetOptions(
     'configFile=s'=>\$configFile
   );
 
-if ($help || $configFile eq ""){
-        print <<STOP;
+pod2usage( verbose => 2 ) if $help;
+pod2usage() if $configFile eq "";
 
 
-Usage: perl $0 
-
-Options:
-
-        --help          Display this help message and exit.
-
-    --configFile    The config file for the site.
-
-    --start         Turn on maintenance mode (default).
-
-    --stop          Turn off maintenance mode.
-
-
-STOP
-        exit;
-}
-
 my $session = WebGUI::Session->open($webguiRoot,$configFile);
 $session->setting->remove('specialState');
 $session->setting->add('specialState','upgrading') unless $stop;
 $session->var->end;
 $session->close;
 
+__END__
+
+=head1 NAME
+
+maintenanceMode - Set WebGUI site into maintenance mode.
+
+=head1 SYNOPSIS
+
+maintenanceMode --configFile config.conf [--start|--stop]
+
+maintenanceMode --help
+
+=head1 DESCRIPTION
+
+This utility script will set or unset WebGUI's C<specialState>
+setting to signal the beginning or end of Maintenance Mode.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--start>
+
+Set C<specialState> to signal the beginning of maintenance mode.
+This is the default behaviour.
+
+=item C<--stop>
+
+Unset C<specialState> to signal the end of maintenance mode.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/migrateCollabToGallery.pl b/sbin/migrateCollabToGallery.pl
index be9ab59ef..85ca41d78 100644
--- a/sbin/migrateCollabToGallery.pl
+++ b/sbin/migrateCollabToGallery.pl
@@ -68,7 +68,7 @@ sub start {
 
     # Show usage
     if ($help) {
-        pod2usage(1);
+        pod2usage( verbose => 2);
     }
     
     unless ($configFile) {
@@ -95,42 +95,50 @@ sub finish {
     $session->close;
 }
 
+__END__
 
 =head1 NAME
 
-migrateCollabToGallery.pl -- Migrate a collaboration system into a Gallery
+migrateCollabToGallery -- Migrate a collaboration system into a Gallery
 
 =head1 SYNOPSIS
 
-migrateCollabToGallery.pl --configFile=<config> <collab> <gallery>
+migrateCollabToGallery --configFile config.conf collab gallery
 
-=head1 ARGUMENTS
-
-=over
-
-=item collab 
-
-A collaboration system URL or asset ID. The URL must be an absolute URL, and
-so must begin with a "/".
-
-=item gallery 
-
-A Gallery URL or asset ID. The URL must be an absolute URL, and so much begin
-with a "/".
-
-=back
-
-=head1 OPTIONS
-
-=over
-
-=item configFile
-
-The WebGUI config file to use.
-
-=back
+migrateCollabToGallery --help
 
 =head1 DESCRIPTION
 
-This script migrates a collaboration system's threads into gallery albums. It
-uses C<WebGUI::Utility::Gallery> for its major features.
+This WebGUI utility script migrates a collaboration system's threads
+into gallery albums. It uses C<WebGUI::Utility::Gallery> for its major
+features.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<collab>
+
+A WebGUI's Collaboration System URL or Asset ID. If an URL is given,
+it must be an absolute URL beginning with a slash.
+
+=item C<gallery>
+
+A WebGUI's Gallery URL or Asset ID. If an URL is given, it must be
+an absolute URL beginning with a slash.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/purgeWGAccess.pl b/sbin/purgeWGAccess.pl
index e28e714df..c17ead8a3 100644
--- a/sbin/purgeWGAccess.pl
+++ b/sbin/purgeWGAccess.pl
@@ -1,13 +1,18 @@
 use lib "../lib";
 use strict;
 use Getopt::Long;
+use Pod::Usage;
 use WebGUI::Config;
 
 local $| = 1; #disable output buffering
 GetOptions(
     'configFile=s' => \(my $configFile),
-    'configFile=s' => \(my $configFile),
+    'help'         => \(my $help),
 );
+
+pod2usage( verbose => 2 ) if $help;
+pod2usage() if $configFile eq '';
+
 my $config = WebGUI::Config->new("..",$configFile);
 use File::Find;
 
@@ -28,3 +33,42 @@ File::Find::find({wanted => sub {
     }
 }}, $uploadsPath);
 
+__END__
+
+=head1 NAME
+
+purgeWGAccess - Clean up unneeded .wgaccess files from WebGUI repository
+
+=head1 SYNOPSIS
+
+ purgeWGAccess --configFile config.conf
+
+ purgeWGAccess --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script removes unneeded .wgaccess files from
+a specific site's upload directory. The script finds all the
+.wgaccess files recursively starting from the upload path for
+the WebGUI site specified in the given configuration file and
+removes it.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/rebuildLineage.pl b/sbin/rebuildLineage.pl
index 01cf494a2..eaa5c05b3 100644
--- a/sbin/rebuildLineage.pl
+++ b/sbin/rebuildLineage.pl
@@ -19,6 +19,7 @@ BEGIN {
 $| = 1;
 
 use Getopt::Long;
+use Pod::Usage;
 use strict;
 use WebGUI::Session;
 use WebGUI::Utility;
@@ -33,37 +34,8 @@ GetOptions(
         'quiet'=>\$quiet,
 );
 
-
-if ($help || $configFile eq ""){
-        print <<STOP;
-
-
-Usage: perl $0 --configfile=<webguiConfig>
-
-This utility will rebuild your WebGUI Lineage Tree. The lineage tree is an
-index that is used to make WebGUI run faster. It will also detect and fix
-orphan data, and detect cirular relationships in your tree.
-
-WARNING: Use this tool only if you know what you're doing. It should only
-be used if somehow your lineage tree has become corrupt (very rare) or if
-you have done some massive reorganization of your asset tree and you want
-to fill in the gaps between the ranks of your assets. A side effect of
-using this utility can be that your assets may no longer be in the same rank
-as they once were, which means that they may appear out of order in your
-navigation.
-
-        --configFile	WebGUI config file.
-
-Options:
-
-        --help		Display this help message and exit.
-
-	--quiet		Disable output unless there's an error.
-
-STOP
-	exit;
-}
-
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless (defined($configFile) && $configFile ne '');
 
 print "Starting..." unless ($quiet);
 my $session = WebGUI::Session->open($webguiRoot,$configFile);
@@ -153,3 +125,53 @@ sub printChange {
 	print sprintf("%-25s",$assetId).sprintf("%-51s",$oldLineage).$newLineage."\n" unless ($quiet);
 }
 
+__END__
+
+=head1 NAME
+
+rebuildLineage - Rebuild WebGUI Lineage Tree.
+
+=head1 SYNOPSIS
+
+ rebuildLineage --configFile config.conf
+
+ rebuildLineage --help
+
+=head1 DESCRIPTION
+
+WebGUI's Lineage Tree is an index that helps WebGUI run faster, if
+built propely. This utility will rebuild your WebGUI Lineage Tree,
+detect and fix orphaned data, and circular relationships (loops)
+in the tree.
+
+B<WARNING>: Use this tool only if you know what you're doing. It should
+only be used if somehow your lineage tree has become corrupt (very rare)
+or if you have done some massive reorganization of your asset tree and
+you want to fill in the gaps between the ranks of your assets. A side
+effect of using this utility can be that your assets may no longer be
+in the same rank as they once were, which means that they may appear
+out of order in your navigation.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--quiet>
+
+Disable all output unless there's an error.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/search.pl b/sbin/search.pl
index 86bfa6a1a..caeef2e76 100644
--- a/sbin/search.pl
+++ b/sbin/search.pl
@@ -17,6 +17,7 @@ use WebGUI::Session;
 use WebGUI::Search;
 use WebGUI::Search::Index;
 use Time::HiRes;
+use Pod::Usage;
 
 $|=1;
 my $search = "";
@@ -35,6 +36,8 @@ GetOptions(
 	'updatesite'=>\$updatesite
 	);
 
+pod2usage( verbose => 2 ) if $help;
+
 if ($configFile) {
 	my $session = WebGUI::Session->open("..", $configFile);
 	if ($indexsite) {
@@ -44,51 +47,16 @@ if ($configFile) {
 	} elsif ($search) {
 		searchSite($session, $search);
 	} else {
-		displayHelp();
+		pod2usage();
 	}
 	$session->var->end;
 	$session->close;
 } elsif ($indexAll) {
 	reindexAllSites();
 } else {
-	displayHelp();
+	pod2usage();
 }
 
-#-------------------------------------------------------------------
-sub displayHelp {
-	print <<STOP;
-perl $0 [ options ]
-
-Options:
-
-	--configFile=		The config file of the site you wish to perform
-				an action on.
-
-	--help			Displays this message.
-
-	--indexall		Reindexes all the sites. Note that this can take
-				many hours and will affect the performance of the
-				server during the indexing process.
-
-	--indexsite *		Reindexes the entire site. Note that depending
-				upon the amount of content you have, it may take
-				hours to index a site and server performance will
-				suffer somewhat during the indexing process.
-
-	--search= *		Searches the site for a keyword or phrase and
-				returns the results.
-
-	--updatesite *		Indexes content that has not be indexed, but does not
-				index content that has been indexed. This is useful
-				if the --indexsite option had to be stopped part way
-				through.
-
-	* This option requires the --configFile option.
-
-STOP
-}
-
-
 #-------------------------------------------------------------------
 sub reindexAllSites {
 	my $configs = WebGUI::Config->readAllConfigs("..");
@@ -165,3 +133,73 @@ sub updateSite {
 	print "\nSite indexing took ".Time::HiRes::tv_interval($siteTime)." seconds.\n";
 }
 
+__END__
+
+=head1 NAME
+
+search - Reindex and search a WebGUI site.
+
+=head1 SYNOPSIS
+
+ search --configFile config.conf --indexsite
+
+ search --configFile config.conf --updatesite
+
+ search --configFile config.conf --search text
+
+ search --indexall
+
+ search --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility scripts helps maintaining search indexes on
+any site. It can be used to build the index for an entire site,
+build the index only for new content, and perform searches.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--indexsite>
+
+Reindexes the entire site specified in the config file. This process
+may take a while (even hours) depending on the amount of content the
+site has. Server performance will suffer somewhat during the
+indexing process. This option requires a C<--configFile> to be
+specified.
+
+=item C<--updatesite>
+
+Indexes content that has not be indexed for the site specified in
+the config file, keeping the indexes for already indexed content
+intact. This is useful if the C<--indexsite> had to be stopped
+partway through. This option requires a C<--configFile> to be
+specified.
+
+=item C<--search text>
+
+Searches the site specified in the config file for a given keyword or
+phrase, returning the results. This option requires a C<--configFile>
+to be specified.
+
+=item C<--indexall>
+
+Reindexes B<all> the sites. Note that this can take many hours and
+will affect performance of the server during the indexing process.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/spectre.pl b/sbin/spectre.pl
index eea7fa8eb..7835d006a 100644
--- a/sbin/spectre.pl
+++ b/sbin/spectre.pl
@@ -8,6 +8,7 @@
 # http://www.plainblack.com                     info@plainblack.com
 #-------------------------------------------------------------------
 
+use Pod::Usage;
 use strict;
 use warnings;
 use lib '../lib';
@@ -37,38 +38,8 @@ GetOptions(
 	'test' => \$test
 	);
 
-if ($help || !($ping||$shutdown||$daemon||$run||$test||$status)) {
-	print <<STOP;
-
-	S.P.E.C.T.R.E. is the Supervisor of Perplexing Event-handling Contraptions for 
-	Triggering Relentless Executions. It triggers WebGUI's workflow and scheduling
-	functions.
-
-	Usage: perl spectre.pl [ options ]
-
-
-	Options:
-
-	--daemon	Starts the Spectre server.
-
-	--debug		If specified at startup, Spectre will provide verbose
-			debug to standard out so that you can see exactly what
-			it's doing.
-
-	--ping		Checks to see if Spectre is alive.
-
-	--run		Starts Spectre without forking it as a daemon.
-
-	--shutdown	Stops the running Spectre server.
-
-	--status	Returns a report about the internals of Spectre.
-
-	--test		Tests the connection between Spectre and WebGUI. Both Spectre
-			and WebGUI must be running to use this function.
-
-STOP
-	exit;
-}
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless ($ping||$shutdown||$daemon||$run||$test||$status);
 
 require File::Spec;
 my $config = WebGUI::Config->new(File::Spec->rel2abs(".."),"spectre.conf",1);
@@ -76,8 +47,9 @@ unless (defined $config) {
 	print <<STOP;
 
 
-Cannot open  the Spectre config file. Check that ../etc/spectre.conf exists,
-and that it has the proper privileges to be read by the Spectre server.
+Cannot open the Spectre config file.
+Check that /etc/webgui/spectre.conf exists, and that it has the proper
+privileges to be read by the Spectre server.
 
 
 STOP
@@ -153,3 +125,94 @@ sub getStatusReport {
 	return $result;
 }
 
+__END__
+
+=head1 NAME
+
+spectre - WebGUI's workflow and scheduling.
+
+=head1 SYNOPSIS
+
+ spectre {--daemon|--run} [--debug]
+
+ spectre --shutdown
+
+ spectre --ping
+
+ spectre --status
+
+ spectre --test
+
+ spectre --help
+
+=head1 DESCRIPTION
+
+S.P.E.C.T.R.E. is the Supervisor of Perplexing Event-handling
+Contraptions for Triggering Relentless Executions. It triggers
+WebGUI's workflow and scheduling functions.
+
+Spectre's configuration file, C<spectre.conf>, is located under
+the WebGUI filesystem hierarchy.
+
+=over
+
+=item C<--daemon>
+
+Starts the Spectre server forking as a background daemon. This
+can be done by hand, but it is usually handled by a startup
+script.
+
+=item C<--run>
+
+Starts Spectre in the foreground without forking as a daemon.
+
+=item C<--debug>
+
+If this option is specified at startup either in C<--daemon>
+or C<--run> mode, Spectre will provide verbose debug to standard
+output so that you can see exactly what it's doing.
+
+=item C<--shutdown>
+
+Stops the running Spectre server.
+
+=item C<--ping>
+
+Pings Spectre to see if it is alive. If Spectre is alive, you'll get
+confirmation with a message like
+
+    Spectre is alive!
+
+If Spectre doesn't seem to be alive, you'll get a message like
+
+    Spectre is not responding.
+    Unable to connect to <IP-address>:<Port>
+
+where C<IP-address> is the IP address and C<Port> is the port number
+where Spectre should be listening for connections on according to
+C<spectre.conf>.
+
+=item C<--status>
+
+Shows a summary of Spectre's internal status. The summary contains
+a tally of suspended, waiting and running WebGUI Workflows.
+
+=item C<--test>
+
+Tests whether Spectre can connect to WebGUI. Both Spectre
+and the Apache server running WebGUI must be running for this
+option to work. It will test the connection between every site
+and Spectre, by looking for configuration files in WebGUI's
+configuration directory, showing success or failure in each case.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/testCodebase.pl b/sbin/testCodebase.pl
index ea6673291..5166a72da 100644
--- a/sbin/testCodebase.pl
+++ b/sbin/testCodebase.pl
@@ -15,6 +15,7 @@ use FindBin;
 use lib "$FindBin::Bin/../t/lib";
 use File::Spec qw[];
 use Getopt::Long;
+use Pod::Usage;
 
 my $configFile;
 my $help;
@@ -32,32 +33,8 @@ GetOptions(
 	'coverage'=>\$coverage,
 	);
 
-my $helpmsg=<<STOP;
-
-	perl $0 --configFile
-
-	--configFile		The config file of the WebGUI site you'll use
-				to test the codebase. Note that you should not
-				use a production config file as some tests may
-				be destructive.
-
-	--coverage		Turns on additional coverage tests. Note that
-				this can take a long time to run.
-
-	--noLongTests		Prevent long tests from being run
-
-	--perlBase		The path of the perl installation you want to 
-				use. Defaults to the perl installation in your
-				PATH.
-
-	--verbose		Turns on additional output.
-
-STOP
-
-if ($help) {
-    print $helpmsg;
-    die "\n";
-}
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless $configFile ne '';
 
 my $verboseFlag = "-v" if ($verbose);
 
@@ -86,3 +63,67 @@ $prefix .= " HARNESS_PERL_SWITCHES='-MDevel::Cover=-db,/tmp/coverdb'" if $covera
 print(join ' ', $prefix, $perlBase."prove", $verboseFlag, '-r ../t'); print "\n";
 system(join ' ', $prefix, $perlBase."prove", $verboseFlag, '-r ../t');
 
+__END__
+
+=head1 NAME
+
+testCodebase - Test WebGUI's code base.
+
+=head1 SYNOPSIS
+
+ testCodebase --configFile config.conf
+              [--coverage]
+              [--noLongTests]
+              [--perlBase path]
+              [--verbose]
+
+ testCodebase --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script tests all of WebGUI's installed code base
+using a particular confiuration file. It uses C<prove> to run all
+the WebGUI supplied test routines, located in the C<t> subdirectory
+of the WebGUI root.
+
+You should B<NOT> use a production config file for testing, since some
+of the test may be destructive.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory. Be
+aware that some of the tests may be destructive. This parameter is required.
+
+=item C<--coverage>
+
+Turns on additional L<Devel::Cover> based coverage tests. Note that
+this can take a long time to run.
+
+=item C<--noLongTests>
+
+Prevent long tests from being run
+
+=item C<--perlBase path>
+
+Specify a path to an alternative Perl installation you wish to use for the
+tests. If left unspecified, it defaults to the Perl installation in the
+current PATH.
+
+=item C<--verbose>
+
+Turns on additional information during tests.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/testEnvironment.pl b/sbin/testEnvironment.pl
index eb9a4fa7e..9f40554c6 100644
--- a/sbin/testEnvironment.pl
+++ b/sbin/testEnvironment.pl
@@ -19,10 +19,9 @@ BEGIN {
 use strict;
 use CPAN;
 use Getopt::Long;
+use Pod::Usage;
 
 
-print "\nWebGUI is checking your system environment:\n\n";
-
 my ($os, $prereq, $dbi, $dbDrivers, $simpleReport, $help);
 
 GetOptions(
@@ -30,21 +29,9 @@ GetOptions(
 	'help'=>\$help
 );
 
-if ($help){
-        print <<STOP;
+pod2usage( verbose => 2 ) if $help;
 
-
-Usage: perl $0 
-
-Options:
-	
-   --help         Display this help message and exit.
-   --simpleReport Print a status report to stdout and do not upgrade any perl modules
-
-
-STOP
-        exit;
-}
+print "\nWebGUI is checking your system environment:\n\n";
 
 $prereq = 1;
 
@@ -395,5 +382,46 @@ sub prompt {
         return $answer;
 }
 
+__END__
 
+=head1 NAME
 
+testEnvironment - Test Perl environment for proper WebGUI support.
+
+=head1 SYNOPSIS
+
+ testEnvironment --simpleReport
+
+ testEnvironment --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script tests the current Perl environment to make
+sure all of WebGUI's dependencies are satisfied. It also checks for
+proper installation of WebGUI's libraries.
+
+If any of the required Perl modules is not available or outdated, the
+script will ask if it should attempt installation using CPAN. This will
+only be possible if the script is being run as a superuser.
+
+The script will attempt to find out the latest available version from
+L<http://update.webgui.org>, and compare with the currently installed one.
+
+=over
+
+=item C<--simpleReport>
+
+Prints the status report to standard output, but does not attempt
+to upgrade any outdated or missing Perl modules.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/thumbnailer.pl b/sbin/thumbnailer.pl
index 62adbaf5c..518eef3a0 100644
--- a/sbin/thumbnailer.pl
+++ b/sbin/thumbnailer.pl
@@ -17,6 +17,7 @@ use Carp qw(croak);
 use File::stat;
 use File::Find ();
 use Getopt::Long;
+use Pod::Usage;
 
 my $graphicsPackage;
 BEGIN {
@@ -46,20 +47,8 @@ my $ok = GetOptions(
 	'path=s'=>\$path
 );
 
-if ($help || !($path && $ok) ) {
-  print <<USAGE;
-Usage: perl $0 --path=/path/to/files [--size=thumbnailSize] [--missing]
-
---path is the complete path to your uploads directory
-
---size=thumbSize allows you to override the default thumbnail size of 50.
-
---missing says to only create thumbnails for images that are missing thumbnails.
-
-USAGE
-
-exit 0;
-}
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless $path;
 
 $thumbnailSize ||= 50; ##set default
 
@@ -124,3 +113,59 @@ sub getType {
         my ($extension) = $fileName =~ m/(\w+)$/;
         return lc($extension);
 }
+
+__END__
+
+=head1 NAME
+
+thumbnailer - Create thumbnails for WebGUI's uploaded graphic files
+
+=head1 SYNOPSIS
+
+ thumbnailer --path path
+             [--size thumbnailSize]
+	     [--missing]
+
+ thumbnailer --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script generates thumbnails for WebGUI's uploaded
+graphic files. The script finds all the graphic files recursively
+starting from the specified path; it will skip those files that already
+have thumbnails, and create PNG thumbnails for the rest.
+
+Files with JPG, JPEG, GIF, PNG, TIF, TIFF and BMP extensions are
+regarded as graphic files.
+
+The thumbnails are created using L<Graphics::Magick> or L<Image::Magick>
+for image transformations.
+
+=over
+
+=item C<--path path>
+
+Specifies the absolute C<path> to WebGUI's uploads directory.
+This parameter is required.
+
+=item C<--size thumbSize>
+
+Specify the size in pixels of the largest dimension of the thumbanils.
+If left unspecified, it defaults to 50 pixels.
+
+=item C<--missing>
+
+Use this option to create thumbnails only for those images that are
+missing thumbnails.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/upgrade.pl b/sbin/upgrade.pl
index b9d851640..b67636dbd 100644
--- a/sbin/upgrade.pl
+++ b/sbin/upgrade.pl
@@ -19,6 +19,7 @@ use strict;
 use DBI;
 use File::Path;
 use Getopt::Long;
+use Pod::Usage;
 use WebGUI::Config;
 use WebGUI::Session;
 use WebGUI::Utility;
@@ -49,63 +50,8 @@ GetOptions(
 	'skipbackup'=>\$skipBackup
 );
 
-
-if ($help){
-        print <<STOP;
-
-
-Usage: perl $0 --doit
-
-Options:
-
-	--backupDir	The folder where backups should be
-			created. Defaults to '$backupDir'.
-
-	--doit		This flag is required. You MUST include this
-			flag in your command line or the upgrade
-                        will not run.
-
-        --help          Display this help message and exit.
-
-	--history	Displays the upgrade history for each of
-			your sites. Note that running with this
-			flag will NOT run the upgrade.
-
-	--mysql		The path to your mysql client executable.
-			Defaults to '$mysql'.
-
-	--mysqldump	The path to your mysqldump executable.
-			Defaults to '$mysqldump'.
-
-        --override      This utility is designed to be run as
-                        a privileged user on Linux style systems.
-                        If you wish to run this utility without
-                        being the super user, then use this flag,
-                        but note that it may not work as
-                        intended.
-
-        --quiet         Disable output unless there's an error.
-
-	--skipBackup	Backups will not be performed during the
-			upgrade.
-
- 	--skipDelete	The upgrade normally deletes WebGUI's cache
-			and temporary files as part of the upgrade.
-			This is mainly important during big upgrades,
-			but can make the upgrade go very slowly.
-			Using this option skips the deletion of these
-			files.
-
-	--skipMaintenance  
-			The upgrade normally puts up a maintenance
-			page on all the sites while running, but this
-			option will skip that step.
-
-STOP
-        exit;
-}
-
-
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless $doit;
 
 unless ($doit) {
 	print <<STOP;
@@ -405,4 +351,116 @@ sub _parseDSN {
      return $hash;
 }
 
+__END__
 
+=head1 NAME
+
+upgrade - Upgrade WebGUI database to the latest revision.
+
+=head1 SYNOPSIS
+
+ upgrade --doit
+         [--backupDir path]
+         [--history]
+         [--mysql pathname]
+         [--mysqldump pathname]
+         [--override]
+         [--skipBackup]
+         [--skipDelete]
+         [--skipMaintenance]
+         [--quiet]
+
+ upgrade --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script is able to upgrade B<any> WebGUI database
+from 7.3.22 upward to the currently installed version. The WebGUI
+software distribution includes a set of upgrade scripts that
+perform the necessary database changes (schema and data) to bring
+the database up-to-date in order to match the currently installed
+WebGUI libraries and programs.
+
+This utility is designed to be run as a superuser on Linux systems,
+since it needs to be able to access several system directories
+and change ownership of files. If you want to run this utility without
+superuser privileges, use the C<--override> option described below.
+
+=head1 WARNING
+
+There are B<NO> guarantees of any kind provided with this software.
+This utility has been tested rigorously, and has performed without
+error or consequences in our labs, and on our production servers
+for many years. However, there is no substitute for a good backup
+of your software and data before performing any kind of upgrade.
+
+B<BEFORE YOU UPGRADE> you should definitely read docs/gotcha.txt to
+find out what things you should know about that will affect your
+upgrade.
+
+=over
+
+=item C<--doit>
+
+You B<MUST> include this flag in the command line or the script
+will refuse to run. This is to force you to read this documentation
+at least once and be sure that you B<REALLY> want to perform the
+upgrade.
+
+=item C<--backupDir path>
+
+Specify a path where database backups should be created during the
+upgrade procedure. If left unspecified, it defaults to C</var/backups>.
+
+=item C<--history>
+
+Displays the upgrade history for each of your sites. Running with this
+flag will B<NOT> perform the upgrade.
+
+=item C<--mysql pathname>
+
+The full pathname to your mysql client executable. If left unspecified,
+it defaults to C</usr/bin/mysql>.
+
+=item C<--mysqldump pathname>
+
+The full pathname to your mysqldump executable. If left unspecified,
+it defaults to C</usr/bin/mysqldump>.
+
+=item C<--override>
+
+This flag will allow you to run this utility without being the super user,
+but note that it may not work as intended.
+
+=item C<--skipBackup>
+
+Use this if you B<DO NOT> want database backups to be performed
+during the upgrade procedure.
+
+=item C<--skipDelete>
+
+The upgrade procedure normally deletes WebGUI's cache and temporary files
+created as part of the upgrade. This cleanup is very important during
+large upgrades, but can make the procedure quite slow. This option
+skips the deletion of these files.
+
+=item C<--skipMaintenance>
+
+The upgrade procedure normally puts up a simple maintenance page on all
+the sites while running, but this option will skip that step.
+
+=item C<--quiet>
+
+Disable all output unless there's an error.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut
diff --git a/sbin/userImport.pl b/sbin/userImport.pl
index 60644a6f5..09fb3ba5b 100644
--- a/sbin/userImport.pl
+++ b/sbin/userImport.pl
@@ -18,6 +18,7 @@ BEGIN {
 use strict;
 use Digest::MD5;
 use Getopt::Long;
+use Pod::Usage;
 use WebGUI::DateTime;
 use WebGUI::Group;
 use WebGUI::Session;
@@ -45,8 +46,8 @@ my $replaceGroups;
 my $canChangePass;
 
 GetOptions(
-	'usersfile=s'=>\$usersFile,
-	'configfile=s'=>\$configFile,
+	'usersFile=s'=>\$usersFile,
+	'configFile=s'=>\$configFile,
 	'help'=>\$help,
 	'authMethod:s'=>\$authMethod,
 	'delimiter:s'=>\$delimiter,
@@ -64,130 +65,8 @@ GetOptions(
 	'canChangePass'=>\$canChangePass
 );
 
-
-
-
-
-unless ($usersFile && $configFile && !$help) {
-	print <<STOP;
-
-
-Usage: perl $0 --usersfile=<pathToFile> --configfile=<webguiConfig>
-
-	--usersFile	File (and path) containing import information.
-
-	--configFile	WebGUI config file (with no path info). 
-
-
-Options:
-
-	--authMethod	The authentication method to be used for
-			each user. Defaults to 'WebGUI'. Can be
-			overridden in the import file.
-
-	--canChangePass	If this flag is set users will be able to change
-			their passwords.  Otherwise not.
-
-	--delimiter	The string that separates each field in the
-			import file. Defaults to tab.
-
-	--expireOffset	The the amount of time before the user will
-			be expired from the groups they are added
-			to. Defaults to the expire offset set in
-			the group definition within WebGUI. May be
-			overridden in the import file.
-
-	--expireUnits	Valid values are "seconds", "minutes",
-			"hours", "days", "weeks", "months", "years",
-			"epoch", or "fixed". Defaults to "seconds". This is 
-			the units of the expire offset. If set to
-			"epoch" the system will assume that the
-			expire offset is an epoch date rather than
-			an interval.  If set to "fixed" the 
-			system will assume that the expireDate is
-			a fixed date.
-
-	--groups	A comma separated list of group ids that
-			each user in the import file will be set
-			to. Can be overridden in the import file.
-
-	--help		Display this help message.
-
-	--identifier	Alias for --password.  
-
-	--ldapUrl	The URL used to connect to the LDAP server
-			for authentication. Can be overridden in
-			the import file.
-
-	--override      This utility is designed to be run as
-                        a privileged user on Linux style systems.
-                        If you wish to run this utility without
-                        being the super user, then use this flag,
-                        but note that it may not work as
-                        intended.
-
-	--password	The default password to use when none is 
-			specified with the user. Defaults to 
-			'123qwe'. Can be overridden in the import
-			file.
-
-	--quiet         Disable output unless there's an error.
-
-	--status	The user's account status. Defaults to
-			'Active'. Other valid value is 'Deactivated'.
-	
-	--update	looks up all the users from the file in the database
-				and updates all the given fields for each user that 
-				exists in the database. users that are in the file
-				and not in the database are ignored.
-				
-	--updateAdd	looks up the users from the file in the database
-				and updates all the given fields for each user that
-				exists in the database. users who do not exist in the
-				database are added as new users.
-				
-	--replaceGroups	when updating, if the user already belongs to some group
-					this flag will delete all the user's existing groups and
-					and the new groups to him/her
-
-
-User File Format:
-
-	-Tab delimited fields (unless overridden with --delimiter).
-
-	-First row contains field names.
-
-	-Valid field names:
-	
-		username password authMethod status
-		ldapUrl connectDN groups expireOffset
-
-	-In addition to the field names above, you may use any 
-	valid profile field name.
-	
-	-The special field name 'groups' should contain a comma 
-	separated list of group ids.
-
-
-Special Cases:
-
-	-If no username is specified it will default to 
-	'firstName.lastName'.
-
-	-If firstName and lastName or username are not specified, 
-	the user will be skipped.
-
-	-Invalid field names will be ignored.
-
-	-Blank lines will be ignored.
-
-	-If userId is specified for an import record, that userId
-        be used instead of generating one.
-
-STOP
-	exit;
-}
-
+pod2usage( verbose => 2 ) if $help;
+pod2usage() unless ($usersFile && $configFile);
 
 if (!($^O =~ /^Win/i) && $> != 0 && !$override) {
         print "You must be the super user to use this utility.\n";
@@ -359,3 +238,189 @@ sub calculateExpireOffset {
 	return $session->datetime->intervalToSeconds($offset, $units)
 }
 
+__END__
+
+=head1 NAME
+
+userImport - Bulk load users into WebGUI database
+
+=head1 SYNOPSIS
+
+ userImport --configFile config.conf --usersFile pathname
+            [--authMethod method]
+            [--canChangePasswd]
+            [--delimiter string]
+            [--expireOffset integer [--expireUnits string]]
+            [--groups groupid,...]
+            [--ldapUrl uri]
+            [--password text]
+            [--status status]
+            [--override]
+            [--quiet]
+            [--update | --updateAdd]
+            [--replaceGroups]
+
+ userImport --help
+
+=head1 DESCRIPTION
+
+This WebGUI utility script reads user information from a text file
+and loads them into the specified WebGUI database. Default user
+parameters can be specified through command line options, taking
+overriding values from the file.
+
+This utility is designed to be run as a superuser on Linux systems,
+since it needs to be able to put files into WebGUI's data directories
+and change ownership of files. If you want to run this utility without
+superuser privileges, use the C<--override> option described below.
+
+The user information is given in a simple TAB-delimited text file,
+that describes both the field names and field data for each user. You
+can change de actual delimiter with the C<--delimiter> option (see below).
+
+The first line of the file contains the field names whose values are
+going to be loaded. From then on, all non-blank lines in the file must have
+the same number of fields. All-blank lines are ignored. The valid field
+names are:
+
+=over
+
+=item C<username>
+=item C<password>
+=item C<authMethod>
+=item C<status>
+=item C<ldapUrl>
+=item C<connectDN>
+=item C<groups>
+=item C<expireOffset>
+=item Any valid User Profile field name available in WebGUI's database,
+      e.g. C<firstName>, C<lastName>, C<mail>, etc.
+
+=back
+
+If you use the field C<groups>, each following line  should contain a comma
+separated list of WebGUI Group Ids; note that this could be a problem
+if you chose to use comma as a delimiter for fields.
+
+If no username is specified it will default to C<firstName.lastName>. If
+no C<username> is specified, nor C<firstName> and C<lastName>, then the
+user will B<not> be loaded.
+
+If you specify the C<userId> field for import on any record, that C<userId>
+will be used instead of generating a new one automatically. If you do this,
+be careful not to insert duplicates!
+
+If you use an invalid field name, its values will be ignored.
+
+=over
+
+=item C<--configFile config.conf>
+
+The WebGUI config file to use. Only the file name needs to be specified,
+since it will be looked up inside WebGUI's configuration directory.
+This parameter is required.
+
+=item C<--usersFile pathname>
+
+Pathname to the file containing users information for bulk loading.
+
+=item C<--authMethod method>
+
+Specify the default authentication method to set for each loaded user.
+It can be overridden in the import file for specific users.
+If left unspecified, it defaults to C<WebGUI>.
+
+=item C<--canChangePass>
+
+Set loaded users to be able to change their passwords. If left
+unspecified, loaded users will B<NOT> be able to change their
+passwords until and administrator grants them the privilege.
+
+=item C<--delimiter string>
+
+Specify the string delimiting fields in the import file. If left
+unspecified, it defaults to a single TAB (ASCII 9).
+
+=item C<--expireOffset integer>
+
+Specify the default amount of time before the loaded user will be
+expired from the groups they are added to. The units are specified
+by C<--expireUnits> (see below). It can be overridden in the import
+file for specific users. If left unspecified, it defaults to the
+expire offset set in the group definition within WebGUI.
+
+=item C<--expireUnits unidades>
+
+Specify the units for C<--expireOffset> (see above). Valid values
+are C<seconds>, C<minutes>, C<hours>, C<days>, C<weeks>, C<months>,
+C<years>, C<epoch>, or C<fixed>. If set to C<epoch> the system will
+assume that the expire offset should be taken as an epoch date
+(absolute number of seconds since January 1, 1970) rather than an
+interval. If set to C<fixed> the system will assume that the
+C<--expireOffset> is a fixed date. If left unspecified, it defaults
+to C<seconds>.
+
+=item C<--groups groupid,...>
+
+Specify a comma separated list of WebGUI Group Ids that each loaded
+user will be set to. It can be overridden in the import file for
+specific users.
+
+=item C<--ldapUrl uri>
+
+Specify the URI used to connect to the LDAP server for authentication.
+The URI must conform to what L<Net::LDAP> uses for connecting.
+It can be overridden in the import file for specific users.
+
+=item C<--password string>
+=item C<--identifier string>
+
+Specify the default password to use for loaded users. It can (and should)
+be overriden in the import file for specific users. If left unspecified,
+it defaults to C<123qwe>.
+
+=item C<--status status>
+
+Specify the default account status for loaded users. Valid values are
+C<Active> and C<Deactivated>. If left unspecified, it defaults to
+C<Active>.
+
+=item C<--update>
+
+Search WebGUI's database for each user listed in the import file, and
+update its information using the provided fields. Users in the import
+file that are B<not> found in the database are B<ignored>. See
+C<--updateAdd> below if you want to add the extra users.
+
+=item C<--updateAdd>
+
+Search WebGUI's database for each user listed in the import file, and
+update its information using the provided fields. Users in the import
+file that are B<not> found in the database are B<added>. See
+C<--update> above if you do not want to add the extra users.
+
+=item C<--replaceGroups>
+
+If the user being updated with C<--update> or C<--updateAdd> already
+belongs to some other groups, remove the user from them.
+
+=item C<--override>
+
+This flag will allow you to run this utility without being the super user,
+but note that it may not work as intended.
+
+=item C<--quiet>
+
+Disable all output unless there's an error.
+
+=item C<--help>
+
+Shows this documentation, then exits.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2001-2008 Plain Black Corporation.
+
+=cut