Use Pod::Usage and begin to develop internal documentation in Perl POD

POD is Perl's native documentation format, designed to embed an
approximate equivalent to a man page inside a Perl program or module.
POD can be particularly useful for docstring-like embedded per-function
documentation but has a different purpose from Texinfo, which will be
used when a reference manual is written.

diff --git a/gatekeeper.pl b/gatekeeper.pl
index c213fa2524779cd5ca2b41617a63cd215d84dd4a..62dbf9f8cb8ea9789fc30a57e9faf10372e98e52 100755 (executable)
--- a/gatekeeper.pl
+++ b/gatekeeper.pl
@@ -19,6 +19,65 @@
 #    You should have received a copy of the GNU General Public License
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+=head1 NAME
+
+gatekeeper - process uploaded files
+
+=head1 SYNOPSIS
+
+gatekeeper.pl -B<s> I<style> [-B<d> I<debuglevel>] [-B<v>] [-B<h>]
+
+gatekeeper.pl --B<style> I<style> [--B<debug> I<debuglevel>]
+
+gatekeeper.pl --B<version>
+
+gatekeeper.pl --B<help>
+
+=head1 OPTIONS
+
+=over
+
+=item B<--help>
+
+Show usage information and exit.
+
+=item B<--version>
+
+Show version information and exit.
+
+=item B<--style>
+
+Specify the style to use.  The "style" selects a configuration subset for
+the role the tool should process on this run.  Each role is for a different
+collection of files to be managed.
+
+Currently, styles are hardwired in the tool:
+
+=over
+
+=item ftp
+
+Used for ftp.gnu.org.
+
+=item alpha
+
+Used for alpha.gnu.org.
+
+=item distros
+
+Used for system distributions hosted or mirrored on ftp.gnu.org.
+
+=back
+
+=back
+
+=head1 DESCRIPTION
+
+...
+
+=cut
+
+
 #
 # Short overview
 #
@@ -108,6 +167,7 @@ use Carp qw(cluck); # for stack trace on error in ftp_syslog
 
 use FindBin;
 use File::Spec;
+use Pod::Usage;
 
 use Net::SMTP;
 use Date::Manip;
@@ -199,27 +259,6 @@ our $style;
 our $help;
 our $version;
 
-sub usage_information {
-  print "ERROR: You have not supplied all required parameters.\n\n"
-    unless $_[0];
-  print "$NAME protocol v$VERSION ($DATE)\nMore information at $URL\n";
-  print <<"END";
-
- $NAME -s <style> [-d <debuglevel>] [-v] [-h]\n
-  <style>    is the execution 'style'. Call $NAME
-            without the -s parameter to get a list of possible styles.
-  -d <debuglevel> (optional) set debug level. 0 means no debugging
-  -v (optional)  display version information
-  -h (optional)  display this help screen\n
-Possible styles:\n
-  ftp
-  alpha
-  distros
-
-END
-  exit ((defined $_[0] && $_[0]) ? 0 : 1);
-}
-
 sub version_information {
   print "\nThis is $NAME protocol version $VERSION ($DATE)\n";
   print $COPYRIGHT_NOTICE;
@@ -234,8 +273,9 @@ sub version_information {
 }
 
 version_information() if ($version);
-usage_information(1) if ($help);
-usage_information()
+pod2usage(-verbose => 1, -exitval => 0) if ($help);
+pod2usage(-message => 'ERROR:  Required parameter not given or invalid.',
+         -verbose => 0, -exitval => 2)
   if (($style ne 'ftp') && ($style ne 'alpha') && ($style ne 'distros'));
 
 my $m_style = 'ftp';
@@ -335,6 +375,16 @@ if (IN_TEST_MODE) {        # override the above for testing
 
 my %info;   # package being processed; a global so fatal and mail can use it
 
+=head1 INTERNALS
+
+This section catches the internal documentation for internal functions
+within the gatekeeper program.  This is for programmers maintaining the
+gatekeeper itself and these functions may change without notice.
+
+=over
+
+=cut
+
 \f
 #
 # - Logging
@@ -1681,6 +1731,9 @@ sub cleanup {
   }
 }
 
+=back
+
+=cut
 
 \f
 #