Metanorma tutorial (complete)

Learning objectives for the tutorials

Before we dive into using the Metanorma toolchain, let's cover the basic ideas you need to understand to work with Metanorma. In this lesson we will cover:

• What Metanorma is
• The differences between Word and Metanorma
• The paradigms "What you see is what you get" vs. "What you see is what you mean"
• What the Metanorma workflow looks like from document creation to publication

Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. In this lesson, we will discuss what AsciiDoc is and what a typical Metanorma document looks like. You will also learn how to write AsciiDoc.

Reviewing documents is an integral part of developing a standard. The best way to review a document, is to use a version control environment that supports comments as well, such as GitHub and its feature GitHub discussions. In case your organization does not use a git-based approach, Metanorma provides a comment functionality that lets you insert your remarks and create to dos. In this lesson, you will learn:

• How to add comments using AsciiDoc markup
• How to generate a draft using the command line.

Once you are happy with your document, the next step is to generate an output to send your SDO for publishing. Since Metanorma poses some validity criteria for your document, it is normal to face some errors. Don't worry, we will go through some common errors and teach you how to resolve them. In this lesson you will learn:

• How to generate PDF, HTML, and Word output using the command line
• How to troubleshoot common errors

What you get is what you see vs. What you get is what you mean

Is what you see what you get?

Word is probably your go-to application for casual writing, such as letters, invitations - and with good reason, because Word has many benefits, such as:

• Creating Documents quickly
• An intuitive interface
• Printer prints exactly what you see on your screen = What you see is what you get (WYSIWYG)

However, have you ever written a longer text, with many references, like a scientific text? Then you might have experienced some pain with Word: It tends to mess up the formatting, even if you use templates. Reference management in Word is also no fun, but the worst: Word tends to crash for very long documents, like standards.

Because of these issues, another approach to creating documents is popular: "What you see is what you mean" (WYSIWYM). This concept differs from WYSIWYG because you separate the content and the layout into separate files. To tell the compiler how the text should look or behave, you use markup language. You may have heard about Markdown or LaTeX, which are popular markup languages, but Metanorma uses AsciiDoc.

The benefit is that you can publish different outputs from one source, for example into PDF or HTML. Since the layout is stored in a separate file, each output can even be styled differently.

What is Metanorma?

What is Metanorma?

Metanorma is three things in one:

Software

The Metanorma toolchain is the software that you use to create documents and generate output.

Document metamodels

Metanorma provides a document structure for standardization documents, specified in ISO 36001. Since each organization has different requirements for their standard documents, they use a "flavor" of Metanorma. A flavor is a document model that provides additional metadata to reflect the SDO's needs.

XML schemas

To use the defined document metamodels, there needs to be a machine-readable file so that documents can be checked against their intended structure.

Metanorma consists of several layers of complexity, see the figure below.

The basis for each metanorma document is AsciiDoc. Since AsciiDoc itself has limited functionalities for authoring standards, Metanorma extends AsciiDoc as one part of the Metanorma toolchain (1). Metanorma AsciiDoc provides advanced features, such as automatically linking the correct standard in a bibliography section.

The final layer of complexity are flavour-specific document rules and best practices based on the document metamodels (2). For example, ISO documents must include a "Scope" section, whereas NIST requires an "Acknowledgements" section.

Metanorma has many advantages for authoring standards:

• Metanorma supports the needs of many standardization organizations, such as ISO, IETF, and many more.
• Metanorma can be extended with new document models (flavors).
• It uses the "what you see is what you mean" (WYSIWYM) approach based on AsciiDoc.
• You can style your content differently, depending on the output.
• The document models ensure complete and consistent standard documents that follow the rules of your organization.
• Metanorma can create long and complex documents without them becoming corrupted.
• Metanorma enables dynamic integration of external data into documents.

Let's explore the workflow of Metanorma in the next lesson.

>> Start next lesson

Document creation

You can create a new standard document either by:

• Creating a new, empty AsciiDoc file
• Using a template
• Importing a Word Document

*New file*

The easiest way is to create a document from scratch, by creating an empty AsciiDoc file (.adoc) in the desired folder.

*Templates*

Templates get you started faster, as they provide the structure of a standard document already. If your organization provides templates, you can create a new document based on a template using the command line.

*Import from Word*

Importing from Word makes sense if you are moving from Word to Metanorma and need to move several, large documents. To facilitate the migration, you can use the import tool called Reverse AsciiDoc. However, the imports are not always perfect, so you need to be familiar with the Metanorma and know how to resolve error messages. If you new to Metanorma, the simplest way is to transfer your content into Metanorma AsciiDoc manually.

Editing the document

You can edit Metanorma documents in any plain-text editor because they only consist of text. The next lesson will introduce you to the basics of AsciiDoc. These editors have been reported to work well for writing Metanorma AsciiDoc:

• Atom with Asciidoctor plugins
• Microsoft Visual Studio Code with AsciiDoc extension for live preview

Validation

Before you can generate any output, the Metanorma document needs to be checked against the document model to ensure it follows the rules of your SDO.

Since the document model is defined in an XML schema, the compiler converts the Metanorma document into a Metanorma XML file. This XML file is then checked against the SDO's XML schema. Metanorma will log all deviations from the SDO's structure or formatting on the terminal and into an error file.

❌ Invalid XML

The XML file does not comply with the XML schema, or with the formatting rules defined by the SDO.

All errors are logged to the terminal and are saved to an error file (.err.html). Often the document will render successful despite errors, but the error messages point out potential issues with the document structure.

✅ Valid XML

The XML file complies with the XML schema and the compiler can proceed to generate an output.

Output generation

Review

Standards documents require collaboration and every SDO has its own process for reviews. Metanorma does support authors and reviewers by providing metadata that indicate in which phase the document is in and who reviewed it. You can add your remarks to a document with comments or create a to-do if you want someone to act.

Publication

Once you and your reviewers agree that the standard is ready for publishing, you send it to your standard developing organization (SDO). The SDO will publish your document in their preferred channels, such as online or print.

For organizations using the Metanorma release pipeline, publishing is automated: pushing to main triggers compilation and creates a GitHub Release with the document files and metadata. See Organization-Scale Publishing Setup for details.

Summary

Let's recap what we've learned so far:

• Metanorma uses a what you see is what you mean (WYSIWYM) approach, meaning that the text you write is what you want to see.
• You need to render documents to have a correct visible output. The appearance is controlled in a stylesheet.
• Metanorma is an umbrella term for several things and consists of: The Metanorma toolchain, document models and a XML schema of these document models.
• Metanorma documents use Metanorma AsciiDoc markup
• When you want to generate an output, the AsciiDoc document is converted into XML in order to be checked against the XML schema.
• If the document is valid, Metanorma generates an HTML, PDF and Microsoft Word (.doc) output.

Now that we have covered the fundamentals, let's have a look at AsciiDoc.

>> Start next lesson

Learning objectives for the tutorials

Before we dive into using the Metanorma toolchain, let's cover the basic ideas you need to understand to work with Metanorma. In this lesson we will cover:

• What Metanorma is
• The differences between Word and Metanorma
• The paradigms "What you see is what you get" vs. "What you see is what you mean"
• What the Metanorma workflow looks like from document creation to publication

Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. In this lesson, we will discuss what AsciiDoc is and what a typical Metanorma document looks like. You will also learn how to write AsciiDoc.

