Quickstart Guide for Metanorma-CSD

Start using Metanorma-CSD to author CalConnect docs in these steps:

  1. Get Metanorma running on your machine

  2. Fetch and compile an example Metanorma-CSD document

  3. Modify the document to fit your goals while keeping it valid AsciiCSD

This guide assumes proficiency with the terminal, and uses the Docker option of running Metanorma (there’re other options of installing Metanorma, too).

Get Metanorma running on your machine

Assuming you have Docker installed, it’s as easy as:

docker pull ribose/metanorma

Fetch and compile an example Metanorma-CSD document

We’re going to use the vCard Format Specification sample document here. Clone the Metanorma-CSD repository and change into the directory with the example:

git clone https://github.com/metanorma/metanorma-csd.git
cd /spec/examples/

To compile the document, run the Docker container as follows:

docker run -v "$(pwd)":/metanorma/ -w /metanorma ribose/metanorma "metanorma -t csd -x xml,html,pdf,doc rfc6350.adoc"
Note
If you use Metanorma-CLI instead of Docker, see how to use the metanorma executable to compile documnts.

Write valid AsciiCSD

A Metanorma-CSD is a file in AsciiDoc format with certain extensions specific to Metanorma as a whole and Metanorma-CSD in particular. (We call the format AsciiCSD for short.)

AsciiDoc basics

Note
Skip this section if you’re already familiar with AsciiDoc syntax.

Inline formatting

*bold emphasis*, _italic emphasis_, `monospace / code snippet`
"`Typographic double quotes`", '`typographic single quotes`'
Subscript: H~2~O; superscript: E=mc^2^

Sections, anchors and references

== Section 1

Content (see <<anchor>>)

== Section 2

=== Section 2.1

[[anchor]]
==== Section 2.2

Content 2.2. http://www.calconnect.org/[CalConnect]

Lists and blocks

* Unordered list item 1
* Unordered list item 2

. Ordered list item 1
. Ordered list item 2

Definition list:

stem:[w]:: is the mass fraction of grains with defects in the test sample;
stem:[m_D]:: is the mass, in grams, of grains with that defect;
mag:: is the mass, in grams, of the aggregated test sample.

Tables, figures, footnotes

A rather complex table:

[[tableD-1]]
[cols="<,^,^,^,^",headerrows=2]
.Repeatability and reproducibility of husked rice yield
|===
.2+| Description 4+| Rice sample
| Arborio | Drago footnote:[Parboiled rice.] | Balilla | Thaibonnet

| Number of laboratories retained after eliminating outliers | 13 | 11 | 13 | 13
| Mean value, g/100 g | 81,2 | 82,0 | 81,8 | 77,7
|===

Images (figures) and footnotes:

[[figureC-1]]
.Typical gelatinization curve
image::images/rice_image2.png[]
footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]

Admonition blocks, quotes & code listings

Admonitions (notes, warnings, cautions, etc.) and examples:

NOTE: It is unnecessary to compare rice yield across years.

[example]
5 + 3 = 8

Block quotes:

[quote,ISO,"ISO7301,clause 1"]
_____
This Standard gives the minimum specifications for rice (_Oryza sativa_ L.)
_____

Source code:

[source,some-lang]
------
function () -> {}
------

Extensions to AsciiDoc

Document header & custom AsciiDoc attributes

:docnumber:: CalConnect document number, as allocated by TCC.

:status:: The status of the document can be one of:

  • proposal

  • working-draft

  • committee-draft

  • draft-standard

  • final-draft

  • published

  • withdrawn

:doctype:: The type of the document can be one of:

  • standard

  • directive

  • guide

  • specification

  • report

  • amendment

  • technical-corrigendum

:technical-committee:, :technical-committee_N: (where N is a positive integer): Technical committee; there can be more than one.

:draft:: Enables comments in Word and XML.

:local-cache-only:: Used with Metanorma under Docker to ensure bibliographic entries do not get unnecessarily fetched all the time.

Foreword & Introduction

Foreword must be put before the first real section/clause (the == one).

[[foreword]]
.Foreword
The Calendaring and Scheduling Consortium ("`CalConnect`") is global non-profit
organization with the aim to facilitate interoperability of technologies across
user-centric systems and applications...

Introduction comes after Foreword and is unnumbered (actually “0”):

[[introduction]]
:sectnums!:     <== disables display of section number
== Introduction

<<ISO8601>> has been the international standard for date and time representations
and is applied widely, including in the <<RFC5545>> and <<RFC6350>> standards
...

:sectnums:      <== re-enables display of section number
Note
Some ISO standards display Introduction section numbers (the “0”) if there are too many sub-sections.

Normative references & bibliography

What is a normative vs informative reference?

  • A change to a normative reference requires updating of the document;

  • A change to an informative reference should not trigger a change in the document.

Clause 2 must be this:

[bibliography]
== Normative references

* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Test methods_

Last section must be this:

[bibliography]
== Bibliography

* [[[ISO5609,ISO 5609]]], _Soil for laboratory analysis -- Test methods_
Note
the Bibliography is identical in usage with the IETF RFC section “Informative references”.

Citations

In a CSD you often want to cite external or internal references.

Internal:

[[dog-food]]
== Dog food

Dogs love food, not only bones. Mine especially loves eating Oreo's.

== Living with your dog

My dog, Cookie, loves to eat cookies (see <<dog-food>>).

External (remember to add the reference!):

The quality requirements on wheat are described in <<ISO7301>>.

In particular, those for bread wheat (T. aestivum) are given in
<<ISO7301,clause=5.6>>.

Terms and definitions

This must be clause 3.

[[tda]]                      <= anchor if you want it
[source=ISO8601-1]           <= allows inheriting terms and definitions from
another document
== Terms, definitions, symbols and abbreviations   <= can combine T&D and S&A

=== Terms and definitions    <= the real T&D clause

[[term-explicit]]            <= anchor if you want it
==== explicit form           <= term item

date and time representation that uses designator symbols to delimit
time scale components

Term entry in T&D

The structure is strict; the following illustrates the complete structure of a term entry.

In the term source ([.source]), all content after the reference and the “comma” is about “modifications” to the original definition.

[[paddy]]                  <= anchor
=== paddy                  <= term
alt:[paddy rice]           <= alternative term
alt:[rough rice]           <= second alternative
deprecated:[cargo rice]    <= deprecated term
domain:[rice]              <= domain

rice retaining its husk after threshing  <= definition

[example]              <= example
Foreign seeds, husks, bran, sand, dust.

NOTE: The starch of waxy rice consists almost entirely of amylopectin. <= note

[.source]
<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated, <= source
and Note 1 to entry is not included here.

Term entry sourced from IEC Electropedia (IEV)

In the [.source], a termbase such as the IEC Electropedia (“IEV”) can be used, such as:

[.source]
<<IEV,clause "113-01-01">>, the term "space-time" is further explained
in a new Note 2 to entry.

References to the specific IEC 60500 documents (where IEV terms came from) are automatically added to the Bibliography.

Annex

Annexes have to be placed before the “Bibliography”.

[[AnnexA]]
[appendix,subtype=informative]
== Example date and time expressions, and representations
...