.\" @(#)  /u/des/src/sortmail/decomposemail.man  1.2  98/08/11  17:54:33
.\" Copyright (c) 1998, Daniel E. Singer
.\" All Rights Reserved
.\" view this document using [tn]roff with the -man option
.TH decomposemail 1 "09 June 1998" "Toolman"
.\" ------------------------------------------------------------------------
.\" define string D to be a dash appropriate for nroff or troff
.if n .ds D -
.if t .ds D \-
.SH NAME
decomposemail \*D decompose mailboxes into their component email messages
.SH SYNOPSIS
.BR decomposemail " [ " \*Dhrv " ] [ " \*Dc
.IR num " ] [ "
.B \*Dl
.IR num " ] [ "
.B \*Ds
.IR num " ] [ "
.IR mbox... " ]"
.br
.\" ------------------------------------------------------------------------
.SH DESCRIPTION
.B decomposemail
disassembles email mailboxes into their component messages,
storing each message in a separate serialized file.
These message files can then be reassembled into new mailboxes sorted
by date by a program such as
.BR recomposemail (1),
or via standard UNIX commands.
.\" ------------------------------------------------------------------------
.SH OPTIONS
The following options are supported:
.TP 10
.B \*Dc
Split the mailbox into \fInum\fR-message chunks, does not sort.
.TP
.BR \*Dh
Help, just print an informational message, and exit.
.TP
.BR \*Dl
Limit, stop processing after \fInum\fR messages, does not count messages
skipped with
.BR \*Ds .
.TP
.BR \*Dr
Recompose, ignored with
.BR \*Dc .
The new mailbox file created will have the suffix \*(lq.sort\*(rq.
.TP
.BR \*Ds
Skip the first \fInum\fR messages.
.TP
.BR \*Dv
Verbose, provide more feedback.
.\" ------------------------------------------------------------------------
.SH OPERANDS
The following operands are supported:
.TP 10
.IR mbox
The name (with optional path) of a standard Internet style mailbox file.
\*(lq\*D\*(rq can be used for \fIstdin\fR (standard input),
which is also the default if no \fImbox\fR argument is given.
.\" ------------------------------------------------------------------------
.SH USAGE
.B decomposemail
is used to break up standard Internet style mailbox files into serialized
files, each holding one email message.  This is most useful when used with
other programs such as
.BR recomposemail (1)
or
.BR sortmail (1)
to reassemble the message files into new mailboxes.
The serialization used provides for easy ordering by date/time.
All work is done in the current directory.
.PP
With
.BR \*Dr ,
a quick and dirty reassembly \*D sorted by date/time \*D is performed
with no cleanup.
.PP
When \fImbox\fR arguments are specified that have suffixes
\*(lq.Z\*(rq or \*(lq.gz\*(rq
indicating that the files are compressed with either
.BR compress (1)
or
.BR gzip (1),
these files will be uncompressed as they are read in.
.\" ------------------------------------------------------------------------
.SH EXAMPLES
Break out the messages in the mailbox \*(lqzippy\*(rq into individual
serialized files:
.PP
	\fBdecomposemail zippy\fR
.PP
Break out the messages in the mailboxes \*(lq../listA\*(rq and
\*(lq../listB\*(rq into individual
serialized files, then recombine them into two new mailboxes
\*(lqlistA.sort\*(rq and \*(lqlistB.sort\*(rq, each sorted by date/time.
There will be no cleanup of the message files.
Per message progress will be reported:
.PP
	\fBdecomposemail \*Drv ../listA ../listB\fR
.PP
Break out messages 201 through 300 in the mailbox \*(lqoutbox\*(rq
into individual serialized files:
.PP
	\fBdecomposemail \*Ds 200 \*Dl 100 outbox\fR
.PP
Break out messages from the standard input, and chunk them into
serialized mailboxes each holding 50 messages.
The new mailboxes will each have the base name \*(lqstdin\*(rq:
.PP
	\fBcat mbox.* | decomposemail \*Dc 50\fR
.\" ------------------------------------------------------------------------
.SH FILES
.TP 14
.I mbox.YYYYMMDD.hhmmss.nnnnn
Serialized files created for each individual message in a mailbox,
where
\*(lqmbox\*(rq is the name of the mailbox, 
\*(lqYYYYMMDD\*(rq is the year, month, and day,
\*(lqhhmmss\*(rq is the hour, minute, and second, and
\*(lqnnnnn\*(rq is a serial number.
These will be created in the current directory.
.TP
.I mbox-nnnnn
Serialized files created for each chunk of \fInum\fR
messages when the
.B \*Dc
flag is specified,
where
\*(lqnnnnn\*(rq is a serial number starting with \*(lq00001\*(rq.
These will be created in the current directory.
.\" ------------------------------------------------------------------------
.SH DIAGNOSTICS
Returns \fB0\fR if no problems encountered.
.br
Returns \fBnon-zero\fR for any errors encountered.
.\" ------------------------------------------------------------------------
.SH BUGS
\fBdecomposemail\fP is slow.
.PP
Data at the beginning of a mailbox that does not appear to be part of
an email message will be silently discarded.
.PP
\fBdecomposemail\fP looks for and uses the GNU version of
.BR awk (1)
where it can find it, but will default to whatever version is
available.  Since most non-GNU versions have input line length
limitations,
\fBdecomposemail\fP will fold input lines that are too long when these
other versions are used.
.PP
With
.BR \*Dr ,
a simplistic algorithm is used to recombine the messages into a new mailbox,
and may crash on very large numbers of messages.
If this happens, use
.BR recomposemail (1).
.\" ------------------------------------------------------------------------
.SH "SEE ALSO"
.BR compress (1),
.BR gzip (1),
.BR recomposemail (1),
.BR sh (1),
.BR sortmail (1),
.br
\*(lqToolman:  Sorting and Archiving Email\*(rq,
\fI;login:\fR magazine (USENIX Association), August 1998.
.\" ------------------------------------------------------------------------
.SH AUTHOR
\fBsortmail\fR was written by Daniel E. Singer (a.k.a. Toolman)
at the Department of Computer Science, Duke University.