Import tzcode 2025c - src - FreeBSD source tree

diff options


context:
space:
mode:

author	Dag-Erling Smørgrav <des@FreeBSD.org>	2025-12-11 10:28:59 +0000
committer	Dag-Erling Smørgrav <des@FreeBSD.org>	2025-12-11 10:28:59 +0000
commit	0d46d875e60091694abe5d38e0cbb4c8019bfd71 (patch)
tree	5d52afe9fe7ccb0e9f4357ab8e9926be47b129a3 /tz-how-to.html
parent	76d3e9d6b36023210e896d00ecef2d19f0acd2d8 (diff)

Import tzcode 2025cvendor/tzcode/tzcode2025c

Diffstat (limited to 'tz-how-to.html')

-rw-r--r--

tz-how-to.html

178

1 files changed, 89 insertions, 89 deletions

diff --git a/tz-how-to.html b/tz-how-to.html
index 9e438f93092a..ccfdc9eb4fdb 100644
--- a/tz-how-to.html
+++ b/tz-how-to.html

@@ -23,18 +23,18 @@ times of day from the <a href="tz-link.html">tz database</a>

source files. It might be helpful, but not absolutely necessary,

for the reader to have already downloaded the

latest release of the database and become familiar with the basic layout

-of the data files. The format is explained in the “man

-page” for the zic compiler, <code>zic.8.txt</code>, in

+of the data files. The format is explained in the “man page”

+for the zic compiler, <code>zic.8.txt</code>, in

the <code>code</code> subdirectory.

Although this guide covers many of the common cases, it is not a

complete summary of what zic accepts; the man page is the

authoritative reference.

-We’ll begin by talking about the rules for changing between standard

-and daylight saving time since we’ll need that information when we talk

+We’ll begin by talking about the rules for changing between standard

+and daylight saving time since we’ll need that information when we talk

about the zones.

-First, let’s consider the special daylight saving time rules

+First, let’s consider the special daylight saving time rules

for Chicago (from the <code>northamerica</code> file in

the <code>data</code> subdirectory):

@@ -107,7 +107,7 @@ first and last calendar years defining a contiguous range over which a specific

Rule line is to apply. The keyword <code>only</code> can be used in the

<code>TO</code> field to repeat the value of the <code>FROM</code> field in the

event that a rule should only apply to a single year. Often, the keyword

-<code>max</code> is used to extend a rule’s application into the

+<code>max</code> is used to extend a rule’s application into the

indefinite future; it is a platform-agnostic stand-in for the largest

representable year.

@@ -117,28 +117,28 @@ Prior to the 2020b release, it was called the <code>TYPE</code> field, though

it had not been used in the main data since the 2000e release.

An obsolescent supplementary file used the

field as a proof-of-concept to allow <code>zic</code> to apply a given Rule

-line only to certain “types” of years within the specified range as

+line only to certain “types” of years within the specified range as

dictated by the output of a separate script, such as: only years which would

-have a US presidential election, or only years which wouldn’t.

+have a US presidential election, or only years which wouldn’t.

The <code>SAVE</code> column contains the local (wall clock) offset from

local standard time.

This is usually either zero for standard time or one hour for daylight

-saving time; but there’s no reason, in principle, why it can’t

+saving time; but there’s no reason, in principle, why it can’t

take on other values.

The <code>LETTER</code> (sometimes called <code>LETTER/S</code>)

column can contain a variable

-part of the usual abbreviation of the time zone’s name, or it can just

-be a hyphen if there’s no variable part. For example, the abbreviation

-used in the central time zone will be either “CST” or

-“CDT”. The variable part is ‘S’ or ‘D’;

-and, sure enough, that’s just what we find in

+part of the usual abbreviation of the time zone’s name, or it can just

+be a hyphen if there’s no variable part. For example, the abbreviation

+used in the central time zone will be either “CST” or “CDT”.

+The variable part is ‘S’ or ‘D’;

+and, sure enough, that’s just what we find in

the <code>LETTER</code> column

in the <code>Chicago</code> rules. More about this when we talk about

-“Zone” lines.

+“Zone” lines.

-One important thing to notice is that “Rule” lines

+One important thing to notice is that “Rule” lines

want at once to be both transitions and steady states:

<ul>

<li>On the one hand, they represent transitions between standard and

@@ -158,7 +158,7 @@ years. Similarly, the rule for changing to daylight saving time was

the same from 1922 to 1966; but the rule for returning to standard

time changed in 1955. Got it?

-OK, now for the somewhat more interesting “US” rules:

+OK, now for the somewhat more interesting “US” rules:

<table>

<tr>

@@ -211,15 +211,15 @@ Rule US 2007 max - Nov Sun>=1 2:00 0 S

<tr>

<td colspan="2">February 9th</td>

- <td>go to “war time”</td>

