thh/newsstats
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Activity

Update documentation.

Browse source 
- Fix clientstats doc (copied from hoststats).
- Add some more examples ro README.

Signed-off-by: Thomas Hochstein <thh@thh.name>
This commit is contained in:
Thomas Hochstein 2025-06-01 16:39:25 +02:00
parent 0b87e81b08
commit 66890b68d8
11 changed files with 329 additions and 263 deletions
Download patch file Download diff file Expand all files Collapse all files

147
bin/groupstats.pl
View file

@ -283,7 +283,7 @@ See L<doc/README>.
=head1 DESCRIPTION
This script create reports on newsgroup usage (number of postings per
This script creates reports on newsgroup usage (number of postings per
group per month) taken from result tables created by
B<gatherstats.pl>.
@ -291,16 +291,16 @@ B<gatherstats.pl>.
=head3 Time period and newsgroups
The time period to act on defaults to last month; you can assign another
time period or a single month (or drop all time constraints) via the
B<--month> option (see below).
The time period to act on defaults to last month; you can assign
another time period or a single month (or drop all time constraints)
via the B<--month> option (see below).
B<groupstats> will process all newsgroups by default; you can limit
processing to only some newsgroups by supplying a list of those groups via
B<--newsgroups> option (see below). You can include hierarchy levels in
the output by adding the B<--sums> switch (see below). Optionally
newsgroups not present in a checkgroups file can be excluded from output,
sse B<--checkgroups> below.
processing to only some newsgroups by supplying a list of those groups
via B<--newsgroups> option (see below). You can include hierarchy
levels in the output by adding the B<--sums> switch (see below).
Optionally newsgroups not present in a checkgroups file can be excluded
from output, sse B<--checkgroups> below.
=head3 Report type
@ -321,26 +321,27 @@ below.
=head3 Sorting and formatting the output
By default, all results are grouped by month; you can group results by
newsgroup instead via the B<--groupy-by> option. Within those groups, the
list of newsgroups (or months) is sorted alphabetically (or
chronologically, respectively) ascending. You can change that order (and
sort by number of postings) with the B<--order-by> option. For details and
exceptions, please see below.
newsgroup instead via the B<--groupy-by> option. Within those groups,
the list of newsgroups (or months) is sorted alphabetically (or
chronologically, respectively) ascending. You can change that order
(and sort by number of postings) with the B<--order-by> option. For
details and exceptions, please see below.
The results will be formatted as a kind of table; you can change the
output format to a simple list or just a list of newsgroups and number of
postings with the B<--format> option. Captions will be added by means of
the B<--caption> option; all comments (and captions) can be supressed by
using B<--nocomments>.
output format to a simple list or just a list of newsgroups and number
of postings with the B<--format> option. Captions will be added by means
of the B<--caption> option; all comments (and captions) can be supressed
by using B<--nocomments>.
Last but not least you can redirect all output to a number of files, e.g.
one for each month, by submitting the B<--filetemplate> option, see below.
Last but not least you can redirect all output to a number of files,
e.g. one for each month, by submitting the B<--filetemplate> option,
see below.
=head2 Configuration
B<groupstats> will read its configuration from F<newsstats.conf>
which should be present in etc/ via Config::Auto or from a configuration file
submitted by the B<--conffile> option.
which should be present in etc/ via Config::Auto or from a configuration
file submitted by the B<--conffile> option.
See doc/INSTALL for an overview of possible configuration options.
@ -352,18 +353,18 @@ You can override some configuration options via the B<--groupsdb> option.
=item B<-V>, B<--version>
Print out version and copyright information and exit.
Display version and copyright information and exit.
=item B<-h>, B<--help>
Print this man page and exit.
Display this man page and exit.
=item B<-m>, B<--month> I<YYYY-MM[:YYYY-MM]|all>
Set processing period to a single month in YYYY-MM format or to a time
period between two month in YYYY-MM:YYYY-MM format (two month, separated
by a colon). By using the keyword I<all> instead, you can set no
processing period to process the whole database.
processing period to process the whole database. Defaults to last month.
=item B<-n>, B<--newsgroups> I<newsgroup(s)>
@ -388,17 +389,20 @@ See the B<gatherstats> man page for details.
This option does not work together with the B<--checkgroups> option as
all "virtual" groups will not be present in the checkgroups file.
False by default.
=item B<--checkgroups> I<filename>
Restrict output to those newgroups present in a file in checkgroups format
(one newgroup name per line; everything after the first whitespace on each
line is ignored). All other newsgroups will be removed from output.
Restrict output to those newgroups present in a file in checkgroups
format (one newgroup name per line; everything after the first
whitespace on each line is ignored). All other newsgroups will be
removed from output.
Contrary to B<gatherstats>, I<filename> is not a template, but refers to
a single file in checkgroups format.
Contrary to B<gatherstats>, I<filename> is not a template, but refers
to a single file in checkgroups format.
The B<--sums> option will not work together with this option as "virtual"
groups will not be present in the checkgroups file.
The B<--sums> option will not work together with this option as
"virtual" groups will not be present in the checkgroups file.
=item B<-r>, B<--report> I<default|average|sums>
@ -406,8 +410,8 @@ Choose the report type: I<default>, I<average> or I<sums>
By default, B<groupstats> will report the number of postings for each
newsgroup in each month. But it can also report the average number of
postings per group for all months or the total sum of postings per group
for all months.
postings per group for all months or the total sum of postings per
group for all months.
For report types I<average> and I<sums>, the B<group-by> option has no
meaning and will be silently ignored (see below).
@ -426,12 +430,13 @@ Set the boundary type to one of I<default>, I<level>, I<average> or
I<sums>.
By default, all newsgroups with more postings per month than the upper
boundary and/or less postings per month than the lower boundary will be
excluded from further processing. For the default report that means each
month only newsgroups with a number of postings between the boundaries
will be displayed. For the other report types, newsgroups with a number of
postings exceeding the boundaries in all (!) months will not be
considered.
boundary and/or less postings per month than the lower boundary will
be
excluded from further processing. For the default report that means
each month only newsgroups with a number of postings between the
boundaries will be displayed. For the other report types, newsgroups
with a number of postings exceeding the boundaries in all (!) months
will not be considered.
For example, lets take a list of newsgroups like this:
@ -461,22 +466,23 @@ month. If you want to list all newsgroups with more than 25 postings
I<in total>, you'll have to set the boundary type to I<sum>, see below.
A boundary type of I<level> will show only those newsgroups - at all -
that satisfy the boundaries in each and every single month. With the above
list of newsgroups and
that satisfy the boundaries in each and every single month. With the
above list of newsgroups and
C<groupstats --month 2012-01:2012-03 --lower 25 --boundary level --report sums>,
you'll get this result:
----- All months:
de.comp.datenbanken.ms-access 293
de.comp.datenbanken.mysql has not been considered because it had less than
25 postings in 2012-02 (only).
de.comp.datenbanken.mysql has not been considered because it had less
than 25 postings in 2012-02 (only).
You can use that to get a list of newsgroups that have more (or less) then
x postings in every month during the whole reporting period.
You can use that to get a list of newsgroups that have more (or less)
then x postings in every month during the whole reporting period.
A boundary type of I<average> will show only those newsgroups - at all -that
satisfy the boundaries on average. With the above list of newsgroups and
A boundary type of I<average> will show only those newsgroups - at
all - that satisfy the boundaries on average. With the above list of
newsgroups and
C<groupstats --month 2012-01:2012-03 --lower 25 --boundary avg --report sums>,
you'll get this result:
@ -491,8 +497,8 @@ The average number of postings in the three groups is:
de.comp.datenbanken.mysql 48.33
Last but not least, a boundary type of I<sums> will show only those
newsgroups - at all - that satisfy the boundaries with the total sum of
all postings during the reporting period. With the above list of
newsgroups - at all - that satisfy the boundaries with the total sum
of all postings during the reporting period. With the above list of
newsgroups and
C<groupstats --month 2012-01:2012-03 --lower 25 --boundary sum --report sums>,
you'll finally get this result:
@ -505,8 +511,8 @@ you'll finally get this result:
=item B<-g>, B<--group-by> I<month[-desc]|newsgroups[-desc]>
By default, all results are grouped by month, sorted chronologically in
ascending order, like this:
By default, all results are grouped by month, sorted chronologically
in ascending order, like this:
----- 2012-01:
de.comp.datenbanken.ms-access 84
@ -525,8 +531,8 @@ B<--group-by> I<newsgroup>:
2012-01 88
2012-02 21
By appending I<-desc> to the group-by option parameter, you can reverse
the sort order - e.g. B<--group-by> I<month-desc> will give:
By appending I<-desc> to the group-by option parameter, you can
reverse the sort order - e.g. B<--group-by> I<month-desc> will give:
----- 2012-02:
de.comp.datenbanken.ms-access 126
@ -541,9 +547,9 @@ this option will therefore be ignored.
=item B<-o>, B<--order-by> I<default[-desc]|postings[-desc]>
Within each group (a single month or single newsgroup, see above), the
report will be sorted by newsgroup names in ascending alphabetical order
by default. You can change the sort order to descending or sort by number
of postings instead.
report will be sorted by newsgroup names in ascending alphabetical
order by default. You can change the sort order to descending or sort
by number of postings instead.
=item B<-f>, B<--format> I<pretty|list|dump>
@ -587,19 +593,19 @@ False by default.
=item B<--comments|--nocomments>
Add comments (group headers) to I<dump> and I<pretty> output. True by default
as logn as B<--filetemplate> is not set.
Add comments (group headers) to I<dump> and I<pretty> output. True by
default as long as B<--filetemplate> is not set.
Use I<--nocomments> to suppress anything except newsgroup names/months and
numbers of postings.
Use I<--nocomments> to suppress anything except newsgroup names/months
and numbers of postings.
=item B<--filetemplate> I<filename template>
Save output to file(s) instead of dumping it to STDOUT. B<groupstats> will
create one file for each month (or each newsgroup, accordant to the
setting of B<--group-by>, see above), with filenames composed by adding
year and month (or newsgroup names) to the I<filename template>, for
example with B<--filetemplate> I<stats>:
Save output to file(s) instead of dumping it to STDOUT. B<groupstats>
will create one file for each month (or each newsgroup, according to
the setting of B<--group-by>, see above), with filenames composed by
adding year and month (or newsgroup names) to the I<filename template>,
for example with B<--filetemplate> I<stats>:
stats-2012-01
stats-2012-02
@ -611,7 +617,7 @@ Override I<DBTableGrps> from F<newsstats.conf>.
=item B<--conffile> I<filename>
Load configuration from I<filename> instead of F<newsstats.conf>.
Read configuration from I<filename> instead of F<newsstats.conf>.
=back
@ -635,9 +641,9 @@ by number of postings, descending, in I<pretty> format:
groupstats --upper 30 --order-by postings-desc
Show the total of all postings for the year of 2010 for all groups that
had 30 postings or less in every single month in that year, ordered by
number of postings in descending order:
Show the total of all postings for the year of 2010 for all groups
that had 30 postings or less in every single month in that year,
ordered by number of postings in descending order:
groupstats -m 2010-01:2010-12 -u 30 -b level -r sums -o postings-desc
@ -651,7 +657,6 @@ machine-readable form (without formatting):
groupstats -m 2010-01:2010-12 -f dump --filetemplate stats
=head1 FILES
=over 4