Merge pull request cf-convention#520 from JonathanGregory/issue515

clarify the recommendation to use the convention of 4.3.3 for parametric vertical coordinates

ch01.adoc

@@ -136,8 +136,8 @@ For backwards compatibility with COARDS none of these attributes is required, bu
 Each variable in a netCDF file has an associated description which is provided by the attributes **`units`**, **`long_name`**, and **`standard_name`**.
 The **`units`**, and **`long_name`** attributes are defined in the NUG and the **`standard_name`** attribute is defined in this document.
 
-The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in <<cell-boundaries>>.
-The values of the **`units`** attributes are character strings that are recognized by UNIDATA's UDUNITS package <<UDUNITS>>, (with exceptions allowed as discussed in <<units>>).
+The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in <<cell-boundaries>>).
+The values of the **`units`** attributes are character strings that are recognized by UNIDATA's UDUNITS package <<UDUNITS>> (with exceptions allowed as discussed in <<units>>).
 
 The **`long_name`** and **`standard_name`** attributes are used to describe the content of each variable.
 For backwards compatibility with COARDS neither is required, but use of at least one of them is strongly recommended.
@@ -161,11 +161,8 @@ Because identification of a coordinate type by its units involves the use of an
 
 Latitude, longitude, and time are defined by internationally recognized standards, and hence, identifying the coordinates of these types is sufficient to locate data values uniquely with respect to time and a point on the earth's surface.
 On the other hand identifying the vertical coordinate is not necessarily sufficient to locate a data value vertically with respect to the earth's surface.
-In particular a model may output data on the dimensionless vertical coordinate used in its mathematical formulation.
-To achieve the goal of being able to spatially locate all data values, this convention includes the definitions of common dimensionless vertical coordinates in <<parametric-v-coord>>.
-These definitions provide a mapping between the dimensionless coordinate values and dimensional values that can be uniquely located with respect to a point on the earth's surface.
-The definitions are associated with a coordinate variable via the **`standard_name`** and **`formula_terms`** attributes.
-For backwards compatibility with COARDS use of these attributes is not required, but is strongly recommended.
+In particular a model may output data on the parametric (usually dimensionless) vertical coordinate used in its mathematical formulation.
+To achieve the goal of being able to spatially locate all data values, this convention provides a mapping, via the **`standard_name`** and **`formula_terms`** attributes of a parametric vertical coordinate variable, between its values and dimensional vertical coordinate values that can be uniquely located with respect to a point on the earth's surface (<<parametric-vertical-coordinate>>; <<parametric-v-coord>>).
 
 It is often the case that data values are not representative of single points in time and/or space, but rather of intervals or multidimensional cells.
 This convention defines a **`bounds`** attribute to specify the extent of intervals or cells.
@@ -197,7 +194,7 @@ Often a buffering operation can be used to miminize performance penalties when a
 
 COARDS addresses the issue of identifying dimensionless vertical coordinates, but does not provide any mechanism for mapping the dimensionless values to dimensional ones that can be located with respect to the earth's surface.
 For backwards compatibility we continue to allow (but do not require) the **`units`** attribute of dimensionless vertical coordinates to take the values "level", "layer", or "sigma_level."
-But we recommend that the **`standard_name`** and **`formula_terms`** attributes be used to identify the appropriate definition of the dimensionless vertical coordinate (see <<dimensionless-vertical-coordinate>>).
+But we recommend that the **`standard_name`** and **`formula_terms`** attributes be used to identify the appropriate definition of the dimensionless vertical coordinate (see <<parametric-vertical-coordinate>>).
 
 The CF conventions define attributes which enable the description of data properties that are outside the scope of the COARDS conventions.
 These new attributes do not violate the COARDS conventions, but applications that only recognize COARDS conforming datasets will not have the capabilities that the new attributes are meant to enable.

ch04.adoc

@@ -5,9 +5,7 @@ The commonest use of coordinate variables is to locate the data in space and tim
 
 Four types of coordinates receive special treatment by these conventions: latitude, longitude, vertical, and time.
 We continue to support the special role that the **`units`** and **`positive`** attributes play in the COARDS convention to identify coordinate type.
-We extend COARDS by providing explicit definitions of dimensionless vertical coordinates.
-The definitions are associated with a coordinate variable via the **`standard_name`** and **`formula_terms`** attributes.
-For backwards compatibility with COARDS use of these attributes is not required, but is strongly recommended.
+As an extension to COARDS, we strongly recommend that a parametric (usually dimensionless) vertical coordinate variable should be associated, via **`standard_name`** and **`formula_terms`** attributes, with its explicit definition, which provides a mapping between its values and dimensional vertical coordinate values that can be uniquely located with respect to a point on the earth's surface.
 
 Because identification of a coordinate type by its units is complicated by requiring the use of an external package <<UDUNITS>>, we provide two optional methods that yield a direct identification.
 The attribute **`axis`** may be attached to a coordinate variable and given one of the values **`X`**, **`Y`**, **`Z`** or **`T`** which stand for a longitude, latitude, vertical, or time axis respectively.

history.adoc

@@ -7,6 +7,7 @@
 
 === Working version (most recent first)
 
+* {issues}515[Issue #515]: Clarify the recommendation to use the convention of 4.3.3 for parametric vertical coordinates, because the previous wording caused confusion.
 * {issues}511[Issue #511]: Appendix B: New element in XML file header to record the "first published date"
 * {issues}509[Issue #509]: In exceptional cases allow a standard name to be aliased into two alternatives
 * {issues}501[Issue #501]: Clarify that data variables and variables containing coordinate data are highly recommended to have **`long_name`** or **`standard_name`** attributes, that **`cf_role`** is used only for discrete sampling geometries and UGRID mesh topologies, and that CF does not prohibit CF attributes from being used in ways that are not defined by CF but that in such cases their meaning is not defined by CF.