From 63207b74698aa9642f9c17f635c65b0114c6d191 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Thu, 29 Sep 2016 13:45:39 -0700 Subject: [PROPOSED PATCH 2/2] Cover interface stability in 'Theory' * NEWS, Theory (Interface stability): New section. (Requested by Paul Koning.) --- NEWS | 6 ++++-- Theory | 29 +++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/NEWS b/NEWS index d87e7fd..81b05b5 100644 --- a/NEWS +++ b/NEWS @@ -19,8 +19,10 @@ Unreleased, experimental changes Changes to documentation and commentary - The Theory file now mentions features like tm_zone and - localtime_rz that have long been supported by the reference code. + The 'Theory' file now has a section on interface stability. + (Requested by Paul Koning.) It also mentions features like + tm_zone and localtime_rz that have long been supported by the + reference code. The US commentary now mentions Allen and the "day of two noons". diff --git a/Theory b/Theory index dc9ca36..677baf6 100644 --- a/Theory +++ b/Theory @@ -583,6 +583,35 @@ more powerful time conversion functions can be standardized, so much the better. +----- Interface stability ----- + +The tz code and data supply the following interfaces: + + * A set of zone names as per "Names of time zone rules" above. + + * Library functions described in "Time and date functions" above. + + * The programs tzselect, zdump, and zic, documented in their man pages. + + * The format of zic input files, documented in the zic man page. + + * The format of zic output files, documented in the tzfile man page. + + * The format of zone table files, documented in zone1970.tab. + + * The format of the country code file, documented in iso3166.tab. + +When these interfaces are changed, an effort is made to preserve +backward compatibility. For example, tz data files typically do not +rely on recently-added zic features, so that users can run older zic +versions to process newer data files. + +Interfaces not listed above are less stable. For example, users +should not rely on particular UT offsets or abbreviations for time +stamps, as data entries are often based on guesswork and these guesses +may be corrected or improved. + + ----- Calendrical issues ----- Calendrical issues are a bit out of scope for a time zone database, -- 2.7.4