From cda2c00ad20568b93c35b169827c0571e7daf978 Mon Sep 17 00:00:00 2001 From: David Hassell Date: Tue, 12 Nov 2024 21:44:55 +0000 Subject: [PATCH] Formatting of local links in text; Lists of Figures, Tables and Examples --- appd.adoc | 11 +++++----- appf.adoc | 4 ++-- appi.adoc | 4 ++-- appj.adoc | 6 +++++- ch01.adoc | 2 +- ch03.adoc | 2 +- ch04.adoc | 2 +- ch05.adoc | 2 +- ch07.adoc | 6 +++--- ch08.adoc | 14 ++++++------- ch09.adoc | 57 +++++++++++++++++++++++++++----------------------- toc-extra.adoc | 7 +++++++ 12 files changed, 66 insertions(+), 51 deletions(-) diff --git a/appd.adoc b/appd.adoc index e1d6beb9..0d0d5464 100644 --- a/appd.adoc +++ b/appd.adoc @@ -356,13 +356,12 @@ 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 <>. 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, +// 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. "] |=============== diff --git a/appf.adoc b/appf.adoc index 063450dd..8645013f 100644 --- a/appf.adoc +++ b/appf.adoc @@ -173,7 +173,7 @@ link:$$https://proj.org/operations/projections/cea.html$$[https://proj.org/opera and link:$$http://geotiff.maptools.org/proj_list/cylindrical_equal_area.html$$[http://geotiff.maptools.org/proj_list/cylindrical_equal_area.html] ("Lambert Cylindrical Equal Area" or EPSG 9834 or EPSG 9835). -Detailed formulas can be found in <> pages 76-85. +Detailed formulas can be found in <> pages 76-85. === Latitude-Longitude @@ -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, <> formula 21-7 can be used to compute it from the scale factor if needed. === Rotated pole diff --git a/appi.adoc b/appi.adoc index 8eac2306..d4841c4d 100644 --- a/appi.adoc +++ b/appi.adoc @@ -40,7 +40,7 @@ The CF-netCDF elements are listed in <> 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 <>. +.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 (<>, <> and <>, are related to CF-netCDF elements (<>), 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 <>, <> and <>. +.The constructs of the CF data model [options="header",cols="2",caption="Table I.2. "] |=============== |{set:cellbgcolor!} diff --git a/appj.adoc b/appj.adoc index 31135d0e..d80d3a27 100644 --- a/appj.adoc +++ b/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"] +<> 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 diff --git a/ch01.adoc b/ch01.adoc index 7fa20950..e3cc269f 100644 --- a/ch01.adoc +++ b/ch01.adoc @@ -54,7 +54,7 @@ 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. +The terms in this document that refer to components of a netCDF file are defined in the NetCDF User's Guide (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 diff --git a/ch03.adoc b/ch03.adoc index 9e54fce0..f1c3f62f 100644 --- a/ch03.adoc +++ b/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. diff --git a/ch04.adoc b/ch04.adoc index 7763f730..5fea121e 100644 --- a/ch04.adoc +++ b/ch04.adoc @@ -122,7 +122,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 <> representation of one of the following: * units of pressure. diff --git a/ch05.adoc b/ch05.adoc index c8a8497b..fac4d173 100644 --- a/ch05.adoc +++ b/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. diff --git a/ch07.adoc b/ch07.adoc index d71db454..dfbdd42f 100644 --- a/ch07.adoc +++ b/ch07.adoc @@ -807,7 +807,9 @@ This interior ring variable must contain the value 0 to indicate an exterior rin The single dimension of the interior ring variable must be the same dimension as that of the part node count variable. The geometry types included in this convention are listed in Table 7.1. -[cols="4"] +[[table-geometry-types]] +.Dimensionality, description, and additional required attributes for geometry_types. +[cols="4", options="header",caption="Table 7.1. "] |=============== | geometry_type | Dimensionality | Description of Geometry Instance | Additional required attributes on geometry container variable @@ -818,8 +820,6 @@ The geometry types included in this convention are listed in Table 7.1. | **polygon** | 2 | A collection of one or more polygons, where a polygon is a planar surface comprised of an exterior ring and zero or more interior rings (i.e., holes), where a ring is a closed line (i.e., the last point in the line is assumed to be connected to the first point) | node_count, part_node_count (if holes or multipart geometries are present), interior_ring (if holes are present) |=============== -**Table 7.1.** Dimensionality, description, and additional required attributes for geometry_types. - [[complete-multipolygon-example]] [caption="Example 7.16. "] .Polygons with holes diff --git a/ch08.adoc b/ch08.adoc index 6c387ad2..ab5b2611 100644 --- a/ch08.adoc +++ b/ch08.adoc @@ -17,7 +17,7 @@ The disadvantage is that generic utilities that don't recognize the CF conventio === Packed Data At the current time the netCDF interface does not provide for packing data. -However a simple packing may be achieved through the use of the optional NUG defined attributes **`scale_factor`** and **`add_offset`**. +However a simple packing may be achieved through the use of the optional NUG <> defined attributes **`scale_factor`** and **`add_offset`**. After the data values of a variable have been read, they are to be multiplied by the **`scale_factor`**, and have **`add_offset`** added to them. If both attributes are present, the data are scaled before the offset is added. When scaled data are written, the application should first subtract the offset and then divide by the scale factor. @@ -588,8 +588,8 @@ The full set of bounds tie points is formed by appending, for each continuous ar **Bounds Tie Point Attribute and Bounds Tie Point Variable** + A **`bounds_tie_points`** attribute must be defined for each tie point coordinate variable corresponding to reconstituted coordinates with cell boundaries. -It is a single word of the form __“bounds_tie_point_variable”__ that identifies a bounds tie point variable, containing a bounds tie point coordinate value for each tie point stored in its tie point coordinate variable, and therefore the bounds tie point variable has the same set of dimensions as its tie point coordinate variable. -An example of the usage of the **`bounds_tie_points`** is shown in <>. +Its string value identifies a __bounds tie point variable__ which contains a bounds tie point coordinate value for each tie point stored in its tie point coordinate variable, and therefore the bounds tie point variable has the same set of dimensions as its tie point coordinate variable. +An example of the usage of the **`bounds_tie_points`** is shown in <>. Since a bounds tie point variable is considered to be part of a tie point coordinate variable’s metadata, it is not necessary to provide it with attributes such as long_name and units, following the same rules as for the bounds of an uncompressed coordinate variable, see <>. **Uncompressing coordinate bounds** + @@ -604,9 +604,9 @@ For one-dimensional coordinate bounds, in the second step of the process, for ea **Uncompression of two-dimensional coordinate bounds** + For two-dimensional coordinate bounds, in the second step of the process, for each index pair `(j, i)` of the interpolated dimension, the four bounds of the boundary variable is set to the value of the interpolated bounds point grid at index pairs `B0`, `B1`, `B2` and `B3`, respectively, where the index pairs are defined above under <>. -[[example-interpolation-of-cell-boundaries, Interpolation of 2D Cell Boundaries corresponding to Figure 8.4]] +[[example-interpolation-of-cell-boundaries]] [caption="Example 8.7. "] -.Interpolation of 2D Cell Boundaries corresponding to <> +.Interpolation of the 2D cell boundaries corresponding to Figure 8.4 ==== ---- dimensions: @@ -668,8 +668,8 @@ The data creator shall specify the floating-point arithmetic precision used duri [cols="3,10"] |=============== | ** Value ** | ** Description** -| "32" | 32-bit floating-point arithmetic, comparable to the binary32 standard in [<>] -| "64" | 64-bit floating-point arithmetic, comparable to the binary64 standard in [<>] +| "32" | 32-bit floating-point arithmetic, comparable to the IEEE binary32 standard <> +| "64" | 64-bit floating-point arithmetic, comparable to the IEEE binary64 standard <> |=============== Using the given computational precision in the interpolation computations is a necessary, but not sufficient, condition for the data user to be able to reconstitute the coordinates to an accuracy comparable to that intended by the data creator. diff --git a/ch09.adoc b/ch09.adoc index 9a61fca9..f8665d46 100644 --- a/ch09.adoc +++ b/ch09.adoc @@ -13,10 +13,12 @@ The representation of such features in a CF dataset was supported previous to th This chapter describes further conventions which offer advantages of efficiency and clarity for storing a collection of features in a single file. When using these new conventions, __the features contained within a collection must always be of the same type; and all the collections in a CF file must be of the same feature type__. (Future versions of CF may allow mixing of multiple feature types within a file.) -Table 9.1 presents the feature types covered by this chapter. +<> presents the feature types covered by this chapter. Details and examples of storage of each of these feature types are provided in Appendix H, as indicated in the table. -[cols="4"] +[[table-feature-types]] +.Logical structure and mandatory coordinates for discrete sampling geometry featureTypes +[options="header",caption="Table 9.1. "] |=============== | featureType 2+| Description of a single feature with this discrete sampling geometry | Link @@ -41,10 +43,7 @@ Details and examples of storage of each of these feature types are provided in A ||| data(i,p,o) | x(i,p) y(i,p) z(i,p,o) t(i,p) | <> |=============== -**Table 9.1.** Logical structure and mandatory coordinates for discrete sampling geometry featureTypes. -Other space-time coordinates may be included which are not mandatory. - -In Table 9.1 the spatial coordinates x and y typically refer to longitude and latitude but other horizontal coordinates could also be used (see sections 4 and 5.6).   +In <> the spatial coordinates x and y typically refer to longitude and latitude but other horizontal coordinates could also be used (see sections 4 and 5.6).   The spatial coordinate z refers to vertical position. The time coordinate is indicated as t. The space-time coordinates that are indicated for each feature are mandatory. @@ -115,13 +114,15 @@ The **orthogonal multidimensional array representation**, the simplest represent For example, for a collection of the timeSeries that share a common set of times, or a collection of profiles that share a common set of vertical levels, this is likely to be the natural representation to use. In both examples, there will be longitude and latitude coordinate variables, x(i), y(i), that are one-dimensional and defined along the instance dimension. -Table 9.2 illustrates the storage of a data variable using the orthogonal multidimensional array representation. +<> illustrates the storage of a data variable using the orthogonal multidimensional array representation. The data variable holds a collection of 4 features. The individual features, distinguished by color, are sequenced along the horizontal axis by the instance dimension indices, i1, i2, i3, i4. Each instance contains three elements, sequenced along the vertical with element dimension indices, o1, o2, o3. -The i and o subscripts would be interchanged (i.e. Table 9.2 would be transposed) if the element dimension were the netCDF unlimited dimension. +The i and o subscripts would be interchanged (i.e. <> would be transposed) if the element dimension were the netCDF unlimited dimension. -[cols="4"] +[[table-orthogonal-array]] +.The storage of a data variable using the orthogonal multidimensional array representation (subscripts in CDL order) +[cols="4", options="header",caption="Table 9.2. "] |=============== |(i1, o1){set:cellbgcolor:#99dddd} |(i2, o1){set:cellbgcolor:#f6c682} @@ -142,8 +143,6 @@ The i and o subscripts would be interchanged (i.e. Table 9.2 would be transposed {set:cellbgcolor:#ddaaaa} |=============== -Table 9.2  The storage of a data variable using the orthogonal multidimensional array representation (subscripts in CDL order). - The instance variables of a dataset corresponding to Table 9.2 will be one-dimensional with size 4 (for example, the latitude locations of timeSeries), [cols="4"] @@ -178,15 +177,17 @@ The **incomplete multidimensional array representation** can used if the feature That is, features that are shorter than the longest feature must be padded with missing values to bring all instances to the same storage size. This representation sacrifices storage space to achieve simplicity for reading and writing.   -Table 9.3 illustrates the storage of a data variable using the orthogonal multidimensional array representation.   +<> illustrates the storage of a data variable using the orthogonal multidimensional array representation.   The data variable holds a collection of 4 features. The individual features, distinguished by color, are sequenced by the instance dimension indices, i1, i2, i3, i4. The instances contain respectively 2, 4, 3 and 6 elements, sequenced by the element dimension index with values of o1, o2, o3, ... . -The i and o subscripts would be interchanged (i.e. Table 9.3 would be transposed) if the element dimension were the netCDF unlimited dimension. +The i and o subscripts would be interchanged (i.e. <> would be transposed) if the element dimension were the netCDF unlimited dimension. -[cols="4"] +[[table-incomplete-array]] +.The storage of data using the incomplete multidimensional array representation (subscripts in CDL order) +[cols="4"", options="header", caption="Table 9.3. "] |=============== -| (i1, o1){set:cellbgcolor:#99dddd} +| (i1, o1){set:cellbgcolor:#99dddd} |(i2, o1){set:cellbgcolor:#f6c682} |(i3, o1){set:cellbgcolor:#d4b4de} |(i4, o1) @@ -232,14 +233,14 @@ The i and o subscripts would be interchanged (i.e. Table 9.3 would be transposed {set:cellbgcolor:#ddaaaa} |=============== -Table 9.3.   The storage of data using the incomplete multidimensional array representation (subscripts in CDL order). - ====  Contiguous ragged array representation The **contiguous ragged array representation** can be used only if the size of each feature is known at the time that it is created. -In this representation the data for each feature will be contiguous on disk, as shown in Table 9.4. +In this representation the data for each feature will be contiguous on disk, as shown in <>. -[cols="1",width="25%"] +[[table-contiguous-array]] +.The storage of data using the contiguous ragged representation (subscripts in CDL order) +[cols="1",width="25%", caption="Table 9.4. "] |=============== |(i1, o1) {set:cellbgcolor:#99dddd} @@ -287,8 +288,6 @@ In this representation the data for each feature will be contiguous on disk, as {set:cellbgcolor:#ddaaaa} |=============== -Table 9.4. The storage of data using the contiguous ragged representation (subscripts in CDL order). - In this representation, the file contains a **count variable**, which must be an integer type and [cols="4"] @@ -316,11 +315,20 @@ For indices that correspond to features, whose data have not yet been written, t ==== Indexed ragged array representation -The **indexed ragged array representation** stores the features interleaved along the sample dimension in the data variable as shown in Table 9.4. +The **indexed ragged array representation** stores the features interleaved along the sample dimension in the data variable as shown in <>. The canonical use case for this representation is the storage of real-time data streams that contain reports from many sources; the data can be written as it arrives. -[cols="3",width="75"] +[[table-indexed-array]] +.The storage of data using the indexed ragged representation (subscripts in CDL order) +[cols="3",width="75", options="header",caption="Table 9.5. "] |=============== +|{set:cellbgcolor!} +Data variable indices +|{set:cellbgcolor!} + +|{set:cellbgcolor!} +Index variable values + |(i1, o1){set:cellbgcolor:#99dddd} |{set:cellbgcolor!}         @@ -412,9 +420,6 @@ The canonical use case for this representation is the storage of real-time data {set:cellbgcolor:#ddaaaa} |=============== -Table 9.4 The storage of data using the indexed ragged representation (subscripts in CDL order). -The left hand side of the table illustrates a data variable; the right hand side of the table contains the values of the index variable. - In this representation, the file contains an **index variable**, which must be an integer type, and must have the sample dimension as its single dimension. The index variable contains the zero-based index of the feature to which each element belongs. This representation is identifiable by the presence of an attribute, **`instance_dimension`**, on the index variable, which names the dimension of the instance variables. diff --git a/toc-extra.adoc b/toc-extra.adoc index e73da712..ef3a2d17 100644 --- a/toc-extra.adoc +++ b/toc-extra.adoc @@ -4,6 +4,12 @@ 3.1. <> 3.2. <> 3.3. <> +7.1. <> +9.1. <> +9.2. <> +9.3. <> +9.4. <> +9.5. <> A.1. <> C.1. <> D.1. <> @@ -11,6 +17,7 @@ E.1. <> F.1. <> I.1. <> I.2. <> +J.1. <> K.2. <> **List of Figures**