The “Terms and Definitions” section

Grammar summary

Terms and Definitions sections follow a strict grammar, which is reflected in their AsciiDoc markup:

  • The term is given as a subheading at the appropriate level (three equal signs, unless there are subsections in the Terms and Definition section). The term may be cross-referenced from other terms, in which case it should have an anchor.

  • The term is optionally followed by alternative/admitted terms, which must be marked up in an alt:[...] macro; deprecated terms, which must be marked up in a deprecated:[...] macro; and a term domain, which must be marked up in a domain:[...] macro.

  • The definition of the term is given in a separate paragraph.

  • The definition is optionally followed by examples (paragraphs with an [example] style attribute).

  • The definition is then optionally followed by notes (denoted with a NOTE: prefix).

  • The definition is then followed by a citation for the term (marked with a [.source] role attribute).

  • The citation is a cross-reference to a normative reference, optionally followed by a comma and a modification if applicable.

For example:

=== paddy
alt:[paddy rice]
alt:[rough rice]
deprecated:[cargo rice]

rice retaining its husk after threshing

Foreign seeds, husks, bran, sand, dust.

NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking.

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

The requirement that the source of a term be given in a citation also applies when the source is a term bank, such as the International Electrotechnical Vocabulary (IEV). Formally, IEV references should be cited as IEC 60050-nnn:20xx, where n is the top-level clause, and 20xx is the year when that particular specification was published; e.g. IEC 60050-113:2011, 113-01-07.

Empty section

If there are no terms and definitions defined in this standards document, no terms should be included in the section body (it should be blank). The boilerplate at the start of the section is adjusted to reflect both possibilities; any paragraphs or lists in the AsciiDoc input (which can replicate the expected boilerplate) is stripped in the intermediate XML format.

Grouping IEV references

For convenience, Metanorma requires all IEV references to be to a single reference, named IEV in the normative references. During the rendering of AsciiDoc into Metanorma XML, this reference will be replaced by the various required IEC 60050-nnn:20xx references. (That means that you should not insert your own instances of IEC 60050 references for IEV citations: they will be duplicated by the automatically generated references.)



* [[[ievtermbank,IEV]]], _IEV: Electropedia_
// will be excluded from HTML and Word output. Will be replaced by a canonical reference in XML output.

Note that, for IEV entries to be validated, the IEV reference must be given as a Clause, and in quotes (otherwise the locality syntax would be interpreted as a range); so clause="103-01-02" for IEV 103-01-02.


The title of a top-level Terms and Definitions clause is populated automatically, overriding the title provided by the user: if it contains a Symbols and Abbreviated Terms subclause, it is titled Terms, definitions, symbols and abbreviated terms, otherwise it is titled Terms and definitions. A Terms and Definitions clause will be recognized if either title is given, regardless of case. Symbols and Abbreviated Terms subclauses are also automatically titled; other subclauses of Terms and Definitions clauses are not.


If the Terms and Definitions of a standard are partly or fully sourced from another standard, that standard is cited in a “source” attribute to the section: e.g., source=STANDARD_IDENTIFIER, where standard identifier is the reference anchor of the cited standard as given under the Normative References. (The attribute needs to be applied to the top-level clause, if there are subclauses.)

Any boilerplate of the Terms and Definitions section is adjusted accordingly.

== Terms and Definitions

Multiple sources are allowed, and need to be quoted and comma-delimited:

== Terms and Definitions

Markup within term macros

The macros alt:[...], deprecated:[...] and domain:[...] can contain their own markup.

=== paddy
alt:[_paddy_ rice]
deprecated:[#[smallcap]#cargo# rice]

_paddy_ (<<paddy>>) from which the husk only has been removed

Stem expressions

AsciiDoc does not permit macros to be nested inside other macros; so the following markup, introducing a stem expression as an admitted term, is illegal. (The use of stem expressions as preferred terms is not a problem, because the macro appears as a header.)

Bad example
=== stem:[t_90]

Time to launch.

However, Metanorma will treat any standalone paragraph in a term section, consisting of just a stem macro, as an admitted term:

Good example
=== stem:[t_90]


Time to launch.


Any clause within a Terms & Definitions section which is a nonterminal subclause (has child nodes) is automatically itself a terms (or definitions) section. On the other hand, any descendant of a nonterm clause is also a nonterm clause.

Informative clauses are indicated with the attribute [obligation=informative]; clauses are normative by default.

Introductory non-clause section

As defined above, all terminal subclauses of a term section (i.e. clauses that have no subclauses of their own) are treated as term definitions. Exceptionally, an introductory section can be treated as a subclause instead of a term, by prefixing it with the style attribute [.nonterm]:

== Terms and definitions

=== Introduction
The following terms have non-normative effect, and should be ignored by the ametrical.

=== Anapaest

metrical foot consisting of a short, a long, and a short

Blank subclases

Blank subclause headings can be given like this:

=== {blank}

These are used when you want to give a subclause number for a new subclause, but without an associated header text. For example, in AsciiISO Rice sample document,

=== Physical and chemical characteristics

==== {blank}

The mass fraction of moisture, determined in accordance with...

renders as

4.2. Physical and chemical characteristics

4.2.1. The mass fraction of moisture, determined in accordance with…​


This notation should not be used to implement paragraph numbering as required for UNECE. The UNECE Metanorma flavor treats each paragraph as a distinct clause and automatically numbers it.