Subject: [Tzdist-bis] AD review of draft-murchison-tzdist-tzif-12

From: Alexey Melnikov <[email-masked]>
Date: Wed, 05 Sep 2018 15:06:00 +0100

Hi,
I've got a request from Eliot to start publication process for this document. Below is my review:

My general impression of the document is that it has some extra complexity due to backward compatibility with earlier formats. Not much can be done about this, unless this group wants to deprecate the version 1 of the format.

Nit: Please add a reference on first mention of ASCII. I believe it is RFC 20.

In Section 3.2:

      corr(ection):  A four-octet signed integer specifying the value of
         TAI - UTC - 10 on or after the occurrence.  The correction

Maybe you should introduce a shortcut variable for this and reference it below in the same paragraph? It is a bit tedious to read "TAI - UTC - 10" every time.

         value in the first leap second record, if present, MUST be
         either one (1) or minus one (-1).  The correction values in
         adjacent leap second records MUST differ by exactly one (1).
         For timestamps that occur before the occurrence time in the
         first leap second record (or for all timestamps if there are no
         leap second records), the value of TAI - UTC - 10 is zero, and
         this zero value applies even to timestamps before the
         introduction of TAI or UTC.

Maybe it is just me, but I read the part of the last sentence that starts with "the value of TAI - UTC - 10 is zero" several times and I am still not sure what it means. Can you elaborate?

         (The expression "TAI - UTC - 10"
         comes from the fact that TAI - UTC was defined to be 10 just
         prior to the first leap second in 1972, so clocks with leap
         seconds that use the UNIX Time origin of 1970 have a zero
         offset relative to UTC before the first leap second.)

Section 3.3.1:

I think this is the most problematic section in the whole document and I struggled with it. I think it is missing ABNF, because I can't figure out from examples what is and is not allowed there. (You also have some useful suggestions in Appendix A, which again can be a part of the ABNF.) Examples help, but, IMHO, they are not enough to implement interoperably.

2 media type definitions: this is typically done with a single media type that has a parameter, so I would like to know why you didn't do that? Are both media types already deployed?

Last sentence in 5.1:

   TZDIST clients SHOULD NOT use a truncated TZif file to interpret
   timestamps outside the truncation time range.

I am not entirely sure what is "the truncation time range". Maybe reword?

Also, why is this SHOULD NOT, instead of MUST NOT?

Empty "Privacy Considerations" section - is it really empty and if it is, do we need to have it in the document?

In Section 8.2.  application/tzif-leap

   Same as application/tzif (Section 8.1).

(Twice) - can you please cut & paste relevant text from Section 8.1? This whole section will be cut & pasted to IANA website, so it has to be self sufficient.

That is it for now.

Best Regards,
Alexey

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 10:43:48 -0400

Hi Alexey,

Thanks for the review.  Responses inline.

> My general impression of the document is that it has some extra complexity due to backward compatibility with earlier formats. Not much can be done about this, unless this group wants to deprecate…

We talked about deprecation and decided against it.  I'm open to 
discussing again if need be.

> Nit: Please add a reference on first mention of ASCII. I believe it is RFC 20.

Will do.

> Maybe you should introduce a shortcut variable for this and reference it below in the same paragraph? It is a bit tedious to read "TAI - UTC - 10" every time.

Paul, do you have a suggestion for a term we can use here?

> Maybe it is just me, but I read the part of the last sentence that starts with "the value of TAI - UTC - 10 is zero" several times and I am still not sure what it means. Can you elaborate?

Paul?

> I think this is the most problematic section in the whole document and I struggled with it. I think it is missing ABNF, because I can't figure out from examples what is and is not allowed there. (Y…

I will work on an ABNF for TZ Strings.

> 2 media type definitions: this is typically done with a single media type that has a parameter, so I would like to know why you didn't do that? Are both media types already deployed?

