Merge pull request cf-convention#565 from davidhassell/list-fixes

Formatting of local links in text; Lists of Figures, Tables and Examples

appd.adoc

@@ -356,13 +356,13 @@ formula_terms = "sigma: var1 depth: var2 z1: var3 z2: var4 a: var5 href: var6
 The `standard_name` for `depth` and the `computed_standard_name` must be one of the consistent sets shown in <<table-computed-standard-names, Table D.1>>.
 No `standard_name` has been defined for `z1`, `z2`, `a`, `href` or `k_c`.
 
-// This table has an unusually long title, and AsciiDoctor is unable to wrap it.
-// But AsciiDoctor will wrap an image title, so assign the title to a 1-pixel transparent image,
-// and put the table immediately thereafter, with its own title:
+// (Leaving this comment here in case it's useful in the future!)
+// This table used to have an unusually long title, and AsciiDoctor was unable to wrap it.
+// But AsciiDoctor will wrap an image title, so the title was assigned to 
+// a 1-pixel transparent image (images/NFFFFFF-1.0.png)
+// and the table put immediately thereafter, with its own title.
 [[table-computed-standard-names]]
-.Consistent sets of values for the standard_names of formula terms and the computed_standard_name needed in defining the ocean sigma coordinate, the ocean s-coordinate, the ocean_sigma over z coordinate, and the ocean double sigma coordinate.
-image::images/NFFFFFF-1.0.png[caption=""]
-
+.Consistent sets of values for the standard_names of formula terms and the computed_standard_name
 [options="header",cols="1,3,2,3",caption="Table D.1. "]
 |===============
 

appf.adoc

@@ -280,7 +280,7 @@ and
 link:$$http://geotiff.maptools.org/proj_list/polar_stereographic.html$$[http://geotiff.maptools.org/proj_list/polar_stereographic.html].
 
 The standard_parallel variant corresponds to EPSG Polar Stereographic (Variant B) (EPSG dataset coordinate operation method code 9829), while the scale_factor_at_projection_origin variant corresponds to EPSG Polar Stereographic (Variant A) (EPSG dataset coordinate operation method code 9810).
-As PROJ requires the standard parallel, [Snyder] formula 21-7 can be used to compute it from the scale factor if needed.
+As PROJ requires the standard parallel, <<Snyder>> formula 21-7 can be used to compute it from the scale factor if needed.
 
 === Rotated pole
 

appi.adoc

@@ -40,7 +40,7 @@ The CF-netCDF elements are listed in <<table-cf-concepts, Table I.1>> and shown
 The CF data model has been derived from these CF-netCDF elements and relationships with the aims of removing aspects specific to the netCDF encoding, and reducing the number of elements, whilst retaining the ability to describe the CF conventions fully, in order to meet the design criteria.
 
 [[table-cf-concepts]]
-.The elements of the CF-netCDF conventions. The relationships to netCDF elements are shown in <<figure-cf-concepts>>.
+.The elements of the CF-netCDF conventions
 [options="header",cols="2",caption="Table I.1. "]
 |===============
 |{set:cellbgcolor!}
