CalConnect Standards Registry

Introduction

The CalConnect Standards Registry is used to publish CalConnect deliverables, including its Standards and other public documents.

This repository provides all necessary information for the https://standards.calconnect.org site.

The site is managed by TC PUBLISH.

Sites

Site	Git branch	URL
Production	master	https://standards.calconnect.org

All sites are automatically deployed from their respective branches.

Building the index

# removes all generated CSD files
make distclean

# makes everything except _site
# (if we're using `make serve`, we don't need to pre-build)
make all

# generates all required files for Jekyll and runs `jekyll build`
make _site

Structure

General

Run the following command to update the list of CC documents in the site:

make repopulate-metanorma-yamls

# Behind the scene,

DOC_TYPE=standard \
DOC_CLASS=cc \
  scripts/repopulate-metanorma-yaml src-documents  metanorma-standard.yml

DOC_TYPE=administrative \
DOC_CLASS=cc \
  scripts/repopulate-metanorma-yaml src-documents  metanorma-administrative.yml

# ... and so on, for other doc types, if any

Note	Relaton is a bibliographic model developed for ISO 690, the International Standard for citations. Relaton currently supports Relaton-XML (.xml or .rxl) and Relaton-YAML (.yaml) formats. More details about Relaton can be found here.

These are entries that are either:

• managed outside of this repository (i.e. they are not generated using information provided in this repository)

• does not provide a public draft (in CSD XML) but would like the entry to be displayed in this site.

Note	The filename prefix of external indicates that the actual documents are managed outside of this repository (i.e. they are not generated using information provided in this repository).

The basic structure of _input/%.yaml is in a format called “Relaton-YAML”, and looks like this.

root:
  author: CalConnect
  title: CalConnect Standards Registry
  items:
    - technical_committee: PUBLISH
      docidentifier: "CC/NP 36000"
      doctype: standard
      title: Standardization documents -- Vocabulary
      stage: proposal
      revdate: 2018-10-25
    - technical_committee: DATETIME
      ...

The _input/%.yaml file specifies a “bibliographic group” using a Relaton Collection. This YAML file represents a collection of bibliographic entries.

• Each bibliographic entry is placed under the items key.

• Each bibliographic entry can have the following attributes:

  • technical_committee: {TCNAME}: is the name of the TC that owns this work item. Please exclude the prefix “TC” in there as it will be automatically generated. e.g. DATETIME for TC DATETIME will suffice. It has a data type of “string”.

  • docidentifier: "{prefix} {doc-number}" provides the full document identifier, including the prefix, stage codes, and the document number of the work item. You may also specify the edition year suffix, such as, “:2019” at the end. e.g. CC/DIR/FDS 10001:2019. It has a data type of “string”.

  • doctype: article provides the document type of the document. These currently include directive, standard, guide, specification, report, amendment, technical-corrigendum, administrative, and advisory. Please refer to CC/DIR 10001 for document types of CalConnect Standardization deliverables. It has a data type of “string”.

  • title: {title} is the document title. If there are funny characters in it (it shouldn’t), remember to double quote the string. It has a data type of “string”.

  • stage: {stage} is the string representation of the stage identifier. This attribute accepts the following stage codes proposal, working-draft, committee-draft, draft-standard, final-draft, withdrawn, cancelled. It has a data type of “string”.

  • revdate: 2018-10-25 is the date when the document was last updated. It is optional and accepts the ISO 8601-1 date format. A full date-time could be provided, but the “time” is not rendered in the index. It has a data type of “date”.

The _input/%.yaml document is read. The relaton yaml2xml command from the relaton-cli gem does the following:

• splits off each entry into its own Relaton XML file in a specified directory (bib/*.rxl)

• converts the Relaton YAML collection into a Relaton XML collection called _input/%.rxl

Sorting of entries

Sorting of the entries is by reverse sort order of the revdate attribute of documents.

Rendering of HTML

Jekyll is used to compile the HTML site, and metanorma-cli is used to compile CC documents via Metanorma YAML files.

In particular, our Makefile builds a new directory _documents from the data from bib/, as a Jekyll collection:

• The Jekyll collection, called documents, is used in the following pages:

  • _pages/public-review.adoc

• In _config.yml, it specifies that the document collection uses the layout document which allows rendering a separate page per document.

Usage

Install

You will need to have Ruby 3.3+ installed.

make update-init
make prep

How to add/remove entries?

• Bibliographic entry: add an entry in _input/external.yaml under the items: key.

• CSD document entry: add your CSD XML file to the document-register repo (push it), and update the submodule _input/csd here. It can be done here as easy as make update-modules:

pushd ~/standards.calconnect.org
make update-modules
git add src-documents
git commit -m 'chore: Update to use latest CC documents'
git push

On the next run of make clean _site you will see your entry added to the site.

Deployment

Please push all changes to the staging branch, and changes will be automatically deployed and reflected on the staging site.

If your changes are to be made public to the production site, please contact TC PUBLISH.