**********************************************************************
* Copyright (c) 2003-2004, International Business Machines
* Corporation and others.  All Rights Reserved.
**********************************************************************
* Author: Alan Liu
* Created: August 18 2003
* Since: ICU 2.8
**********************************************************************

----------------------------------------------------------------------
OVERVIEW

This file describes the tools in icu/source/tools/tzcode

The purpose of these tools is to process the zoneinfo or "Olson" time
zone database into a form usable by ICU4C (release 2.8 and later).
Unlike earlier releases, ICU4C 2.8 supports historical time zone
behavior, as well as the full set of Olson compatibility IDs.

References:

ICU4C:  http://oss.software.ibm.com/icu/
Olson:  ftp://elsie.nci.nih.gov/pub/

----------------------------------------------------------------------
ICU4C vs. ICU4J

For ICU releases >= 2.8, both ICU4C and ICU4J implement full
historical time zones, based on Olson data.  The implementations in C
and Java are somewhat different.  The C implementation is a
self-contained implementation, whereas ICU4J uses the underlying JDK
1.3 or 1.4 time zone implementation.

Older versions of ICU (C and Java <= 2.6) implement a "present day
snapshot".  This only reflects current time zone behavior, without
historical variation.  Furthermore, it lacks the full set of Olson
compatibility IDs.

----------------------------------------------------------------------
BACKGROUND

The zoneinfo or "Olson" time zone package is used by various systems
to describe the behavior of time zones.  The package consists of
several parts.  E.g.:

  Index of ftp://elsie.nci.nih.gov/pub/

  classictzcode.tar.gz    65 KB        12/10/1994    12:00:00 AM
  classictzdata.tar.gz    67 KB        12/10/1994    12:00:00 AM
  e5+57.tar.gz            2909 KB      3/22/1993     12:00:00 AM
  iso8601.ps.gz           16 KB        7/27/1996     12:00:00 AM
  leastsq.xls             49 KB        4/24/1997     12:00:00 AM
  ltroff.tar.gz           36 KB        7/16/1993     12:00:00 AM
  pi.shar.gz              4 KB         3/9/1994      12:00:00 AM
  tzarchive.gz            3412 KB      8/18/2003     4:00:00 AM
  tzcode2003a.tar.gz      98 KB        3/24/2003     2:32:00 PM
  tzdata2003a.tar.gz      132 KB       3/24/2003     2:32:00 PM

ICU only uses the tzcodeYYYYV.tar.gz and tzdataYYYYV.tar.gz files,
where YYYY is the year and V is the version letter ('a'...'z').

----------------------------------------------------------------------
HOWTO

1. Obtain the current versions of tzcodeYYYYV.tar.gz (aka `tzcode')
   and tzdataYYYYV.tar.gz (aka `tzdata') from the FTP site given
   above.  Either manually download or use wget:

   $ cd {path_to}/icu/source/tools/tzcode
   $ wget "ftp://elsie.nci.nih.gov/pub/tz*.tar.gz"

2. Unpack tzcode and tzdata directly into the directory tzcode:

   $ tar xzvf tzcode*.tar.gz
   $ tar xzvf tzdata*.tar.gz

   *** Make sure you only have ONE FILE named tzdata*.tar.gz in the
       directory.
   *** Do NOT delete the tzdata*.tar.gz file.

   The Makefile looks in the current directory to determine the
   version of Olson data it is building by looking for tzdata*.tar.gz.

3. Apply the ICU patch to zic.c:

   $ patch < patch-icu-tzcode

   If patch complains at this point, there is a mismatch that must be
   manually addressed.  See the CVS log of `patch-icu-tzcode' for
   version details.

4. Build:

   $ make icu_data

5. Copy the data files to the correct location in the ICU4C/ICU4J
   source trees:

   $ cp zoneinfo.txt ../../../data/misc/
   $ cp ZoneMetaData.java {path_to}/icu4j/src/com/ibm/icu/impl

6. Rebuild ICU:

   $ cd ../../../
   $ {*make}

7. Don't forget to check in the new zoneinfo.txt (from its location at
   {path_to}/icu/source/data/misc/zoneinfo.txt) into CVS.

----------------------------------------------------------------------
HOWTO regenerate patch-icu-tzcode

If you need to edit any of the tzcode* files, you will need to
regenerate the patch file as follows.

1. Follow the above instructions to extract and patch the tzcode*
   files in {path_to}/icu/source/tools/tzcode.  Modify any of the
   tzcode files.

2. Extract a clean set of the tzcode* files into a new directory,
   ../tzcode.orig/:

   $ mkdir ../tzcode.orig
   $ cd ../tzcode.orig
   $ tar xzf ../tzcode/tzcode*.tar.gz
   $ cd ../tzcode

3. Compute diffs, ignoring files that are in only one directory:

   $ diff -ur ../tzcode.orig . | grep -vE -e "^Only in " > patch-icu-tzcode

4. Test the patch-icu-tzcode file by regenerating and diffing the
   files again in another directory.  The expected output from the
   final diff command is *nothing*.

   $ mkdir ../tzcode.new
   $ cd ../tzcode.new
   $ tar xzf ../tzcode/tzcode*.tar.gz
   $ patch < ../tzcode/patch-icu-tzcode
   $ cd ../tzcode
   $ diff -ur ../tzcode.new . | grep -vE -e "^Only in "

5. Check in the new patch-icu-tzcode file.

----------------------------------------------------------------------
eof