= Quickstart Guide for Metanorma-CSD

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

. Get Metanorma running on your machine
. Fetch and compile an example Metanorma-CSD document
. 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
https://www.metanorma.com/overview/getting-started/[options of installing Metanorma],
too).


== Get Metanorma running on your machine

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

[source,console]
--
docker pull metanorma/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:

[source,console]
--
git clone https://github.com/metanorma/metanorma-csd.git
cd /spec/examples/
--

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

[source,console]
--
docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma -t csd -x xml,html,pdf,doc rfc6350.adoc
--

NOTE: If you use Metanorma-CLI instead of Docker,
http://metanorma.com:4001/software/metanorma-cli/docs/usage/[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

[source,asciidoc]
--
*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

[source,asciidoc]
--
== 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

[source,asciidoc]
--
* 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:

[source,adoc]
----
[[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:

[source,adoc]
----
[[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:

[source,adoc]
----
NOTE: It is unnecessary to compare rice yield across years.

[example]
5 + 3 = 8
----

Block quotes:

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

Source code:

[source,adoc]
----
[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:
[source,adoc]
----
[[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!):

[source,adoc]
----
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.

[source,adoc]
----
[[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.

[source,adoc]
----
[[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,adoc]
----
[.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`".

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


== Where next?

* https://www.metanorma.com/overview/[Learn more about Metanorma]