[tz] [PROPOSED] Mention Zone names with two slashes

Paul Eggert eggert at cs.ucla.edu
Fri Apr 6 00:44:51 UTC 2018


* theory.html: Mention that some zone names have two slashes,
e.g., America/Indiana/Petersburg.  Use past tense for Mars
Pathfinder.  Avoid contractions.  Use full zone names in examples
and omit no-longer-needed quotes.  Add URLs and fix typos.
---
 theory.html | 105 +++++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 61 insertions(+), 44 deletions(-)

diff --git a/theory.html b/theory.html
index 596b32c..ba57653 100644
--- a/theory.html
+++ b/theory.html
@@ -53,7 +53,7 @@ However, the database is not designed for and does not suffice for
 applications requiring accurate handling of all past times everywhere,
 as it would take far too much effort and guesswork to record all
 details of pre-1970 civil timekeeping.
-Athough some information outside the scope of the database is
+Although some information outside the scope of the database is
 collected in a file <code>backzone</code> that is distributed along
 with the database proper, this file is less reliable and does not
 necessarily follow database guidelines.
@@ -79,7 +79,7 @@ flip back and forth between two alternatives, and the rules themselves
 can change at times.
 Whether and when a <code><abbr>tz</abbr></code> region changes its
 clock, and even the region's notional base offset from UTC, are variable.
-It doesn't even really make sense to talk about a region's
+It does not always make sense to talk about a region's
 "base offset", since it is not necessarily a single number.
 </p>
 
@@ -92,8 +92,8 @@ Each <code><abbr>tz</abbr></code> region has a unique name that
 corresponds to a set of time zone rules.
 Inexperienced users are not expected to select these names unaided.
 Distributors should provide documentation and/or a simple selection
-interface that explains the names; for one example, see the 'tzselect'
-program in the <code><abbr>tz</abbr></code> code.
+interface that explains the names; for one example, 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
 interfaces.
@@ -137,6 +137,9 @@ region.
 North and South America share the same area, '<code>America</code>'.
 Typical names are '<code>Africa/Cairo</code>',
 '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
+Some names are further qualified to help avoid confusion; for example,
+'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
+Indiana from other Petersburgs in America.
 </p>
 
 <p>
@@ -159,7 +162,8 @@ in decreasing order of importance:
     <code>TZ</code> strings</a>.
     A file name component must not exceed 14 characters or start with
     '<code>-</code>'.
-    E.g., prefer '<code>Brunei</code>' to '<code>Bandar_Seri_Begawan</code>'.
+    E.g., prefer <code>Asia/Brunei</code> to
+    <code>Asia/Bandar_Seri_Begawan</code>.
     Exceptions: see the discussion of legacy names below.
   </li>
   <li>
@@ -177,8 +181,8 @@ in decreasing order of importance:
     name <var>AB</var> (ignoring case), then <var>B</var> must not
     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>'.
+    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
@@ -193,50 +197,56 @@ in decreasing order of importance:
   </li>
   <li>
     If all the clocks in a region have agreed since 1970,
-    don't bother to include more than one location
+    do not bother to include more than one location
     even if subregions' clocks disagreed before 1970.
     Otherwise these tables would become annoyingly large.
   </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>Costa_Rica</code>' to '<code>San_Jose</code>' and
-    '<code>Guyana</code>' to '<code>Georgetown</code>'.
+    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
     <code><abbr>tz</abbr></code> regions.
-    E.g., prefer '<code>Paris</code>' to '<code>France</code>', since
+    E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
+    since
     <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France
     has had multiple time zones</a>.
   </li>
   <li>
-    Use mainstream English spelling, e.g., prefer '<code>Rome</code>'
-    to '<code>Roma</code>', and prefer '<code>Athens</code>' to the
-    Greek '<code>Αθήνα</code>' or the Romanized '<code>Athína</code>'.
+    Use mainstream English spelling, e.g., prefer
+    <code>Europe/Rome</code> to <code>Europe/Roma</code>, and
+    prefer <code>Europe/Athens</code> to the Greek
+    <code>Europe/Αθήνα</code> or the Romanized
+    <code>Europe/Athína</code>.
     The POSIX file name restrictions encourage this guideline.
   </li>
   <li>
     Use the most populous among locations in a region,
