Revise section 4, include new subsection on leap seconds, define utc and tai calendars and leap_seconds in units_metadata

.github/workflows/adoc_build.yml

@@ -18,24 +18,41 @@
 #   https://github.com/Analog-inc/asciidoctor-action
 #   https://github.com/actions/upload-artifact
 #   https://github.com/actions/download-artifact
+#   https://github.com/action-badges/create-orphan-branch
 #
+#   Custom workflow for pages deployment
+#     
 name: Asciidoctor Build Workflow
 on:
   # manually run workflow
   workflow_dispatch:
-  # trigger on PR event against main (will not run publish job)
+
+  # trigger on PR event against default branch (i.e. main) (will not run publish job)
   pull_request:
     branches: [ main ]
-  # Trigger on a push to main (a PR is merged), or when a release is
+  # Trigger on a push to default branch (i.e. main) (a PR is merged), or when a release is
+
   # published on github. These will run the publish job.
   push:
-    branches:
-      - main
+    branches: [ main ]
   # Trigger when a GitHub release is published.
   release:
     types:
       - published
-jobs:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs: 
   # Job to build cf-conventions.html, cf-conventions.pdf
   build_conventions_and_conformance:
     name: Build cf-conventions and conformance html and pdf
@@ -75,12 +92,35 @@ jobs:
     if: github.event_name != 'pull_request'
     # Wait for the build artifacts to become available
     needs: [build_conventions_and_conformance]
+
+#    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+#    permissions:
+#      pages: write      # to deploy to Pages
+#      id-token: write   # to verify the deployment originates from an appropriate source
+
+#    # Deploy to the github-pages environment
+#    environment:
+#      name: github-pages
+#      url: ${{ steps.deployment.outputs.page_url }}
+
     runs-on: ubuntu-latest
     steps:
+      # Checkout repo
+      - uses: actions/checkout@v4
+      # create a new orphan branch if a branch with the given name does not already exist
+      - name: Create Orphan Branch
+        uses: action-badges/[email protected]
+        with:
+          branch-name: 'gh-pages'
       # Checkout gh-pages branch
       - uses: actions/checkout@v4
         with:
           ref: 'gh-pages'
+      - name: Add .nojekyll file if it doesn't exist
+        run: |
+          if [ ! -f .nojekyll ]; then
+            touch .nojekyll
+          fi
       # Will new docs go into root, or into a directory named after the
       # release?
       - name: Determine where the new documents should live
@@ -102,10 +142,10 @@ jobs:
         if: github.event_name == 'release'
         run: mkdir -p ${{ env.TARGET_DIR }}
       # If we are not doing a release, let's clean out the previous images
-      # directory in the root directory
+      # directory in the root directory (OLD TO BE DEPRECATED)
       - name: Remove old images directory
         if: github.event_name != 'release'
-        run: rm -rf ${{ env.TARGET_DIR }}/images
+        run: sudo rm -rf ${{ env.TARGET_DIR }}/images
       - name: Copy conventions and conformance documents
         run: |
           cp -p build/cf-conventions.html ${{ env.TARGET_DIR }}/

.gitignore

@@ -8,4 +8,5 @@ conventions_build/
 conformance.html
 conformance.pdf
 conformance_build/
+build/
 .vscode/

appa.adoc

@@ -386,8 +386,8 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 | **`units_metadata`**
 | S
 | C, D, BI
-| <<units>>
-| Specifies the interpretation (on-scale, difference or unknown) of the unit of temperature appearing in the **`units`** attribute.
+| <<units>>, and <<time-coordinate>>
+| Specifies the interpretation of a unit of measure appearing in the **`units`** attribute.
 
 | **`valid_max`**
 | N

ch01.adoc

@@ -71,6 +71,8 @@ The netCDF utilities ncdump and ncgen use this format (see
 link:$$https://docs.unidata.ucar.edu/nug/current/_c_d_l.html$$[NUG section on CDL syntax]).
 All examples in this document use CDL syntax.
 
+calendar:: A CF calendar defines an ordered set of valid datetimes with integer seconds.
+
 cell:: A region in one or more dimensions whose boundary can be described by a set of vertices.
 The term __interval__ is sometimes used for one-dimensional cells.
 
@@ -81,6 +83,8 @@ The coordinate values must be in strict monotonic order (all values are differen
 Missing values are not allowed in coordinate variables.
 To avoid confusion with coordinate variables, CF does not permit a one-dimensional string-valued variable to have the same name as its dimension.
 
+datetime:: The set of numbers which together identify an instant of time, namely its year, month, day, hour, minute and second, where the second may have a fraction but the others are all integer.
+
 grid mapping variable:: A variable used as a container for attributes that define a specific grid mapping.
 The type of the variable is arbitrary since it contains no data.
 

ch02.adoc

@@ -182,7 +182,7 @@ If it is observational, **`source`** should characterize it (e.g., "**`surface o
 
 **`history`**:: Provides an audit trail for modifications to the original data.
 Well-behaved generic netCDF filters will automatically append their name and the parameters with which they were invoked to the global history attribute of an input netCDF file.
-We recommend that each line begin with a timestamp indicating the date and time of day that the program was executed.
+We recommend that each line begin by indicating the date and time of day that the program was executed.
 
 **`references`**:: Published or web-based references that describe the data or methods used to produce it.
 

ch03.adoc

@@ -165,6 +165,12 @@ A standard name contains no whitespace and is case sensitive.
 canonical units:: Representative units of the physical quantity.
 Unless it is dimensionless, a variable with a **`standard_name`** attribute must have units which are physically equivalent (not necessarily identical) to the canonical units, possibly modified by an operation specified by the standard name modifier (see below and <<standard-name-modifiers>>) or by the **`cell_methods`** attribute (see <<cell-methods>> and <<appendix-cell-methods>>) or both.
 
+Units of time coordinates (<<time-coordinate>>), whose **`units`** attribute includes the word **`since`**, are _not_ physically equivalent to time units that do not include **`since`** in the **`units`**.
+To mark this distinction, the canonical unit given for quantities used for time coordinates is **`s since 1958-1-1`**.
+The reference datetime in the canonical unit (the beginning of the day i.e. midnight on 1st January 1958 at 0 `degrees_east`) is not restrictive; the time coordinate variable's own **`units`** may contain any reference datetime (after **`since`**) that is valid in its calendar.
+(We use `1958-1-1` because it is the beginning of International Atomic Time, and a valid datetime in all CF calendars; see also <<leap-seconds>>.)
+In both kinds of time **`units`** attribute (with or without **`since`**), any unit for measuring time can be used i.e. any unit which is physically equivalent to the SI base unit of time, namely the second.
+
 description:: The description is meant to clarify the qualifiers of the fundamental quantities such as which surface a quantity is defined on or what the flux sign conventions are.
 We don't attempt to provide precise definitions of fundumental physical quantities (e.g., temperature) which may be found in the literature.
 The description may define rules on the variable type, attributes and coordinates which must be complied with by any variable carrying that standard name (such as in Example 3.5).