[tz] [PROPOSED] Improve doc for some source files
scolebourne at joda.org
Thu Jan 27 22:41:59 UTC 2022
AFAICT, this is a reasonable enhancement to the docs that describes
the current state of tzdb.
On Wed, 26 Jan 2022 at 18:59, Paul Eggert via tz <tz at iana.org> wrote:
> * theory.html: Mention zone.tab and improve description of
> 'backward' and 'etcetera'. The goal of this change is to describe
> existing practice, and to allay concerns that names listed in
> 'backward' are going away.
> theory.html | 27 +++++++++++++++++++++------
> 1 file changed, 21 insertions(+), 6 deletions(-)
> diff --git a/theory.html b/theory.html
> index 5a05f4b..28cc88e 100644
> --- a/theory.html
> +++ b/theory.html
> @@ -296,7 +296,7 @@ in decreasing order of importance:
> If a name is changed, put its old spelling in the
> - '<code>backward</code>' file.
> + '<code>backward</code>' file as a link to the new spelling.
> This means old spellings will continue to work.
> Ordinarily a name change should occur only in the rare case when
> a location's consensus English-language spelling changes; for example,
> @@ -348,22 +348,37 @@ timestamps correctly and it increased maintenance burden.
> -The file '<code>zone1970.tab</code>' lists geographical locations used
> +The file <code>zone1970.tab</code> lists geographical locations used
> to name timezones.
> It is intended to be an exhaustive list of names for geographic
> regions as described above; this is a subset of the timezones in the data.
> -Although a '<code>zone1970.tab</code>' location's
> +Although a <code>zone1970.tab</code> location's
> <a href="https://en.wikipedia.org/wiki/Longitude">longitude</a>
> corresponds to
> its <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean
> time (<abbr>LMT</abbr>)</a> offset with one hour for every 15°
> east longitude, this relationship is not exact.
> +The backward-compatibility file <code>zone.tab</code> is similar
> +but conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1;
> +it lists only one country code per entry and unlike <code>zone1970.tab</code>
> +it can list names defined in <code>backward</code>.
> -Excluding '<code>backward</code>' should not affect the other data.
> -If '<code>backward</code>' is excluded, excluding
> -'<code>etcetera</code>' should not affect the remaining data.
> +The database defines each timezone name to be a zone, or a link to a zone.
> +The source file <code>backward</code> defines links for backward
> +compatibility; it does not define zones.
> +Although <code>backward</code> was originally designed to be optional,
> +nowadays distributions typically use it
> +and no great weight should be attached to whether a link
> +is defined in <code>backward</code> or in some other file.
> +The source file <code>etcetera</code> defines names that may be useful
> +on platforms that do not support POSIX-style <code>TZ</code> strings;
> +no other source file other than <code>backward</code>
> +contains links to its zones.
> +One of <code>etcetera</code>'s names is <code>GMT</code>,
> +used by functions like <code>gmtime</code> to obtain leap
> +second information on platforms that support leap seconds.
More information about the tz