add readme file

[SVN r24962]

data/README.zone_spec_csv_file

@@ -0,0 +1,92 @@
+
+The csv file containing the zone_specs used by the 
+boost::local_time::tz_database is intended to be customized by the 
+library user. When customizing this file (or creating your own) the 
+file must follow a specific format.
+
+This first line is expected to contain column headings and is therefore 
+not processed by the tz_database.
+
+Each record (line) must have eleven fields. Some of those fields can 
+be empty. Every field (even empty ones) must be enclosed in double-quotes. 
+Ex:
+  "America/Phoenix" <- string enclosed in quotes
+  ""                <- empty field
+
+Some fields represent a length of time. The format of these fields must be: 
+  "{+|-}hh:mm[:ss]" <- length-of-time format
+Where the plus or minus is mandatory and the seconds are optional.
+
+Since some time zones do not use daylight savings it is not always necessary 
+for every field in a zone_spec to contain a value. All zone_specs must have 
+at least ID and GMT offset. Zones that use daylight savings must have all 
+fields filled except: STD ABBR, STD NAME, DST NAME. You should take note 
+that DST ABBR is mandatory for zones that use daylight savings (see field 
+descriptions for further details).
+
+
+********* Fields and their description/details ********* 
+
+* ID 
+        Contains the identifying string for the zone_spec. Any string will
+        do as long as it's unique. No two ID's can be the same. 
+
+* STD ABBR
+* STD NAME
+* DST ABBR
+* DST NAME
+        These four are all the names and abbreviations used by the time 
+        zone being described. While any string will do in these fields, 
+        care should be taken. These fields hold the strings that will be 
+        used in the output of many of the local_time classes. 
+        Ex:
+        time_zone nyc = tz_db.time_zone_from_region("America/New_York");
+        local_time ny_time(date(2004, Aug, 30), IS_DST, nyc);
+        cout << ny_time.to_long_string() << endl;
+        // 2004-Aug-30 00:00:00 Eastern Daylight Time
+        cout << ny_time.to_short_string() << endl;
+        // 2004-Aug-30 00:00:00 EDT
+        
+        NOTE: The exact format/function names may vary - see local_time 
+        documentation for further details.
+
+* GMT offset
+        This is the number of hours added to utc to get the local time 
+        before any daylight savings adjustments are made. Some examples 
+        are: America/New_York offset -5 hours, & Africa/Cairo offset +2 hours.
+        The format must follow the length-of-time format described above.
+
+* DST adjustment
+        The amount of time added to gmt_offset when daylight savings is in 
+        effect. The format must follow the length-of-time format described
+        above.
+
+#####################################################################
+##### TODO: more rule capabilities are needed - this portion of #####
+##### the tz_database is incomplete                             ##### 
+#####################################################################
+* DST Start Date rule
+        This is a specially formatted string that describes the day of year
+        in which the transition take place. It holds three fields of it's own,
+        separated by semicolons. 
+        * The first field indicates the "nth" weekday of the month. The
+                possible values are: 1 (first), 2 (second), 3 (third), 
+                4 (fourth), 5 (fifth), and -1 (last).
+        * The second field indicates the day-of-week from 0-6 (Sun=0).
+        * The third field indicates the month from 1-12 (Jan=1).
+        
+        Examples are: "-1;5;9"="Last Friday of September", 
+        "2;1;3"="Second Monday of March"
+
+* Start time
+        Start time is the number of hours past midnight, on the day of the
+        start transition, the transition takes place. More simply put, the 
+        time of day the transition is made (in 24 hours format). The format
+        must follow the length-of-time format described above with the 
+        exception that it must always be positive.
+
+* DST End date rule
+        See DST Start date rule. The difference here is this is the day 
+        daylight savings ends (transition to STD).
+* End time
+        Same as Start time.