+ <td>go to “war time”</td>

</tr>

<tr>

<td colspan="2">August 14th</td>

<td>

- rename “war time” to “peace time;”

- clocks don’t change

+ rename “war time” to “peace time;”

+ clocks don’t change

</td>

</tr>

<tr>

@@ -272,33 +272,33 @@ Rule US 2007 max - Nov Sun>=1 2:00 0 S

First, the time that something happens (in the <code>AT</code>

column) is not necessarily the local (wall clock) time. The time can be

-suffixed with ‘s’ (for “standard”) to mean

+suffixed with ‘s’ (for “standard”) to mean

local standard time, different from local (wall clock) time when observing

-daylight saving time; or it can be suffixed with ‘g’,

-‘u’, or ‘z’, all three of which mean the

+daylight saving time; or it can be suffixed with ‘g’,

+‘u’, or ‘z’, all three of which mean the

standard time at the

<a href="https://en.wikipedia.org/wiki/Prime_Meridian">prime meridian</a>.

-‘g’ stands for “<a

-href="https://en.wikipedia.org/wiki/Greenwich_Mean_Time">GMT</a>”;

-‘u’ stands for “<a

-href="https://en.wikipedia.org/wiki/Universal_Time">UT</a>” or “<a

-href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a>”

-(whichever was official at the time); ‘z’ stands for the

+‘g’ stands for “<a

+href="https://en.wikipedia.org/wiki/Greenwich_Mean_Time">GMT</a>”;

+‘u’ stands for “<a

+href="https://en.wikipedia.org/wiki/Universal_Time">UT</a>” or “<a

+href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a>”

+(whichever was official at the time); ‘z’ stands for the

<a href="https://en.wikipedia.org/wiki/Nautical_time">nautical time zone</a>

-Z (a.k.a. “Zulu” which, in turn, stands for ‘Z’).

-The time can also be suffixed with ‘w’ meaning local (wall

-clock) time; but it usually isn’t because that’s the

+Z (a.k.a. “Zulu” which, in turn, stands for ‘Z’).

+The time can also be suffixed with ‘w’ meaning local (wall

+clock) time; but it usually isn’t because that’s the

default.

Second, the day in the <code>ON</code> column, in addition to

-“<code>lastSun</code>” or a particular day of the month,

-can have the form, “<code>Sun>=</code>x” or

-“<code>Sun<=</code>x,” where x is a day

-of the month. For example, “<code>Sun>=8</code>” means

-“the first Sunday on or after the eighth of the month,” in

+“<code>lastSun</code>” or a particular day of the month,

+can have the form, “<code>Sun>=</code>x” or

+“<code>Sun<=</code>x,” where x is a day

+of the month. For example, “<code>Sun>=8</code>” means

+“the first Sunday on or after the eighth of the month,” in

other words, the second Sunday of the month. Furthermore, although

-there are no examples above, the weekday needn’t be

-“<code>Sun</code>” in either form, but can be the usual

+there are no examples above, the weekday needn’t be

+“<code>Sun</code>” in either form, but can be the usual

three-character English abbreviation for any day of the week.

And the US rules give us more examples of a couple of things

@@ -317,8 +317,8 @@ state or other more local rule).</li>

<li>The <code>SAVE</code> and <code>LETTER</code> columns

contain steady state, not transitions. Consider, for example,

-the transition from “war time” to “peace time”

-that happened on August 14, 1945. The “1:00” in

+the transition from “war time” to “peace time”

+that happened on August 14, 1945. The “1:00” in

the <code>SAVE</code> column is not an instruction to advance

the clock an hour. It means that clocks should be one hour

ahead of standard time, which they already are because of the previous

@@ -326,7 +326,7 @@ rule, so there should be no change.</li>

</ul>

-OK, now let’s look at a Zone record:

+OK, now let’s look at a Zone record:

<table>

<tr>

@@ -365,14 +365,14 @@ Zone America/Chicago -5:50:36 - LMT 1883 Nov 18 12:09:24

</tr>

<tr>

- <td>−5:50:36</td>

+ <td>−5:50:36</td>

<td>not observed</td>

</tr>

<tr>

- <td rowspan="2">−6:00:00</td>

+ <td rowspan="2">−6:00:00</td>

<td>US rules</td>

@@ -384,13 +384,13 @@ Zone America/Chicago -5:50:36 - LMT 1883 Nov 18 12:09:24

</tr>

<tr>

- <td>−5:00:00</td>

+ <td>−5:00:00</td>

<td>not observed</td>

</tr>

<tr>

- <td rowspan="4">−6:00:00</td>

+ <td rowspan="4">−6:00:00</td>

<td>Chicago rules</td>

@@ -408,7 +408,7 @@ Zone America/Chicago -5:50:36 - LMT 1883 Nov 18 12:09:24