We used 2 different media types per Ned Freed's suggestion.  I'm 
comfortable using one type with a parameter, as it was in an earlier 
(private?) draft.  Neither type is widely deployed as far as I know.  
I'm using them in my TZDIST server, but that is mostly just a toy at 
this point.

> I am not entirely sure what is "the truncation time range". Maybe reword?

I will try to do some wordsmithing here.

> Also, why is this SHOULD NOT, instead of MUST NOT?

Paul, did we have a reason to not strictly prohibit?  Is this a 
backwards compatibility issue?

> Empty "Privacy Considerations" section - is it really empty and if it is, do we need to have it in the document?

I'm not aware of any privacy considerations.  I will remove it.

> (Twice) - can you please cut & paste relevant text from Section 8.1? This whole section will be cut & pasted to IANA website, so it has to be self sufficient.

Will do, if we decide to keep separate types.

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Lester Caine <[email-masked]>
Date: Wed, 5 Sep 2018 15:59:22 +0100

On 05/09/18 15:43, Ken Murchison wrote:
>> Empty "Privacy Considerations" section - is it really empty and if it 
>> is, do we need to have it in the document?
> 

Given the current developments in data privacy, should this section 
actually says "After due assessment we are not aware of any privacy 
considerations." ... Simply leaving it out does not cover that the 
assessment has been made as is now required on all RFC's?

-- 
Lester Caine - G8HFL
-----------------------------
Contact - https://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - https://lsces.co.uk
EnquirySolve - https://enquirysolve.com/
Model Engineers Digital Workshop - https://medw.co.uk
Rainbow Digital Media - https://rainbowdigitalmedia.co.uk

---

From: Alexey Melnikov <[email-masked]>
Date: Wed, 05 Sep 2018 16:11:25 +0100

Hi,

On Wed, Sep 5, 2018, at 3:59 PM, Lester Caine wrote:
> considerations."

That would be better.

> ... Simply leaving it out does not cover that the 

This section is not required in RFCs. But I don't have any personal objections to having it.

Best Regards,
Alexey

---

From: Paul Eggert <[email-masked]>
Date: Wed, 5 Sep 2018 08:15:26 -0700

> I will work on an ABNF for TZ Strings.

Let's not go that route. The basic problem here is poor citations, not 
inadequate doc. I'll try to follow up shortly.

---

From: Paul Eggert <[email-masked]>
Date: Wed, 5 Sep 2018 08:23:31 -0700

> Maybe you should introduce a shortcut variable for this and reference it below in the same paragraph? It is a bit tedious to read "TAI - UTC - 10" every time.

Good idea. I suggest LEAPCORR, since it's the value of the "corr(ection)" field 
and it's a leap-second correction. Please see attached proposed patch.

> Maybe it is just me, but I read the part of the last sentence that starts with "the value of TAI - UTC - 10 is zero" several times and I am still not sure what it means. Can you elaborate?

Please see the attached proposed patch, which tries to make this clearer.

> I think this is the most problematic section in the whole document and I struggled with it. I think it is missing ABNF, because I can't figure out from examples what is and is not allowed there. (Y…

Section 3.3.1 describes an extension to POSIX Section 8.3, and cannot be 
understood without reading POSIX Section 8.3 first. This should be stated more 
clearly, and the citations should be fixed. No wonder you struggled to figure 
this stuff out, if you didn't know POSIX 8.3 already.

Right now the XML is messed up here, and I don't know how to fix it. For 
example, this text:

           <eref target="http://pubs.opengroup.org/onlinepubs/9699919799/">
           The Open Group Base Specifications Issue 7, 2018 edition</eref>.

in the XML does not actually work in 
<https://tools.ietf.org/html/draft-murchison-tzdist-tzif-12>, which merely 
contains a stray "[4]" that doesn't lead anywhere. Plus, that URL points to a 
thousand-page document instead of to the specific section required here.

