Merge branch 'main' into asciidoc-fixes

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,10 +1,10 @@
 See issue #XXX for discussion of these changes.
 
 # Release checklist
-- [ ] Authors updated in `cf-conventions.adoc`?
+- [ ] Authors updated in `cf-conventions.adoc`? Add in two places: on line 3 and under `.Additional Authors` in `About the authors`.
 - [ ] Next version in `cf-conventions.adoc` up to date? Versioning inspired by [SemVer](https://semver.org).
 - [ ] `history.adoc` up to date?
-- [ ] Conformance document up-to-date?
+- [ ] Conformance document up to date?
 
 # For maintainers
 After the merge remember to delete the source branch.

.github/workflows/adoc_build.yml

@@ -44,20 +44,24 @@ jobs:
     - uses: actions/checkout@v2
     # Create build directory
     - run: mkdir conventions_build
-    - name: Set "final" tag
+    - name: Set draft date-time formatting
+      if: github.event_name != 'release'
+      run: |
+        echo "DATE_FMT=+%d %B, %Y %H:%M:%SZ" >> "$GITHUB_ENV"
+    - name: Set "final" tag and date-time formatting
       if: github.event_name == 'release'
       run: |
-        echo "FINAL_TAG=-a final" >> "$GITHUB_ENV"
+        echo "FINAL_TAG=-a final" >> "$GITHUB_ENV"; echo "DATE_FMT=+%d %B, %Y" >> "$GITHUB_ENV"
     # Build cf-conventions.html using the Analog-inc asciidoctor-action
     - name: Build cf-conventions.html
       uses: Analog-inc/[email protected]
       with:
-        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} cf-conventions.adoc -D conventions_build; cp -r images conventions_build'
+        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) cf-conventions.adoc -D conventions_build; cp -r images conventions_build'
     # Build cf-conventions.pdf using the Analog-inc asciidoctor-action
     - name: Build cf-conventions.pdf
       uses: Analog-inc/[email protected]
       with:
-        shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -d book -a pdf-theme=default-theme-CF-version.yml --trace cf-conventions.adoc -D conventions_build'
+        shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) -d book -a pdf-theme=default-theme-CF-version.yml --trace cf-conventions.adoc -D conventions_build'
     # Upload artifact containing cf-conventions.html, cf-conventions.pdf
     - name: Upload cf-conventions doc preview
       uses: actions/upload-artifact@v2

appa.adoc

@@ -8,7 +8,8 @@ All CF attributes are listed here except for those that are used to describe gri
 See Appendix F for the grid mapping attributes, and Appendix K for mesh topology attributes.
 
 The "Type" values are **S** for string, **N** for numeric, and **D** for the type of the data variable.
-The "Use" values are **G** for global, **Gr** for applying to groups, **C** for variables containing coordinate data, **D** for data variables, **M** for geometry container variables, **Do** for domain variables, and **-** for variables with a special purpose.
+Each attribute may be used in any of the ways shown in its "Use" entry.
+**G** indicates it can appear as a global attribute, and **Gr** as a group attribute; if use of an attribute is restricted to certain kinds of variables this is indicated as follows: **C** for variables containing coordinate data, **D** for data variables, **M** for geometry container variables, **Do** for domain variables, **BI** and **BO** for boundary variables (see <<cell-boundaries>> for the distinction between **BI** and **BO**), and **-** for variables with some other purpose.
 "Links" indicates the location of the attribute"s original definition (first link) and sections where the attribute is discussed in this document (additional links as necessary).
 
 [[table-attributes]]
@@ -24,13 +25,13 @@ Attribute
 
 | **`actual_range`**
 | N
-| C, D
+| C, D, BO
 | <<missing-data>>
 | The smallest and the largest valid non-missing values occurring in the variable.
 
 | **`add_offset`**
 | N
-| C, D
+| C, D, BO
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"], and <<packed-data>>
 | If present for a variable, this number is to be added to the data after it is read by an application.
 If both **`scale_factor`** and **`add_offset`** attributes are present, the data are first scaled before the offset is added.
@@ -44,7 +45,7 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 
 | **`axis`**
 | S
-| C
+| C, BI
 | <<coordinate-types>>
 | Identifies latitude, longitude, vertical, or time axes.
 
@@ -56,7 +57,7 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 
 | **`calendar`**
 | S
-| C
+| C, BI
 | <<calendar>>
 | Calendar used for encoding time axes.
 
@@ -74,7 +75,7 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 
 | **`cf_role`**
 | S