</tr>

<tr>

<td>US rules</td>

- <td colspan="2">—</td>

+ <td colspan="2">–</td>

</tr>

</table>

@@ -417,24 +417,24 @@ Zone America/Chicago -5:50:36 - LMT 1883 Nov 18 12:09:24

First, and somewhat trivially, whereas Rules are considered to

contain one or more records, a Zone is considered to be a single

record with zero or more continuation lines. Thus, the keyword,

-“<code>Zone</code>,” and the zone name are not

+“<code>Zone</code>,” and the zone name are not

repeated. The last line is the one without anything in

the <code>[UNTIL]</code> column.

Second, and more fundamentally, each line of a Zone represents a

steady state, not a transition between states. The state exists from

-the date and time in the previous line’s <code>[UNTIL]</code>

+the date and time in the previous line’s <code>[UNTIL]</code>

column up to the date and time in the current

-line’s <code>[UNTIL]</code> column. In other words, the date and

+line’s <code>[UNTIL]</code> column. In other words, the date and

time in the <code>[UNTIL]</code> column is the instant that separates

this state from the next. Where that would be ambiguous because

-we’re setting our clocks back, the <code>[UNTIL]</code> column

+we’re setting our clocks back, the <code>[UNTIL]</code> column

specifies the first occurrence of the instant. The state specified by

the last line, the one without anything in the <code>[UNTIL]</code>

column, continues to the present.

The first line typically specifies the mean solar time observed

-before the introduction of standard time. Since there’s no line before

+before the introduction of standard time. Since there’s no line before

that, it has no beginning. <code>8-) </code> For some places near the <a

href="https://en.wikipedia.org/wiki/International_Date_Line">International

Date Line</a>, the first two lines will show solar times

@@ -453,16 +453,16 @@ Alaska was then 24 hours earlier than it had

been. <code><aside></code>(6 October in the Julian calendar,

which Russia was still using then for religious reasons, was followed

by a second instance of the same day with a different name, 18

-October in the Gregorian calendar. Isn’t civil time

+October in the Gregorian calendar. Isn’t civil time

wonderful? <code>8-)</code>)<code></aside></code>

-The abbreviation, “LMT” stands for “local mean

-time”, which is an invention of

+The abbreviation, “LMT” stands for “local mean

+time”, which is an invention of

the <a href="https://en.wikipedia.org/wiki/Tz_database">tz

database</a> and was probably never actually used during the

period. Furthermore, the value is almost certainly wrong except in the

archetypal place after which the zone is named. (The tz database

-usually doesn’t provide a separate Zone record for places where

+usually doesn’t provide a separate Zone record for places where

nothing significant happened after 1970.)

The <code>RULES</code> column tells us whether daylight saving time is being observed:

@@ -470,7 +470,7 @@ nothing significant happened after 1970.)

<li>A hyphen, a kind of null value, means that we have not set our

clocks ahead of standard time.</li>

-<li>An amount of time (usually but not necessarily “1:00”

+<li>An amount of time (usually but not necessarily “1:00”

meaning one hour) means that we have set our clocks ahead by that

amount.</li>

@@ -488,10 +488,10 @@ Zone Pacific/Honolulu ... 1933 Apr 30 2:00

</pre>

Hawaii tried daylight saving time for three weeks in 1933 and

-decided they didn’t like it. <code>8-) </code>Note that

+decided they didn’t like it. <code>8-) </code>Note that

the <code>STDOFF</code> column always contains the standard time

-offset, so the local (wall clock) time during this period was GMT −

-10:30 + 1:00 = GMT − 9:30.

+offset, so the local (wall clock) time during this period was GMT −

+10:30 + 1:00 = GMT − 9:30.

The <code>FORMAT</code> column specifies the usual abbreviation of

the time zone name. It should have one of four forms:

@@ -499,24 +499,24 @@ the time zone name. It should have one of four forms:

<li>a time zone abbreviation that is a string of three or more

characters that are either ASCII alphanumerics,

-“<code>+</code>”, or “<code>-</code>”</li>

+“<code>+</code>”, or “<code>-</code>”</li>

-<li>the string “%z”, in which case the

-“<code>%z</code>” will be replaced by a numeric time zone

+<li>the string “%z”, in which case the

+“<code>%z</code>” will be replaced by a numeric time zone

abbreviation</li>

<li>a pair of time zone abbreviations separated by a slash

-(‘<code>/</code>’), in which case the first string is the

+(‘<code>/</code>’), in which case the first string is the

abbreviation for the standard time name and the second string is the

abbreviation for the daylight saving time name</li>

-<li>a string containing “<code>%s</code>”, in which case

-the “<code>%s</code>” will be replaced by the text in the

-appropriate Rule’s <code>LETTER</code> column, and the resulting

