Convert section heading comments to POD section headings

This commit also removes some leftover comments.

diff --git a/gatekeeper.pl b/gatekeeper.pl
index 916d26bac2a3763f1c24cb39e4f09a0383bb33fb..f4615298f902e2679f81adc945862c3648dd2291 100755 (executable)
--- a/gatekeeper.pl
+++ b/gatekeeper.pl
@@ -181,6 +181,16 @@ use Text::Wrap;
 use POSIX qw(strftime WIFSIGNALED WTERMSIG);
 use Email::MessageID;
 
+=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
 #
 # - Initialization and preliminaries
@@ -368,21 +378,16 @@ if (IN_TEST_MODE) {       # override the above for testing
   close $gpgv;
 }
 
-=head1 INTERNALS
+\f
 
-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.
+=back
+
+=head2 Logging
 
 =over
 
 =cut
 
-\f
-#
-# - Logging
-#
-
 {
   # To identify which zone is being processed, ftp_syslog will prepend
   # this, inside parentheses, to all messages logged.
@@ -608,9 +613,14 @@ BEGIN {
 }
 
 \f
-#
-# - Local exception definitions and utilities
-#
+
+=back
+
+=head2 Local exception definitions and utilities
+
+=over
+
+=cut
 
 {
   package Local::Exception;
@@ -773,9 +783,12 @@ sub throw {
 }
 
 \f
-#
-# - GPG helpers
-#
+
+=back
+
+=head2 GPG helpers
+
+=over
 
 =item $text = slurp_clearsigned_message ( $filename )
 
@@ -1202,9 +1215,12 @@ sub verify_detached_signature {
 }
 
 \f
-#
-# - Package configuration access
-#
+
+=back
+
+=head2 Package configuration access
+
+=over
 
 =item $package_name = directory_package_name ( $directory )
 
@@ -1308,9 +1324,12 @@ sub directory_email_addresses {
 }
 
 \f
-#
-# - Email
-#
+
+=back
+
+=head2 Email
+
+=over
 
 =item @unique_list = unique ( @list )
 
@@ -1497,9 +1516,12 @@ sub report_upload_to_archive {
 }
 
 \f
-#
-# - Directive reader and parsing helpers
-#
+
+=back
+
+=head2 Directive reader and parsing helpers
+
+=over
 
 =item $directive = read_directive ( $handle )
 
@@ -1666,21 +1688,12 @@ sub find_package {
 }
 
 \f
-#
-# - [SC] Scan for incoming packets
-#
 
-# Read the ftp incoming dir (which is assumed to be the current
-# directory), looking for completed upload triples (the three files
-# described at the beginning).  Ignore if we don't have all three files,
-# or if any of the files are still open, or if the filenames are dubious
-# -- things'll get cleaned up as needed separately.
-#
-# If we accept a triplet, we rename the files into a temporary
-# directory.  This is to avoid attackers overwriting files as or after
-# we check them.  This is redundant protection -- the ftp config on
-# ftp.gnu.org does not allow overwrites or deletes.
-#
+=back
+
+=head2 [SC] Scan for incoming packets
+
+=over
 
 =item @files = scan_incoming ( $directory )
 
@@ -1913,17 +1926,12 @@ sub gather_packets {
 }
 
 \f
-#
-# - [PV] Parsing and Validation
-#
 
-# Return the information for this upload out of DIRECTIVE_FILE --
-# directory and package.  Make sure the key that signed the directive
-# file has permission to write to this package, too.
-#
-# We assume DIRECTIVE_FILE is clear-signed (gpg --clearsign).  Among
-# other things, this lets us use gpgv everywhere, for paranoia's sake.
-#
+=back
+
+=head2 [PV] Parsing and Validation
+
+=over
 
 =item $oplist = interpret_directive ( $directive )
 
@@ -2389,9 +2397,12 @@ sub check_automake_vulnerabilities {
 }
 
 \f
-#
-# - [EX] Execution
-#
+
+=back
+
+=head2 [EX] Execution
+
+=over
 
 =item mkdir_p ( $base, @directory )
 
@@ -2591,9 +2602,12 @@ sub execute_commands {
 }
 
 \f
-#
-# - Clean up
-#
+
+=back
+
+=head2 Clean up
+
+=over
 
 =item cleanup_dir ( $directory )
 
@@ -2656,14 +2670,13 @@ sub cleanup {
   }
 }
 
+\f
+
 =back
 
-=cut
+=head2 Main execution path
 
-\f
-#
-# - Main execution path
-#
+=cut
 
 our $Phase;
 my @packets;