-| C
+| C, BI
 | <<coordinates-metadata>>, and <<mesh-topology-variables>> 
 | Identifies the roles of variables that identify features in discrete sampling geometries; and the roles of mesh topology and location index set variables.
 
@@ -98,7 +99,7 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 
 | **`computed_standard_name`**
 | S
-| C
+| C, BI
 | <<parametric-vertical-coordinate>>
 | Indicates the standard name, from the standard name table, of the computed vertical coordinate values, computed according to the formula in the definition.
 
@@ -135,8 +136,9 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 
 | **`_FillValue`**
 | D
-| C, D
+| C, D, BO
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"], and <<missing-data>>, and <<ch9-missing-data>>.
+
 | A value used to represent missing or undefined data.
 Allowed for auxiliary coordinate variables but not allowed for coordinate variables.
 
@@ -168,7 +170,7 @@ Use in conjunction with **`flag_meanings`**.
 
 | **`formula_terms`**
 | S
-| C
+| C, BO
 | <<parametric-vertical-coordinate>>
 | Identifies variables that correspond to the terms in a formula.
 
@@ -217,13 +219,13 @@ The index variable indicates that the indexed ragged array representation is bei
 
 | **`leap_month`**
 | N
-| C
+| C, BI
 | <<calendar>>
 | Specifies which month is lengthened by a day in leap years for a user defined calendar.
 
 | **`leap_year`**
 | N
-| C
+| C, BI
 | <<calendar>>
 | Provides an example of a leap year for a user defined calendar.
 It is assumed that all years that differ from this year by a multiple of four are also leap years.
@@ -242,7 +244,7 @@ It is assumed that all years that differ from this year by a multiple of four ar
 
 | **`long_name`**
 | S
-| C, D, Do
+| C, D, Do, BI
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"], and <<long-name>>
 | A descriptive name that indicates a variable's content.
 This name is not standardized.
@@ -255,14 +257,14 @@ This name is not standardized.
 
 | **`missing_value`**
 | D
-| C, D
+| C, D, BO
 | <<missing-data>>, and <<ch9-missing-data>>
 | A value or values used to represent missing or undefined data.
 Allowed for auxiliary coordinate variables but not allowed for coordinate variables.
 
 | **`month_lengths`**
 | N
-| C
+| C, BI
 | <<calendar>>
 | Specifies the length of each month in a non-leap year for a user defined calendar.
 
@@ -292,7 +294,7 @@ Allowed for auxiliary coordinate variables but not allowed for coordinate variab
 
 | **`positive`**
 | S
-| C
+| C, BI
 | <<COARDS>>
 | Direction of increasing vertical coordinate value.
 
@@ -311,7 +313,7 @@ The count variable indicates that the contiguous ragged array representation is
 
 | **`scale_factor`**
 | N
-| C, D
+| C, D, BO
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"], and <<packed-data>>
 | If present for a variable, the data are to be multiplied by this factor after the data are read by an application.
 See also the **`add_offset`** attribute.
@@ -331,7 +333,7 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 
 | **`standard_name`**
 | S
-| C, D
+| C, D, BI
 | <<standard-name>>
 | A standard name that references a description of a variable"s content in the standard name table.
 
@@ -343,25 +345,25 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 
 | **`units`**
 | S
-| C, D
+| C, D, BI
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"], and <<units>>
 | Units of a variable"s content.
 
 | **`valid_max`**
 | N
-| C, D
+| C, D, BO
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"]
 | Largest valid value of a variable.
 
 | **`valid_min`**
 | N
-| C, D
+| C, D, BO
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"]
 | Smallest valid value of a variable.
 
 | **`valid_range`**
 | N
-| C, D
+| C, D, BO
 | link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"]
 | Smallest and largest valid values of a variable.
 |===============

cf-conventions.adoc

@@ -1,7 +1,7 @@
 include::version.adoc[]
 = NetCDF Climate and Forecast (CF) Metadata Conventions