Reviewing documents is an integral part of developing a standard. The best way to review a document, is to use a version control environment that supports comments as well, such as GitHub and its feature GitHub discussions. In case your organization does not use a git-based approach, Metanorma provides a comment functionality that lets you insert your remarks and create to dos. In this lesson, you will learn:

• How to add comments using AsciiDoc markup
• How to generate a draft using the command line.

Once you are happy with your document, the next step is to generate an output to send your SDO for publishing. Since Metanorma poses some validity criteria for your document, it is normal to face some errors. Don't worry, we will go through some common errors and teach you how to resolve them. In this lesson you will learn:

• How to generate PDF, HTML, and Word output using the command line
• How to troubleshoot common errors

Unsupported AsciiDoc features

While Metanorma mostly adds functionality to the AsciiDoc markup language, there are also some mechanisms, that Metanorma does not support:

• Sidebars (asides) are not supported. Instead, they are used for reviewer comments.
• Page breaks (thematic break) are only supported in select flavors.
• ASCII art/preformatted text (literal) are only supported in select flavors.

General

Information about a document itself is called the "metadata" of the document. The document header is where metadata is entered. Metadata is specified by using document attributes.

Document attributes are used in the following ways:

• provide semantic information for the document
• modify visual appearance of output format
• adjust the document generation process

You can specify metadata about:

• Authors: Issuing organization, authors, and their location
• Document information: Title, language, document stages (draft, published, etc.) copyright holder, etc.
• Identifiers: Document numbers, ISBNs, URIs
• Dates: Draft dates, revision dates, publishing date, copyright year, etc.

Some metadata influence how the document is generated and should only be used by advanced users. Often, they will require familiarity with the structures and processes of the flavor's organization.

A document attribute looks like this:

:title: My document
:novalid:

Document attributes can be used as simple flags like on/off switches, which do not take a value, but typically accept one or more values.

= Rice model <1>
:docnumber: 17301 <2>
:doctype: international-standard <3>
:copyright-year: 2021
:language: en
:mn-document-class: iso <4>
:technical-committee: Food products <5>
:mn-output-extensions: xml,html,doc,html_alt <6>

Which attributes to specify?

The attributes required or allowed to be specified for given document depend on the type of document and the Metanorma flavor used.

See generic attribute reference for attributes supported by most Metanorma flavors.

When using one of the officially supported Metanorma flavors, please consult your flavor's author documentation.

Re-using attributes in text

The body of the document can reference the values of document attributes. Here's an example of referencing committee-related metadata entries:

:technical-committee-number: 184
:technical-committee: Automation systems and integration
:subcommittee-number: 4
:subcommittee: Industrial data
...
This document was prepared by Technical Committee ISO/TC
{technical-committee-number}, _{technical-committee}_, Subcommittee SC
{subcommittee-number}, _{subcommittee}_.

If the corresponding document attributes are not populated in the header, then the references themselves will not be populated.

Dealing with Unicode characters

Document attribute values that contain Unicode characters must be entered directly as Unicode.

Any non-ASCII characters in document attribute values, or dashes for compound titles, will need to be entered as Unicode.

If you need to have non-ASCII characters in document title, or dashes for compound titles, you will need to enter them directly as Unicode.

Document attribute values, unlike document text, cannot deal with HTML entities.

As an example, this would work:

:title-part-en: Information Technology—Security
:title-main-fr: Spécification et méthodes d'essai

Entering them as HTML Entities or XML Entities would not:

:title-part-en: Information Technology\—Security
:title-main-fr: Sp\écification et m\éthodes d'essai

General

Sections define hierarchy levels in a document, as chapters do. In AsciiDoc, sections are encoded with titles prefixed by equal signs (=).

• The document title is considered the highest section in the hierarchy, and is created by prepending a = sign in front of the heading.
• Subsequent sections are encoded with titles prefixed with least two equal signs:
  • == indicates a first-level section;
  • === indicates a second-level section;
  • ==== indicates a third-level subsection;
  • and so on.

.Example of setting document and section titles

= Document title
== Section 1
=== Section 1.1
==== Section 1.1.1
===== Section 1.1.1.1
== Section 2
=== Section 2.1
...

Section types

Automatic type recognition

Metanorma automatically detects these standard section types when their titles match common patterns in any supported language:

• Abstract
• Foreword
• Introduction
• Acknowledgements
• Executive summary
• Scope
• Normative references
• Terms and definitions
• Symbols and abbreviated terms (or individual Symbols/Abbreviated terms sections)
• Bibliography
• metanorma-extension (special container section)

The content body, or annexes, are entered as normal sections without need for pre-defined titles.

Fixed section names are specific to either the preface of a document, or the main body; so for example an instance of "Introduction" the main body of the text will not be treated as part of the preface.

Note

The underlying document model behind all Metanorma flavors is called the StandardDocument model, also abbreviated as "StanDoc". The available section types available in StanDoc are reproduced in this section. StanDoc represents the harmonized common requirements of standardization documents, not the document model of a particular SDO.

Flavours may overrule these pre-defined section titles with titles of their own, or may choose not to recognise at least some of them as special sections.

Note

Each organization is based on the standard document model but they can omit sections or make them mandatory, if they choose to. For example, only NIST uses the acknowledgments section, whereas other SDOs do not require it. Flavours may overrule these pre-defined section titles with titles of their own, or may choose not to recognise at least some of them as special sections. Check the flavor documentation for more details on how your SDO uses Metanorma.

[type_attribute]
== Your Custom Title

= Document title
== Abstract
== Foreword
[preface] <1>
== Introduction to version 3 of this standard
[bibliography] <2>
== Normative references
[heading=terms and definitions] <3>
== Terms, definitions, and abbreviations
[bibliography]
== Bibliography
...
[appendix,obligation=informative] <4>
== Additional content
...

== General
[heading=scope]
=== Scope
[bibliography,heading=normative references]
=== Normative references
[heading=terms and definitions]
=== Terms and definitions

[heading=foreword]
== Fore Word

[heading=foreword,keeptitle=true]
== Fore Word

=== {blank}

=== Physical and chemical characteristics
==== {blank}
The mass fraction of moisture, determined in accordance with...

[%inline-header]
==== Sieve,
with round perforations of diameter 1,4 mm.

=== Proper title
[.variant-title,type=sub]
This is the variant title
Text of section.

=== Section 2.1
[discrete]
==== I am a floating title within section 2.1
==== Section 2.1.1

Sections deeper than 5 levels

Standards can contain many levels of embedding: ISO/IEC DIR 2 only considers it a problem if there are more than 7 levels of embedding.

To realise higher levels of embedding, prefix a 5-level section title with the attribute level=:

// Six equal signs for five levels
====== Clause 5A
[level=6]
====== Clause 6A
[level=7]
====== Clause 7A
[level=7]
====== Clause 7B
[level=6]
====== Clause 6B
====== Clause 5B

This generates the following ISO XML:

<clause id="_" inline-header="false" obligation="normative">
	<title>
		Clause 5
	</title>
	<clause id="_" inline-header="false" obligation="normative">
		<title>
			Clause 6
		</title>
		<clause id="_" inline-header="false" obligation="normative">
			<title>
				Clause 7A
			</title>
		</clause>
		<clause id="_" inline-header="false" obligation="normative">
			<title>
				Clause 7B
			</title>
		</clause>
	</clause>
	<clause id="_" inline-header="false" obligation="normative">
		<title>
			Clause 6B
		</title>
	</clause>
</clause>
<clause id="_" inline-header="false" obligation="normative">
	<title>
		Clause 5B
	</title>
</clause>

and the rendering would be something like

*1.1.1.1.1 Clause 5A*

*1.1.1.1.1.1 Clause 6A*

1.1.1.1.1.1.1 Clause 7A

1.1.1.1.1.1.2 Clause 7B

*1.1.1.1.1.2 Clause 6B*

1.1.1.1.2 Clause 5B

Lists

Metanorma AsciiDoc supports three types of lists:

• Unordered lists
• Ordered lists
• Definition lists

The main changes compared to the previous edition are:
* updated normative references;
* deletions:
** deletion of 4.3. [nested list item]
** deletion of 4.4. [nested list item]

. First Step
. Second Step
. Third Step

`term:: Definition`

stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
stem:[m_D]:: is the mass, in grams, of grains with that defect;
stem:[m_S]:: is the mass, in grams, of the test sample.

include::learn/exercises.adoc[tag=exercise-2-3-1]

Great work! Let's have a look at term definitions in the next lesson.

>> Start next lesson

Term definitions

If you want to cite a term throughout the standard, include it in the terms and definitions section. Term definitions vary from definition lists, as they are more granular and provide metadata to mark features such as alternative terms or deprecated terms. Let's have a look at a term entry:

== Terms and definitions <1>
=== husked rice <2>
deprecated:[cargo rice] <3>
Paddy from which the husk only has been removed. <4>
[.source] <5>
<<ISO7301,clause 3.2>>, The term "cargo rice" is shown as deprecated, and Note 1 to entry is not included here
=== milled rice
alt:[white rice] <6>
term:[husked rice] from which almost all of the bran and embryo have been removed by milling. <7>
=== extraneous matter
alt:[EM]
domain:[rice] <8>
organic and inorganic components other than whole or broken kernels
[example] <9>
Foreign seeds, husks, bran, sand, dust.

include::learn/exercises.adoc[tag=exercise-2-3-2]

The next type of block we will cover are tables.

>> Start next lesson

Tables

[cols="1,1"] <1>
.A table with a title <2>
|=== <3>
|Cell in column 1, header row |Cell in column 2, header row <4>
|Cell in column 1, row 2
|Cell in column 2, row 2 <5>
|=== <6>

[width=70%]
|===
| Vehicle | Passenger
| Mazda 3 | Bob
| Tesla Model Y | Alice
|===

[width=full-page-width]
|===
|A |B
|C |D
|===

[cols="1,1,1"]

|===
|Location |Distance
|Over there | 6
|===
[%key] <1>
{some-id}:: {some-description} <2>

|===
|Location       | Distance
|Over here      | s
|Over there     | m
|Way over there | l
|===
[%key]
stem:[s]:: Short distance
stem:[m]:: Medium distance
stem:[l]:: Far away

[%key]
Paragraph used instead of definition list

[%key]
--
Open block allowing multiple paragraphs and definition lists to be combined into a single key
a::b
c::d
Text may also follow after the definition list in a key
--

|===
|Location |Distance
|Over there | 6
|===
[NOTE,type=units]
Distance in kilometres

|===
|Location |Distance
|Over there | 6
|===
[NOTE,type=requirement]
The distance shall be verified independently
[NOTE]
"Over there" is to be understood as not over here

[headerrows=2]
|===
.2+|Sample 3+^| Value
| Test A | Test B | Test C
| Component 1 | Pass | Fail | Pass
|===

[css-style="background-color: yellow"]
|===
|A |B |C tr-style:[background-color: red]
h|1 td-style:[background-color: green] td-style:[color: blue]
|2 tr-style:[background-color: green]
|3
|4 |5 td-style:[background-color: green] | 6
|===

|===
|Test ID |Test Method |Result |Conformity tr-style:[background-color: #eeeeee]
|TC-001 |Method A |Pass td-style:[color: green] |Conforms
|TC-002 |Method B |Fail td-style:[color: red] |Does not conform
|TC-003 |Method A |Not tested td-style:[color: gray] |Incomplete
|===

|===
|Standard |Edition |Publication Date tr-style:[border-bottom: 2px solid black]
|ISO 8601 td-style:[border-right: 1px solid gray] |Third edition |2019-02
|ISO 19005-1 td-style:[border-right: 1px solid gray] |First edition |2005-10
|ISO/IEC 10646 td-style:[border-right: 1px solid gray] |Sixth edition |2020-05
|===

[alt=Table of tested components,summary=Table of components being tested in Tests A to C]
.2+|Sample 3+^| Value
| Test A | Test B | Test C
| Component 1 | Pass | Fail | Pass
|===

Complex table examples

Example table 1

Example of a more complex tableadoc

[headerrows=2,alt=Table of maximum mass fraction of defects in husked rice,summary=Table enumerating the permissible mass fraction of defects in husked and various classes of milled rice,width=70%]
|===
.2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice +
stem:[w_max]
| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice
| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5
|===

which renders:

Example table 2

Table 1 in the Metanorma ISO Rice example document illustrates a large range of table formatting options. Search for #table1.

|===
| Head | Head
| Row  | Row
|===
[.source]
<<iso1212>>
NOTE: Note 1

|===
| Head | Head
| Row  | Row
|===
[.source]
<<iso1212>>, reformatted
[.source]
<<iso1213>>,
NOTE: Note 1
NOTE: Note 2

include::learn/exercises.adoc[tag=exercise-2-3-3]

Let's look at inserting images next.

>> Start next lesson

Images

image::{PATH}[]

[[my-anchor]] <1>
.Title for image <2>
image::images/path.png[Alt text] <3>

This is an inline image:{PATH}[], appearing within a paragraph.

image::data:image/png;base64,ivBO...[alt text]

= Document title
:imagesdir: my-images <1>
...
image::myimage01.png[] <2>

[altmedia]
.Image with alternatives
--
html:: image:spec/assets/correct.png[200,300,media="(width >= 800px)"]]
doc:: image:spec/assets/corrupt.png[300,600]
default:: image:spec/assets/warning_test.png[auto,auto,alttext]
--

image::logo.jpg[height=150px,width=100px]

image::logo.jpg[height=150,width=100]

image::logo.jpg[height=150,width=auto]

image::logo.jpg[height=150]

[width=full-page-width]
image::abc.png[]

[.figure,width=full-page-width]
====
image::abc.png[]
====

include::learn/exercises.adoc[tag=exercise-2-3-4]

Let's look at admonitions next.

>> Start next lesson

Admonitions

[TIP,type=box]
====
This is a box
====

NOTE: Advice on when to use which admonition type is specified in ANSI Z535.6.

[NOTE] <1>
==== <2>
Content of the admonition block. <3>
Unlike an admonition paragraph, it may contain any AsciiDoc content.
==== <4>