I gave a shot at fixing this particular problem in the attached patch, but 
someone with more XML experience than I needs to go through the whole draft and 
fix all the <eref> elements (some work, some don't, I don't know why)
--- draft-murchison-tzdist-tzif-12.xml	2018-09-05 08:00:00.349921625 -0700
+++ draft-murchison-tzdist-tzif-12-01.xml	2018-09-05 08:13:26.263619012 -0700
@@ -147,6 +147,15 @@
	          The time standard based on atomic clocks since 1972.
	          It is equal to UTC except without leap second adjustments.
	        </t>
+		<t hangText="Leap Second Correction (LEAPCORR):">
+		  The value of TAI - UTC - 10 for timestamps after the
+		  first leap second, and zero for timestamps before that.
+		  The expression "TAI - UTC - 10" comes from the fact
+		  that TAI - UTC was defined to be 10 just prior to
+		  the first leap second in 1972, so clocks with leap
+		  seconds have a zero LEAPCORR before the first leap
+		  second.
+		</t>
	        <t hangText="Local Time:">
	          The time according to a location's current time zone
	          offset from Universal Time.
@@ -163,7 +172,7 @@
	            <t>a change in whether standard or daylight saving time is
	            in use</t>
	            <t>a change in time zone abbreviation</t>
-	            <t>a leap second (i.e., a change in UTC - TAI)</t>
+	            <t>a leap second (i.e., a change in LEAPCORR)</t>
	          </list>
	        </t>
	        <t hangText="Time Zone Data:">
@@ -313,7 +322,8 @@
	                  The TZ string in the
			  <xref target='footer'>footer</xref>, if
	                  nonempty, MUST strictly adhere to the
-			  POSIX requirements for the TZ environment variable,
+			  <xref target="POSIX-8.3"/>
+			  requirements for the TZ environment variable,
			  and MUST encode the POSIX portable character set as
			  ASCII.
		        </t>
@@ -526,23 +536,15 @@
	                </t>
		        <t hangText="corr(ection):">
		          A four-octet signed integer specifying the value
-			  of TAI - UTC - 10 on or after the occurrence.
+			  of LEAPCORR on or after the occurrence.
			  The correction value in the first leap second record,
			  if present, MUST be either one (1) or minus one (-1).
	                  The correction values in adjacent leap second
	                  records MUST differ by exactly one (1).
-			  For timestamps that occur before the occurrence time
+			  The value of LEAPCORR is zero
+			  for timestamps that occur before the occurrence time
			  in the first leap second record (or for all
-			  timestamps if there are no leap second records), the
-			  value of TAI - UTC - 10 is zero, and this zero value
-			  applies even to timestamps before the introduction
-			  of TAI or UTC.
-			  (The expression "TAI - UTC - 10" comes from the fact
-			  that TAI - UTC was defined to be 10 just prior to
-			  the first leap second in 1972, so clocks with leap
-			  seconds that use the UNIX Time origin of 1970 have a
-			  zero offset relative to UTC before the first leap
-			  second.)
+			  timestamps if there are no leap second records).
	                </t>
	              </list>
		    </t>
@@ -635,9 +637,9 @@
	              A rule for computing local time changes after the last
	              transition time stored in the 64-bit data block.
		      The string is either empty or uses the expanded format
-	              of the "TZ" environment variable as defined in Section 8
-	              of the "Base Definitions" Volume of <xref
-		      target="POSIX"/> with ASCII encoding, possibly utilizing
+	              of the "TZ" environment variable as defined in
+		      <xref target="POSIX-8.3"/>
+		      with ASCII encoding, possibly utilizing
	              <xref target='tzstrext'>extensions described below</xref>
	              in version 3 files.
		      If the string is empty, the corresponding information is
@@ -656,8 +658,10 @@
	        </t>
	
	        <section anchor='tzstrext' title='TZ String Extensions'>