-Brian{nbsp}Eaton; Jonathan{nbsp}Gregory; Bob{nbsp}Drach; Karl{nbsp}Taylor; Steve{nbsp}Hankin; Jon{nbsp}Blower; John{nbsp}Caron; Rich{nbsp}Signell; Phil{nbsp}Bentley; Greg{nbsp}Rappa; Heinke{nbsp}Höck; Alison{nbsp}Pamment; Martin{nbsp}Juckes; Martin{nbsp}Raspaud; Randy{nbsp}Horne; Timothy{nbsp}Whiteaker; David{nbsp}Blodgett; Charlie{nbsp}Zender; Daniel{nbsp}Lee; David{nbsp}Hassell; Alan{nbsp}D.{nbsp}Snow; Tobias{nbsp}Kölling; Dave{nbsp}Allured; Aleksandar{nbsp}Jelenak; Anders{nbsp}Meier{nbsp}Soerensen; Lucile{nbsp}Gaultier; Sylvain{nbsp}Herlédan; Fernando{nbsp}Manzano; Lars{nbsp}Bärring; Christopher{nbsp}Barker
-Version {current-version}, 31 August, 2022: See https://cfconventions.org for further information
+Brian{nbsp}Eaton; Jonathan{nbsp}Gregory; Bob{nbsp}Drach; Karl{nbsp}Taylor; Steve{nbsp}Hankin; Jon{nbsp}Blower; John{nbsp}Caron; Rich{nbsp}Signell; Phil{nbsp}Bentley; Greg{nbsp}Rappa; Heinke{nbsp}Höck; Alison{nbsp}Pamment; Martin{nbsp}Juckes; Martin{nbsp}Raspaud; Randy{nbsp}Horne; Timothy{nbsp}Whiteaker; David{nbsp}Blodgett; Charlie{nbsp}Zender; Daniel{nbsp}Lee; David{nbsp}Hassell; Alan{nbsp}D.{nbsp}Snow; Tobias{nbsp}Kölling; Dave{nbsp}Allured; Aleksandar{nbsp}Jelenak; Anders{nbsp}Meier{nbsp}Soerensen; Lucile{nbsp}Gaultier; Sylvain{nbsp}Herlédan; Fernando{nbsp}Manzano; Lars{nbsp}Bärring; Christopher{nbsp}Barker; Sadie{nbsp}Bartholomew
+Version{nbsp}{current-version},{nbsp}{nbsp}{docprodtime}: See https://cfconventions.org for further information
 :doctype: book
 :pdf-folio-placement: physical
 :sectanchors:

ch06.adoc

@@ -106,7 +106,7 @@ variables:
     time:standard_name = "time" ;
     time:units = "days since 2019-01-01" ;
   float abundance(time,taxon) ;
-    abundance:standard_name = "number_concentration_of_organisms_in_taxon_in_sea_water" ;
+    abundance:standard_name = "number_concentration_of_biological_taxon_in_sea_water" ;
     abundance:coordinates = "taxon_lsid taxon_name" ;
   char taxon_name(taxon,string80) ;
     taxon_name:standard_name = "biological_taxon_name" ;

ch07.adoc

@@ -20,10 +20,15 @@ To represent cells we add the attribute **`bounds`** to the appropriate coordina
 The value of **`bounds`** is the name of the variable that contains the vertices of the cell boundaries.
 We refer to this type of variable as a "boundary variable."
 __A boundary variable will have one more dimension than its associated coordinate or auxiliary coordinate variable.__ The additional dimension should be the most rapidly varying one, and its size is the maximum number of cell vertices.
-Since a boundary variable is considered to be part of a coordinate variable's metadata, it is not necessary to provide it with attributes such as **`long_name`** and **`units`**.
 
-Boundary variable attributes which determine the coordinate type (**`units`**, **`standard_name`**, **`axis`** and **`positive`**) or those which affect the interpretation of the array values (**`units`**, **`calendar`**, **`leap_month`**, **`leap_year`** and **`month_lengths`**) must always agree exactly with the same attributes of its associated coordinate, scalar coordinate or auxiliary coordinate variable.
-To avoid duplication, however, it is recommended that these are not provided to a boundary variable.
+A boundary variable inherits the values of some attributes from its parent coordinate variable.
+If a coordinate variable has any of the attributes marked "BI" (for "inherit") in the "Use" column of <<attribute-appendix>>, they are assumed to apply to its bounds variable as well.
+It is recommended that BI attributes not be included on a boundary variable.
+If a BI attribute is included, it must also be present in the parent variable, and it must exactly match the parent attribute's data type and value.
+A boundary variable can only have inheritable attributes if they are also present on its parent coordinate variable.
+A bounds variable may have any of the attributes marked "BO" for ("own") in the "Use" column of <<attribute-appendix>>.
+These attributes take precedence over any corresponding attributes of the parent variable.
+In these cases, the parent variable's attribute does not apply to the bounds variable, regardless of whether the latter has its own attribute.
 
 If a parametric coordinate variable with a **`formula_terms`** attribute (section 4.3.2) also has a **`bounds`** attribute, its boundary variable must have a **`formula_terms`** attribute too.
 In this case the same terms would appear in both (as specified in Appendix D), since the transformation from the parametric coordinate values to physical space is realized through the same formula.