== General requirements
[NOTE]
====
This is just a note providing guidance.
====
[IMPORTANT]
====
This is an important message.
====
== Safety requirements
[WARNING]
====
This important notice applies to safety concerns.
====
[CAUTION]
====
This notice must not be ignored.
====

[type=Danger]
CAUTION: Do not perform maintenance tasks while the machine is still operating.
[WARNING,type=Safety Precaution]
====
This is a safety precaution
spanning multiple-blocks.
====

* A
* B
* C
[NOTE,keep-separate=true]
====
Note not folded into its preceding block
====

[NOTE]
This note will be folded in the preceding block.
NOTE: This one too.

[NOTE,type=bibliographic]
====
Bibliographic note
====

[NOTE%termnote]
====
Bibliographic note
====

== Scope
[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====
My scope text...

= Document title
:document-attribute: XXXX
[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====
== Foreword
My foreword text...

= Document title
:document-attribute: XXXX
[IMPORTANT,coverpage=true]
====
This important notice appears on the cover page.
====
== Foreword
My foreword text...

= Document title
:document-attribute: XXXX
[IMPORTANT,coverpage=true,notag=true]
====
This important notice appears on the cover page.
====
== Foreword
My foreword text...

[NOTE%termnote]
====
Bibliographic note
====

include::learn/exercises.adoc[tag=exercise-2-3-5]

Great progress so far! Let's look at code samples in the next lesson.

>> Start next lesson

Code Samples

Now it's your turn. Fill the document with the following attributes:

• [ ] Document title
• [ ] Your name
• [ ] Your organization using the :publisher: attribute
• [ ] Your organization's address
• [ ] The document class: standoc
• [ ] The document type: document
• [ ] The language
• [ ] The copyright year

Look at the prepopulated Metanorma document. There are many clauses describing the content but there are sections missing to form a correct standard document.

Add the following sections:

• [ ] Foreword on line 13
• [ ] Introduction on line 21
• [ ] Terms and definitions on line 27
• [ ] Bibliography on line 60

Add lists to the prepopulated document.

• [ ] Add an ordered list in lines 17-24.
• [ ] Add an unordered list in lines 36-40.
• [ ] Add a definition list in lines 46-48.

Create a term definition entry for the term "immature kernel":

• [ ] Add an alternative term ("unripe kernel")
• [ ] Add a deprecated term ("raw kernel")
• [ ] Add a definition: kernel, whole or broken, which is unripe and/or underdeveloped.

=== Term
alt:[alternative term]
deprecated:[deprecated term]
definition

Let's compare rice against wheat in a table:

• [ ] Create an empty three column table with seven rows.
• [ ] Add a table title: "Nutrient profile of rice vs. wheat"
• [ ] Let's make the first column a bit wider than the other two columns in the ratio 3:2:2 by using the cols attribute.
• [ ] Populate the table like this:

.Nutrient profile of rice vs. wheat

|===
|||
|||
|||
|===

Insert an image of a rice plant in line 17 by following the steps below:

• [ ] Add an image macro.
• [ ] Populate the image:: macro with this link:

 https://upload.wikimedia.org/wikipedia/commons/2/27/Oryza_sativa_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-232.jpg

• [ ] Add a picture title (Oryza sativa)
• [ ] Create a key with three entries

A:: Rice - A flowering specimen of the variety _melanoceras_ Alef.
B:: blossom panicle
C:: crop panicle

Turn the existing text into admonitions:

• [ ] Turn the text in line 15 into an IMPORTANT admonition.
• [ ] Turn the text in lines 17-19 into a WARNING admonition.
• [ ] Turn the text in line 21 into a NOTE admonition.

[NOTE]
====
This is a long note.
It contains three lines.
Line three.
====

There are some code samples in the document but they are not neatly packed into source blocks, so they cause trouble.

• [ ] Create a source block with the attribute ruby for the code in lines 14-29.
• [ ] Create a source block with the attribute python for the code in line 32
• [ ] Create a source block with the attribute java for the code in lines 35-39.

[source,language]
----
Code
----

Format the text using the following formatting:

• [ ] Add underline formatting to "Earth institute" in line 18
• [ ] Add bold formatting to "from Africa, for Africa" in line 20
• [ ] Add italic formatting to The New York times and International Herald Tribune in line 21
• [ ] Add smallcaps formatting to all instances of "NERICA"
• [ ] Add a footnote on line 22 explaining the term "perennial". Footnote text: A perennial plant lives more than two years.

Let's add some index entries to the text.

• [ ] Add a visible index entry to "UN Millennium Development project" in line 17
• [ ] Add an invisible three level index entry after NERICA in line 21: NERICA, economy, Green revolution
• [ ] Add an invisible two level index entry in line 22 after rice: rice, perennial
• [ ] Create a new index section at the bottom of the document

Let's add some references to the sample document.

Internal references:

• [ ] Create an anchor for the table called table1
• [ ] Reference the table in lines 30 and 36.

Bibliographic references: The text references some standards which don't have a matching entry in the bibliography section. Add the following references:

• [ ] ISO712, ISO712:2009, Cereals and cereal products — Determination of moisture content — Reference method
• [ ] ISO7301, ISO 7301:2011, Rice -- Specification
• [ ] IEC61010-2, IEC 61010-2:1998, Safety requirements for electric equipment for measurement, control, and laboratory use -- Part 2: Particular requirements for laboratory equipment for the heating of material

[[anchor]]

<<anchor>>

The text contains some typos. Mark the errors using comments.

• [ ] Line 16: weter
• [ ] Line 18: exseed
• [ ] Line 20: eyes

Enter the command metanorma document.adoc into the terminal and see what happens.

The following document doesn't compile because there are some errors.

1. Enter metnanorma exercise-4.adoc to trigger the build process
2. Have a look at the error messages
3. Try to debug the document. If you get stuck, have a look at the hints.
4. Once you solved the errors, run metanorma exercise-4.adoc again to see if the document compiles.

As of this writing, double-sided annotations are not supported in Word, and the nested annotations are realised as bracketed text.

Capitalisation

Capitalisation may be applied automatically in the rendering of documents, despite not being present in the source material; for example, titles and captions may be title-cased or put in all caps. In order to prevent a span of text automatically having its case changed, use CSS styling to set its CSS text-transform property to "none" [added in https://github.com/metanorma/isodoc/releases/tag/v2.8.5]:

.Example of a word in a title not to be capitalized

:title: [css text-transform:none]#IoT# and content standards
...
=== Approaches to [css text-transform:none]#IoT#

As shown, such styling extends to document titles as document attributes.

Custom character sets

When a private use codepoint is used in a document, reflecting an agreement between the document author and the document renderer, but not a standard like Unicode, the custom character set that includes that codepoint needs to be flagged. So U+F8D0 is the Klingon letter for "a" in the Conscript Unicode Registry, but the Kanji-Katakana hybrid of 訁and コ (equivalent to 講) in the BabelStone PUA.

In order to flag such a custom interpretation of the codepoint, the interpretation can be named in a formatting directive, flagged as custom-charset [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.3]. For example:

[custom-charset:conscript]#\\uf8d0#
[custom-charset:babelstone]#\\uf8d0#

In order to be rendered, a font implementing that interpretation needs to be indicated as a processing hint for Metanorma. This is done with the Presentation XML metadata directive :presentation-metadata-custom-charset-font: {name of interpretation}:"{name of font}", as a document attribute, giving a comma-delimited list of charset-font pairs. For instance:

:presentation-metadata-custom-charset-font: conscript:"Code 2000",babelstone:"BabelStone PUA"
:fonts: "Code 2000";"BabelStone PUA"

As with CSS declarations, any font specified as a custom charset font also needs to be passed to Metanorma in the :fonts: document attribute.

For a more deep explanation about encoding custom characters, see Encoding and rendering special characters in Metanorma.

Numeric ranges

Numeric ranges, like dates (e.g., 1981–1995), make use of en dashes in between the numbers, usually without any white space around.

At the time writing, there is no AsciiDoc encoding to render en dashes.

In Metanorma, there is a vision of implementing a semantic encoding for numeric ranges, perhaps an option like range:[n,m] or shorthands like n..m.

For the time being, the existent workaround for such cases is the use of entity codes, more specifically:

&‌ndash;

.Examples of encoding numeric ranges

See chapters 15–17...
Issues 18–20 are in fact a single issue...
_Laser Physics_ *17* 1017–1024 (2007).

Character substitutions

Metanorma AsciiDoc supports Asciidoctor-style character substitutions as shown in table-char-sub.

Metanorma AsciiDoc also recognises HTML and XML character references, and decimal and hexadecimal Unicode code points.

.Supported Metanorma AsciiDoc character substitutions

In addition to these character substitutions, Metanorma converts straight quotes to smart quotes in postprocesssing: see ink:/author/ref/document-attributes#smart-quotes[Smart quotes] for the associated rules.

CSS declarations

The css command is used to wrap content with a CSS declaration (MDN) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6].

This feature only applies to HTML output.

The syntax is as follows:

[css {css-directive}]#{styled-text}#

Where:

• {css-directive} is a CSS declaration
• {styled-text} is text where the CSS declaration is to be applied

.Example of applying a custom CSS declaration to content

[css font-family:"Noto Sans JP"]#お好み焼き#
[css font-family:"Noto Sans Canadian Aboriginal"]#ᓀᐦᐃᔭᐍᐏᐣ#

Identifier

The identifier command, used to indicate that its contents are an identifier as semantic markup (and not to be processed as a hyperlink) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2].

The syntax is as follows:

identifier:[my-identifier]

Where:

• my-identifier is the identifier to be encoded.

This functionality is very useful for encoding URIs, which can be virtually indistinguishable from URLs that can be resolved. URIs very often cannot be resolved since they are simply namespaced identifiers.

.Example of rendering a URI using the identifier command

identifier:[https://schemas.isotc211.org/19115/-1/mdb/1.3]

.Example of rendering a URN using the identifier command

identifier:[urn:iso:std:iso:8601:-1:en]

Semantic spans

The span command is used to introduce semantic markup into Metanorma text [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6].

The syntax is as follows:

span:category[text]

Where:

• category is a semantic label for the content given as text
• text is the textual content

Here, the text is tagged as belonging to category.

A semantically-tagged text with span is not normally rendered any different to normal, although the semantic markup introduced can be used to influence rendering.

Nesting of styles

Character styles can be nested within each other, with both constrained and unconstrained formatting marks.

*Boldmono__space__*

General

Footnotes are useful for adding remarks to content without distracting from the reading flow.

Metanorma AsciiDoc supports:

• inline footnotes
• multi-paragraph footnotes

Inline footnotes

Footnotes are added to a document using the footnote command (¹).

The syntax is demonstrated as:

Oryza sativafootnote:[Sativa means "cultivated"], is rice that is farmed commercially.

Multi-paragraph footnotes

The multi-paragraph footnote command footnoteblock:[id] allows for specification of multi-paragraph content within a footnote, through a named note block. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.4].

The id is the identifier of a note containing the contents of the footnote.

The following syntax is used:

... footnoteblock:[my-anchor] ... <1>
...
[[my-anchor]] <2>
[NOTE] <3>
--
Multi-paragraph footnote content.
--

This is a paragraph.footnoteblock:[id1] This continues the paragraph.
[[id]]
[NOTE]
--
This is
a multi-paragraph
footnote
--

Named footnotes and duplicate footnotes

In some cases, identical footnote content can apply to multiple places. Metanorma AsciiDoc supports named footnotes that facilitate reuse without repeated definitions.

By default, Metanorma already detects whether footnote text is reused. When the text of a footnote is repeated in two different places, the same footnote number in both places, rather than treat the repetition as a new footnote. Assignment of IDs is therefore optional.

The following syntax is used:

... footnote:{id}[text] ... <1>
... footnote:{id}[] ... <2>

A bold statement!footnote:disclaimer[Opinions are my own.]
Another outrageous statement.footnote:disclaimer[]

Special footnotes

───────────────▄▄───▐█ a)
───▄▄▄───▄██▄──█▀───█─▄
─▄██▀█▌─██▄▄──▐█▀▄─▐█▀
▐█▀▀▌───▄▀▌─▌─█─▌──▌─▌
▌▀▄─▐──▀▄─▐▄─▐▄▐▄─▐▄─▐▄

