Add on-line documentation. Whitespace cleanup.

9 files changed, 190 insertions, 103 deletions

diff --git a/lib/App/Mangemanche.pm b/lib/App/Mangemanche.pm
index d719ecb..2bcbc44 100644
--- a/lib/App/Mangemanche.pm
+++ b/lib/App/Mangemanche.pm
@@ -20,24 +20,28 @@ sub new {
     my $config = {};
 
     GetOptions(
-        'shorthelp|?' => sub {
-            pod2usage(-input => pod_where({-inc => 1}, $class),
-                      -verbose => 99,
-                      -sections => [qw(NAME SYNOPSIS COMMANDS)],
-                      -exitstatus => 'NOEXIT');
+        'shorthelp|?' => sub {
+            pod2usage(-input => pod_where({-inc => 1}, $class),
+                      -verbose => 99,
+                      -sections => [qw(NAME SYNOPSIS COMMANDS)],
+                      -exitstatus => 'NOEXIT');
             $class->list_commands;
             exit(EX_OK);
-        },
-        'help' => sub {
+        },
+        'help' => sub {
             App::Mangemanche::Command::mandoc($class, basename($0)),
-        },
-        'usage' => sub {
-            pod2usage(-exitstatus => EX_OK,
-                      -input => pod_where({-inc => 1}, $class),
-                      -verbose => 0)
         },
-        'config|c=s' => \$config_file,
-        'url|u=s' => \$url      
+        'usage' => sub {
+            pod2usage(-exitstatus => EX_OK,
+                      -input => pod_where({-inc => 1}, $class),
+                      -verbose => 0)
+        },
+        'version' => sub {
+            print "$0 version $VERSION\n";
+            exit(EX_OK);
+        },
+        'config|c=s' => \$config_file,
+        'url|u=s' => \$url
     ) or exit(EX_USAGE);
 
     if ($config_file) {
@@ -64,7 +68,7 @@ sub new {
     }
 
     my $agent = new Net::Ping903($config->{baseurl});
-    
+
     my $com = shift @ARGV;
     die "no command name\n" unless $com;
 
@@ -75,7 +79,7 @@ sub new {
     my $cmd;
     eval {
         require $modpath;
-        $cmd = $modname->new($com, $agent);
+        $cmd = $modname->new($com, $agent);
     };
     if ($@) {
         if ($@ =~ /Can't locate $modpath/) {
@@ -114,33 +118,33 @@ sub list_commands {
     print "\nAvailable commands are:\n";
     foreach my $mod (sort
                      map {
-                         my $name = basename($_);
+                         my $name = basename($_);
                          if (exists($INC{File::Spec->catfile(@classpath,$name)})) {
                              ()
                          } else {
                              eval {
                                      require $_;
                              };
-                             $name =~ s/\.pm$//;                             
+                             $name =~ s/\.pm$//;
                              $@ ? () : [$name, $_];
                         }
                      }
-                     map {
-                           glob File::Spec->catfile($_, @classpath, '*.pm')
-                     } @INC) {
+                     map {
+                           glob File::Spec->catfile($_, @classpath, '*.pm')
+                     } @INC) {
 
         my $s;
         open(my $fh, '>', \$s);
-        pod2usage(-input => $mod->[1],
+        pod2usage(-input => $mod->[1],
                   -output => $fh,
-                      -verbose => 99,
-                      -sections => ['NAME'],
-                      -exitstatus => 'NOEXIT');
+                      -verbose => 99,
+                      -sections => ['NAME'],
+                      -exitstatus => 'NOEXIT');
         close $fh;
         my (undef, $descr) = split("\n", $s||'');
         unless ($descr) {
             $descr = '    ' . $mod->[0]
-        } 
+        }
         print "$descr\n";
     }
 }
@@ -149,25 +153,121 @@ sub list_commands {
 
 =head1 NAME
 
-mangemanche - interface to B<ping903> daemon.
-    
+mangemanche - remote management interface to B<ping903> daemon.
+
 =head1 SYNOPSIS
 
 B<mangemanche>
 [B<-c> I<FILE>]
 [B<-u> I<FILE>]
 [B<--config=>I<FILE>]
-[B<--url=>I<FILE>]    
+[B<--url=>I<FILE>]
 I<COMMAND>
 I<ARG>...
 
 B<mangemanche>
 [B<-?>]
 [B<--help>]
-[B<--usage>]    
-    
+[B<--usage>]
+[B<--version>]
+
 =head1 DESCRIPTION
 
+Mangemanche provides remote management facilities for the running B<ping903>
+daemon.  First non-optional argument specifies the name of the I<command> to
+run.  Arguments following it supply options and arguments to that command.
+
+Mangemanche reads the IP address and port number of the B<ping903> management
+socket from its configuration file, F</etc/ping903.conf>.  If the file does
+not exist, the default port (B<localhost:8080>) is used.  The location of
+both can be overridden in the command line.
+
+If the server requests HTTP authorization, the program will look up the
+authorization credentials in the B<.ping903.cred> file located in the
+home directory.  Refer to L<ping903.cred>(5) for a detailed description.
+
 =head1 OPTIONS
 
-    
+=over 4
+
+=item B<-c>, B<--config=>I<FILE>
+
+Specifies alternative configuration file to use instead of
+F</etc/ping903.conf>.
+
+=item B<-u>, B<--url=>I<FILE>
+
+Sets the URL of the B<ping903> management socket.
+
+=back
+
+=head2 Informative options
+
+Each of these options causes the program to display a particular piece of
+information and exit with the zero status.  Any other options and arguments
+are ignored.
+
+=over 4
+
+=item B<-?>
+
+Displays a short option reminder and lists the available commands with
+their short descriptions.
+
+=item B<--help>
+
+Displays this manual page.
+
+=item B<--usage>
+
+Displays a terse command line usage summary.
+