Add comments and POD.
[usenet/newsstats.git] / gatherstats.pl
index 09157d1..4b4b8dd 100755 (executable)
@@ -47,11 +47,11 @@ $ConfOverride{'DBTableHosts'} = $Options{'s'} if $Options{'s'};
 $ConfOverride{'TLH'} = $Options{'n'} if $Options{'n'};\r
 &OverrideConfig(\%Conf,\%ConfOverride);\r
 \r
-### get type of information to gather, default to 'all'\r
+### get type of information to gather, defaulting to 'all'\r
 $Options{'t'} = 'all' if !$Options{'t'};\r
 die "$MySelf: E: Unknown type '-t $Options{'t'}'!\n" if !exists($LegalTypes{$Options{'t'}});\r
 \r
-### get time period\r
+### get time period (-m or -p)\r
 my ($StartMonth,$EndMonth) = &GetTimePeriod($Options{'m'},$Options{'p'});\r
 \r
 ### init database\r
@@ -94,9 +94,219 @@ foreach my $Month (&ListMonth($StartMonth,$EndMonth)) {
         $DBQuery->finish;\r
       };\r
     };\r
+  } else {\r
+    # other types of information go here - later on\r
   };\r
 };\r
 \r
 ### close handles\r
 $DBHandle->disconnect;\r
 \r