-	          <t>Version 3 TZif files MAY use the following extensions in
-	          the TZ string:
+	          <t>The TZ string in a Version 3 TZif file MAY use the
+		  following extensions to POSIX TZ strings.
+		  These extensions are described using the terminology of
+		  <xref target="POSIX-8.3"/>.
	
	          <list style='symbols'>
	            <t>The hours part of the transition times may be
@@ -1014,7 +1018,7 @@
	      &rfc8174;
	
	      <reference anchor='POSIX'
-	                 target="https://ieeexplore.ieee.org/servlet/opac?punumber=8277151">
+	                 target="http://pubs.opengroup.org/onlinepubs/9699919799/">
	        <front>
	          <title>Standard for Information Technology--Portable Operating
	          System Interface (POSIX(R)) Base Specifications, Issue 7</title>
@@ -1026,9 +1030,17 @@
	        <seriesInfo name="IEEE" value="1003.1-2017"/>
	        <seriesInfo name="DOI" value="10.1109/IEEESTD.2018.8277153"/>
	        <annotation>
-	          This is identical to
-	          <eref target="http://pubs.opengroup.org/onlinepubs/9699919799/">
-	          The Open Group Base Specifications Issue 7, 2018 edition</eref>.
+	          This standard is also <eref
+		  target="https://ieeexplore.ieee.org/servlet/opac?punumber=8277151">
+		  published</a> by ieeexplore.ieee.org.
+	        </annotation>
+	      </reference>
+	
+	      <reference anchor='POSIX-8.3'
+	                 target="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">
+	        <annotation>
+		  This is <xref target="POSIX"> section 8.3, which
+		  describes the POSIX TZ string.
	        </annotation>
	      </reference>
	    </references>

---

From: Paul Eggert <[email-masked]>
Date: Wed, 5 Sep 2018 08:29:34 -0700

> Paul, did we have a reason to not strictly prohibit?  Is this a backwards 
> compatibility issue?

Yes, every GNU/Linux or BSD client that takes a truncated tzdist file, slaps it 
into their /usr/share/zoneinfo (or whatever), and then has an application that 
uses the file for a timestamp out of the range, will behave contrary to that 
recommendation. We don't want to absolutely prohibit this behavior.

---

From: Alexey Melnikov <[email-masked]>
Date: Wed, 05 Sep 2018 16:45:04 +0100

>            The Open Group Base Specifications Issue 7, 2018 edition</eref>.

I think you should always use <xref>.

---

From: Alexey Melnikov <[email-masked]>
Date: Wed, 05 Sep 2018 16:48:07 +0100

> and it's a leap-second correction. Please see attached proposed patch.

Yes, this is an improvement. Thank you!

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 12:37:48 -0400

> I think you should always use <xref>.

Alexey, can we have a normative reference that is simply a subsection of 
another normative reference?

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Alexey Melnikov <[email-masked]>
Date: Wed, 5 Sep 2018 17:51:26 +0100

> On 5 Sep 2018, at 17:37, Ken Murchison <[email-masked]> wrote:
> 
> Alexey, can we have a normative reference that is simply a subsection of another normative reference?

Just add subsection reference?
If RFC Editor can figure out how to reference it, I am sure it is fine.

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 12:51:41 -0400

