I've formatted the man page for "digest"; any comments on format or
content would be appreciated.
Kevin Kelleher
--------------------------------------------------------------------
.TH digest 1
.SH NAME
digest \- receive a file for a digest, or create and mail a digest
.LP
.SH SYNOPSIS
.B digest \-r|m \-C \-l
.I majordomo-listname recipient
.LP
.B digest \-r|m
[
.B \-c
.I configuration-file
]
.LP
.SH AVAILABILITY
Provided with distributions of Majordomo.
.LP
.SH 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.
.LP
It requires two directories: a work directory and an
archive directory. Incoming email messages are stored
in the work directory. Digests are created and stored
in the archive directory.
.LP
When invoked with the
.B \-r
option, the digest script reads
the incoming email message from standard input and stores
the file in the work directory. These files are given
numerical names starting with ``001'' and are numbered in
order of arrival. Each time that a file is added to the
directory, digest checks the total size of the files in bytes.
If the sum exceeds the digest's size limit (a configured value),
a digest is created and mailed.
.LP
When invoked with the
.B \-m
option, the digest script will
create and mail a digest, if there are any numbered files
in the work directory.
.LP
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
.SB $HOME/.digestrc
file.
.LP
.SH OPTIONS
.TP 10
.B \-r
Receive an email message via standard input
and place the file into the working directory.
If the total size (in bytes) of files in the
working directory exceeds the digest's size limit,
create and mail a digest.
.TP
.B \-m
If there are any numbered files in the working
directory, create and mail a digest. Store the
digest in the archive directory.
.TP
.B \-c
.IR configuration-file
Use the parameters defined in
.IR configuration-file.
.TP
.B \-C
Read
.BR /etc/majordomo.cf
and the configuration file for the Majordomo list specified in the
.BR \-l
option to define operational parameters. If both
.BR \-C
and
.BR \-c
options are specified (not recommended) only the
.BR \-C
option will be used.
.TP
.B \-l
.IR majordomo-listname
This option is ignored if used without the
.BR \-C
option. Specifies the Majordomo email list.
.LP
.SH OPERANDS
.TP 10
.I recipient
Email recipient of the digest. This operand is ignored if used
without the
.BR \-C
option. It specifies one of the system mail
aliases created for the Majordomo list named in the
.BR \-l
option.
.LP
.SH MAJORDOMO DIGEST CONFIGURATION
When used as a part of Majordomo, digest takes these parameters
from
.B /etc/majordomo.cf:
.LP
.PD 0
.B $listdir
\- the location of the mailing lists
.LP
.B $digest_work_dir
\- parent directory for the digests' work directories
.LP
.B $filedir
\- parent directory for archive directories
.LP
.B $filedir_suffix
\- an optional identifier (may be the null string)
.PD
.LP
Incoming messages for
.B $listname-digest
will be held in
.B $digest_work_dir/$listname-digest.
.LP
Digests will be stored in
.B $filedir/$listname-digest$filedir_suffix.
.LP
The list's configuration file will be
.B $listdir/$listname-digest.config.
.LP
Examples of these values are given in
.SB EXAMPLES,
below.
.LP
The list's configuration file contains several digest parameters that
are not yet implemented and/or should NOT be changed from their defaults
(blank):
.B digest_archive, digest_rm_footer, digest_rm_fronter, digest_work_dir.
.LP
The parameters which specifically deal with digest creation
and maintenance are:
.LP
.PD 0
.B digest_name
\- the title of the digest
.LP
.B digest_volume
\- volume number
.LP
.B digest_issue
\- issue number
.LP
.B maxlength
\- maximum number of characters in a digest
.LP
.B message_fronter
\- text prepended to the digest
.LP
.B message_footer
\- text appended to the digest
.PD
.LP
The last three parameters are also used in the configuration of
an ordinary (non-digest) Majordomo list.
.LP
Each digest begins with the a line containing the
.B digest_name, current date, digest_volume and digest_issue.
. The digest script will update the issue number in the configuration file.
.LP
A blank line follows, and then the text from the
.B message_fronter,
if any. The message fronter may contain the
.SB _SUBJECT_
token, which will be replaced by the subject lines from the messages
in the digest.
.LP
The text in the
.B message_footer,
if any, will be appended to the digest.
.LP
To embed a blank line in the
.B message_footer
or
.B 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.
.LP
Both message_footer and message_fronter may also use the tokens
.SB $LIST, $SENDER,
and
.SB $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.
.LP
Examples of the aliases usually used with the digest are
given in
.SB EXAMPLES,
below.
.LP
The list owner can prompt Majordomo to build a digest by
sending the command
.LP
``mkdigest
.I digest-name
[
.I digest-password
]''
.LP
to majordomo either via email or from cron. The cron
command has the format:
.LP
echo mkdigest
.I digest-name
[
.I digest-password
] | mail majordomo@domain.com
.LP
.SH 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.
.LP
If no configuration file is specified when digest is invoked,
it looks for a file named
.SB $HOME/.digestrc that must be in the
same format as the example file.
.LP
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.
.LP
The easiest way to configure a standalone digest is to copy
the five files (firewalls-digest.*) and edit them to taste.
.LP
Incoming mail is piped to digest with the
.B \-r
option. This can be done from some mail-reading programs, through
the command line, or via mail aliases similar to those
found in
.SB EXAMPLES,
below.
.LP
.SH EXAMPLES
.LP
1. Example values from
.B /etc/majordomo.cf:
.LP
.PD 0
.B $listdir = ``usr/local/mail/lists'';
.LP
.B $digest_work_dir = ``usr/local/mail/digest'';
.LP
.B $filedir = ``listdir'';
.LP
.B $filedir_suffix ``archive'';
.PD
.LP
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.
.LP
2. Typical aliases for Majordomo digests:
.LP
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''.
.LP
.PD 0
.B banjo-digest-approval: kevink
.LP
.B banjo-digest-outgoing: :include:/usr/local/lists/banjo-digest
.LP
.B owner-banjo-digest-outgoing: kevink
.LP
.B banjo-digest-digestify: ``|usr/majordomo/wrapper digest \-r \-C \-l banjo-digest banjo-digest-outgoing''
.LP
.B banjo-digest: banjo
.PD
.LP
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:
.LP
.B banjo-outgoing: :include:/usr/local/lists/banjo,banjo-digestify
.LP
.SH EXIT STATUS
The following exit values are returned:
.TP 10
.B 0
Successful completion.
.TP
.B >0
An error occurred.
.LP
.SH FILES
.PD 0
.TP 20
.B /etc/aliases
.TP
.B /etc/majordomo.cf
.PD
.LP
.SH SEE ALSO
.B majordomo(8)
.LP
.SH 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 <kevink@concorde.com>.
|
|
