updates

ch04.adoc

@@ -197,7 +197,7 @@ There is no default value for the **`units`**.
 A time coordinate is identifiable from its **`units`** alone.
 Optionally, a time coordinate may be indicated additionally by providing the **`standard_name`** attribute with an appropriate value, and/or the **`axis`** attribute with the value **`T`**.
 
-[[time-axis-ex, Example 4.4, "Example of a time axis"]]
+[[time-axis-ex]]
 [caption="Example 4.4. "]
 .Example of a time axis
 ====
@@ -392,59 +392,78 @@ If the **`units_metadata`** attribute is not present, or does not contain the `l
 A variable's **`units_metadata`** attribute may only contain the **`leap_seconds`** keyword if the variable's calendar is one of **`standard`** , **`proleptic_gregorian`**, or **`julian`**.
 
 [[units-metadata-leap-seconds-ex]]
-[caption="Example 4.7. "]
+[caption="Example 4.5. "]
 .Use of **`units_metadata`** and **`calendar`** to define the treatment of leap seconds
 ====
 
 ----
 variables:
-  float time1 ;
-    time1:standard_name = "time" ;
-    time1:long_name = "Observed station data with unreliable information on leap seconds" ;
-    time1:calendar = "standard" ;
-    time1:units = "seconds since 2016-12-31 23:59:58" ;
-    time1:units_metadata = "leap_seconds: unknown" ;
-  float time2 ;
-    time2:standard_name = "time" ;
-    time2:long_name = "Model data with no leap seconds" ;
-    time2:calendar = "proleptic_gregorian" ;
-    time2:units = "seconds since 2016-12-31 23:59:58" ;
-    time2:units_metadata = "leap_seconds: none" ;
-  float time3 ;
-    time3:standard_name = "time" ;
-    time3:long_name = "Model data with leap seconds or obs with accurately recorded UTC" ;
-    time3:calendar = "standard" ;
-    time3:units = "seconds since 2016-12-31 23:59:58" ;
-    time3:units_metadata = "leap_seconds: utc" ;
-  float time4 ;
-    time4:standard_name = "time" ;
-    time4:long_name = "Time signal from UK National Physical Laboratory" ;
-    time4:calendar = "utc" ;
-    time4:units = "seconds since 2016-12-31 23:59:58" ;
-  float time5 ;
-    time5:standard_name = "time" ;
-    time5:long_name = "Satellite data" ;
-    time5:calendar = "tai" ;
-    time5:units = "seconds since 2016-12-31 23:59:58" ;
+  float time_tai ;
+    time_tai:standard_name = "time" ;
+    time_tai:long_name = "Satellite data" ;
+    time_tai:calendar = "tai" ;
+    time_tai:units = "seconds since 2016-12-31 23:59:58" ;
+  float time_stdnone ;
+    time_stdnone:standard_name = "time" ;
+    time_stdnone:long_name = "Model data with no leap seconds" ;
+    time_stdnone:calendar = "standard" ;
+    time_stdnone:units = "seconds since 2016-12-31 23:59:58" ;
+    time_stdnone:units_metadata = "leap_seconds: none" ;
+  float time_stdutc ;
+    time_stdutc:standard_name = "time" ;
+    time_stdutc:long_name = "Model data with leap seconds or obs data with accurate UTC" ;
+    time_stdutc:calendar = "standard" ;
+    time_stdutc:units = "seconds since 2016-12-31 23:59:58" ;
+    time_stdutc:units_metadata = "leap_seconds: utc" ;
+  float time_utc ;
+    time_utc:standard_name = "time" ;
+    time_utc:long_name = "Time signal from UK National Physical Laboratory" ;
+    time_utc:calendar = "utc" ;
+    time_utc:units = "seconds since 2016-12-31 23:59:58" ;
+  float time_unknown ;
+    time_unknown:standard_name = "time" ;
+    time_unknown:long_name = "Observed data with unreliable information on leap seconds" ;
+    time_unknown:calendar = "standard" ;
+    time_unknown:units = "seconds since 2016-12-31 23:59:58" ;
+    time_unknown:units_metadata = "leap_seconds: unknown" ;
 data: // time coordinate variable and the date/time it represents
-  time1 = 2; // unknown whether 2016-12-31 23:59:60 or 2017-1-1 0:0:0
-  time2 = 2; // 2017-1-1 0:0:0 because no leap seconds in the timeline
-  time3 = 2; // 2017-1-1 0:0:0 because the leap second in the timeline is not counted
-  time4 = 2; // leap second 2016-12-31 23:59:60
-  time5 = 2; // 2017-1-1 0:0:0 because no leap seconds in the timeline
+  time_tai = 2; // 2017-1-1 0:0:0 because no leap seconds in the timeline
+  time_stdnone = 2; // 2017-1-1 0:0:0 because no leap seconds in the timeline
+  time_stdutc = 2; // 2017-1-1 0:0:1 because the leap second in the timeline is not counted
+  time_utc = 2; // leap second 2016-12-31 23:59:60
+  time_unknown = 2; // unknown whether 2016-12-31 23:59:60 or 2017-1-1 0:0:0
 ----
-====
 
-Although the five time coordinates have the same value and reference date/time, they do not all refer to the same instant, as shown in the comments on their data values.
-The value of **`2`** seconds for **`time2`**, **`time4`** and **`time5`** can be correctly interpreted as the length of the interval from the reference date/time 2016-12-31 23:59:58 to the date/time indicated in their comments.
-In the case of **`time3`**, the time coordinate is again **`2`** and represents 2017-1-1 0:0:0, but the interval between the reference date/time 2016-12-31 23:59:58 and 2017-1-1 0:0:0 is actually 3 seconds.
-In the case of **`time1`**, we cannot convert the time coordinate to a date/time with certainty, and we do not know the exact length of the interval.
+This example shows five time coordinate variables with the same **`units`** attribute.
+The first four of them correspond to the instants marked 2 **`seconds since 2016-12-31 23:59:58`** in <<leap-second-timelines>>.
+Although all five have the same value and reference date/time, they do not all refer to the same instant, as shown in the comments on their data values, because of their different treatments of the leap second added to the UTC calendar at the end of 2016.
+
+The value of **`2`** seconds for **`time_stdnone`**, **`time_utc`** and **`time_tai`** can be correctly interpreted as the length of the interval from the reference date/time 2016-12-31 23:59:58 to 2017-1-1 0:0:0; note, however, that in **`utc`** and **`tai`** this date/time does not refer to the same instant of the real-world timeline.
+In the case of **`time_stdutc`**, the time coordinate is again **`2`** but represents 2017-1-1 0:0:1, although the interval along the timeline between the reference date/time 2016-12-31 23:59:58 and 2017-1-1 0:0:1 is actually 3 seconds.
+In the case of **`time_unknown`**, we cannot convert the time coordinate to a date/time with certainty, and we do not know the exact length of the interval.
+====
 
 [[leap-second-timelines]]
 [caption="Figure {doc-part}.{counter:figure}. ", reftext=Figure {doc-part}.{figure}]
-[.text-center]
-.Illustration of the equivalence between date/times and time coordinate values with **`units="seconds since 2016-12-31 23:59:58"`** for various choices of the **`calendar`** attribute and **`leap_seconds`** keyword. This illustration shows that a given time coordinate value (the numbers in columns at the bottom right) can represent different date/times in different calendars. However, the illustration cannot show another important point to keep in mind, that a given date/time may identify different instants in different calendars. The diagonal lines depict the timelines of the calendars. Along each line, a filled circle marks each integer-second date/time in the set allowed by the calendar. There is no meaning in the slight left-right displacement of the circles at each second, which is done only so they can all be seen; they are supposed to be exactly coincident. As explained in the text of this section, the time coordinate in seconds is the count of valid date/times (= the number of circles) that occur along the timeline _after_ the reference date/time **`2016-12-31 23:59:58`** (which is the first circle on the line in every case, hence with a count of zero as shown in the column below its group of circles), up to and including the date/time represented. A leap second was added to the UTC calendar at the end of 2016. The duration of the leap second is shown by the shading. The **`utc`** calendar is the only one in which date/times in the leap second are valid; hence the black circle is the only marker of **`2016-12-31 23:59:60`**. The grey timeline of the **`utc`** variant of the **`standard`** calendar includes the the leap second as well, but date/times in the leap second are not valid in that calendar, so there is no grey circle for it. The leap second does not appear in the timelines of the **`tai`** calendar and the *`none`* variant of the *`standard`* calendar. Their timelines (red and purple) skip over the leap second, and they have no circle for it.
+.Illustration of the equivalence between date/times and time coordinate values with **`units="seconds since 2016-12-31 23:59:58"`** for various choices of the **`calendar`** attribute and **`leap_seconds`** keyword.
+====
 image::images/leap-second-timelines.svg[,70%,pdfwidth=50vw,align="center"]
+This illustration shows that a given time coordinate value (the numbers in columns at the bottom right) can represent different date/times in different calendars.
+However, the illustration cannot show another important point to keep in mind, that a given date/time may identify different instants in different calendars.
+
+The diagonal lines depict the timelines of the calendars.
+Along each line, a filled circle marks the instant on the timeline that begins each second in the set of date/times allowed by the calendar.
+There is no meaning in the slight left-right displacement of the circles at each second, which is done only so they can all be seen; they are supposed to be exactly coincident.
+As explained in the text of this section, the time coordinate in seconds is the count of valid date/times (= the number of circles) that occur along the timeline _after_ the reference date/time **`2016-12-31 23:59:58`** (which is the first circle on the line in every case, hence with a count of zero as shown in the column below its group of circles), up to and including the date/time represented.
+The instants marked 2 **`seconds since 2016-12-31 23:59:58`** are the ones represented by the first four time coordinate variables of Example 4.5.
+
+A leap second was added to the UTC calendar at the end of 2016.
+The duration of the leap second is shown by the shading.
+The **`utc`** calendar is the only one in which date/times in the leap second are valid; hence the black circle is the only marker of **`2016-12-31 23:59:60`**.
+The grey timeline of the **`utc`** variant of the **`standard`** calendar includes the the leap second as well, but date/times in the leap second are not valid in that calendar, so there is no grey circle for it.
+The leap second does not appear in the timelines of the **`tai`** calendar and the *`none`* variant of the *`standard`* calendar.
+Their timelines (red and purple) skip over the leap second, and they have no circle for it.
+====
 
 
 [[none-calendar, Section 4.4.4, "Time Coordinates with no Annual Cycle"]]
@@ -455,7 +474,7 @@ The time of year is indicated by the date in the reference time of the **`units`
 The time coordinates that might apply in a perpetual July experiment are given in the following example.
 
 [[perpetual-time-axis-ex]]
-[caption="Example 4.5. "]
+[caption="Example 4.6. "]
 .Perpetual time axis
 ====
 
@@ -496,7 +515,7 @@ This attribute is ignored if **`leap_year`** is not specified.
 When an explicitly defined calendar is being used, the calendar may be described by giving a value not defined in <<calendar>> to the **`calendar`** attribute; alternatively, the attribute may be omitted.
 
 [[paleoclimate-time-axis-ex]]
-[caption="Example 4.6. "]
+[caption="Example 4.7. "]
 .Paleoclimate time axis
 ====
 

toc-extra.adoc

@@ -16,8 +16,9 @@ K.2. <<table-mesh-topology-attributes>>
 **List of Figures**
 
 [%hardbreaks]
-7.1. <<img-bnd_1d_coords, figure 1>>
-7.2. <<img-bnd_2d_coords, figure 2>>
+7.1. <<img-bnd_1d_coords>>
+7.2. <<img-bnd_2d_coords>>
+4.1. <<leap-second-timelines>>
 8.1. <<interpolation_subarea_generation>>
 8.2. <<ci_dimensions_overview>>
 8.3. <<ci_interpolation_parameters>>
@@ -49,9 +50,9 @@ J.5. <<quadratic3>>
 4.2. <<longitude-axis-ex>>
 4.3. <<atm-sigma-coord-ex>>
 4.4. <<time-axis-ex>>
-4.5. <<perpetual-time-axis-ex>>
-4.6. <<paleoclimate-time-axis-ex>>
-4.7. <<units-metadata-leap-seconds-ex>>
+4.5. <<units-metadata-leap-seconds-ex>>
+4.6. <<perpetual-time-axis-ex>>
+4.7. <<paleoclimate-time-axis-ex>>
 5.1. <<independent-coordinate-variables-ex>>
 5.2. <<two-dimensional-coordinate-variables-ex>>
 5.3. <<reduced-horizontal-grid-ex>>