Merge remote-tracking branch 'upstream/main'

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Q&A about using CF
+    url: https://github.com/orgs/cf-convention/discussions/new?category=q-a-about-using-cf
+    about: Ask a question about how to use any aspect of CF or how it works (conventions, vocabulary, website, governance, GitHub etc.)
+  - name: Comments and ideas for changing CF
+    url: https://github.com/orgs/cf-convention/discussions/new?category=comments-and-ideas-for-changing-cf
+    about: Start a discussions about an improvement to any aspect of CF (conventions, vocabulary, website, governance, GitHub etc.)

.github/workflows/adoc_build.yml

@@ -21,6 +21,8 @@
 #
 name: Asciidoctor Build Workflow
 on:
+  # manually run workflow
+  workflow_dispatch:
   # trigger on PR event against main (will not run publish job)
   pull_request:
     branches: [ main ]
@@ -40,32 +42,25 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     # Check out PR
-    - uses: actions/checkout@v3
-    # Create build directory
-    - run: mkdir conventions_build
-    - 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
+    - uses: actions/checkout@v4
+    # If it is release event, tag for final
+    - name: If it is a release add the "final" tag and date timestamp formatting
       if: github.event_name == 'release'
       run: |
-        echo "FINAL_TAG=-a final" >> "$GITHUB_ENV"; echo "DATE_FMT=+%d %B, %Y" >> "$GITHUB_ENV"
+        echo "CF_FINAL=True" >> "$GITHUB_ENV"
     # Build cf-conventions.html using the Analog-inc asciidoctor-action
     - name: Build cf-conventions.html
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) cf-conventions.adoc -D conventions_build; cp -r images conventions_build'
-    # Patch the cfconventions.org link
-    - run: sed -E -i 's+(See&#160;)(https://cfconventions.org)(&#160;for&#160;further&#160;information.)+\1<a href="\2" target="_blank">\2</a>\3+' ./conventions_build/cf-conventions.html
+        shellcommand: 'make conventions-html'
     # Build cf-conventions.pdf using the Analog-inc asciidoctor-action
     - name: Build cf-conventions.pdf
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        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'
+        shellcommand: 'make conventions-pdf'
     # Upload artifact containing cf-conventions.html, cf-conventions.pdf
-    - name: Upload cf-conventions doc preview
-      uses: actions/upload-artifact@v3
+    - name: Save cf-conventions doc preview
+      uses: actions/upload-artifact@v4
       with:
         name: conventions_docs
         path: conventions_build/
@@ -75,46 +70,31 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     # Checkout PR
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     # Create build directory
     - run: mkdir conformance_build
-    - name: Set "final" tag
+    # If it is release event, tag for final
+    - name: If it is a release add the "final" tag and date timestamp formatting
       if: github.event_name == 'release'
       run: |
-        echo "FINAL_TAG=-a final" >> "$GITHUB_ENV"
+        echo "CF_FINAL=True" >> "$GITHUB_ENV"
     # Build conformance.html using the Analog-inc asciidoctor-action
     - name: Build conformance.html
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} conformance.adoc -D conformance_build'
+        shellcommand: 'make conformance-html'
     # Build conformance.pdf using the Analog-inc asciidoctor-action
     - name: Build conformance.pdf
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -d book conformance.adoc -D conformance_build'
+        shellcommand: 'make conformance-pdf'
     # Upload artifact containing conformance.html, conformance.pdf
-    - name: Upload conformance doc preview
-      uses: actions/upload-artifact@v3
+    - name: Save conformance doc preview
+      uses: actions/upload-artifact@v4
       with:
         name: conformance_docs
         path: conformance_build/
 
-  # Job to an artifact of the images/ directory.
-  # Only needed if we are going to run the publish job.
-  images_artifact:
-    name: Create artifact of image directory
-    if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-    # Checkout ref
-    - uses: actions/checkout@v3
-    # Create the image_directory artifact
-    - name: Upload images directory
-      uses: actions/upload-artifact@v3
-      with:
-        name: image_directory
-        path: images/
-
   # Use artifacts from the build_conventions, build_conformance, and
   # images_artifact jobs to update the gh-pages branch. The location of the
   # files to be updated depend on whether the job it triggered from a PR merge
@@ -126,11 +106,11 @@ jobs:
     # Do not run on pull requests
     if: github.event_name != 'pull_request'
     # Wait for the build artifacts to become available
-    needs: [build_conventions, build_conformance, images_artifact]
+    needs: [build_conventions, build_conformance]
     runs-on: ubuntu-latest
     steps:
       # Checkout gh-pages branch
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: 'gh-pages'
       # Will new docs go into root, or into a directory named after the