[figure]
====
image::evolution.png{blank}footnote:[hiddenref%A depiction of evolution]
====

General

Metanorma supports index entries with primary, secondary and tertiary index terms. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10].

Primary index terms are listed under the first-level index, the secondary index terms are listed under the primary index terms' sub-index, and the tertiary index terms are listed under the secondary index term's sub-index.

Index term behavior differs per rendered output format:

• In PDF, indexes are rendered as references to page numbers.
• In HTML and DOC, indexes are rendered as references to the nearest labelled block; a note, example, figure, formula etc., if the index term is contained within it, or a clause or subclause, otherwise.

Index term links are only rendered in certain flavours, and do not appear otherwise in DOC, PDF or HTML output.

[index]
== Index

The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)), <1>
was to carry Excalibur (((Sword, Broadsword, Excalibur))). <2>

[index]
== Index

The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)),
was to carry Excalibur (((Sword, Broadsword, Excalibur))).

signifying by divine providence that I, ((*Arthur*)),
was to carry Excalibur (((Sword~E~, stem:[sqrt(E)], Excalibur))).

signifying by divine providence that I, index-range:end-range-1[((*Arthur*))],
was to carry Excalibur index-range:end-range-2[(((Sword~A~, stem:[sqrt(2)], Excalibur)))].
...
and so forth.[[end-range-1]]
...
_Sic explicit fabula._[[end-range-2]]

index:see[Satchmo,Louis Armstrong]
index:see[James Brown,influences,Hank Ballard and the Midnighters]
index:also[guitar,electric,technique,Jimi Hendrix]

Hyperlinks

Metanorma AsciiDoc lets you include links to external sources, and sources to files within the same project.

To reference an internal source:

1. Use the link: command to include a link to a file. The syntax looks like this: \PATH[].
2. Add link text in square brackets after the path.

To reference an external source:

1. Paste the URL into the document.
2. Add link text in square brackets after the URL (optional) URL[Link text].

*Adding accessibility in URIs*

To add accessibility URIs, use the ,title=... option in the square brackets. The option corresponds to HTML's alt text a@title attribute.