-    e.g., prefer '<code>Shanghai</code>' to
-    '<code>Beijing</code>'.
+    e.g., prefer <code>Asia/Shanghai</code> to
+    <code>Asia/Beijing</code>.
     Among locations with similar populations, pick the best-known
-    location, e.g., prefer '<code>Rome</code>' to
-    '<code>Milan</code>'.
+    location, e.g., prefer <code>Europe/Rome</code> to
+    <code>Europe/Milan</code>.
   </li>
   <li>
-    Use the singular form, e.g., prefer '<code>Canary</code>' to
-    '<code>Canaries</code>'.
+    Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
+    <code>Atlantic/Canaries</code>.
   </li>
   <li>
     Omit common suffixes like '<code>_Islands</code>' and
     '<code>_City</code>', unless that would lead to ambiguity.
-    E.g., prefer '<code>Cayman</code>' to
-    '<code>Cayman_Islands</code>' and '<code>Guatemala</code>' to
-    '<code>Guatemala_City</code>', but prefer
-    '<code>Mexico_City</code>' to '<code>Mexico</code>'
+    E.g., prefer <code>America/Cayman</code> to
+    <code>America/Cayman_Islands</code> and
+    <code>America/Guatemala</code> to
+    <code>America/Guatemala_City</code>, but prefer
+    <code>America/Mexico_City</code> to
+    <code>America/Mexico</code>
     because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the
     country of Mexico has several time zones</a>.
   </li>
@@ -245,13 +255,14 @@ in decreasing order of importance:
   </li>
   <li>
     Omit '<code>.</code>' from abbreviations in names.
-    E.g., prefer '<code>St_Helena</code>' to '<code>St._Helena</code>'.
+    E.g., prefer <code>Atlantic/St_Helena</code> to
+    <code>Atlantiic/St._Helena</code>.
   </li>
   <li>
     Do not change established names if they only marginally violate
     the above guidelines.
-    For example, don't change the existing name '<code>Rome</code>' to
-    '<code>Milan</code>' merely because Milan's population has grown
+    For example, do not change the existing name <code>Europe/Rome</code> to
+    <code>Europe/Milan</code> merely because Milan's population has grown
     to be somewhat greater than Rome's.
   </li>
   <li>
@@ -318,8 +329,10 @@ in decreasing order of importance:
     Use three to six characters that are ASCII alphanumerics or
     '<code>+</code>' or '<code>-</code>'.
     Previous editions of this database also used characters like
