Read Me

zAlbee's IMmerge
Trillian/ICQ Instant Messaging Log Merger

by: zAlbee
email: zalbee -AT- gmail -DOT- com
site: http://zalbee.intricus.net/immerge

version 0.45	(Jan 25, 2007)
=============================================================

What it does:
-------------

Do you use Trillian on multiple computers to chat? IMmerge can synchronize 
your IM logs together, in chronological order. It can even merge in certain 
logs from the original clients (ICQ Pro/2003b). All merged logs 
come out as Trillian-format.


IMmerge supports:
- merging classic text logs (.LOG) from all versions of Trillian 0.74 - 3.1,
  Basic and Pro
- merging new XML logs (.XML) from Trillian 3.0+ Basic and Pro. This means you 
  can continue to view your history with the Trillian 3.0+ Pro history viewer.
- converting ICQ Pro (98-2003) logs into Trillian LOG and XML, automatically 
  during merging


What it doesn't do:
-------------------

It doesn't compare the message text itself. It only compares session timestamps.

It doesn't yet produce XML logs from Trillian text logs, or vice-versa. This 
means that if you have a mix of Trillian pre-3.0 and Trillian 3.0+ history, 
those messages with XML logged will continue to be in the XML, but those 
without will continue to be in LOG format only. I intend to implement 
LOG-to-XML conversion in a future version.


Requirements:
-------------

Java Runtime Environment (JRE). http://java.sun.com
  - version 1.4 or greater


If you plan to merge ICQ Pro logs:
  - ICQ History Reader
    - converts ICQ 98/99/2000/2001/2002 databases to HTML format
    - http://hitu.host.sk/icqhr.php
      or http://www.headstrong.de/cgi-bin/download.cgi?icqhr


How to install:
---------------
Simple extract the contents of the ZIP file into a folder of your choice.
For example, "C:\immerge".


How to run:
-------------

Right now it is very basic and command-line only:

  0. Run ICQ History Reader (only if you have logs from the original ICQ Pro 
     client). Click "Open Database", select your ICQ DB, then "Export to HTML".
     Under settings, use "UIN per file".


  1. Go to your Trillian logs from one computer. By default, they are in
     "C:\Program Files\Trillian\users\<username>\logs". Copy the folders 
     inside that are named "AIM", "ICQ", "IRC", "MSN", "YAHOO", and put these
     into a new folder called "logs1".

     Put the logs1 folder in the same place where IMmerge is installed.

     Repeat for the other computers, renaming them to logs2, logs3, logs4, etc.


  2. Put your ICQ Pro HTML logs (from step 0: ICQ History Reader) from one 
     computer into one folder, named "icqh1".

     Put this folder in the same place where IMmerge is installed.

     Repeat for the other computers, renaming them to icqh2, icqh3, etc.


  3. Run "java immerge" from a command prompt.

	-> If you get a NoClassDefFoundError, make sure you are in the directory 
           with immerge.class. 
           If that doesn't work, try "java -classpath . immerge"


  4. The program will ask you for three things:

	1) How many folders ... : enter the number of "logs" folders (from step 1)
	2) How many folders ... : enter the number of "icqh" folders (from step 2)

	3) Should the logs be output to a "Query" folder?
		- enter "Yes" to write both LOG and XML files into the Query subfolder
		  (this is what fresh installs of Trillian 3.0+ expect)
		  
		- enter "No" to write LOG files into the parent folder
		  (this is what pre-3.0 versions OR pre-3.0 upgraded to 3.0+ installs expect)

		- XML files are always written to the Query folder

		- Regardless of what you choose, IMmerge will still read all your 
		  logs successfully

     If you are merging ICQ History Reader HTML files, it will also ask you:

	4) Your ICQ UIN: this is your ICQ number (required)
			- this only affects the logs that are merged from ICQ History Reader
			- this is required for making functional XML files 
	5) Your ICQ Nickname:
			- this only affects the logs that are merged from ICQ History Reader

	6) Correct ICQHR timezone by how many hours?:
			- Check the times that ICQ History Reader produces in your logs;
			  if they are wrong, enter a number of hours to correct it.
			- For example, I found that -16 hours is the correct offset for mine.

	7) Display time in 24-hr format?
			- Enter Yes to write log times like [18:45]
			- Enter No to write log times like [06:45 PM]


  5. The merged logs will be created in a folder called "output". Stats and error 
     messages are displayed on screen.


  6. If all was sucessful, you can copy the output folder back to your Trillian
     folder.


Technical Notes:
----------------

- Currently, the program only merges Trillian logs found in the following folders:

  - AIM
  - ICQ
  - IRC
  - MSN
  - YAHOO

  However, you could trick it into merging logs of other mediums by renaming the 
  folder. There is no actual difference in the way it treats one medium vs. another.


- Note that ICQ 98-2002b single messages are transformed into Trillian-format 
  sessions by IMmerge. The way it works is all messages within 24 hours of the first 
  message are put in the same session. Then a new session is started, and the 
  process is repeated.


- It is unknown how ICQ History Reader calculates timezones, as it does not handle 
  as I expected. When using ICQHR to convert your history, you should leave the 
  ICQHR TimeZone setting on default, otherwise it may omit large portions of your 
  history. Then in the IMmerge program specify an offset.
  A value of -16 works for my logs; you may have to experiment. 
  Please e-mail me (zalbee@gmail.com) if have any additional insight into this.


Changelog:
----------

- v0.45 (Jan 24, 2007):
    - greatly improved the conversion from ICQ Pro to Trillian XML logs.
      -> fixed the way non-ASCII characters were converted from ICQ Pro to character 
	     entities in Trillian XML logs, including UTF-8 entity sequences.
	     Also fixes certain combinations of HTML entities.
      -> fixed a bug where merging ICQ Pro with Trillian XML logs would leave all 
         Trillian sessions at the beginning and ICQ Pro at the end (date was in 
         seconds, should be ms)
    - now adds a space in front of subsequent lines of a multi-line message, when 
	  converting from ICQ Pro. This is more like the newer Trillian behaviour 
	  (in both LOG and XML files)
    - now requires JRE 1.4 (for regex support)

- v0.4 (Jul 13, 2006):
    - added XML log merging
       - also produces XML logs from ICQ history files, and then merges
    - fixed the read/write methods for UTF-8 files when detected. It was using the 
      system default character encoding before. IMmerge is now completely safe to use 
      on logs with foreign Unicode characters.

- v0.3 (Nov 30, 2005):
    - fixed Trillian log timestamp-parsing in other locales/language regions.
    - added option to use 24hr display
    - added option to change timezone correction of ICQHR

- v0.22 (Nov 27, 2005):
    - important fix! did not fix corrupt UTF-8 header before, now it does.

- v0.21 (Nov 26, 2005):
    - no longer needs JRE 1.5. now runs on 1.2 and up.

- v0.2 (Nov 23, 2005):
    - now looks in Query folder + regular folder
    - added option to output to Query folder
    - now keeps true to all the text in the original logs, even if it's formatted 
      incorrectly, not in a session, etc.
    - fixed nested sesssion handling
    - now outputs own UTF-8 header
    - (--fixes logs with corrupt header-- note: was not actually implemented)
    - now works with ICQ History Reader logs that don't have user info

- v0.1 (Oct 4, 2005):
    - first version, little buggy


Things to work on:
------------------

- GUI
- let user specify timestamp format for converting from ICQ History Reader
- produce XML logs from Trillian logs if they do not have a corresponding XML file already
- convert & merge from ICQ Lite logs (coming soon!)
- convert & merge from MSN/Windows Live Messenger logs (coming somewhat later!)
- commandline arguments