+<li>a string containing “<code>%s</code>”, in which case

+the “<code>%s</code>” will be replaced by the text in the

+appropriate Rule’s <code>LETTER</code> column, and the resulting

string should be a time zone abbreviation</li>

</ul>

-The last two make sense only if there’s a named rule in effect.

+The last two make sense only if there’s a named rule in effect.

An example of a slash is:

<pre>

@@ -552,9 +552,9 @@ database</a> gives abbreviations for time zones

in popular English-language usage. For

example, the last line in

<code>Zone</code> <code>Pacific/Honolulu</code> (shown below) gives

-“HST” for “Hawaii standard time” even though the

+“HST” for “Hawaii standard time” even though the

<a href="https://www.law.cornell.edu/uscode/text/15/263">legal</a>

-name for that time zone is “Hawaii-Aleutian standard time.”

+name for that time zone is “Hawaii–Aleutian standard time”.

This author has read that there are also some places in Australia where

popular time zone names differ from the legal ones.

@@ -562,10 +562,10 @@ popular time zone names differ from the legal ones.

href="https://en.wikipedia.org/wiki/Internationalization_and_localization">localize</a>

the abbreviations. They are intended to be the values returned through the

<code>"%Z"</code> format specifier to

-<a href="https://en.wikipedia.org/wiki/C_(programming_language)">C</a>’s

-<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.html"><code>strftime</code></a>

+<a href="https://en.wikipedia.org/wiki/C_(programming_language)">C</a>’s

+<a href="https://pubs.opengroup.org/onlinepubs/9799919799/functions/strftime.html"><code>strftime</code></a>

function in the

-<a href="https://kirste.userpage.fu-berlin.de/chemnet/use/info/libc/libc_19.html#SEC324">“C” locale</a>.

+<a href="https://kirste.userpage.fu-berlin.de/chemnet/use/info/libc/libc_19.html#SEC324">“C” locale</a>.

<li>If there is no generally accepted abbreviation for a time zone,

a numeric offset is used instead, e.g., <code>+07</code> for 7 hours

@@ -574,7 +574,7 @@ zone while uninhabited, where the offset is zero but in some sense

the true offset is undefined.

</ul>

-As a final example, here’s the complete history for Hawaii:

+As a final example, here’s the complete history for Hawaii:

<table>

<tr>

@@ -626,15 +626,15 @@ Zone Pacific/Honolulu -10:31:26 - LMT 1896 Jan 13 12:00

</tr>

<tr>

- <td>−10:31:26</td>

- <td>—</td>

+ <td>−10:31:26</td>

+ <td>–</td>

<td>local mean time</td>

</tr>

<tr>

- <td>−10:30</td>

+ <td>−10:30</td>

<td>Hawaii standard time</td>

@@ -642,7 +642,7 @@ Zone Pacific/Honolulu -10:31:26 - LMT 1896 Jan 13 12:00

</tr>

<tr>

- <td>−9:30</td>

+ <td>−9:30</td>

<td>Hawaii daylight time</td>

@@ -650,15 +650,15 @@ Zone Pacific/Honolulu -10:31:26 - LMT 1896 Jan 13 12:00

</tr>

<tr>

- <td>−10:30¹</td>

- <td>−1:00¹</td>

+ <td>−10:30¹</td>

+ <td>−1:00¹</td>

<td>Hawaii standard time</td>

</tr>

<tr>

- <td rowspan="2">−9:30</td>

+ <td rowspan="2">−9:30</td>

<td>Hawaii war time</td>

@@ -673,34 +673,34 @@ Zone Pacific/Honolulu -10:31:26 - LMT 1896 Jan 13 12:00

</tr>

<tr>

- <td>−10:30</td>

- <td>−1:00</td>

+ <td>−10:30</td>

+ <td>−1:00</td>

<td rowspan="2">Hawaii standard time</td>

</tr>

<tr>

- <td>−10:00³</td>

+ <td>−10:00³</td>

- <td colspan="2">—</td>

+ <td colspan="2">–</td>

</tr>

<tr>

- ¹Switching to US rules…most recent transition (in 1919) was to standard time

+ ¹Switching to US rules...most recent transition (in 1919) was to standard time

</td>

</tr>

<tr>

²23:00 <a href="https://en.wikipedia.org/wiki/Universal_Time">UT</a>

- + (−9:30) = 13:30 local

+ + (−9:30) = 13:30 local

</td>

</tr>

<tr>

- ³Since <a href="https://en.wikipedia.org/wiki/ISO_8601">1947–06–08T12:30Z</a>,

+ ³Since <a href="https://en.wikipedia.org/wiki/ISO_8601">1947-06-08T12:30Z</a>,

the civil time in Hawaii has been

- − 10:00 year-round.

+ −10:00 year-round.

</td>

</tr>

</table>