-    '<code> </code>' and '<code>?</code>', but these characters have a
-    special meaning to the shell and cause commands like
+    space and '<code>?</code>', but these characters have a
+    special meaning to the
+    <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a>
+    and cause commands like
     '<code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
     `<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
     to have unexpected effects.
@@ -688,7 +701,7 @@ href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanes
     subsecond accuracy is needed.
   </li>
   <li>
-    Civil time was not based on atomic time before 1972, and we don't
+    Civil time was not based on atomic time before 1972, and we do not
     know the history of
     <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's
     rotation</a> accurately enough to map <a
@@ -720,7 +733,7 @@ href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanes
     Ideally it would contain information about when data entries are
     incomplete or dicey.
     Partial temporal knowledge is a field of active research, though,
-    and it's not clear how to apply it here.
+    and it is not clear how to apply it here.
   </li>
 </ul>
 
@@ -764,7 +777,7 @@ an older <code>zic</code>.
     Unfortunately, the POSIX
     <code>TZ</code> string takes a form that is hard to describe and
     is error-prone in practice.
-    Also, POSIX <code>TZ</code> strings can't deal with daylight
+    Also, POSIX <code>TZ</code> strings cannot deal with daylight
     saving time rules not based on the Gregorian calendar (as in
     Iran), or with situations where more than two time zone
     abbreviations or <abbr>UT</abbr> offsets are used in an area.
@@ -874,7 +887,7 @@ an older <code>zic</code>.
     need access to multiple time zone rulesets.
   </li>
   <li>
-    In POSIX, there's no tamper-proof way for a process to learn the
+    In POSIX, there is no tamper-proof way for a process to learn the
     system's best idea of local wall clock.
     (This is important for applications that an administrator wants
     used only at certain times – without regard to whether the
@@ -973,14 +986,16 @@ an older <code>zic</code>.
     by subsequent calls to <code>localtime</code>.
     Source code for portable applications that "must" run on local wall
     clock time should call <code>tzsetwall</code>;
-    if such code is moved to "old" systems that don't
-    provide <code>tzsetwall</code>, you won't be able to generate an
+    if such code is moved to "old" systems that do not
+    provide <code>tzsetwall</code>, you will not be able to generate an
     executable program.
     (These functions also arrange for local wall clock time to
     be used if <code>tzset</code> is called – directly or
-    indirectly – and there's no <code>TZ</code> environment
+    indirectly – and there is no <code>TZ</code> environment
     variable; portable applications should not, however, rely on this
-    behavior since it's not the way SVR2 systems behave.)
+    behavior since it is not the way <a
+    href="https://en.wikipedia.org/wiki/UNIX_System_V#SVR2"><abbr>SVR2</abbr></a>
+    systems behave.)
   </li>
   <li>
     Negative <code>time_t</code> values are supported, on systems
@@ -1040,7 +1055,7 @@ The vestigial <abbr>API</abbr>s are:
   <li>
     The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition
     UNIX</a> <code>timezone</code> function is not present in this
-    package; it's impossible to reliably map <code>timezone</code>'s
+    package; it is impossible to reliably map <code>timezone</code>'s
     arguments (a "minutes west of <abbr>GMT</abbr>" value and a
     "daylight saving time in effect" flag) to a time zone
     abbreviation, and we refuse to guess.
@@ -1052,7 +1067,9 @@ The vestigial <abbr>API</abbr>s are:
     zone abbreviation to use.
   </li>
   <li>
-    The <abbr>4.2BSD</abbr> <code>gettimeofday</code> function is not
+    The <a
+    href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a>
+    <code>gettimeofday</code> function is not
     used in this package.
     This formerly let users obtain the current <abbr>UTC</abbr> offset
     and <abbr>DST</abbr> flag, but this functionality was removed in
@@ -1061,7 +1078,7 @@ The vestigial <abbr>API</abbr>s are:
   <li>
     In <abbr>SVR2</abbr>, time conversion fails for near-minimum or
     near-maximum <code>time_t</code> values when doing conversions
-    for places that don't use <abbr>UT</abbr>.
+    for places that do not use <abbr>UT</abbr>.
     This package takes care to do these conversions correctly.
     A comment in the source code tells how to get compatibly wrong
     results.
@@ -1170,11 +1187,11 @@ They sometimes disagree.
 <p>
 Some people's work schedules
 use <a href="https://en.wikipedia.org/wiki/Timekeeping on Mars">Mars time</a>.
-Jet Propulsion Laboratory (JPL) coordinators have kept Mars time on
-and off at least since 1997 for the
+Jet Propulsion Laboratory (JPL) coordinators kept Mars time on
+and off during the
 <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder#End_of_mission">Mars
 Pathfinder</a> mission.
-Some of their family members have also adapted to Mars time.
+Some of their family members also adapted to Mars time.
 Dozens of special Mars watches were built for JPL workers who kept
 Mars time during the Mars Exploration Rovers mission (2004).
 These timepieces look like normal Seikos and Citizens but use Mars
@@ -1262,7 +1279,7 @@ Sources for time on other planets:
     Jia-Rui Chong,
     "<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays
     Fit for a Martian</a>", <cite>Los Angeles Times</cite>
-    (2004-01-14), pp A1, A20-A21.
+    (2004-01-14), pp A1, A20–A21.
   </li>
   <li>
     Tom Chmielewski,
-- 
2.14.3



More information about the tz mailing list