http://www.iso.org[International Organization for Standardization,title=This is a tooltip for the link]

Metadata references

Every document contains a set of metadata to describe the document. You can insert a metadata reference by putting the attribute in curly braces {attribute}. The reference will be replaced with the value in the rendered output.

:technical-committee-number: 2
:technical-committee: Fasteners
:subcommittee-number: 11
:subcommittee: Fasteners with metric external thread
This document was prepared by Technical Committee ISO/TC {technical-committee-number}, _{technical-committee}_, Subcommittee SC {subcommittee-number}, _{subcommittee}_.

Internal references

To link to an important section, table, figure, formula, or list item in your document:

1. Set an anchor using double square brackets before the content you want to reference: \[[anchor]].
2. To reference an anchor, type the anchor name like this \<<anchor>>.
3. To set an alternative text other than the anchor text, append the text inside the brackets using a comma.

Auto-numbering of references

Metanorma automatically numbers and names references; because they are autonumbered, they will be renumbered automatically if you insert any new text of the same type.

Since the markup will be converted into XML, the anchor must follow the XML namespace conventions.

Therefore, an anchor name name must not contain:

• colons
• whitespaces
• words starting with numbers

If you want to learn more about the technical aspects of cross-references, read Deep-dive into cross-references.

Format-independent links

Typical links created by the link command require the correct file path that includes the file suffix (e.g. .html for HTML documents).

When linking a Metanorma document to another Metanorma document, which can be rendered into multiple output formats with different suffixes (such as in HTML, PDF or DOC), the option update-type=true can be specified to achieve format-independent links [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

When the option update-type=true is given, the rendered link will provide the correct file paths dependent on the output format.

The following conditions must be satisfied to use format-independent links:

• The link shall be relative and not absolute
• The link shall not have a file suffix

.Example of links to other Metanorma documents

link:../parent[update-type=true]
link:../child[This is the child document,update-type=true]

Hyperlink validation

Hyperlinks are validated and normalized in Metanorma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.5.2].

Hyperlinks are treated as IRIs (internationalized resource identifiers, where non-ASCII Unicode characters are allowed.)

As with normal AsciiDoc, http(s) links are assumed by default to be intended as hyperlinks, and are marked up and rendered as such.

