Merge pull request #506 from JonathanGregory/issue501

clarify various issues relating to attributes

appa.adoc

@@ -4,11 +4,13 @@
 == Attributes
 
 All CF attributes are listed here except for those that are used to describe grid mappings and mesh topologies.
-See Appendix F for the grid mapping attributes, and Appendix K for mesh topology attributes.
+See <<appendix-grid-mappings>> for the grid mapping attributes, and <<appendix-mesh-topology-attributes>> for mesh topology attributes.
 
 The "Type" values are **S** for string, **N** for numeric, and **D** for the type of the data variable.
 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.
+**G** indicates it can appear as a global attribute, and **Gr** as a group attribute.
+For variable attributes, the possible values of "Use" are: **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.
+CF does not prohibit any of these attributes from being attached to variables of different kinds from those listed as their "Use" in this table, but their meanings are not defined by CF if they are used in these other ways.
 "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]]
@@ -75,8 +77,9 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 | **`cf_role`**
 | S
 | 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.
+| <<coordinates-metadata>>
+| Identifies the roles of variables that identify features in discrete sampling geometries.
+Identifies the roles of mesh topology and location index set variables (see <<appendix-mesh-topology-attributes>>).
 
 | **`climatology`**
 | S

ch03.adoc

@@ -141,7 +141,7 @@ Use of these attributes for data packing, which is their most important applicat
 
 The **`long_name`** attribute is defined by the NUG to contain a long descriptive name which may, for example, be used for labeling plots.
 For backwards compatibility with COARDS this attribute is optional.
-But it is highly recommended that either this or the **`standard_name`** attribute defined in the next section be provided to make the file self-describing.
+But it is highly recommended that either this or the **`standard_name`** attribute defined in the next section be provided for all data variables and variables containing coordinate data, in order to make the file self-describing.
 If a variable has no **`long_name`** attribute then an application may use, as a default, the **`standard_name`** if it exists, or the variable name itself.
 
 [[standard-name, Section 3.3, "Standard Name"]]

ch09.adoc

@@ -434,8 +434,8 @@ Every feature within a Discrete Geometry CF file must be unambiguously associate
 Every element of every feature must be unambiguously associated with its space and time coordinates and with the feature that contains it.
 The **`coordinates`** attribute must be attached to every data variable to indicate the spatiotemporal coordinate variables that are needed to geo-locate the data.
 
-Where feasible, one of the coordinate or auxiliary coordinate variables of a discrete sampling geometry should have an attribute named **`cf_role`**.
-This attribute has no other function in the CF convention (despite its general-sounding name), and its only permitted values are **`timeseries_id`**, **`profile_id`**, and **`trajectory_id`**.
+Where feasible, one of the coordinate or auxiliary coordinate variables of a discrete sampling geometry should have an attribute named **`cf_role`**, whose only permitted values for this purposes are **`timeseries_id`**, **`profile_id`**, and **`trajectory_id`**.
+(Despite its general-sounding name, this attribute only one other function, namely in <<mesh-topology-variables>>.)
 The variable carrying the **`cf_role`** attribute may have any data type.
 When a variable is assigned this attribute, it must provide a unique identifier for each feature instance.  
 CF files that contain timeSeries, profile or trajectory featureTypes, should include only a single occurrence of a **`cf_role`** attribute;  CF files that contain timeSeriesProfile or trajectoryProfile may contain two occurrences, corresponding to the two levels of structure in these feature types.

conformance.adoc

@@ -128,11 +128,6 @@ References can be absolute, relative or with no path, in which case, the variabl
 [[description-of-the-data]]
 === 3 Description of the Data
 
-*Recommendations:*
-
-* All variables should use either the **`long_name`** or the **`standard_name`** attributes to describe their contents.
-Exceptions are boundary and climatology variables.
-
 [[section-7]]
 [[units]]
 === 3.1 Units
@@ -154,6 +149,13 @@ Exceptions are the units **`level`**, **`layer`**, and **`sigma_level`**.
 * The units **`level`**, **`layer`**, and **`sigma_level`** are deprecated.
 * Any variable whose **`units`** involve a temperature unit should also have a **`units_metadata`** attribute.
 
+[[long-name]]
+=== 3.2 Long Name
+
+*Recommendations:*
+
+* All data variables and variables containing coordinate data should use either the **`long_name`** or the **`standard_name`** attributes to describe their contents.
+
 [[section-8]]
 [[standard-name]]
 === 3.3 Standard Name

history.adoc

@@ -7,6 +7,7 @@
 
 === Working version (most recent first)
 
+* {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.
 * {issues}477[Issue #477]: Period and hyphen allowed in attribute names
 * {issues}500[Issue #500]: Appendix B: Added a **`conventions`** string to the standard name xml file format definition