ch08.adoc

@@ -57,6 +57,7 @@ The list variable has a string attribute **`compress`**, __containing a blank-se
 The presence of this attribute identifies the list variable as such.
 The list, the original dimensions and coordinate variables (including boundary variables), and the compressed variables with all the attributes of the uncompressed variables are written to the netCDF file.
 The uncompressed variables can be reconstituted exactly as they were using this information.
+The list variable must not have an associated boundary variable.
 
 [[horiz-compression-of-three-d-array-ex]]
 [caption="Example 8.1. "]

conformance.adoc

@@ -369,8 +369,8 @@ If there are two dimensions, the leading dimension (CDL order) must match one of
 The specified variable must exist in the file.
 * A boundary variable must have the same dimensions as its associated variable, plus have a trailing dimension (CDL order) for the maximum number of vertices in a cell.
 * A boundary variable must be a numeric data type.
-
-*  If a boundary variable has **`units`**,**`standard_name`**, **`axis`**, **`positive`**, **`calendar`**, **`leap_month`**, **`leap_year`** or **`month_lengths`** attributes, they must agree with those of its associated variable.
+* A boundary variable can only have inheritable attributes, i.e. any of those marked "BI" in the "Use" column of http://cfconventions.org/cf-conventions/cf-conventions.html#attribute-appendix[Appendix A], if they are also present on its parent coordinate variable.
+* If a boundary variable has an inheritable attribute then its data type and its value must be exactly the same as the parent variable's attribute.
 * Starting with version 1.7, a boundary variable must have a **`formula_terms`** attribute when it contains bounds for a parametric vertical coordinate variable that has a **`formula_terms`** attribute.
 In this case the same terms and named variables must appear in both except for terms that depend on the vertical dimension.
 For such terms the variable name appearing in the boundary variable's **`formula_terms`** attribute must differ from that found in the **`formula_terms`** attribute of the coordinate variable itself.
@@ -381,7 +381,7 @@ If a named variable in the **`formula_terms`** attribute of the vertical coordin
 *Recommendations:*
 
 * The points specified by a coordinate or auxiliary coordinate variable should lie within, or on the boundary, of the cells specified by the associated boundary variable.
-* Boundary variables should not have the **`_FillValue`**, **`missing_value`**, **`units`**, **`standard_name`**, **`axis`**, **`positive`**, **`calendar`**, **`leap_month`**, **`leap_year`** or **`month_lengths`** attributes.
+* Boundary variables should not include inheritable attributes, i.e. any of those marked "BI" in the "Use" column of http://cfconventions.org/cf-conventions/cf-conventions.html#attribute-appendix[Appendix A].
 
 
 [[section-19]]
@@ -504,6 +504,7 @@ The specified variable must be a node coordinate variable that exists in the fil
 * The type of the **`compress`** attribute is a string whose value is a blank separated list of dimension names.
 The specified dimensions must exist in the file.
 * The values of the associated coordinate variable must be in the range starting with 0 and going up to the product of the compressed dimension sizes minus 1 (CDL index conventions).
+* The associated coordinate variable must not have an associated boundary variable.
 
 [[compression-by-coordinate-subsampling]]
 === 8.3 Lossy Compression by Coordinate Subsampling

history.adoc

@@ -8,6 +8,8 @@
 === Working version (most recent first)
 
 * {issues}486[Issue #486]: Fix PDF formatting problems and invalid references
+* {issues}490[Issue #490]: Simple correction to Example 6.1.2
+* {issues}457[Issue #457]: Creation date of the draft Conventions document 
 * {issues}445[Issue #445]: Updates concerning the Polar Stereographic Grid Mapping
 * {issues}468[Issue #468]: Update section 2.3 to clarify recommended character set
 * {issues}147[Issue #147]: Clarify the use of compressed dimensions in related variables
@@ -32,6 +34,7 @@
 * {issues}428[Issue #428]: Recording deployment positions
 * {issues}430[Issue #430]: Clarify the function of the `cf_role` attribute
 * {pull-requests}408[Pull request #408]: Deleted a sentence on "rotated Mercator" under `Oblique Mercator` grid mapping in Appendix F
+* {issues}265[Issue #265]: Clarification of the requirements on bounds variable attributes
 * {issues}260[Issue #260]: Clarify use of dimensionless units
 * {issues}410[Issue #410]: Delete "on a spherical Earth" from the definition of the `latitude_longitude` grid mapping in Appendix F 
 * {issues}153[Issue #153]: Reference UGRID conventions in CF