Example hyperlinks are often invalid (e.g. http://{domain}), and Metanorma execution will be aborted if they are found, since they cannot be rendered as meaningful hyperlinks.

Such links should be escaped by prefixing them with a backslash, which will result in them being treated as plain text (e.g. \http://{domain}.)

Entering a bibliographic entry

To enter a reference entry:

1. Start a new unordered list (*) item.
2. Enter triple square brackets ([[[]]]) which contain:

Referencing a bibliographic entry

To cite an entry from your bibliography:app-name:

1. Enter the anchor name like this: \<<ISO20483>>.
2. To specify a location within the cited document, you can add localities in the brackets like so: \<<ISO20483, part=IV,chapter=3,paragraph=12>>.

Bibliography example

The following code sample illustrates how a bibliography section looks like in AsciiDoc Metanorma.

[bibliography]
== Normative references
* [[[ISO20483,ISO 20483:2013]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_
* [[[ISO6540,ISO 6540:1980]]]. _Maize -- Determination of moisture content (on milled grains and on whole grains)_

Gets rendered as:

• ISO 20483:2013. Cereals and cereal products — Determination of moisture content — Reference method
• ISO 6540:1980. Maize — Determination of moisture content (on milled grains and on whole grains)

Learning objectives for the tutorials

Before we dive into using the Metanorma toolchain, let's cover the basic ideas you need to understand to work with Metanorma. In this lesson we will cover:

• What Metanorma is
• The differences between Word and Metanorma
• The paradigms "What you see is what you get" vs. "What you see is what you mean"
• What the Metanorma workflow looks like from document creation to publication

Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. In this lesson, we will discuss what AsciiDoc is and what a typical Metanorma document looks like. You will also learn how to write AsciiDoc.

Reviewing documents is an integral part of developing a standard. The best way to review a document, is to use a version control environment that supports comments as well, such as GitHub and its feature GitHub discussions. In case your organization does not use a git-based approach, Metanorma provides a comment functionality that lets you insert your remarks and create to dos. In this lesson, you will learn:

• How to add comments using AsciiDoc markup
• How to generate a draft using the command line.

Once you are happy with your document, the next step is to generate an output to send your SDO for publishing. Since Metanorma poses some validity criteria for your document, it is normal to face some errors. Don't worry, we will go through some common errors and teach you how to resolve them. In this lesson you will learn:

• How to generate PDF, HTML, and Word output using the command line
• How to troubleshoot common errors

Adding Comments

You can annotate a Metanorma AsciiDoc document with comments and TODOs to indicate a pending action.

Reviewer comments

To create a comment:

1. Define the start of the comment by creating an anchor \[[start]].
2. Define where the comment should end by creating an anchor \[[end]] (optional).
3. Add the comments metadata: [reviewer="Your Name",date=YYYYMMDDT0000,from=start,to=end] The date and to attributes are optional. The timestamp in the date attribute is optional, too. The from and to elements can be bookmarks which cover no space.
4. Begin the comment block using four asterisks \****.
5. Enter your comment.
6. Close the comment block with four asterisks \****.

Example of a commentasciidoc

=== Address Profile Definition (AddressProfileDescription)
This is a clause address [[A]]proflie[[B]] definition
[reviewer="Nick Nicholas",date=20180125T0121,from=A,to=B]
****
proflie?!
****

which renders

By default, Metanorma will render annotations in output only if the document is unpublished, using SDO-specific criteria to determine document status (the document stage). This can be overridden by setting :presentation-metadata-render-document-annotations: to true or false.

TODO: This is treated as a reviewer note.
[TODO]
====
This is also treated as a reviewer note
====

include::learn/exercises.adoc[tag=exercise-3-1]

Now that we've commented on the content, let's create a draft of the document.

>> Start next lesson

Rendering a Draft Document

To render a draft that your peers should review, you need to add these metadata to the document header:

• :draft:: Tells the compiler to display comments in the final output
• :status: draft Defines the current document stage. NOTE: Some flavors, for example ISO, use :docstage: and a status code to indicate in what stage the document is.

To compile a Metanorma document you must enter the command metanorma and the document you want to compile document.adoc.

metanorma document.adoc

With this command you trigger the Metanorma toolchain to:

• Read the AsciiDoc input
• Convert it into XML
• Check the XML against the document model (XML schema)
• Create HTML, PDF, and DOC output

include::learn/exercises.adoc[tag=exercise-3-2]

Now that you are familiar with the simplest way of creating a Metanorma document, let's look at different ways to compile documents in the next lesson.

>> Start next lesson

Learning objectives for the tutorials

Before we dive into using the Metanorma toolchain, let's cover the basic ideas you need to understand to work with Metanorma. In this lesson we will cover:

• What Metanorma is
• The differences between Word and Metanorma
• The paradigms "What you see is what you get" vs. "What you see is what you mean"
• What the Metanorma workflow looks like from document creation to publication

Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. In this lesson, we will discuss what AsciiDoc is and what a typical Metanorma document looks like. You will also learn how to write AsciiDoc.

Reviewing documents is an integral part of developing a standard. The best way to review a document, is to use a version control environment that supports comments as well, such as GitHub and its feature GitHub discussions. In case your organization does not use a git-based approach, Metanorma provides a comment functionality that lets you insert your remarks and create to dos. In this lesson, you will learn:

• How to add comments using AsciiDoc markup
• How to generate a draft using the command line.

Once you are happy with your document, the next step is to generate an output to send your SDO for publishing. Since Metanorma poses some validity criteria for your document, it is normal to face some errors. Don't worry, we will go through some common errors and teach you how to resolve them. In this lesson you will learn:

• How to generate PDF, HTML, and Word output using the command line
• How to troubleshoot common errors

Compiling a Metanorma Document

To successfully compile a Metanorma document, the toolchain looks at:

• Metadata: The title, document flavor, and document type.
• Syntax: Is the entered AsciiDoc code correct?
• Dependencies: Are all tools needed to compile the document installed?
• File references: Are any files referred to by the file being compiled, and is their path entered correctly, for example when you include images (image::PATH[]). Advanced AsciiDoc usage also allows a document to embed other AsciiDoc documents (include::PATH[]), and Metanorma extends this in advanced usage to external data sources.

To compile a Metanorma document:

1. On the command line, go to the folder where the document you want to compile is located.
2. Enter the following command:

metanorma document.adoc

With this command you trigger the Metanorma toolchain to:

• Read the AsciiDoc input
• Convert it into XML
• Check the XML against the document model (XML schema)
• Create HTML, PDF, and DOC output

You can also manipulate the way Metanorma compiles a document by setting flags.

Flags are appended to the build command, like this:

metanorma document.adoc -x html

You can use the following flags to manipulate the building process:

• -t: Sets the flavor of the document NOTE: Either define the flavor in the metadata using mn-document-class or use -t flavor
• -x: Sets the output format(s) of the document
• -o: Enter a path that the output should be saved to.

To see the full list of possible build commands, open the Metanorma help on the command line.

metanorma help compile

>> Start next lesson

Troubleshooting

There can be many reasons why you can't compile a Metanorma AsciiDoc document into the final output, but you can easily fix them when you are familiar with typical errors.

Metanorma tells you what's wrong in the terminal while it is building the document. The errors are also stored in an Error file .err in the same directory where your original document is stored, so you can debug them later.

 Header with metadata...
 // include::sections/00-foreword.adoc[]
 include::sections/01-introduction.adoc[]
 include::sections/02-scope.adoc[]
 ...

• If Metanorma did not generate any visual output, you need to work with the errors in the terminal.

• If execution has aborted before the XML content could be finalised, the XML file is still output to disk, suffixed with .xml.abort rather than .xml, and you can use it to make sense of error messages.
• *If the document did compile and generated visual output:*

• Have a look at the compiled output: Are there missing sections? Is the formatting different than what you expected? Sometimes you can catch errors by looking at the rendered document. After that, have a look at the errors on the terminal to pinpoint where things went wrong.

The following sections discuss common errors and how to fix them.

my-standard $ metanorma document.adoc <1>
Error: Specified input file 'document.adoc' does not exist.
sources $ metanorma document.adoc <2>

...
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.4.6/exe/metanorma:20:in `<top (required)>'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `load'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `<main>'
parsing: "normal text""
undefined method `[]' for nil:NilClass

[[anchor1]]
== Section 1
...
[[anchor1]]
== Section 2
...

[source,asciidoc]
=== <1>
image::../assets/image.png[]
===
|== <2>
|Name of Column 1
|Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|--- <3>

Visible index terms: `((Level 1 index term))`
Hidden index terms: `(((Level 1 index term, Level 2 index term, Level 3 index term)))`

// Examples of incorrect anchors in references
* [[[123anchor1,identifier 1]]], ... // Anchors cannot begin with a number
* [[[_anchor2,identifier 2]]], ... // Anchors cannot begin with underscores or hyphens
* [[[#anchor3,identifier 3]]], ... // Anchors cannot begin with any special character. Just letters.

[[anchor1234]]
<<anchor1432>>
Error message: No label has been processed for ID anchor1432

[bibliography]
== References
* [[[bt2267-10,ITU-R BT.2267-10]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._

...
[relaton-itu] ("ITU-R BT.2267-10") fetching...
C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:440:in `block in symbolize': undefined method `to_sym' for 404:Integer (NoMethodError)
Did you mean?  to_s
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `each'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `reduce'
...

[bibliography]
== References
* [[[bt2267-10,nofetch(ITU-R BT.2267-10)]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._

|===
|A footnote:a[ABC] | B footnote:a[]
|===

There can be many reasons why you can't compile a Metanorma AsciiDoc document into the final output, but you can easily fix them when you are familiar with typical errors.

Metanorma tells you what's wrong in the terminal while it is building the document. The errors are also stored in an Error file .err in the same directory where your original document is stored, so you can debug them later.

 Header with metadata...
 // include::sections/00-foreword.adoc[]
 include::sections/01-introduction.adoc[]
 include::sections/02-scope.adoc[]
 ...

• If Metanorma did not generate any visual output, you need to work with the errors in the terminal.

• If execution has aborted before the XML content could be finalised, the XML file is still output to disk, suffixed with .xml.abort rather than .xml, and you can use it to make sense of error messages.
• *If the document did compile and generated visual output:*

• Have a look at the compiled output: Are there missing sections? Is the formatting different than what you expected? Sometimes you can catch errors by looking at the rendered document. After that, have a look at the errors on the terminal to pinpoint where things went wrong.

The following sections discuss common errors and how to fix them.

my-standard $ metanorma document.adoc <1>
Error: Specified input file 'document.adoc' does not exist.
sources $ metanorma document.adoc <2>

...
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.4.6/exe/metanorma:20:in `<top (required)>'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `load'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `<main>'
parsing: "normal text""
undefined method `[]' for nil:NilClass

[[anchor1]]
== Section 1
...
[[anchor1]]
== Section 2
...

[source,asciidoc]
=== <1>
image::../assets/image.png[]
===
|== <2>
|Name of Column 1
|Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|--- <3>

Visible index terms: `((Level 1 index term))`
Hidden index terms: `(((Level 1 index term, Level 2 index term, Level 3 index term)))`

// Examples of incorrect anchors in references
* [[[123anchor1,identifier 1]]], ... // Anchors cannot begin with a number
* [[[_anchor2,identifier 2]]], ... // Anchors cannot begin with underscores or hyphens
* [[[#anchor3,identifier 3]]], ... // Anchors cannot begin with any special character. Just letters.

[[anchor1234]]
<<anchor1432>>
Error message: No label has been processed for ID anchor1432

[bibliography]
== References
* [[[bt2267-10,ITU-R BT.2267-10]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._

...
[relaton-itu] ("ITU-R BT.2267-10") fetching...
C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:440:in `block in symbolize': undefined method `to_sym' for 404:Integer (NoMethodError)
Did you mean?  to_s
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `each'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `reduce'
...

[bibliography]
== References
* [[[bt2267-10,nofetch(ITU-R BT.2267-10)]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._

|===
|A footnote:a[ABC] | B footnote:a[]
|===

There can be many reasons why you can't compile a Metanorma AsciiDoc document into the final output, but you can easily fix them when you are familiar with typical errors.

Metanorma tells you what's wrong in the terminal while it is building the document. The errors are also stored in an Error file .err in the same directory where your original document is stored, so you can debug them later.

 Header with metadata...
 // include::sections/00-foreword.adoc[]
 include::sections/01-introduction.adoc[]
 include::sections/02-scope.adoc[]
 ...

• If Metanorma did not generate any visual output, you need to work with the errors in the terminal.

• If execution has aborted before the XML content could be finalised, the XML file is still output to disk, suffixed with .xml.abort rather than .xml, and you can use it to make sense of error messages.
• *If the document did compile and generated visual output:*

• Have a look at the compiled output: Are there missing sections? Is the formatting different than what you expected? Sometimes you can catch errors by looking at the rendered document. After that, have a look at the errors on the terminal to pinpoint where things went wrong.

The following sections discuss common errors and how to fix them.

my-standard $ metanorma document.adoc <1>
Error: Specified input file 'document.adoc' does not exist.
sources $ metanorma document.adoc <2>

...
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.4.6/exe/metanorma:20:in `<top (required)>'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `load'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `<main>'
parsing: "normal text""
undefined method `[]' for nil:NilClass

[[anchor1]]
== Section 1
...
[[anchor1]]
== Section 2
...

[source,asciidoc]
=== <1>
image::../assets/image.png[]
===
|== <2>
|Name of Column 1
|Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|--- <3>

Visible index terms: `((Level 1 index term))`
Hidden index terms: `(((Level 1 index term, Level 2 index term, Level 3 index term)))`

// Examples of incorrect anchors in references
* [[[123anchor1,identifier 1]]], ... // Anchors cannot begin with a number
* [[[_anchor2,identifier 2]]], ... // Anchors cannot begin with underscores or hyphens
* [[[#anchor3,identifier 3]]], ... // Anchors cannot begin with any special character. Just letters.

[[anchor1234]]
<<anchor1432>>
Error message: No label has been processed for ID anchor1432

[bibliography]
== References
* [[[bt2267-10,ITU-R BT.2267-10]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._

...
[relaton-itu] ("ITU-R BT.2267-10") fetching...
C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:440:in `block in symbolize': undefined method `to_sym' for 404:Integer (NoMethodError)
Did you mean?  to_s
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `each'
  from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `reduce'
...

[bibliography]
== References
* [[[bt2267-10,nofetch(ITU-R BT.2267-10)]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._

|===
|A footnote:a[ABC] | B footnote:a[]
|===

Now it's your turn. Fill the document with the following attributes:

• [ ] Document title
• [ ] Your name
• [ ] Your organization using the :publisher: attribute
• [ ] Your organization's address
• [ ] The document class: standoc
• [ ] The document type: document
• [ ] The language
• [ ] The copyright year

Look at the prepopulated Metanorma document. There are many clauses describing the content but there are sections missing to form a correct standard document.

Add the following sections:

• [ ] Foreword on line 13
• [ ] Introduction on line 21
• [ ] Terms and definitions on line 27
• [ ] Bibliography on line 60

Add lists to the prepopulated document.

• [ ] Add an ordered list in lines 17-24.
• [ ] Add an unordered list in lines 36-40.
• [ ] Add a definition list in lines 46-48.

Create a term definition entry for the term "immature kernel":

• [ ] Add an alternative term ("unripe kernel")
• [ ] Add a deprecated term ("raw kernel")
• [ ] Add a definition: kernel, whole or broken, which is unripe and/or underdeveloped.

=== Term
alt:[alternative term]
deprecated:[deprecated term]
definition

Let's compare rice against wheat in a table:

• [ ] Create an empty three column table with seven rows.
• [ ] Add a table title: "Nutrient profile of rice vs. wheat"
• [ ] Let's make the first column a bit wider than the other two columns in the ratio 3:2:2 by using the cols attribute.
• [ ] Populate the table like this:

.Nutrient profile of rice vs. wheat

|===
|||
|||
|||
|===

Insert an image of a rice plant in line 17 by following the steps below:

• [ ] Add an image macro.
• [ ] Populate the image:: macro with this link:

 https://upload.wikimedia.org/wikipedia/commons/2/27/Oryza_sativa_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-232.jpg

• [ ] Add a picture title (Oryza sativa)
• [ ] Create a key with three entries

A:: Rice - A flowering specimen of the variety _melanoceras_ Alef.
B:: blossom panicle
C:: crop panicle

Turn the existing text into admonitions:

• [ ] Turn the text in line 15 into an IMPORTANT admonition.
• [ ] Turn the text in lines 17-19 into a WARNING admonition.
• [ ] Turn the text in line 21 into a NOTE admonition.

[NOTE]
====
This is a long note.
It contains three lines.
Line three.
====

There are some code samples in the document but they are not neatly packed into source blocks, so they cause trouble.

• [ ] Create a source block with the attribute ruby for the code in lines 14-29.
• [ ] Create a source block with the attribute python for the code in line 32
• [ ] Create a source block with the attribute java for the code in lines 35-39.

[source,language]
----
Code
----

Format the text using the following formatting:

• [ ] Add underline formatting to "Earth institute" in line 18
• [ ] Add bold formatting to "from Africa, for Africa" in line 20
• [ ] Add italic formatting to The New York times and International Herald Tribune in line 21
• [ ] Add smallcaps formatting to all instances of "NERICA"
• [ ] Add a footnote on line 22 explaining the term "perennial". Footnote text: A perennial plant lives more than two years.

Let's add some index entries to the text.

• [ ] Add a visible index entry to "UN Millennium Development project" in line 17
• [ ] Add an invisible three level index entry after NERICA in line 21: NERICA, economy, Green revolution
• [ ] Add an invisible two level index entry in line 22 after rice: rice, perennial
• [ ] Create a new index section at the bottom of the document

Let's add some references to the sample document.

Internal references:

• [ ] Create an anchor for the table called table1
• [ ] Reference the table in lines 30 and 36.

Bibliographic references: The text references some standards which don't have a matching entry in the bibliography section. Add the following references:

• [ ] ISO712, ISO712:2009, Cereals and cereal products — Determination of moisture content — Reference method
• [ ] ISO7301, ISO 7301:2011, Rice -- Specification
• [ ] IEC61010-2, IEC 61010-2:1998, Safety requirements for electric equipment for measurement, control, and laboratory use -- Part 2: Particular requirements for laboratory equipment for the heating of material

[[anchor]]

<<anchor>>

The text contains some typos. Mark the errors using comments.

• [ ] Line 16: weter
• [ ] Line 18: exseed
• [ ] Line 20: eyes

Enter the command metanorma document.adoc into the terminal and see what happens.

The following document doesn't compile because there are some errors.

1. Enter metnanorma exercise-4.adoc to trigger the build process
2. Have a look at the error messages
3. Try to debug the document. If you get stuck, have a look at the hints.
4. Once you solved the errors, run metanorma exercise-4.adoc again to see if the document compiles.

>> Start next lesson

Summary

Let's summarize what we've learnt in this lesson:

• To generate a Metanorma document, enter the following command:

metanorma document.adoc

• More often than not, we encounter errors that we need to fix: