'br $Id: splitdigest.1,v 2.8 1998/03/30 13:18:26 chris Released $'
.TH SPLITDIGEST 1 "Version 2.4" "30 March 1998"

.SH NAME
splitdigest
\- Undigest a mail folder.

.SH SYNOPSIS
.B "splitdigest"
[
.I options
][
.I file...
]
.br

.SH DESCRIPTION
.I Splitdigest
undigests a mail folder that has one or more digests concatenated together.
The result is a series of mail folders named according to the digest
name, number and volume. The folders are in a form suitable for reading by
a mail user agent, using, for example, "mail -f" or "elm -f". Each message
in the digest would have been separated by
.I splitdigest
so that you can read and reply to each message individually instead of
having to deal with the whole digest as one mail item.
.PP
If
.I splitdigest
is invoked without arguments, it will take its input from stdin. Otherwise
it will take its input from the file(s) listed on the command line.
.PP
The types of digests which
.I splitdigest
can handle as well as the output filename it generates can be customized
by modifying the file
.I splitdigest.config
which is by default placed in the
.I /usr/local/lib
directory.
.PP
As shipped,
.I splitdigest
will unconcatenate linux-kernel-digest digests generated from
.I vger.rutgers.edu
into
.I kernel-volnum.digestnum
where
.I volnum
is the digest volume number and
.I digestnum
is the digest number.
.PP
Likewise,
.I splitdigest
will unconcatenate
.I comp.os.linux.*
digests files generated from
.I news-digests.mit.edu 
into
.I digestname.digestnum.volnum
where
.I digestname
will be replaced by a truncated form of the digest name,
.I digestnum
will be replaced by the digest number, and
.I volnum
will be replaced by the digest volume number. For example, Linux-Admin
Digest #565 Volume 1 will be captured in the file
.IP
.I admin.565.1
.PP
ANNOUNCE Channel digests from Linux-Activists will be extracted to into
.I announce.date
where
.I date
is the date of issue of the digest. This is because the Linux-Activists
digests do not appear to have digest numbers.
.PP
MSDOS announce digests from SimTel are extracted to
.I msdos.digestnum.volnum
where
.I digestnum
is replaced by the digest number and
.I volnum
is replaced by the volume number.
.PP
Other digests may be supported as well. Check
.I splitdigest.config
for the complete list of supported digests.
.PP
The names can be changed by a simple modification of the
.I splitdigest.config
file. No recompilation of the sources is required.
.PP
Similarly, if you wish to extend the number of digest types
.I splitdigest
can recognise and undigest, you only have to modify the
.I splitdigest.config
file. Again, no recompilation is required.
.PP
For further information on the format of the
.I splitdigest.config
file, see the instructions included at the beginning of the configuration
file. The complete list of supported digest types (as shipped) can also
be obtained from the configuration file.

.SH OPTIONS
.PP
.IP -C<configfile>
Use the configuration file specified in the argument.
This is useful for testing a new configuration file without replacing
the existing one.
.IP -V
Display the version number. The program terminates immediately.
.IP -c
Compress the output file. This option is obsolete.
.IP -d<outdir>
Specifies a directory where all the undigested files are to be placed.
The directory is created if it does not exist.
.IP -h
Display usage information.
The program terminates without any further action.
.IP -l
Do not remove the "Content-Length:" header when undigesting. By default,
splitdigest will not copy the "Content-Length:" header to the output
file when undigesting since it has been reported to confuse some mail
user agents. This option suppresses the feature.
.IP -o<outfile>
Specifies that the output should be written to outfile. A special
case of
.I -o
is when you specify
.I -o-
which will be taken by
.B splitdigest
to mean that you want the output sent to stdout.
.IP -t
Do not compress the output file (default). This option is obsolete.
Splitdigest does not compress the output file by default.
.IP -v
Verbose mode.

.SH EXAMPLE
.PP
.I splitdigest
saved-folder-1
.PP
In this example, if
.I saved-folder-1
consists of comp.os.linux.admin digest files numbers 446 to 448 the output
will be
.IP
admin.446.1
.br
admin.447.1
.br
admin.448.1
.PP
in the current directory. The extracted files, admin.*, can be read using
a mail user agent such as
.I elm
as follows:
.IP
elm -f admin.446.1
.br
elm -f admin.447.1
.br
elm -f admin.448.1
.PP
If you are using
.I mail
the following commands will read the extracted files.
.IP
mail -f admin.446.1
.br
mail -f admin.447.1
.br
mail -f admin.448.1
.PP
The files will have the individual messages in each digest appropriately
"undigested" so that they may be read and replied to as individual messages.
.SH FILES
/usr/bin/gzip
.br
/usr/local/lib/splitdigest.config
.SH SEE ALSO
gzip (1).
.SH BUGS
.IP 1.
.I splitdigest
does not know how to handle files which has ordinary mail stuffed into them
besides the digest files.
.IP 2.
.I splitdigest
merely copies till the next "From " header the moment it encounters a string
that matches the end-of-digest marker in the digest. This generally yields
the correct behaviour. However, if the digest itself contains embedded
digests (such as digests that contain bounced mail which are themselves
digests), it is possible that
.I splitdigest
might terminate the digest too early under certain conditions. I have not
encountered a situation where a confluence of factors led to this, but
it's theoretically possible (and hence, under Murphy's Laws) is bound to
happen some day.
.PP
Please send all bug reports, fixes, comments and suggestions to me at my
email address below. I am also interested in knowing any additions you make
to the configuration file so that
.I splitdigest
can recognise other digest types.
.SH COPYRIGHT
Copyright (c) 1994-1998 by Christopher Heng. All rights reserved.
This program is released under the conditions of the GNU General Public
License. In addition, you may not remove or alter any of the copyright notices
and/or the conditions for use and distribution.
.PP
You can email me at one of the following addresses:
.IP
cyfheng@singnet.com.sg
.br
ChristopherHeng@pobox.org.sg
.PP
A link to the latest version of splitdigest can be found on my home page,
http://www.singnet.com.sg/~cyfheng.