On 09/05/2018 11:23 AM, Paul Eggert wrote:
>
> Section 3.3.1 describes an extension to POSIX Section 8.3, and cannot 
> be understood without reading POSIX Section 8.3 first. This should be 
> stated more clearly, and the citations should be fixed. No wonder you 
> struggled to figure this stuff out, if you didn't know POSIX 8.3 already.
>
> Right now the XML is messed up here, and I don't know how to fix it. 
> For example, this text:
>
>           <eref 
> target="http://pubs.opengroup.org/onlinepubs/9699919799/">
> <https://tools.ietf.org/html/draft-murchison-tzdist-tzif-12>, which 
> merely contains a stray "[4]" that doesn't lead anywhere. Plus, that 
> URL points to a thousand-page document instead of to the specific 
> section required here.
>
> I gave a shot at fixing this particular problem in the attached patch, 
> but someone with more XML experience than I needs to go through the 
> whole draft and fix all the <eref> elements (some work, some don't, I 
> don't know why)

So, the second POSIX reference in the patch is broken from the 
standpoint that it doesn't have some of the required XML elements. I can 
fix that by simply add those from the first reference, but we've also 
changed the link to the doc from IEEE to OpenGroup.  Is that change 
necessary?  It really is an IEEE work product, correct?

Actually, I clipped the original POSIX reference from another RFC (I 
don't recall which).

Do we really need a separate reference to one section within the POSIX spec?

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 12:52:52 -0400

> If RFC Editor can figure out how to reference it, I am sure it is fine.

Subsection reference within the text itself, correct?  E.g. "[POSIX] 
Section 8.3"

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Alexey Melnikov <[email-masked]>
Date: Wed, 05 Sep 2018 18:13:06 +0100

> Subsection reference within the text itself, correct?  E.g. "[POSIX] 

Yes.

---

From: Paul Eggert <[email-masked]>
Date: Wed, 5 Sep 2018 10:14:06 -0700

Ken Murchison wrote:

> So, the second POSIX reference in the patch is broken from the standpoint that 
> it doesn't have some of the required XML elements. I can fix that by simply add 
> those from the first reference, but we've also changed the link to the doc from 
> IEEE to OpenGroup.  Is that change necessary?  It really is an IEEE work 
> product, correct?

It's really an Open Group work product. As far as I can tell, it's an IEEE 
standard by courtesy. In practice, nobody looks at the IEEE copy (because it's 
behind a paywall) and everybody looks at the Open Group copy (because it's not). 
We should point people to the Open Group copy, though we can also mention the 
IEEE copy if it will help more reviewers salute.

> Actually, I clipped the original POSIX reference from another RFC (I don't 
> recall which).
> 

Yes, we really need a convenient way for readers to click through to the 
specific section that talks about the POSIX TZ string. Otherwise readers will 
likely fall prey to the same problem that Alexey fell into, namely, they won't 
know what the POSIX TZ string extensions mean because they won't know what a 
POSIX TZ string is, and merely pointing to a 1000-page document is too vague.

---

From: Paul Eggert <[email-masked]>
Date: Wed, 5 Sep 2018 10:15:15 -0700

Ken Murchison wrote:
> Subsection reference within the text itself, correct?  E.g. "[POSIX] Section 8.3"

The idea is that readers should be able to click on the phrase (whatever it is) 
and go directly to POSIX Section 8.3.

---

From: Eliot Lear <[email-masked]>
Date: Wed, 5 Sep 2018 10:42:19 -0700

Hi Alexey and thanks very much for your review.  I will consolidate
peoples' comments over the weekend so that we can see where we are.  I
want to just address one point:

> 2 media type definitions: this is typically done with a single media type that has a parameter, so I would like to know why you didn't do that? Are both media types already deployed?

We discussed this with our media reviewer, and the concern he had was
that parameters are often ignored.  To quote him:

> There's plenty of stuff out there that ignores parameters completely.

That was what drove the decision.

Eliot

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 13:46:08 -0400

On 09/05/2018 01:15 PM, Paul Eggert wrote:
> The idea is that readers should be able to click on the phrase 
> (whatever it is) and go directly to POSIX Section 8.3.

Completely agree and understand.  I'm mostly concerned with whether this 
practice in RFCs is common and/or accepted and if so, if we are doing it 
correctly.

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 13:48:34 -0400

On 09/05/2018 01:14 PM, Paul Eggert wrote:
>> standpoint that it doesn't have some of the required XML elements. I 
>> can fix that by simply add those from the first reference, but we've 
>> also changed the link to the doc from IEEE to OpenGroup.  Is that 
>> change necessary?  It really is an IEEE work product, correct?
>
> It's really an Open Group work product. As far as I can tell, it's an 
> IEEE standard by courtesy. In practice, nobody looks at the IEEE copy 
> (because it's behind a paywall) and everybody looks at the Open Group 
> copy (because it's not). We should point people to the Open Group 
> copy, though we can also mention the IEEE copy if it will help more 
> reviewers salute.

Fair enough.  Are we comfortable keeping the same title, author, and 
series info with the OpenGroup link?

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Paul Eggert <[email-masked]>
Date: Wed, 5 Sep 2018 10:50:02 -0700

Ken Murchison wrote:
> Fair enough.  Are we comfortable keeping the same title, author, and series info 
> with the OpenGroup link?

Yes, that's fine.

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 13:52:49 -0400

On 09/05/2018 01:14 PM, Paul Eggert wrote:
> Yes, we really need a convenient way for readers to click through to 
> the specific section that talks about the POSIX TZ string. Otherwise 
> readers will likely fall prey to the same problem that Alexey fell 
> into, namely, they won't know what the POSIX TZ string extensions mean 
> because they won't know what a POSIX TZ string is, and merely pointing 
> to a 1000-page document is too vague.

I guess before we continue beating around whether we need a separate 
reference and/or how to do it...

Alexey, does the text in 
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03 
help you to understand the format of the TZ string and how its extended 
by TZif?

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Eliot Lear <[email-masked]>
Date: Wed, 5 Sep 2018 11:02:30 -0700

Hang on.  There's no way we're redefining or "simplifying" OpenGroup's
work.  I hope a reference is sufficient.  I don't want us describing the
definition, lest we accidentally diverge  (and we'll spend many months
doing just this).  As such, the reference REALLY has to suffice.

Eliot

On 05.09.18 10:52, Ken Murchison wrote:
>> into, namely, they won't know what the POSIX TZ string extensions
>> mean because they won't know what a POSIX TZ string is, and merely
>> pointing to a 1000-page document is too vague.
>
>
> help you to understand the format of the TZ string and how its
> extended by TZif?
>
>
>
> _______________________________________________
> Tzdist-bis mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tzdist-bis

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 14:04:34 -0400

I agree.  I just wanted to confirm that the reference is sufficient to 
address Alexey's concern/confusion.

On 09/05/2018 02:02 PM, Eliot Lear wrote:
> work.  I hope a reference is sufficient.  I don't want us describing 
> the definition, lest we accidentally diverge (and we'll spend many 
> months doing just this).  As such, the reference REALLY has to suffice.
>
> Eliot
>
>
>>>> standpoint that it doesn't have some of the required XML elements. 
>>>> I can fix that by simply add those from the first reference, but 
>>>> we've also changed the link to the doc from IEEE to OpenGroup.  Is 
>>>> that change necessary?  It really is an IEEE work product, correct?
>>>
>>> It's really an Open Group work product. As far as I can tell, it's 
>>> an IEEE standard by courtesy. In practice, nobody looks at the IEEE 
>>> copy (because it's behind a paywall) and everybody looks at the Open 
>>> Group copy (because it's not). We should point people to the Open 
>>> Group copy, though we can also mention the IEEE copy if it will help 
>>> more reviewers salute.
>>>
>>>> Actually, I clipped the original POSIX reference from another RFC 
>>>> (I don't recall which).
>>>>

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Ken Murchison <[email-masked]>
Date: Wed, 5 Sep 2018 14:23:18 -0400

> (whatever it is) and go directly to POSIX Section 8.3.

So, it looks like we have 2 different refs to POSIX:

- The aforementioned TZ string format from Section 8.3 of the Base 
Definitions volume

- The C time() function from Section 3 of the System Interfaces volume

Following Paul's lead, I'm going to make the original (generic) 
reference point directly to the time() function.

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Alexey Melnikov <[email-masked]>
Date: Tue, 11 Sep 2018 15:52:27 +0100

> help you to understand the format of the TZ string and how its extended 

Yes, this will do.