man(txt) manual page

Name

tb2kmail - exports mailboxes from The Bat! to a KMail compatible directory structure

tb2kmail.pl [-i indir] [-o outdir] [-OD] [--(read|unread)-only] [--(replied|unreplied)-only] [--(parked|unparked)-only] [--maxage days] [--append option[;...]] ... [-A path_to_thebat.exe] [--noexit] user ...

History

The Bat! is a very nifty shareware mailer for Windows. It is (almost) as configurable as mutt with an interface as easy to use (aka klickibunti") as KMail's. It's only disadvantage is that there's no Linux port :o)

So when I moved to Linux I had to choose a new mailer. I decided to give KMail a try, even though it's missing many features of The Bat! I became used to (especially the template management was IMHO very useful).

Whatever, I moved to Linux and (of course) didn't want to loose all my mail. The Bat! indeed has a feature to export single folders to the mbox format but I'm some kind of a deep-nested-folders-fetishist ;-) And I did not like the idea very much of exporting about 100 folders from an up to 4 level deep folder structure one by one and afterwards sort them together in the right order again.

But then I discovered The Bat!'s export- and batch-commands...

Description

tb2kmail uses the export feature of The Bat! to recursively export the whole account(s) given with user to a KMail compatible directory structure.

This can be done under Windows only, as the script has to call the The Bat! executable (thebat.exe). I don't think you need to have The Bat! installed (e.g. a local copy of the thebat.exe plus some DLLs should be enough) but it makes life much easier as the script can get the location of the executable and the mail directory from the Registry.

If the script can't determine location of the executable, you've got to pass it via the -A option. The mail directory can/must be passed via the -i option.

The output directory can be changed with the -o option. It defaults the the current directory. Inside the output directory a sub directory for each exported account will be created.

Options

-i indir, --indir indir
The location of the input directory (where the accounts can be found). If omitted, the script tries to get it from the Registry (works with an installed copy of The Bat! only).

-o outdir, --outdir outdir: The location of the output directory (where the KMail mailbox(es) are saved to). If omitted, it defaults to the current directory. A sub directory for each exported account will be created below this directory.
-O, --override: Instruct The Bat! to overwrite already existing mbox files. By default, The Bat! will append new messages to the mbox file. Be careful with this one when exporting directly to your (mounted) KMail mail directory!
-D, --delete: Instruct The Bat! to delete exported mails from the account at the end of a successful export operation. Be very careful with this one!
--read-only, --nounread: --unread-only, --noread Only mails flagged as read/unread (respectively) are exported.
--replied-only, --nounreplied: --unreplied-only, --noreplied Only mails flagged as replied/unreplied (respectively) are exported.
--parked-only, --nounparked: --unparked-only, --noparked Only mails flagged as parked/unparked (respectively) are exported.
--maxage days, --age days: No mails older than days will be exported.
--append option[;...], --raw option[;...]: Append the given option(s) to the export command. Multiple options can be given either by seperating them with a semicolon or by using --append more than once.
-A path_to_thebat.exe, --app path_to_thebat.exe: Tell the script where it can find the executable thebat.exe. If omitted, it's tried to resolve the location from the Registry.
--noexit: Don't close The Bat! when the export is finished. Per default any instance of The Bat! will be shut down, whether it has already been running or it has been started by the script.
--version: Print version and exit.
--help, -h, -?: Print short usage overview and exit.
--man: Print man page and exit.

Bugs

Currently I'm aware of three nasty bugs:

1. When the script is finished and let you back out to the command line, The Bat! is propably not yet finished exporting your mailbox(es). So don't use the --noexit option if you want to be shure to see when your export is finished.

Short technical summary of the problem: We can control The Bat! by writing commands to the file thebat.ipc. The Bat! deletes this files when it processed all commands and that's our signal to exit our script. But somehow it looks like The Bat! processes the tasks parallely and thus removes the file before it's finished.

2. There's a problem exporting mailboxes containing special (aka non-ASCII) characters like ДЖЭИА etc. Plainly said: They won't be exported. tb2kmail will give you a Oops, what happened to directory? in this case. Seems like it's a problem with different character sets. Just avoid those characters in your mailbox names and/or rename them.

3. Trailing dots in your mailboxes are fatal, too. Those thingies just aren't allowed at the end of DOS file/directory names and are atomatically stripped away. Seems like The Bat! uses the file ACCOUNT.FLX in the account directory to map such mailboxes to their physical names. A solution is to rename your mailboxes prior to the export.

If you found a solution to those or any other bug, or found one yet undiscovered, please send a mail to <tb2kmail-bugs (at) msquadrat (dot) de>.

If you're interested in scripting The Bat!, give the help pages at [1] a try. Especially [2] and [3] should be from interest.

Author

Malte S. Stretz <tb2kmail (at) msquadrat (dot) de>

References

[1] The Bat! Help System <http://www.ritlabs.com/the_bat/hlp/>

[2] About The Bat! Command line parameters <http://www.ritlabs.com/the_bat/hlp/idh_cmdp.htm>

[3] Export messages or addresses - /EXPORT command <http://www.ritlabs.com/the_bat/hlp/idh_cmd_export.htm>