@@ -145,7 +125,7 @@ jobs:
           fi
       # Obtain the build artifacts from the previous jobs and place them in the
       # build/ directory
-      - uses: actions/download-artifact@v3
+      - uses: actions/download-artifact@v4
         with:
           path: build/
       # If we are doing a release, we need to create the release directory
@@ -157,8 +137,6 @@ jobs:
       - name: Remove old images directory
         if: github.event_name != 'release'
         run: rm -rf ${{ env.TARGET_DIR }}/images
-      - name: Move images directory to target directory
-        run: mv build/image_directory ${{ env.TARGET_DIR }}/images
       - name: Copy conventions and conformance documents
         run: |
           cp build/conventions_docs/cf-conventions.html ${{ env.TARGET_DIR }}/

.gitignore

@@ -4,3 +4,8 @@
 # Do not store generated HTML and PDF files
 cf-conventions.html
 cf-conventions.pdf
+conventions_build/
+conformance.html
+conformance.pdf
+conformance_build/
+.vscode/

.zenodo.json

@@ -157,7 +157,7 @@
     {"name": "Philip Cameron-Smith", "affiliation": "LLNL"},
     {"name": "John Caron", "affiliation": "Unidata"},
     {"name": "Guilherme Castelão", "affiliation": "Scripps Institution of Oceanography, UC San Diego", "orcid": "0000-0002-6765-0708"},
-    {"name": "Antonio Cofi\u00f1o", "affiliation": "University of Cantabria"},
+    {"name": "Antonio S. Cofi\u00f1o", "affiliation": "Institute of Physics of Cantabria, CSIC-UC", "orcid": "0000-0001-7719-979X"},
     {"name": "Lorenzo Corgnati", "affiliation": "CNR-ISMAR"},
     {"name": "Ethan Davis", "affiliation": "NSF Unidata", "orcid": "0000-0002-8530-2213"},
     {"name": "Cecelia DeLuca", "affiliation": "NOAA"},

Makefile

