NAME

mail2chart - Generate various charts from mail messages


SYNOPSIS

mail2chart [global-options] command [command-options] [args]...

mail2chart -H


DESCRIPTION

mail2chart considers mails for various information and generates graphical charts from this. command controls which information is considered. The mail messages are obtained using MH commands and the graphics are generated by gnuplot. See COMMANDS for a description of the implemented commands.


OPTIONS

-a alias-file
--aliases=alias-file

If the same person wrote mail from varying addresses this file can list all the aliases. Then each address is treated as if it came from the last name returned by

ali -alias alias-file -list -user address

I.e. alias-file is kind of a reversed alias file because many addresses are mapped onto one address instead of one address to many ones.

The default aliases which may be introduced by the default alias file are not considered.

Of course this option can also be used to define groups. A verbose message is output if there are more than one aliases for a single address.

The file is a regular alias file for MH. See mh-alias for a description.

-d date-file
--dates=date-file

A file containing special dates with a description of the date. May be used to mark special events in charts using time as one axis.

The file is organized line by line. Each line must be made up of the date in the form %Y/%m/%d and an arbitrary string for that date seperated by whitespace. # as the first non-blank character marks comment lines and blank lines are ignored.

-f folder
--folder=folder

The MH folder to obtain mails from without leading +.

This option is actually required for most commands.

This option may be given multiple to include multiple folders in one run.

-i image-type
--image-type=image-type

The image type to use by gnuplot. image-type is used as the argument to the gnuplot command set terminal.

If image-type is the empty string, then no terminal is set and the gnuplot default will be used. Under X this is the X display and care is taken, to allow the generated picture to be viewed. Hit q when done.

This option defaults to png. Another useful value is postscript eps.

Note: Try help set terminal at the gnuplot prompt to get an idea of what is possible.

-o output-file
--output-file=output-file

output-file gives the output file the chart is written to.

If image-type is empty, output-file defaults to standard output. In practice there usually is no output file in this case.

In other cases output-file defaults to a useful name based on the arguments of command (usually the name of the mailing list) and is extended by the first word of the image format given as image-type.

-p period
--period=period

Give the period for which to sample time data. period must be one of the following letters:

y

Year

q

Quarter

m

Month

w

Week

d

Day

Each of these units starts when it starts naturally. I.e. a new day starts at 0 o'clock local time, a new week starts when Monday of that week starts, a new month starts when the 1st of it starts and so on. The time range shown in the figure is determined by the first and the last of the selected messages.

Defaults to m.

-v
--verbose

Operate verbose.

-H
--help

Generate the man page for this program on standard output.

If an unknown option such as -. is given, a short usage message is generated.


COMMANDS

The following commands may be given as command. First a general description is given, then the options and arguments are considered one by one.

subscribe

subscribe [option...] [list-type list-name list-host]...

The subscribe command picks mail from an MH folder folder which looks like a subscribe/unsubscribe message of a majordomo or mailman. The data generated from the Date: and Subject: lines of these mails is used to generate the chart showing number of subscribed persons over time.

-a list-address
--address=list-address

The address of the mailing list. If list-address contains no @ list-host is added. This name is used for the title string of the chart. If list-address is the empty string no title is generated.

Defaults to list-name@list-host. This option is useful if the official address of the list is an alias for the real address.

list-name is used as the default base name of the output file.

-c condition
--condition=condition

By this option you can give additional options for the mails to be found by pick. Use a normal condition option of pick including its arguments.

Defaults to nothing.

This option can be used to create a figure only for a certain time. Try something like --condition "-after '`date -R -d '4 weeks ago'`'" to show only the past four weeks. However, this gives only a relative measure.

-o start-offset
--offset=start-offset

If start-offset is given it must be a number giving the number of subscribers the mailing list started with (i.e. there are no explicit subscribe messages for them).

Defaults to 0.

list-type list-host list-name

list-type identifies the type of list server this list is run by. At the moment the following types are supported:

majordomo

A list run by a majordomo list server.

mailman

A list run by a maliman list server.

mailman2_1

A list run by a maliman list server V2.1.

Note: Mailman V2.1 seems to generate subscribe/unsubscribe messages for the list administrator based on the language choice of the subscriber. I consider this behaviour a bug. At the moment mail2chart recognizes only English subscribe/unsubscribe messages.

list-host gives the real host this list is run on.

list-name gives the real name of the list on the host it is run on.

This triple must be given at least once, but may given more than once so different setups of list type, list host and list name may be merged into one chart. If multiple triples are given, any defaults used elsewhere are drawn from the last triple.

This command requires the -f option. It uses the -d option if present.

count

count [option...]

The count command counts the mails in MH folder folder originating from the same mail account (typically a person). Several options can be used to select mail accounts. The data generated from the Date: and From: lines of the selected mails is used to generate the chart showing number of contributions in a certain time interval.

-n name
--name=name

name gives a name appearing in the title and being used as the base name of the output file if any.

Defaults to the base name of folder.

-o
--others

Add a dummy contributor OTHERS which shows the numbers of contributions from other contributors than the ones shown.

For stacked style this results in showing the total number of contributions.

-r
--relative

Instead of showing the absolute number of contributions in the vertical direction show all values relative to the total number of contributions in the given period. If there are no contributions in a given period all contributors all relative values are set to 0.

-s
--stacked

Change the style used for the chart. Normally each shown contributor is shown independent of all other contributors. This chart is suited well to show the absolute number of contributions of each particular contributor.

In stacked style the top ranked contributor is shown at the base. The second ranked contributor is stacked on this and so on until the OTHERS dummy contributor is stacked on top of all. This chart is suited well to show the combined contributions of the shown contributors.

-t count[%]
--top=count[%]

Rank all considered contributors by the number of their total contributions during the whole period and consider only the count contributors ranked first. At the end of the rank all contributors with the same number of contributions than the last one are added so actually there may be more than count contributors. 0 means to consider all contributors regardless of their ranking.

If count is followed by a % instead of the count first ranked contributors the contributors are shown which contribute at least count percent of all contributions for the whole period.

The legend of the chart always lists the contributors as they are ranked. Contributors with same total number of contributions are ranked alphabetically. If -o/--others is given OTHERS are always listed last.

Defaults to 0.

This command requires the -f option. It uses the -a and the -d option if present and uses the -p option.


PREREQUISITES

Because this is a Perl program, Perl (>= V5.005) must be installed.

This program needs the Time-modules package installed. Try

        http://search.cpan.org/search?dist=Time-modules

Because the charts are generated by gnuplot, you need this program installed. See

        http://www.gnuplot.info/

Because mail2chart accesses mail by MH commands, you need the MH program suite installed. See

        http://www1.ics.uci.edu/~mh/


SEE ALSO

majordomo

gnuplot

mh


AUTHOR

Stefan Merten <smerten@oekonux.de>


LICENSE

This program is licensed under the terms of the GPL. See

        http://www.gnu.org/licenses/gpl.txt


AVAILABILTY

See

        http://www.merten-home.de/FreeSoftware/mail2chart/