mbox 1.00 (c) Juergen Luethje 2003
Packer Plugin for Total Commander 5.50 and later (32 bit only)
==============================================================

What it does
------------
"mbox.wcx" is a DLL that reads Unix mailbox files (mbox format). It
lists the mails inside a mailbox (subject, size, date), and allows to
access the content of the mails.


Features
--------
Each mail is named after it's subject. Special characters, that are not
allowed in file names, are replaced. "Re:","Re[2]:","Re[3]:","Re[4]:",
"Aw:", and "Fw:" at the beginning of the name, and superfluous blanks
and tabs are removed.
To avoid ambiguity, a unique number is appended to each file name. Long
file names are truncated, so that they don't exceed a maximum length of
64 characters (including the extension .EML). Truncation is denoted by
"[...]" at the end of the file name.

Each EML file gets a time stamp according to it's Date header field.
Since this time stamp is expressed in Universal Time Coordinated (UTC)
for all mails, messages from all parts of the world (e.g. on a mailing
list) can be sorted by time in a consistent way.

o This plugin allows Total Commander to list the mails inside mbox
  files, and to sort them by subject, size, or date (UTC).
  The user can view the content of selected mails, compare the content
  of two mails in the same or in different mailboxes, and extract
  individual (or all) mails to EML files.
  This plugin also allows Total Commander (using the option "Search in
  archives") to search for EML files inside mbox files. Thereby, it can
  search for duplicate EML files, too.

o Programmers can also use this 32-bit Windows DLL with their own
  programs, written in Euphoria, C, Delphi, or whatever. The DLL
  supports the functions
      OpenArchive()
      ReadHeader()
      ProcessFile()
      CloseArchive()
      SetProcessDataProc()
      GetPackerCaps()
      CanYouHandleThisFile()

  'mboxdemo.exw' is a sample Euphoria program, that uses the DLL. For
  additional information see "WCX Writer's Reference" [5].


Since the mbox files are opened in binary mode, the plugin can read even
corrupted files that contain binary data.
When extracting messages, any ASCII character 26 ("End of File" marker)
is replaced with the string "<EOF>". So it should be possible, to open
even corrupted messages with almost any text editor after extraction.

If the last line of a message in an mbox file only contains a dot, then
that line will not be copied to the EML file during extraction. This is
because there are programs, which cannot handle EML files containing
such a line correctly.

This software has successfully been tested whether it opens mailboxes,
and extracts messages from them, using files with a size up to 100 MB
(one hundred Megabytes!), containing 28000 messages.
Even bigger mbox files should cause no problems, if there is sufficient
(virtual) memory available on the machine. It may take some time to open
such a huge file, though. This is because an mbox file doesn't contain
any header data, and therefore the whole file must be parsed on opening.


The mbox format [1,2]
---------------------
This is a common format for storage of mail messages (not only on Unix
platforms). There is no true specification of it, though.
An mbox is a text file containing an arbitrary number of e-mail
messages. Each message consists of a postmark, followed by an e-mail
message, formatted according to RFC 2822 [4]. The file format is line-
oriented.

The postmark is a line that begins with the string "From " (note the
trailing space), _not_ followed by a colon.
Because of the wide-range of variations in practice, nothing else on the
"From " line should be considered.

However, this software does not regard _any_ such "From " line as the
beginning of a new message, because sometimes it is a normal line in
the text body of the mail (e.g. "From now on ...").
Therefore, when the plugin finds a "From " line, it looks ahead:
If and only if any line, up to the next blank line, is a syntactically
valid part of a header field (according to RFC 2822 [4]), then this
"From " line is regarded as delimiter between two messages.
This algorithm has proven to be reliable for intact messages, but it
probably will fail, if any of the concerned header fields is seriously
damaged.

The plugin uses the bodies of the Subject and Date header field of
each message, to generate a file name and a time stamp, respectively.
If there is no Subject header field, or the field body is empty,
"[no subject]" will be used as file name.
If a mail doesn't have a Date header field, or the field body contains
invalid data, "01.01.1980 00:00:00" is used as time stamp.

o Eudora [3]
  The Eudora mailbox format is nearly unix mbox format.
  The Date header field is often left off of Eudora messages, presumably
  because it is contained in the initial "From " line. This does not
  correspond to RFC 2822 [4].
  Also in contrast to the mbox format, Eudora extracts all attachments,
  and saves them as separate files.


Installation
------------
1.  Unzip the file "mbox.wcx" to the Total Commander directory.
2.  In Total Commander, choose "Configuration" > "Options".
3.  Choose the "Packer" tab.
4.  Click the "Configure packer extension DLLs" button.
5.  Type "mbx" as the extension.

5a. If there is an older version of mbox.wcx installed on your PC,
    uninstall it by choosing "Associate with:" [none].
    Then click "OK", and continue with point 4.

6.  Click "New type", and select the file "mbox.wcx".
7.  Click "OK".


Version history
---------------
o 2003, Jul 27 -- v1.00 beta 1
  * first public release

o 2003, Aug 12 -- v1.00 beta 2
  * fixed:   - Obsolete time zone formats (according to RFC 2822 [4])
               now are handled correctly.
  * changed: - The mbox files now are opened in binary mode.
             - When extracting messages, any ASCII character 26
               (EOF marker) is replaced with the string "<EOF>".
             - Several minor tweaks.
  + new:     - Considerably enhanced documentation.

o 2003, Aug 24 -- v1.00 beta 3
  * changed: - Several minor tweaks.
  + new:     - Mailboxes now can also be opened with [Ctrl]+[PageDown],
               regardless of the file extension.

o 2003, Nov 09 -- v1.00 final
  * fixed:   - Now any Quoted-Printable encoded text in the subject of
               a mail is decoded in a simple way, before it is used to
               build the name of an EML file.
  * changed: - If the last line of a message in an mbox file only
               contains a dot, then that line will be ignored.
             - License supplemented.
  + new:     - Source code released.


References
----------
Unix mailbox format:
[1] <http://resin.csoft.net/cgi-bin/man.cgi?section=5&topic=mbox>
[2] <http://www.python.org/doc/current/lib/module-mailbox.html>

Eudora mailbox format:
[3] <http://eudora2unix.sourceforge.net/details.html>

Internet Message Format (RFC 2822):
[4] <ftp://ftp.isi.edu/in-notes/pdfrfc/rfc2822.txt.pdf>

WCX Writer's Reference:
[5] <http://ghisler.fileburst.com/plugins/wcx_ref2.1.zip>


Credits
-------
This software was written in Euphoria. Finally it was translated using
the Euphoria To C Translator 2.4. Thanks to Robert Craig for one of the
best general purpose programming languages.
<http://www.rapideuphoria.com/>

Thanks to Elliott Sales de Andrade and Bob Elia from the "Euphoria
Community", for their very valuable help.

The C code produced by Euphoria was compiled with the Borland C++ 5.5.1
Command-line Compiler. Thanks to Borland Software Corporation for
providing this great tool at no charge.
<http://www.borland.com/products/downloads/download_cbuilder.html>

Thanks to Christian Ghisler for the Total Commander, the "Swiss army
knife" for the Windows PC, and also for patiently answering my
questions. The Total Commander is an essential tool for me, that greatly
enhances my productivity.
<http://www.ghisler.com/>

Thanks to all beta testers.


License
-------
All rights and the copyright of the software distributed with this
license remain with the developer, Juergen Luethje.

This software is distributed as Freeware, you are free to use it at no
charge. You may copy the software and it's documentation freely, as long
as you are not selling it and the file "mbox100.zip" is distributed
unchanged and completely.
Without special written permission by the author, you are not allowed to
wrap the file "mbox100.zip". That means you must not distribute the file
in a way, that it is packed in another archive or any other file.

This software is distributed WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
I do not accept responsibility for any effects, adverse or otherwise,
that this code may have on you or your computer. Use it at your own risk.


Contact
-------
Please send questions, suggestions, comments, and bug reports to
<jlpost@arcor.de>

This software can be downloaded from
<http://home.arcor.de/luethje/prog/>
