+__END__\r
+\r
+################################ Documentation #################################\r
+\r
+=head1 NAME\r
+\r
+groupstats - create reports on newsgroup usage\r
+\r
+=head1 SYNOPSIS\r
+\r
+B<groupstats> [B<-Vhiscqd>] [B<-m> I<YYYY-MM>] [B<-p> I<YYYY-MM:YYYY-MM>] [B<-n> I<newsgroup(s)>] [B<-t> I<threshold>] [B<-l> I<level>] [B<-b> I<number>] [B<-o> I<output type>] [B<-g> 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 create reports on newsgroup usage (number of postings per\r
+group per month) taken from result tables created by\r
+F<gatherstats.pl>.\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
+B<groupstats> will process all newsgroups by default; you can limit\r
+that to only some newsgroups by supplying a list of those groups via\r
+B<-n> (see below). You can include hierarchy levels in the output by\r
+adding the B<-s> switch (see below).\r
+\r
+Furthermore you can set a threshold via B<-t> so that only newsgroups\r
+with more postings per month will be included in the report. You can\r
+invert that by the B<-i> switch so only newsgroups with less than\r
+I<threshold> postings per month will be included.\r
+\r
+You can sort the output by number of postings per month instead of the\r
+default (alphabetical list of newsgroups) by using B<-q>; you can\r
+reverse the sorting order (from highest to lowest or in reversed\r
+alphabetical order) by using B<-d>.\r
+\r
+Furthermore, you can create a list of newsgroups that had consistently\r
+more (or less) than x postings per month during the whole report\r
+period by using B<-l> (together with B<i> as needed).\r
+\r
+Last but not least you can create a "best of" list of the top x\r
+newsgroups via B<-b> (or a "worst of" list by adding B<i>).\r
+\r
+By default, B<groupstats> will dump a very simple alphabetical list of\r
+newsgroups, one per line, followed by the number of postings in that\r
+month. This output format of course cannot sensibly be combined with\r
+time periods, so you can set the output format by using B<-o> (see\r
+below). Captions can be added by setting the B<-c> switch.\r
+\r
+=head2 Configuration\r
+\r
+F<groupstats.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<-g> switch.\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<-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<-n> I<newsgroup(s)> (newsgroups)\r
+\r
+Limit processing to a certain set of newsgroups. I<newsgroup(s)> can\r
+be a single newsgroup name (de.alt.test), a newsgroup hierarchy\r
+(de.alt.*) or a list of either of these, separated by colons, for\r
+example\r
+\r
+ de.test:de.alt.test:de.newusers.*\r
+\r
+=item B<-t> I<threshold> (threshold)\r
+\r
+Only include newsgroups with more than I<threshold> postings per\r
+month. Can be inverted by the B<-i> switch so that only newsgroups\r
+with less than I<threshold> postings will be included.\r
+\r
+This setting will be ignored if B<-l> or B<-b> is set.\r
+\r
+=item B<-l> I<level> (level)\r
+\r
+Only include newsgroups with more than I<level> postings per\r
+month, every month during the whole reporting period. Can be inverted\r
+by the B<-i> switch so that only newsgroups with less than I<level>\r
+postings every single month will be included. Output will be ordered\r
+by newsgroup name, followed by month.\r
+\r
+This setting will be ignored if B<-b> is set. Overrides B<-t> and\r
+can't be used together with B<-q> or B<-d>.\r
+\r
+=item B<-b> I<n> (best of)\r
+\r
+Create a list of the I<n> newsgroups with the most postings over the\r
+whole reporting period. Can be inverted by the B<-i> switch so that a\r
+list of the I<n> newsgroups with the least postings over the whole\r
+period is generated. Output will be ordered by sum of postings.\r
+\r
+Overrides B<-t> and B<-l> and can't be used together with B<-q> or\r
+B<-d>. Output format is set to I<pretty> (see below).\r
+\r
+=item B<-i> (invert)\r
+\r
+Used in conjunction with B<-t>, B<-l> or B<-b> to set a lower\r
+threshold or level or generate a "bottom list" instead of a top list.\r
+\r
+=item B<-s> (sum per hierarchy level)\r
+\r
+Include "virtual" groups for every hierarchy level in output, for\r
+example:\r
+\r
+ de.alt.ALL 10\r
+ de.alt.test 5\r
+ de.alt.admin 7\r
+\r
+See the B<gatherstats> man page for details.\r
+\r
+=item B<-o> I<output type> (output format)\r
+\r
+Set output format. Default is I<dump>, consisting of an alphabetical\r
+list of newsgroups, each on a new line, followed by the number of\r
+postings in that month. This default format can't be used with time\r
+periods of more than one month.\r
+\r
+I<list> format is like I<dump>, but will print the month in front of\r
+the newsgroup name.\r
+\r
+I<dumpgroup> format can only be use with a group list (see B<-n>) of\r
+exactly one newsgroup and is like I<dump>, but will output months,\r
+followed by the number of postings.\r
+\r
+If you don't need easily parsable output, you'll mostly use I<pretty>\r
+format, which will print a header for each new month and try to align\r
+newsgroup names and posting counts. Usage of B<-b> will force this\r
+format.\r
+\r
+=item B<-c> (captions)\r
+\r
+Add captions to output (reporting period, newsgroups list, threshold).\r
+\r
+=item B<-q> (quantity of postings)\r
+\r
+Sort by number of postings instead of by newsgroup names.\r
+\r
+Cannot be used with B<-l> or B<-b>.\r
+\r
+=item B<-d> (descending)\r
+\r
+Change sort order to descending.\r
+\r
+Cannot be used with B<-l> or B<-b>.\r
+\r
+=item B<-g> I<table> (postings per group table)\r
+\r
+Override I<DBTableGrps> from F<newsstats.conf>.\r
+\r
+=back\r
+\r
+=head1 INSTALLATION\r
+\r
+See doc/INSTALL.\r
+\r
+=head1 EXAMPLES\r
+\r
+Show number of postings per group for lasth month in I<dump> format:\r
+\r
+ groupstats\r
+\r
+Show that report for January of 2010 and de.alt.* plus de.test,\r
+including display of hierarchy levels:\r
+\r
+ groupstats -m 2010-01 -n de.alt.*:de.test -s\r
+\r
+Show that report for the year of 2010 in I<pretty> format:\r
+\r
+ groupstats -p 2010-01:2010-12 -o pretty\r
+\r
+Only show newsgroups with less than 30 postings last month, ordered\r
+by number of postings, descending, in I<pretty> format:\r
+\r
+ groupstats -iqdt 30 -o pretty\r
+\r
+Show top 10 for the first half-year of of 2010 in I<pretty> format:\r
+\r
+ groupstats -p 2010-01:2010-06 -b 10 -o pretty\r
+\r
+Report all groups that had less than 30 postings every singele month\r
+in the year of 2010 (I<pretty> format is forced)\r
+\r
+ groupstats -p 2010-01:2010-12 -il 30\r
+\r
+=head1 FILES\r
+\r
+=over 4\r
+\r
+=item F<groupstats.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
+=item -\r
+\r
+gatherstats -h\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