@@ -107,7 +107,7 @@ The elements of the CF data model (<<figure-field>>, <<figure-dim-aux>> and <<fi
 The constructs, listed in <<table-cf-constructs, Table I.2>>, are related to CF-netCDF elements (<<figure-cf-concepts>>), which in turn relate to the components of netCDF file.
 
 [[table-cf-constructs]]
-.The constructs of the CF data model. The relationships between the constructs and CF-netCDF elements are shown in in <<figure-field>>, <<figure-dim-aux>> and <<figure-coordinate-reference>>.
+.The constructs of the CF data model
 [options="header",cols="2",caption="Table I.2. "]
 |===============
 |{set:cellbgcolor!}

appj.adoc

@@ -87,7 +87,11 @@ In the two-dimensional case, `a = tp(tpi2, tpi1)`, `b = tp(tpi2, tpi1+1)`, `c =
 [[common-conversions-and-formulas, Section J.2, "Common Conversions and Formulas"]]
 ==== Common Conversions and Formulas
 
-[cols="2, 8, 8"]
+<<subsampling-formulas, Table J.1>> describes conversions and formulas that are used in the descriptions of the interpolation techniques.
+
+[[table-subsampling-formulas]]
+.Conversions and formulas used in the definitions of subsampling interpolation methods
+[cols="2, 8, 8", options="header",caption="Table J.1. "]
 |===============
 | |Description | Formula
 

ch01.adoc

@@ -54,12 +54,12 @@ Therefore CF-netCDF does not use codes, but instead relies on controlled vocabul
 [[terminology, Section 1.3, "Terminology"]]
 === Terminology
 
-The terms in this document that refer to components of a netCDF file are defined in the NetCDF User's Guide (NUG) <<NUG>> NUG.
+The terms in this document that refer to components of a netCDF file are defined in the NetCDF User's Guide (NUG) <<NUG>>.
 Some of those definitions are repeated below for convenience.
 
 ancestor group:: A group from which the referring group is descended via direct parent-child relationships
 
-auxiliary coordinate variable:: Any netCDF variable that contains coordinate data, but is not a coordinate variable (in the sense of that term defined by the NUG and used by this standard - see below).
+auxiliary coordinate variable:: Any netCDF variable that contains coordinate data, but is not a coordinate variable (in the sense of that term defined by the <<NUG>> and used by this standard - see below).
 Unlike coordinate variables, there is no relationship between the name of an auxiliary coordinate variable and the name(s) of its dimension(s).
 
 boundary variable:: A boundary variable is associated with a variable that contains coordinate data.
@@ -137,18 +137,18 @@ vertical dimension:: A dimension of a netCDF variable that has an associated ver
 === Overview
 
 No variable or dimension names are standardized by this convention.
-Instead we follow the lead of the NUG and standardize only the names of attributes and some of the values taken by those attributes.
+Instead we follow the lead of the <<NUG>> and standardize only the names of attributes and some of the values taken by those attributes.
 Variable or dimension names can either be a single variable name or a path to a variable.
 The overview provided in this section will be followed with more complete descriptions in following sections.
 <<attribute-appendix>> contains a summary of all the attributes used in this convention.
 
-Files using this version of the CF Conventions must set the NUG defined attribute **`Conventions`** to contain the string value "**`CF-{current-version-as-attribute}`**" to identify datasets that conform to these conventions.
+Files using this version of the CF Conventions must set the <<NUG>> defined attribute **`Conventions`** to contain the string value "**`CF-{current-version-as-attribute}`**" to identify datasets that conform to these conventions.
 
 The general description of a file's contents should be contained in the following attributes: **`title`**, **`history`**, **`institution`**, **`source`**, **`comment`** and **`references`** (<<description-of-file-contents>>).
 For backwards compatibility with COARDS none of these attributes is required, but their use is recommended to provide human readable documentation of the file contents.
 
 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`**, 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>>).
@@ -163,7 +163,7 @@ Two independent parts of the convention allow this to be done.
 There are conventions that identify the variables that contain the coordinate data, and there are conventions that identify the type of coordinate represented by that data.
 
 There are two methods used to identify variables that contain coordinate data.
-The first is to use the NUG-defined "coordinate variables."
+The first is to use the <<NUG>>-defined "coordinate variables."
 __The use of coordinate variables is required for all dimensions that correspond to one dimensional space or time coordinates__.
 In cases where coordinate variables are not applicable, the variables containing coordinate data are identified by the **`coordinates`** attribute.
 
@@ -193,7 +193,7 @@ An important application of this attribute is to describe climatological and diu
 
 Methods for reducing the total volume of data include both packing and compression.
 Packing reduces the data volume by reducing the precision of the stored numbers.
-It is implemented using the attributes **`add_offset`** and **`scale_factor`** which are defined in the NUG.
+It is implemented using the attributes **`add_offset`** and **`scale_factor`** which are defined in the <<NUG>>.
 Compression on the other hand loses no precision, but reduces the volume by not storing missing data.
 The attribute **`compress`** is defined for this purpose.
 

ch02.adoc

@@ -1,6 +1,6 @@
 ==  NetCDF Files and Components 
 
-The components of a netCDF file are described in section 2 of the NUG <<NUG>>.
+The components of a netCDF file are described in section 2 of the <<NUG>>.
 In this section we describe conventions associated with filenames and the basic components of a netCDF file.
 We also introduce new attributes for describing the contents of a file.
 
@@ -15,7 +15,7 @@ Data variables must be one of the following data types: **`string`**, **`char`**
 The **`string`** type, which has variable length, is only available in files using the netCDF version 4 (netCDF-4) format.
 The **`char`** and **`string`** types are not intended for numeric data.
 One byte numeric data should be stored using the **`byte`** or **`unsigned byte`** data types.
-It is possible to treat the **`byte`** and **`short`** types as unsigned by using the NUG convention of indicating the unsigned range using the **`valid_min`**, **`valid_max`**, or **`valid_range`** attributes.
+It is possible to treat the **`byte`** and **`short`** types as unsigned by using the <<NUG>> convention of indicating the unsigned range using the **`valid_min`**, **`valid_max`**, or **`valid_range`** attributes.
 In many situations, any integer type may be used.
 When the phrase "integer type" is used in this document, it should be understood to mean **`byte`**, **`unsigned byte`**, **`short`**, **`unsigned short`**, **`int`**, **`unsigned int`**, **`int64`**, or **`unsigned int64`**.
 
@@ -97,8 +97,7 @@ NetCDF variables that contain coordinate data are referred to as __coordinate va
 [[missing-data, Section 2.5.1, "Missing data, valid and actual range of data"]]
 ==== Missing data, valid and actual range of data
 
