[Gen-art] Genart last call review of draft-murchison-tzdist-tzif-14

[Paul Eggert <[e-mail]>]

Thanks for the review. I've attached a proposed patch that attempts to 
address the issues you raised. Unless otherwise noted below, I agreed 
with your comments and incorporated them into the patch. The attached 
patch assumes the patches I proposed earlier in 
<https://www.ietf.org/mail-archive/web/tzdist-bis/current/msg00339.html> 
and in 
<https://www.ietf.org/mail-archive/web/tzdist-bis/current/msg00345.html>.

> Certain
> passages suggest that processors are expected to *not* examine the
> version number in a file,

Readers can examine the version number (which some do), or they can 
charge ahead and assume the version is good enough (some do that too). 
If a passage suggests otherwise let's fix it (I briefly looked for such 
passages and didn't find any).

> silent acceptance of trailing
> garbage is not specified, and this strategy is different from most
> IETF standards.

It's the strategy used in practice for this format. For example, the 
reference implementation (tzcode) does it that way. The attached 
proposed patch proposes adding text to section 3 paragraph 2 to try to 
document this better.

> the glossary (in section 2)
> gives definitions of several terms that suggest the document is
> attempting to define the semantics, but the definitions given are
> nowhere near sufficient to specify those semantics.

The glossary doesn't explain every aspect of timekeeping from the ground 
up and isn't really the place to do so, as it would take a lot of space 
and our readers are likely to be reasonably familiar with timekeeping 
already. That being said, we can fix specific issues with definitions as 
they come up (including the issues you noted). Also, the attached 
proposed patch prefaces the glossary with a pointer to tz-link to try to 
help readers unfamiliar with timekeeping.

> 3. Apparently (see comments on section 4), characters outside the
> ASCII set are allowed in time zone designations.  If so, their
> encoding needs to be specified.

The spec deliberately does not have a MUST for encoding. All the format 
requires is a string of octets terminated by an 0x00 octet. The attached 
proposed patch adds some text to say this explicitly. (Section 4 does 
say the encoding SHOULD be ASCII, and the patch doesn't change this.)

> The sequence "nor does it define the source the time zone data" is
> gramatically incorrect.

Noted earlier with a proposed fix in the 
<https://www.ietf.org/mail-archive/web/tzdist-bis/current/msg00339.html> 
email cited above.

> Also, it's not clear how "as defined in Section
> 3 of [RFC7808]" attaches to the sentence, since the closest item in
> the list, "versions", is defined in section 3 and not RFC 7808.

As far as I'm concerned the sentence is mostly a red herring, and we can 
reduce confusion by dropping the laundry list and the most-irrelevant 
citation of RFC 7808, as done in the attached proposed patch.


>     Daylight Saving Time (DST):  The time according to a location's law
>        or practice, adjusted as necessary from standard time.  The
>        adjustment may be positive, negative, or zero.
> 
> This seems to read that "Daylight Saving Time" is not "standard time"
> plus the summer time offset, but standard time, adjusted by whatever
> summer time offset might be in effect at the moment.  But that is not
> not the definition of DST, at least, not as commonly used in the US.

In general there is no single "summer time offset"; some localities have 
used different offsets at different points in the summer.  The attached 
proposed patch attempts to make this clearer.

>        2.  a change in whether standard or daylight saving time is in use
> 
> Is this intended to include the regular transition between summer time
> and winter time, or only when a locality starts or stops the practice
> of using summer time each year or the schedule of transitions?

The former. The attached proposed patch rewords this.

>     Wall Time:  The time as shown on a clock set according to a
>        location's law or practice.
> 
> In what way does this differ from "Local Time"?

It doesn't. Good catch. Fixed in the attached proposed patch, which also 
tries to nail down "local time" better.


> 
>        '2' (0x32)  Version 2 - The file MUST contain the 32-bit header
>           and data block, a 64-bit header and data block, and a footer.
> 
> The phrases "32-bit header" and "64-bit header" don't work, as the
> headers have the same format.  They could be called "header for 32-bit
> data", etc., but that's a bit awkward.  Alternatively, names for all
> of the data sections could be defined in section 2.

The attached proposed patch attempts to address this by using the names 
"version 1 header" and "version 2+ header", and similarly for data blocks.

> 
>     typecnt:  A four-octet unsigned integer specifying the number of
>        local time type records contained in the data block - MUST NOT be
>        zero.  (Although time type 0 is not used in files that have
>        nonempty TZ strings but no transitions, it is nevertheless
>        required because many TZif readers reject files that lack time
>        types.)
> 
> This is hard to understand.

Reworded in the attached proposed patch.

>        *  "application/tzif-leap" (Section 8.2) to indicate that leap
>           second records are included in the TZif data.
> 
> You probably need to spell out:  "For version 1 files, leap second
> records must be present in the 32-bit data block; for version 2 and 3
> files, leap second records must be present in the 64-bit data block."

Leap second records need not be present even in application/tzif-leap 
files, so the attached draft changes this to "leap second records are 
included in the TZif data as necessary (none are necessary if the file 
is truncated to a range that precedes the first leap second)".

> 10.3.  URIs
> 
> This section is odd.  Item [1] is just the URL for BCP 14, but BCP 14
> is also listed in the references section.  Items [6] and [7] duplicate
> [8] and [9], but they're references and should be treated as such.
> Items [3], [4], and [5] are more interesting -- they're locations
> inside reference [POSIX].  The Editor should be able to suggest a
> better way of presenting these references.

The cross references do not work the way I would like 
<https://www.ietf.org/mail-archive/web/tzdist-bis/current/msg00326.html> 
and apparently can't be done well 
<https://www.ietf.org/mail-archive/web/tzdist-bis/current/msg00328.html>. I 
gave up on doing them well, but if someone more expert in 
XML/HTML/whatever can fix things I'll be a happy camper.

> Appendix A.  Common Interoperability Issues
> 
>     Most of these are problems in generating TZif files
>     for use by readers conforming to predecessors of this specification.
> 
> It would be helpful to those dealing with compatibility issues to have
> references to the predecessors of this specification.

The predecessors are published in the version-controlled tzfile.5 man 
pages in the tzdb development version 
<https://github.com/eggert/tz/commits/master/tzfile.5>. The attached 
patch hyperlinks to that.