digest(1)

NAME
digest - receive a file for a digest, or create and mail a digest

SYNOPSIS
digest -r|R|m|p -C -l majordomo-listname recipient

digest -r|R|m|p [ -c configuration-file ]

AVAILABILITY
Provided with distributions of Majordomo.

DESCRIPTION
The digest script is a perl script which automates the management of digests of electronic mail. It can be run in a standalone configuration or as part of Majordomo.

It requires two directories: a work directory and an archive directory. Incoming email messages are held in the work directory until they are collected into a digest. The digests are created and stored in the archive directory.

Incoming email messages are given numerical names starting with ``001'' and are numbered in order of arrival. The digests are named according to volume and number. For example, the filename ``v01.n028'' indicates volume 1, number 28 of the digest.

It should be noted that digest needs a configuration file to define all of its operating parameters. If no such file is specified, digest will use the $HOME/.digestrc file.

Several aspects of digest configuration determine how and when a digest is created. A digest can be created at regular intervals (as long as there are incoming messages) or whenever certain configurable conditions are met. These conditions are: how large the digest can be (in characters), how long the digest can be (in lines), and how old the messages in the digest can be (in days).

OPTIONS

-r  Receive an email message via standard input and place the file into the working directory. If any one of the conditions for digest creation are met, create and mail a digest. These conditions are the same as those described under option -p.

-R  Similar to -r, except that it will not create a digest. It simply places the message in the work directory and stops.

-m  If there are any numbered files in the working directory, create and mail a digest. Store the digest in the archive directory. This is the option used by majordomo's mkdigest command.

-p  Conditionally creates a digest. If any one of the conditions for digest creation are met, the digest is created and sent. There are three conditions, which are connected to three limits: the digest size in characters, the digest length in lines, and the age of the oldest message in days. If one of the files is older than the age limit, a digest is created. If the sum of the messages exceeds either of the size limits, a digest is created. The size limit in characters must be configured; the other two limits are optional.

-c configuration-file
    Use the parameters defined in configuration-file.

-C  Read the majordomo configuration file (either /etc/majordomo.cf or ~majordomo/majordomo.cf) and the configuration file for the Majordomo list specified in the -l option to define operational parameters. If both -C and -c options are specified (not recommended) only the -C option will be used.

-l majordomo-listname
    This option is ignored if used without the -C option. Specifies the Majordomo email list.

OPERANDS

recipient
    Email recipient of the digest. This operand is ignored if used without the -C option. It specifies one of the system mail aliases created for the Majordomo list named in the -l option.

MAJORDOMO DIGEST CONFIGURATION
When used as a part of Majordomo, digest takes these parameters from majordomo.cf (either /etc/majordomo.cf or ~majordomo/majordomo.cf):

$listdir - the location of the mailing lists
$digest_work_dir - parent directory for the digests' work directories
$filedir - parent directory for archive directories
$filedir_suffix - an optional identifier (may be the null string)

Incoming messages for $listname-digest will be held in $digest_work_dir/$listname-digest.

Digests will be stored in $filedir/$listname-digest$filedir_suffix.

The list's configuration file will be $listdir/$listname-digest.config.

Examples of these values are given in EXAMPLES, below.

The list's configuration file contains several digest parameters that are not yet implemented and/or should NOT be changed from their defaults (blank): digest_archive, digest_rm_footer, digest_rm_fronter, digest_work_dir.

The parameters which specifically deal with digest creation and maintenance are:

digest_name - the title of the digest
digest_volume - volume number
digest_issue - issue number
digest_maxdays - age limit in days for oldest message in the digest
digest_maxlines - maximum number of lines in a digest
maxlength - maximum number of characters in a digest
message_fronter - text prepended to the digest
message_footer - text appended to the digest

The last three parameters are also used in the configuration of an ordinary (non-digest) Majordomo list.

Each digest begins with the a line containing the digest_name, current date, digest_volume and digest_issue.

A blank line follows, and then the text from the message_fronter, if any. The message fronter may contain the _SUBJECT_ token, which will be replaced by the subject lines from the messages in the digest.

The text in the message_footer, if any, will be appended to the digest.

To embed a blank line in the message_footer or message_fronter, put a `-' as the first and ONLY character on the line. To preserve whitespace at the beginning of a line, put a `-' on the line before the whitespace to be preserved. To put a literal `-' at the beginning of a line, double it.

Both message_footer and message_fronter may also use the tokens $LIST, $SENDER, and $VERSION, which will be expanded to, respectively: the name of the current list, the sender as taken from the from line, and the current version of Majordomo.

Examples of the aliases usually used with the digest are given in EXAMPLES, below.

The list owner can prompt Majordomo to build a digest by sending the command

mkdigest digest-name [ outgoing-address ] digest-password

to majordomo either via email or from cron. The cron command has the format:

echo mkdigest digest-name [ outgoing-address ] digest-password | mail majordomo@domain.com

STANDALONE DIGEST CONFIGURATION
The Majordomo distribution comes with a ``digest'' subdirectory. The sample configuration file is called firewalls-digest.cf. A file in this format must be used if digest is invoked in standalone configuration.

If no configuration file is specified when digest is invoked, it looks for a file named $HOME/.digestrc that must be in the same format as the example file.

The configuration file defines the email addresses of the sender and recipient of the digest. It also locates the work and archive directories, the digest's size limit, and the names of the files that contain the digest's volume, number, header and footer.

The easiest way to configure a standalone digest is to copy the five files (firewalls-digest.*) and edit them to taste.

Incoming mail is piped to digest with the -r option. This can be done from some mail-reading programs, through the command line, or via mail aliases similar to those found in EXAMPLES, below.

EXAMPLES

1. Example values from /etc/majordomo.cf:

$listdir = ``usr/local/mail/lists'';
$digest_work_dir = ``usr/local/mail/digest'';
$filedir = ``listdir'';
$filedir_suffix ``archive'';

If our digest's name is banjo-digest, the work directory will be /usr/local/mail/digest/banjo-digest; the archive directory will be /usr/local/mail/lists/banjo-digest.archive. Note that these are names of directories, not files.

2. Typical aliases for Majordomo digests:

Usually a Majordomo digest is associated to a regular (non-digest) list. The digest's name is the regular listname plus ``-digest''. The list ``banjo'' will have the digest ``banjo-digest''.

banjo-digest-approval: kevink
banjo-digest-outgoing: :include:/usr/local/lists/banjo-digest
owner-banjo-digest-outgoing: kevink
banjo-digestify: ``|usr/majordomo/wrapper digest -r -C -l banjo-digest banjo-digest-outgoing''
banjo-digest: banjo

Note that mail to ``banjo-digest'' is routed to the regular list. The ``digestify'' alias must be added to the regular list's outgoing alias:

banjo-outgoing: :include:/usr/local/lists/banjo,banjo-digestify

NOTES
The volume number does not change automatically; it must be incremented manually.

For testing/debugging purposes there is a ``hidden'' option -d that creates the digest as /tmp/testdigest.nnn (where nnn is the current digest number). Since it is for testing and debugging purposes, it does not mail the digest, it does not place the digest in the archive directory, and it does not update the digest number.

EXIT STATUS
The following exit values are returned:

0   Successful completion.

>0  An error occurred.

FILES
/etc/aliases
/etc/majordomo.cf

SEE ALSO
majordomo(8)

AUTHOR
The digest script was written by Brent Chapman <brent@GreatCircle.COM>. It is available with distributions of Majordomo via anonymous FTP from FTP.GreatCircle.COM, in the directory pub/majordomo. This man page was written by Kevin Kelleher <fury@world.std.com>.