NAME
    groupstat - Generates statistics from a local news spool

SYNOPSIS
    groupstat [*options*] *newsgroup1* [*newsgroup2* *...*]

DESCRIPTION
    GroupSTAT is an advanced newsgroup statistics program. With the
    help of the *News::Scan* module, GroupSTAT scans the articles in
    the newsgroup(s) of your choice and prints various statistics
    from them. You could look at these statistics for your own
    amusement, or you post them to a newsgroup.

OPTIONS
  Debugging/Help Options

    --usage, --help, -?
            Prints a short usage message, then exits.

    -v, --verbose
            Enables a few helpful debugging messages. Might also be
            useful for submitting bug reports. This facility is
            turned off by default.

    --noverbose
            Turns off debugging messages. (The opposite of --
            verbose.)

  Scan Options

    -d, --days
            Sets the number of days in the past GroupSTAT should
            scan. The default is one week. See the section on
            "NOTES".

    -N, --num-major
            Sets the number of items printed in the "major"
            categories. Both of the 'Posters' and 'Threads'
            categories are considered major. The default is twenty-
            five.

    -n, --num-minor
            Sets the number of items printed in the "minor"
            categories. Both of the 'Original Content Ratings'
            categories and the crossposting category are considered
            minor. The default is ten.

  Formatting Options

    -w, --width
            Sets the width of the printed lines in columns. The
            default of 72 should be acceptable for most purposes.

    -H, --headstrip
            This option enables the use of the `headstrip' routine.
            This routine attempts to remove the email address from
            poster names before printing out results. If you do not
            want this, or if your *Mail::Address* module is buggy,
            see the next option. The default is to turn on
            `headstrip'.

    --noheadstrip
            Disables the `headstrip' routine. See the previous
            option for details.

  Input Options

    -s, --spool
            Sets the base directory of your local news spool. This
            specifies the root of your spool, not the exact
            directory where articles are stored. If you wish to
            specify *exactly* where the articles were stored, use
            the --input-dir option. The default spool directory is
            /var/spool/news.

    -i, --input-dir
            Sets the exact directory where articles are stored.
            These articles must be text files each containing
            exactly one article, and they must have name consisting
            only of numbers. getnews does this automatically for
            you. If you are running a local news server with a
            spool, use the --spool option instead. There is no
            default, setting this option overrides the --spool
            default.

    -d, --dotted
            Replace '.' with '/' in newsgroup names. This only
            applies when using the --spool or --output-base options.
            The default is to do the replacement.

    --nodotted
            Turn off the replacement done by the --dotted option.

  Output Options

    -o, --output-base
            Sets the base directory to store stats files in. These
            files are automatically stored by group, and then by
            date. If any directories are missing, they will be
            created (if possible). This does not specify the exact
            directory to store stats files in, use the --output-dir
            option for that. If you want to store stats in a
            specific file, use the --output-file option. The default
            is to store stats under ~/News/STATS.

    -O, --output-dir
            Sets the exact directory to store stats files in. The
            stats for each group are stored in files with names
            containing the newsgroup name and the date. If any
            directories are missing, they will be created (if
            possible). There is no default, setting the --output-dir
            option overrides the --output-base default.

    -f, --output-file
            Specifies a single file to store stats in. If more than
            one newsgroup was scanned, this file will contain
            multiple scan results. If any directories are missing in
            the path to --output-file, they will be created (if
            possible). Setting --output-file=- will send results to
            standard output (which can be piped to a pager like
            `more' or `less'). There is no default, setting the --
            output-file option overrides the --output-base default.

ENVIRONMENT
    GroupSTAT reads the contents of the environmental variable
    `GROUPSTAT' on startup. If you want to set default options for
    this program, put them here. They will be read as if they were
    normal command-line options.

    GroupSTAT also makes use of the `HOME' variable to determine
    where to place output files in the event that none of the --
    output options were specified.

EXAMPLES
    Scan 'rec.arts.drwho' from seven days ago until now, getting
    articles from `/var/spool/news', putting the output files into
    `~/News/STATS':

            groupstat rec.arts.drwho

    Scan three days of 'alt.sysadmin.recovery', getting articles
    from `/tmp/asr' and putting output into `/tmp/asr-stats.txt':
    groupstat -i=/tmp/asr -f=/tmp/asr-stats.txt
    alt.sysadmin.recovery

    Scan the top 50's for 'news.admin.net-abuse.usenet' with default
    options:

            groupstat -N50 -n50 news.admin.net-abuse.usenet

NOTES
    In order to use the --days option, you must have that many days
    of articles in your "spool". If you don't, GroupSTAT will not
    correct your error and the stats will be skewed. This means that
    if you want to use the default, you must have *at least* a
    week's worth of articles on spool.

    If you are constantly resetting the defaults, you may want to
    define the `GROUPSTAT' environmental variable.

    In ~/.bashrc (Unix platforms):

            export GROUPSTAT=options

    In AUTOEXEC.BAT (M$-DoS type systems):

            SET GROUPSTAT=options

WARNINGS
    If you post statistics about a newsgroup to that newsgroup on a
    regular basis, you may end up starting a series of everlasting
    flamewars. Be warned!

BUGS
    Lots and lots. :-) See the BUGS file that came with GroupSTAT.

AUTHOR
    GroupSTAT was written by H. Alex LaHurreau <alexdw@locl.net>.

HISTORY
    GroupSTAT is partially based on StatNews, which was written by
    Davide G. M. Salvetti <salve@debian.org>.

COPYRIGHT
    Copyright  1999-2000 H. Alex LaHurreau. This is free software;
    see the source for copying conditions. There is NO warranty; not
    even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO
    You may find the News::Scan manpage of interest. See the
    author's homepage (http://www.locl.net/homes/alexdw/) for more
    wonderful things. :-)

