diff --git a/.github/workflows/adoc_build.yml b/.github/workflows/adoc_build.yml
index b1273f77..d5da2f5c 100644
--- a/.github/workflows/adoc_build.yml
+++ b/.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 )(https://cfconventions.org)( for further information.)+\1\2\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 }}/
diff --git a/.gitignore b/.gitignore
index d73bd9c4..662b639a 100644
--- a/.gitignore
+++ b/.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/
diff --git a/.zenodo.json b/.zenodo.json
index 8d872605..8d88ed27 100644
--- a/.zenodo.json
+++ b/.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"},
diff --git a/Makefile b/Makefile
new file mode 100644
index 00000000..9668e68e
--- /dev/null
+++ b/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 )(https://cfconventions.org)( for further information.)+\1\2\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 $@)
diff --git a/README.md b/README.md
index 317c097b..3c59b693 100644
--- a/README.md
+++ b/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.
diff --git a/appd.adoc b/appd.adoc
index 7ee97d74..e1d6beb9 100644
--- a/appd.adoc
+++ b/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. "]
|===============
diff --git a/NFFFFFF-1.0.png b/images/NFFFFFF-1.0.png
similarity index 100%
rename from NFFFFFF-1.0.png
rename to images/NFFFFFF-1.0.png