+__END__\r
+\r
+################################ Documentation #################################\r
+\r
+=head1 NAME\r
+\r
+gatherstats - process statistical data from a raw source\r
+\r
+=head1 SYNOPSIS\r
+\r
+B<gatherstats> [B<-Vhdo>] [B<-m> I<YYYY-MM>] [B<-p> I<YYYY-MM:YYYY-MM>] [B<-t> I<type>] [B<-n> I<TLH>] [B<-r> I<database table>] [B<-g> I<database table>] [B<-c> I<database table>] [B<-s> I<database table>]\r
+\r
+=head1 REQUIREMENTS\r
+\r
+See doc/README: Perl 5.8.x itself and the following modules from CPAN:\r
+\r
+=over 2\r
+\r
+=item -\r
+\r
+Config::Auto\r
+\r
+=item -\r
+\r
+DBI\r
+\r
+=back\r
+\r
+=head1 DESCRIPTION\r
+\r
+This script will extract and process statistical information from a\r
+database table which is fed from F<feedlog.pl> for a given time period\r
+and write its results to (an)other database table(s).\r
+\r
+The time period to act on defaults to last month; you can assign\r
+another month via the B<-m> switch or a time period via the B<-p>\r
+switch; the latter takes preference.\r
+\r
+By default B<gatherstats> will process all types of information; you\r
+can change that using the B<-t> switch and assigning the type of\r
+information to process. Currently only processing of the number of\r
+postings per group per month is implemented anyway, so that doesn't\r
+matter yet.\r
+\r
+Possible information types include:\r
+\r
+=over 3\r
+\r
+=item B<groups> (postings per group per month)\r
+\r
+B<gatherstats> will examine Newsgroups: headers. Crosspostings will be\r
+counted for each single group they appear in. Groups not in I<TLH>\r
+will be ignored.\r
+\r
+B<gatherstats> will also add up the number of postings for each\r
+hierarchy level, but only count each posting once. A posting to\r
+de.alt.test will be counted for de.alt.test, de.alt.ALL and de.ALL,\r
+respectively. A crossposting to de.alt.test and de.alt.admin, on the\r
+other hand, will be counted for de.alt.test and de.alt.admin each, but\r
+only once for de.alt.ALL and de.ALL.\r
+\r
+Data is written to I<DBTableGrps> (see doc/INSTALL).\r
+\r
+=back\r
+\r
+=head2 Configuration\r
+\r
+F<gatherstats.pl> will read its configuration from F<newsstats.conf>\r
+which should be present in the same directory via Config::Auto.\r
+\r
+See doc/INSTALL for an overview of possible configuration options.\r
+\r
+You can override configuration options via the B<-n>, B<-r>, B<-g>,\r
+B<-c> and B<-s> switches, respectively.\r
+\r
+=head1 OPTIONS\r
+\r
+=over 3\r
+\r
+=item B<-V> (version)\r
+\r
+Print out version and copyright information on B<yapfaq> and exit.\r
+\r
+=item B<-h> (help)\r
+\r
+Print this man page and exit.\r
+\r
+=item B<-d> (debug)\r
+\r
+Output debugging information to STDOUT while processing (number of\r
+postings per group).\r
+\r
+=item B<-o> (output only)\r
+\r
+Do not write results to database. You should use B<-d> in conjunction\r
+with B<-o> ... everything else seems a bit pointless.\r
+\r
+=item B<-m> I<YYYY-MM> (month)\r
+\r
+Set processing period to a month in YYYY-MM format. Ignored if B<-p>\r
+is set.\r
+\r
+=item B<-p> I<YYYY-MM:YYYY-MM> (period)\r
+\r
+Set processing period to a time period between two month, each in\r
+YYYY-MM format, separated by a colon. Overrides B<-m>.\r
+\r
+=item B<-t> I<type> (type)\r
+\r
+Set processing type to one of I<all> and I<groups>. Defaults to all\r
+(and is currently rather pointless as only I<groups> has been\r
+implemented).\r
+\r
+=item B<-n> I<TLH> (newsgroup hierarchy)\r
+\r
+Override I<TLH> from F<newsstats.conf>.\r
+\r
+=item B<-r> I<table> (raw data table)\r
+\r
+Override I<DBTableRaw> from F<newsstats.conf>.\r
+\r
+=item B<-g> I<table> (postings per group table)\r
+\r
+Override I<DBTableGrps> from F<newsstats.conf>.\r
+\r
+=item B<-c> I<table> (client data table)\r
+\r
+Override I<DBTableClnts> from F<newsstats.conf>.\r
+\r
+=item B<-s> I<table> (server/host data table)\r
+\r
+Override I<DBTableHosts> from F<newsstats.conf>.\r
+\r
+=back\r
+\r
+=head1 INSTALLATION\r
+\r
+See doc/INSTALL.\r
+\r
+=head1 EXAMPLES\r
+\r
+Process all types of information for lasth month:\r
+\r
+    gatherstats\r
+\r
+Do a dry run, showing results of processing:\r
+\r
+    gatherstats -do\r
+\r
+Process all types of information for January of 2010:\r
+\r
+    gatherstats -m 2010-01\r
+\r
+Process only number of postings for the year of 2010:\r
+\r
+    gatherstats -p 2010-01:2010-12 -t groups\r
+\r
+=head1 FILES\r
+\r
+=over 4\r
+\r
+=item F<gatherstats.pl>\r
+\r
+The script itself.\r
+\r
+=item F<NewsStats.pm>\r
+\r
+Library functions for the NewsStats package.\r
+\r
+=item F<newsstats.conf>\r
+\r
+Runtime configuration file for B<yapfaq>.\r
+\r
+=back\r
+\r
+=head1 BUGS\r
+\r
+Please report any bugs or feature requests to the author or use the\r
+bug tracker at L<http://bugs.th-h.de/>!\r
+\r
+=head1 SEE ALSO\r
+\r
+=over 2\r
+\r
+=item -\r
+\r
+doc/README\r
+\r
+=item -\r
+\r
+doc/INSTALL\r
+\r
+=back\r
+\r
+This script is part of the B<NewsStats> package.\r
+\r
+=head1 AUTHOR\r
+\r
+Thomas Hochstein <thh@inter.net>\r
+\r
+=head1 COPYRIGHT AND LICENSE\r
+\r
+Copyright (c) 2010 Thomas Hochstein <thh@inter.net>\r
+\r
+This program is free software; you may redistribute it and/or modify it\r
+under the same terms as Perl itself.\r
+\r
+=cut\r
This page took 0.012383 seconds and 4 git commands to generate.