[PROPOSED] Improve doc for some source files
* 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: </li> <li> 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. </ul> <p> -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>. </p> <p> -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. </p> </section> -- 2.32.0
AFAICT, this is a reasonable enhancement to the docs that describes the current state of tzdb. Stephen On Wed, 26 Jan 2022 at 18:59, Paul Eggert via tz <tz@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: </li> <li> 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. </ul>
<p> -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>. </p>
<p> -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. </p> </section>
-- 2.32.0
participants (2)
-
Paul Eggert -
Stephen Colebourne