@@ -0,0 +1,97 @@
+MAIN_DOC := cf-conventions
+
+MAIN_DOC_BUILD_DIR := conventions_build
+
+MAIN_DOC_INC := version toc-extra 
+MAIN_DOC_INC += ch01 ch02 ch03 ch04 ch05 ch06 ch07 ch08 ch09
+MAIN_DOC_INC += appa appb appc appd appe appf appg apph appi appj appk
+MAIN_DOC_INC += history bibliography
+
+MAIN_DOC_INC := $(addsuffix .adoc, $(MAIN_DOC_INC))
+
+#These are the static files for the images of the conventions document
+MAIN_DOC_IMG := NFFFFFF-1.0.png
+MAIN_DOC_IMG += ci_1d_interpolation_subarea.svg ci_2d_interpolation_subarea.svg ci_bounds_interpolation.svg
+MAIN_DOC_IMG += ci_dimensions_overview.svg ci_interpolation_coefficients.svg ci_interpolation_subarea_generation_process.svg
+MAIN_DOC_IMG += ci_quadratic1.svg ci_quadratic2.svg ci_quadratic3.svg mesh_figure.svg
+
+#  ... and th list of dynamic files images, with a build rule that appears below
+MAIN_DOC_IMG_BLD := cfdm_cf_concepts.svg cfdm_coordinate_reference.svg cfdm_coordinates.svg cfdm_field.svg
+MAIN_DOC_IMG_BLD += order_horizontal_bounds__1D_coord_variables.png order_horizontal_bounds__2D_coord_variables.png
+
+MAIN_DOC_IMG += $(MAIN_DOC_IMG_BLD)
+
+MAIN_DOC_IMG := $(addprefix images/, $(MAIN_DOC_IMG))
+
+CONF_DOC := conformance
+
+CONF_DOC_BUILD_DIR := conformance_build
+
+CONF_DOC_INC := conformance.adoc version.adoc
+
+ifdef CF_FINAL
+DATE_FORMAT := +%d&\#160;%B,&\#160;%Y
+FINAL_TAG := -a final
+else
+DATE_FORMAT ?= +%d&\#160;%B,&\#160;%Y&\#160;%H:%M:%SZ
+FINAL_TAG ?= -a draft
+endif
+
+DATE_DOCPROD != LC_ALL=C date -u "$(DATE_FORMAT)"
+
+.PHONY: all clean images html pdf conventions-html conventions-pdf conventions conformance-html conformance-pdf conformance
+all: images html pdf 
+images: $(addprefix images/, $(MAIN_DOC_IMG_BLD)) 
+
+conventions-html: $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html
+conventions-pdf: $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).pdf
+conventions: conventions-html conventions-pdf
+
+conformance-html: $(CONF_DOC_BUILD_DIR)/$(CONF_DOC).html
+conformance-pdf: $(CONF_DOC_BUILD_DIR)/$(CONF_DOC).pdf
+conformance: conformance-html conformance-pdf
+
+html: conventions-html conformance-html
+pdf: conventions-pdf conformance-pdf
+
+$(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html: $(MAIN_DOC).adoc $(MAIN_DOC_INC) $(MAIN_DOC_IMG) | $(MAIN_DOC_BUILD_DIR)
+	asciidoctor --verbose --trace -a data-uri -a docprodtime="$(DATE_DOCPROD)" ${FINAL_TAG} $(MAIN_DOC).adoc -D $(MAIN_DOC_BUILD_DIR)
+	sed -E -i 's+(See&#160;)(https://cfconventions.org)(&#160;for&#160;further&#160;information.)+\1<a href="\2" target="_blank">\2</a>\3+' $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html
+
+$(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).pdf: $(MAIN_DOC).adoc $(MAIN_DOC_INC) $(MAIN_DOC_IMG) | $(MAIN_DOC_BUILD_DIR)
+	asciidoctor-pdf --verbose --trace -a docprodtime="$(DATE_DOCPROD)" ${FINAL_TAG} -d book -a pdf-theme=default-theme-CF-version.yml $(MAIN_DOC).adoc -D $(MAIN_DOC_BUILD_DIR)
+
+$(CONF_DOC_BUILD_DIR)/$(CONF_DOC).html: $(CONF_DOC_INC) | $(CONF_DOC_BUILD_DIR)
+	asciidoctor --verbose --trace ${FINAL_TAG} $(CONF_DOC).adoc -D $(CONF_DOC_BUILD_DIR)
+
+$(CONF_DOC_BUILD_DIR)/$(CONF_DOC).pdf: $(CONF_DOC_INC) | $(CONF_DOC_BUILD_DIR)
+	asciidoctor-pdf --verbose --trace ${FINAL_TAG} -d book $(CONF_DOC).adoc -D $(CONF_DOC_BUILD_DIR)
+
+$(MAIN_DOC_BUILD_DIR):
+	mkdir -vp $(MAIN_DOC_BUILD_DIR)
+
+$(CONF_DOC_BUILD_DIR):
+	mkdir -vp $(CONF_DOC_BUILD_DIR)
+
+clean:
+	rm -rvf $(MAIN_DOC_BUILD_DIR)
+	rm -rvf $(CONF_DOC_BUILD_DIR)
+
+#Rules to build non-static images. See MAIN_DOC_IMG_BLD above
+images/cfdm_cf_concepts.svg: images/cfdm_cf_concepts.gv
+	dot -Tsvg $< -o $@
+
+images/cfdm_coordinate_reference.svg: images/cfdm_coordinate_reference.gv
+	dot -Tsvg $< -o $@
+
+images/cfdm_coordinates.svg: images/cfdm_coordinates.gv
+	dot -Tsvg $< -o $@
+
+images/cfdm_field.svg: images/cfdm_field.gv
+	dot -Tsvg $< -o $@
+
+images/order_horizontal_bounds__1D_coord_variables.png: images/order_horizontal_bounds__1D_coord_variables.pdf
+	pdftoppm -progress -singlefile -r 300 -png $< $(basename $@)
+
+images/order_horizontal_bounds__2D_coord_variables.png: images/order_horizontal_bounds__2D_coord_variables.pdf
+	pdftoppm -progress -singlefile -r 300 -png $< $(basename $@)

README.md

@@ -16,10 +16,33 @@ Their implementation in GitHub is described in this repository's [CONTRIBUTING.m
 
 To convert the AsciiDoc files into the resulting HTML file:
 
-1. Ensure you have [Ruby](https://www.ruby-lang.org/) installed (e.g. `sudo apt-get install ruby`)
-2. Ensure you have a recent version of [Asciidoctor](https://asciidoctor.org/) installed (e.g. `gem install asciidoctor`)
-3. Get hold of the AsciiDoc files in this repo (e.g. `git clone git@github.com:cf-metadata/cf-conventions.git`)
-4. Build the HTML: `asciidoctor cf-conventions.adoc`
+1. Ensure you have [Ruby](https://www.ruby-lang.org/) installed (e.g. `sudo apt install ruby`)
+1. Ensure you have a recent version of [Asciidoctor](https://asciidoctor.org/) installed (e.g. `gem install asciidoctor`)
+1. Ensure you have [Make](https://www.gnu.org/software/make/) installed (e.g. `sudo apt install make`)
+1. Get hold of the AsciiDoc files in this repo (e.g. `git clone git@github.com:cf-convention/cf-conventions.git`)
+1. Therare different options to make the conventions and conformance documents:
+   - (All, the default) HTML and PDF conventions and conformance documents: 
+      `make` or `make all`
+   - HTML conventions and conformance documents: 
+      `make html`
+   - PDF conventions and conformance documents: 
+      `make pdf`
+   - Conventions documents (HTML and PDF): 
+      `make conventions`
+   - Conformance documents (HTML and PDF): 
+      `make conformance`
+   - Delete documents and build directories:
+      `make clean`
+   - Build with FINAL tag and date stamp (remember to update version in `version.adoc` file ):
+      `make CF_FINAL=True`
+
+Both HTML documents are build with images embeded into the `.html` file.
+
+The build documents will be rendered into local paths:
+  - `conventions_build/cf-conventions.html`
+  - `conventions_build/cf-conventions.pdf`
+  - `conformance_build/conformance.html`
+  - `conformance_build/conformance.pdf`
 
 See the [GitHub help](https://help.github.com/) pages and plethora of other git/GitHub guides for more details on how to work with repos, forks, pull requests, etc.
 

appd.adoc

@@ -361,7 +361,7 @@ No `standard_name` has been defined for `z1`, `z2`, `a`, `href` or `k_c`.
 // and put the table 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::NFFFFFF-1.0.png[caption=""]
+image::images/NFFFFFF-1.0.png[caption=""]
 
 [options="header",cols="1,3,2,3",caption="Table D.1. "]
 |===============

ch07.adoc

@@ -328,7 +328,7 @@ The horizontal coordinate variables to which "**`area`**" refers are in this cas
 [[recording-spacing-original-data]]
 ==== Recording the spacing of the original data and other information
 
-To indicate more precisely how the cell method was applied, extra information may be included in parentheses () after the identification of the method.
+To indicate more precisely how the cell method was applied, extra information may be included in parentheses **`( )`** at the end of the word list describing the method, after the operation and any **`where`**, **`over`** and **`within`** phrases.
 This information includes standardized and non-standardized parts.
 Currently the only standardized information is to provide the typical interval between the original data values to which the method was applied, in the situation where the present data values are statistically representative of original data values which had a finer spacing.
 The syntax is (**`interval`**: __value unit__), where __value__ is a numerical value and __unit__ is a string that can be recognized by UNIDATA's UDUNITS package <<UDUNITS>>.

history.adoc

@@ -10,7 +10,7 @@
 * {issues}542{Issue #542}: Clarify and rearrange text of section 4.4 about time coordinate units and calendars; introduce new text and a diagram explaining leap-seconds in existing calendars; define leap_second keyword of units_metadata attribute; define utc and tai calendars; define "date/time" in section 1.3.
 * {issues}166{Issue #166}: Clarify that time coordinate variables must have **`units`** containing **`since`** and a reference time; distinguish between canonical units of time with and without **`since`**.
 * {issues}403[Issue #403]: Metadata to encode quantization properties
-* {issues}530{Issue #530]: Define "the most rapidly varying dimension", and use this phrase consistently with the clarification "(the last dimension in CDL order)".
+* {issues}530[Issue #530]: Define "the most rapidly varying dimension", and use this phrase consistently with the clarification "(the last dimension in CDL order)".
 * {issues}163[Issue #163]: Provide a convention for boundary variables for grids whose cells do not all have the same number of sides.
 * {issues}174[Issue #174]: A one-dimensional string-valued variable must not have the same name as its dimension, in order to avoid its being mistaken for a coordinate variable.
 * {issues}237[Issue #237]: Clarify that the character set given in section 2.3 for variable, dimension, attribute and group names is a recommendation, not a requirement.
@@ -24,7 +24,7 @@
 === Version 1.11 (05 December 2023)
 
 * {issues}481[Issue #481]: Introduce **`units_metadata`** attribute and clarify some other aspects of **`units`**
-* {issues}458[Issue #147]: Clarify the use of compressed dimensions in related variables
+* {issues}458[Issue #458]: Clarify the use of compressed dimensions in related variables
 * {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