-The NUG conventions
-(link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, Attribute Conventions])
+link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, Attribute Conventions]
 provide the **`_FillValue`**, **`missing_value`**, **`valid_min`**, **`valid_max`**, and **`valid_range`** attributes to indicate missing data.
 Missing data is allowed in data variables and auxiliary coordinate variables.
 Generic applications should treat the data as missing where any auxiliary coordinate variables have missing values; special-purpose applications might be able to make use of the data.
@@ -144,7 +143,7 @@ See <<attribute-appendix>> for a list of attributes described by this standard.
 [[identification-of-conventions]]
 ==== Identification of Conventions
 
-Files that follow this version of the CF Conventions must indicate this by setting the NUG defined global attribute **`Conventions`** to a string value that contains "**`CF-{current-version-as-attribute}`**".
+Files that follow this version of the CF Conventions must indicate this by setting the <<NUG>> defined global attribute **`Conventions`** to a string value that contains "**`CF-{current-version-as-attribute}`**".
 The Conventions version number contained in that string can be used to find the web based versions of this document are from the link:$$https://cfconventions.org/$$[netCDF Conventions web page].
 Subsequent versions of the CF Conventions will not make invalid a compliant usage of this or earlier versions of the CF terms and forms.
 
@@ -167,7 +166,7 @@ The attribute values are all character strings.
 For readability in ncdump outputs it is recommended to embed newline characters into long strings to break them into lines.
 For backwards compatibility with COARDS none of these global attributes is required.
 
-The NUG defines **`title`** and **`history`** to be global attributes.
+The <<NUG>> defines **`title`** and **`history`** to be global attributes.
 We wish to allow the newly defined attributes, i.e., **`institution`**, **`source`**, **`references`**, and **`comment`**, to be either global or assigned to individual variables.
 When an attribute appears both globally and as a variable attribute, the variable's version has precedence.
 
@@ -241,7 +240,7 @@ A special case exists for coordinate variables.
 Because coordinate variables must share dimensions with the variables that reference them, the ancestor search is executed only until the local apex group is reached.
 For coordinate variables that are not found in the referring group or its ancestors, a further strategy is provided, called lateral search.
 The lateral search proceeds downwards from the local apex group width-wise through each level of groups until the sought coordinate is found.
-The lateral search algorithm may only be used for NUG coordinate variables; it shall not be used for auxiliary coordinate variables.
+The lateral search algorithm may only be used for <<NUG>> coordinate variables; it shall not be used for auxiliary coordinate variables.
 
 [NOTE]
 ====

ch03.adoc

@@ -139,7 +139,7 @@ Use of these attributes for data packing, which is their most important applicat
 [[long-name, Section 3.2, "Long Name"]]
 === Long Name
 
-The **`long_name`** attribute is defined by the NUG to contain a long descriptive name which may, for example, be used for labeling plots.
+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 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.
@@ -148,7 +148,7 @@ If a variable has no **`long_name`** attribute then an application may use, as a
 === Standard Name
 
 A fundamental requirement for exchange of scientific data is the ability to describe precisely the physical quantities being represented.
-To some extent this is the role of the **`long_name`** attribute as defined in the NUG.
+To some extent this is the role of the **`long_name`** attribute as defined in the <<NUG>>.
 However, usage of **`long_name`** is completely ad-hoc.
 For many applications it is desirable to have a more definitive description of the quantity, which allows users of data from different sources (some of which might be models and others observational) to determine whether quantities are in fact comparable.
 For this reason each variable may optionally be given a "standard name", whose meaning is defined by this convention.

ch04.adoc

@@ -123,7 +123,7 @@ Recommendations:  The **`positive`** attribute should be consistent with the sig
 ==== Dimensional Vertical Coordinate
 
 
-Variables representing dimensional vertical coordinates for or height must always explicitly include the  **`units`** attribute.
+Variables representing dimensional vertical coordinates for depth or height must always explicitly include the  **`units`** attribute.
 The acceptable units for a vertical (depth or height) coordinate variable must a UDUNITS <<UDUNITS>> representation of one of the following:
 
 * units of pressure.

ch05.adoc

@@ -20,7 +20,7 @@ We recommend that the name of a multidimensional coordinate variable should not
 This practice also avoids potential bugs in applications that determine coordinate variables by only checking for a name match between a dimension and a variable and not checking that the variable is one dimensional.
 
 If the longitude, latitude, vertical or time coordinate is multi-valued, varies in only one dimension, and varies independently of other spatiotemporal coordinates, it is not permitted to store it as an auxiliary coordinate variable.
-This is both to enhance conformance to COARDS and to facilitate the use of generic applications that recognize the NUG convention for coordinate variables.
+This is both to enhance conformance to COARDS and to facilitate the use of generic applications that recognize the <<NUG>> convention for coordinate variables.
 An application that is trying to find the latitude coordinate of a variable should always look first to see if any of the variable's dimensions correspond to a latitude coordinate variable.
 If the latitude coordinate is not found this way, then the auxiliary coordinate variables listed by the `coordinates` attribute should be checked.
 Note that it is permissible, but optional, to list coordinate variables as well as auxiliary coordinate variables in the `coordinates` attribute.