pike.git / lib / modules / Calendar.pmod / tzdata / theory.html

version» Context lines:

pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:8:    </style>   </head>      <body>   <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>    <h3>Outline</h3>    <nav>    <ul>    <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>    database</a></li> -  <li><a href="#naming">Names of timezones</a></li> +  <li><a href="#naming">Timezone identifiers</a></li>    <li><a href="#abbreviations">Time zone abbreviations</a></li>    <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>    database</a></li>    <li><a href="#functions">Time and date functions</a></li>    <li><a href="#stability">Interface stability</a></li>    <li><a href="#calendar">Calendrical issues</a></li>    <li><a href="#planets">Time and time zones on other planets</a></li>    </ul>    </nav>   
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:100:   can change at times.   Whether and when a timezone changes its   clock, and even the timezone's notional base offset from UTC, are variable.   It does not always make sense to talk about a timezone's   "base offset", which is not necessarily a single number.   </p>      </section>      <section> -  <h2 id="naming">Names of timezones</h2> +  <h2 id="naming">Timezone identifiers</h2>   <p> - Each timezone has a unique name. + Each timezone has a name that uniquely identifies the timezone.   Inexperienced users are not expected to select these names unaided.   Distributors should provide documentation and/or a simple selection   interface that explains each name via a map or via descriptive text like   "Ruthenia" instead of the timezone name "<code>Europe/Uzhgorod</code>".   If geolocation information is available, a selection interface can   locate the user on a timezone map or prioritize names that are   geographically close. For an example selection interface, see the   <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.   The <a href="http://cldr.unicode.org/">Unicode Common Locale Data   Repository</a> contains data that may be useful for other selection
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:135:    <li>    Uniquely identify every timezone where clocks have agreed since 1970.    This is essential for the intended use: static clocks keeping local    civil time.    </li>    <li>    Indicate to experts where the timezone's clocks typically are.    </li>    <li>    Be robust in the presence of political changes. -  For example, names of countries are ordinarily not used, to avoid +  For example, names are typically not tied to countries, to avoid    incompatibilities when countries change their name (e.g., -  Zaire&rarr;Congo) or when locations change countries (e.g., Hong +  Swaziland&rarr;Eswatini) or when locations change countries (e.g., Hong    Kong from UK colony to China). -  +  There is no requirement that every country or national +  capital must have a timezone name.    </li>    <li>    Be portable to a wide variety of implementations.    </li>    <li>    Use a consistent naming conventions over the entire world.    </li>   </ul>      <p>
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:208:    start with '<code>/</code>', as a regular file cannot have the    same name as a directory in POSIX.    For example, <code>America/New_York</code> precludes    <code>America/New_York/Bronx</code>.    </li>    <li>    Uninhabited regions like the North Pole and Bouvet Island    do not need locations, since local time is not defined there.    </li>    <li> -  There should typically be at least one name for each <a -  href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr -  title="International Organization for Standardization">ISO</abbr> -  3166-1</a> officially assigned two-letter code for an inhabited -  country or territory. -  </li> -  <li> +     If all the clocks in a timezone have agreed since 1970,    do not bother to include more than one timezone    even if some of the clocks disagreed before 1970.    Otherwise these tables would become annoyingly large.    </li>    <li> -  +  If boundaries between regions are fluid, such as during a war or +  insurrection, do not bother to create a new timezone merely +  because of yet another boundary change. This helps prevent table +  bloat and simplifies maintenance. +  </li> +  <li>    If a name is ambiguous, use a less ambiguous alternative;    e.g., many cities are named San José and Georgetown, so    prefer <code>America/Costa_Rica</code> to    <code>America/San_Jose</code> and <code>America/Guyana</code>    to <code>America/Georgetown</code>.    </li>    <li>    Keep locations compact.    Use cities or small islands, not countries or regions, so that any    future changes do not split individual locations into different
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:292:    to be somewhat greater than Rome's.    </li>    <li>    If a name is changed, put its old spelling in the    '<code>backward</code>' file.    This means old spellings will continue to work.    </li>   </ul>      <p> - 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 - <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&deg; - east longitude, this relationship is not exact. + Guidelines have evolved with time, and names following old versions of + this guideline might not follow the current version. When guidelines + have changed, old names continue to be supported. Guideline changes + have included the following:   </p>    - <p> - Older versions of this package used a different naming scheme, - and these older names are still supported. + <ul> + <li> + Older versions of this package used a different naming scheme.   See the file '<code>backward</code>' for most of these older names   (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').   The other old-fashioned names still supported are   '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and   '<code>EET</code>' (see the file '<code>europe</code>'). - </p> + </li>    - <p> + <li>   Older versions of this package defined legacy names that are   incompatible with the first guideline of location names, but which are   still supported.   These legacy names are mostly defined in the file   '<code>etcetera</code>'.   Also, the file '<code>backward</code>' defines the legacy names   '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>',   and the file '<code>northamerica</code>' defines the legacy names   '<code>EST5EDT</code>', '<code>CST6CDT</code>',   '<code>MST7MDT</code>', and '<code>PST8PDT</code>'. -  + </li> +  + <li> + Older versions of this guideline said that + there should typically be at least one name for each <a + href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr + title="International Organization for Standardization">ISO</abbr> + 3166-1</a> officially assigned two-letter code for an inhabited + country or territory. + This old guideline has been dropped, as it was not needed to handle + timestamps correctly and it increased maintenance burden. + </li> + </ul> +  + <p> + 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 + <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&deg; + east longitude, this relationship is not exact.   </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.   </p>   </section>      <section>
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:976:   <code><abbr>tz</abbr></code> code</h3>   <ul>    <li>    <p>    The <code>TZ</code> environment variable is used in generating    the name of a file from which time-related information is read    (or is interpreted à la POSIX); <code>TZ</code> is no longer    constrained to be a string containing abbreviations    and numeric data as described <a href="#POSIX">above</a>.    The file's format is <dfn><abbr>TZif</abbr></dfn>, -  a timezone information format that contains binary data. +  a timezone information format that contains binary data; see +  <a href="https://tools.ietf.org/html/8536">Internet +  <abbr>RFC</abbr> 8536</a>.    The daylight saving time rules to be used for a    particular timezone are encoded in the    <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,    Australian, and other rules to be encoded, and    allows for situations where more than two time zone    abbreviations are used.    </p>    <p>    It was recognized that allowing the <code>TZ</code> environment    variable to take on values such as '<code>America/New_York</code>'
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:1159:      <section>    <h2 id="stability">Interface stability</h2>   <p>   The <code><abbr>tz</abbr></code> code and data supply the following interfaces:   </p>      <ul>    <li>    A set of timezone names as per -  "<a href="#naming">Names of timezones</a>" above. +  "<a href="#naming">Timezone identifiers</a>" above.    </li>    <li>    Library functions described in "<a href="#functions">Time and date    functions</a>" above.    </li>    <li>    The programs <code>tzselect</code>, <code>zdump</code>,    and <code>zic</code>, documented in their man pages.    </li>    <li>
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:1206:   the <code><abbr>tz</abbr></code> database</a> describes how releases   are tagged and distributed.   </p>      <p>   Interfaces not listed above are less stable.   For example, users should not rely on particular <abbr>UT</abbr>   offsets or abbreviations for timestamps, as data entries are often   based on guesswork and these guesses may be corrected or improved.   </p> +  + <p> + Timezone boundaries are not part of the stable interface. + For example, even though the <samp>Asia/Bangkok</samp> timezone + currently includes Chang Mai, Hanoi, and Phnom Penh, this is not part + of the stable interface and the timezone can split at any time. + If a calendar application records a future event in some location other + than Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record, + the application should be robust in the presence of timezone splits + between now and the future time. + </p>   </section>      <section>    <h2 id="calendar">Calendrical issues</h2>   <p>   Calendrical issues are a bit out of scope for a time zone database,   but they indicate the sort of problems that we would run into if we   extended the time zone database further into the past.   An excellent resource in this area is Edward M. Reingold   and Nachum Dershowitz, <cite><a