Terms

Defining Terms: the “Terms and definitions” section

Grammar summary

“Terms and definitions” sections follow a strict grammar reflected in their Metanorma 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. If the comma is used on its own, then the term will be shown as modified, with no specific modification.

EXAMPLE:

=== instant

point on the term:[time axis]

NOTE: An instantaneous event occurs at a specific instant.

[.source]
<<IEV,clause "113-01-08">>

renders as

Example of a single term
Figure 1. Example of a single term.
Note
An unmodified term and definition does not require any text after the source reference.

More complex concepts can also be specified, with alternative terms, deprecated terms, domain, examples and a definition modified from its original source.

EXAMPLE:

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

rice retaining its husk after threshing

[example]
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.

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

renders as

Example of a single term with elaborated specifications
Figure 2. Example of a single term with elaborated specifications

A trailing comma after the source reference can indicate that the term or definition was “modified”, but with no further detail:

[.source]
<<ISO7301,section 3.2>>,

renders as

Example of a single source tagged as modified
Figure 3. Example of a single source tagged as “modified”.

A term and definition can be sourced from multiple sources (in accordance with ISO 10241-1). In this case each source should be entered in a separate [.source] paragraph.

EXAMPLE:

[.source]
<<ISO7301,section 3.2>>,

[.source]
<<ISO7302,section 3.10>>,

The requirement that the source of a term be given in a citation also applies when the source is a termbase, 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.

EXAMPLE: “IEC 60050-113:2011, 113-01-07”.

Predefined text / Boilerplate

Appending to predefined text

The “terms and definitions” clause is often prefixed with predefined text (“predefined text”) automatically before any terms are listed.

Such predefined text typically serve the following purposes:

  • indicate provenance of definitions (see Source); and

  • provide the location where definitions may be consulted, depending on the flavour.

EXAMPLE: For ISO documents, a reference to the ISO Online Browsing Platform and to the IEC Electropedia is provided in the predefined text.

Any paragraphs or lists in the input before the first term are appended to the flavour’s defined predefined text, in the intermediate XML format [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0]. [The behaviour until that release was for any such text to be overwritten by the flavour’s defined predefined text.]

In the following example the Metanorma ISO flavor is used to demonstrate the behavior.

Input:

== Terms and definitions

This is some random text I have inserted in this document.

* It does not follow ISO requirements
* Nor does it follow IEC requirements

=== Term 1

In the rendering, the text between the title and the first term definition is appended to the predefined text required by ISO:

3. Terms and definitions

ISO and IEC maintain terminological databases for use in standardization at the following addresses:

This is some random text I have inserted in this document.

  • It does not follow ISO requirements

  • Nor does it follow IEC requirements

3.1 Term 1

Overriding predefined text

If there are no terms and definitions defined in the document, no terms should be included in the clause body (it should be blank). The predefined text at the start of the clause is adjusted to reflect both possibilities.

In order to replace (override) the predefined text with custom content, an initial subclause with the style attribute [.boilerplate] can be used to do so [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0].

Input:

== Terms and definitions

[.boilerplate]
=== My predefined text (<<<=== this will be stripped)

This is predefined text that overwrites the default.

* No, it does not follow ISO requirements
* And no, it does not follow IEC requirements either

=== Term 1

Where:

  • The title of the predefined text clause will be stripped (so you could equally use === );

  • The custom predefined text is encoded as a subclause, so that its extent can be made unambiguous in initial processing.

The example above will be rendered as:

3. Terms and definitions

This is predefined text that overwrites the default.

  • No, it does not follow ISO requirements

  • And no, it does not follow IEC requirements either

3.1 Term 1

Emptying predefined text

If you want to prevent the default predefined text from appearing, you can do so by providing an empty predefined text subclause.

== Terms and definitions

[.boilerplate]
=== {blank}

=== Term 1

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 Metanorma 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.)

[.source]
<<ievtermbank,clause="103-01-02">>

...

[bibliography]
* [[[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 <<ievtermbank,clause="103-01-02">> for IEV 103-01-02.

Title

A Terms and Definitions clause will be recognized if either Terms, definitions, symbols and abbreviated terms or Terms and definitions is given as the title, regardless of case.

Source

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 predefined text of the Terms and Definitions section is adjusted accordingly.

[source=ISO712]
== Terms and Definitions

renders as

Illustration of predefined text of the Terms and Definitions section adjusted with a single source ("ISO 712")
Figure 4. Illustration of predefined text of the Terms and Definitions section adjusted with a single source (“ISO 712”).

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

[source="ISO712,ISO24333"]
== Terms and Definitions

which renders as

Illustration of predefined text of the Terms and Definitions section adjusted with two sources
Figure 5. Illustration of predefined text of the Terms and Definitions section adjusted with two sources (“ISO 712 and ISO 24333:2009”).

Markup within term macros

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

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

term:[rice] from which the husk only has been removed

Stem expressions

AsciiDoc does not permit macros to be nested inside other macros.

Therefore the following markup which introduces a stem expression as an admitted term, is considered illegal.

Note
The use of stem expressions as preferred terms is not a problem, because the macro appears as a header.
Bad example
=== stem:[t_90]
alt:[stem:[t_A]]

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]

stem:[t_A]

Time to launch.
Illustration of a term that uses stem expressions
Figure 6. Illustration of a term that uses stem expressions.

Subclauses

Any clause within a “Terms & Definitions” section which is a non-terminal subclause (has child nodes) is automatically considered 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-term section

All terminal subclauses of a term section (i.e. clauses that have no subclauses of their own) are treated as term definitions.

We have already seen one exception to this, in [.boilerplate] clauses. More generally, an introductory section can be treated as a subclause instead of a term (and will retain its status as a subclause), by prefixing it with the style attribute [.nonterm]:

== Terms and definitions

[.nonterm]
=== Terms defined in ISO 10303-1

For the purpose of this part of ISO 10303, the following terms
defined in ISO 10303-1 apply:

* integrated resource

[.nonterm]
=== Terms defined in ISO 10303-11

For the purposes of this document, the following terms defined in
ISO 10303-11 apply.

* entity;
* entity data type;
Inclusion of non-term subclauses
Figure 7. Inclusion of non-term subclauses using the [.nonterm] attribute

The [.nonterm] attribute must only be used in subclauses that do not contain any terms underneath (like the example above). Otherwise, these terms will not be processed following the corresponding formatting rules.

EXAMPLE: If the [.nonterm] attribute is applied to a term-containing subclause, the wrong rendering will occur:

== Terms and definitions

[.nonterm]
=== Terms defined in ISO 10303-1

For the purpose of this part of ISO 10303, the following terms
defined in ISO 10303-1 apply:

==== actual function range
mathematical space containing precisely the tuples of outputs from
the function which are related to some tuple of inputs
Incorrect rendering of a term subclause
Figure 8. Incorrect rendering of a term subclause due to wrong application of [.nonterm]

Therefore the [.nonterm] attribute must be removed:

== Terms and definitions

=== Terms defined in ISO 10303-1

For the purpose of this part of ISO 10303, the following terms
defined in ISO 10303-1 apply:

==== actual function range
mathematical space containing precisely the tuples of outputs from
the function which are related to some tuple of inputs
Proper rendering of a term subclause
Figure 9. Proper rendering of a term subclause

Citing terms

General

Instances of terms in the body of the document can be marked up to indicate where the term is defined. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.14].

This can be done whether the term is defined:

  • in the current document;

  • in a cited document; or

  • in an external termbase.

Marking up term instances does not currently have any impact on how they are rendered: this markup is intended for semantic processing of standards documents.

The following syntax is used:

{{identifier,term}}

// if the display text differs from the cited term
{{identifier,term,text}}

The {{identifier,term,text}} markup is analogous to the markup of cross-references in AsciiDoc, <<anchor,text>>, and consists of:

  • An identifier for the term being cited;

  • The term cited;

  • The text to be displayed, if it is distinct from the cited term.

Term defined within current document

If the term is defined within the current document, the term citation gives the anchor of the term definition in the document, the canonical term name, and optionally the text to be displayed.

The anchor is converted into a document cross-reference in Metanorma XML.

The syntax is:

{{local-anchor,term}}

// if the display text differs from the cited term
{{local-anchor,text,term}}

EXAMPLE:

== Terms and definitions

[[immatk]]
=== immature kernel
alt:[unripe kernel]

kernel, whole or broken, which is unripe and/or underdeveloped

== Discussion
The source of the {{immatk,immature kernel}} has not yet been identified.
Allusions to {{immatk,unripe kernels,immature kernel}} are plentiful in
the literature.

Term defined in external document

If the term is defined in an external document, which has a corresponding bibliographic anchor, the term citation gives the bibliographic anchor of the term definition in that document, the canonical term name, and optionally the text to be displayed.

In other words, the same arguments are used as for the internal cross-reference, except that a bibliographic anchor substitutes the internal anchor. The bibliographic anchor is converted into a citation in the Metanorma XML.

The syntax is:

{{bibliographic-anchor,term}}

// if the display text differs from the cited term
{{bibliographic-anchor,text,term}}

EXAMPLE:

[bibliography]
== Normative References
* [[[iso17301,ISO 17301]]] Cereals and pulses -- Specifications and test methods -- Rice

== Discussion
The source of the {{iso17301,immature kernel}} has not yet been identified.
Allusions to {{iso17301,unripe kernels,immature kernel}} are plentiful in
the literature.

As with citation markup, the bibliographic-anchor element can be supplemented by a comma-delimited list of localities and locality values.

EXAMPLE:

[bibliography]
== Normative References
* [[[iso17301,ISO 17301]]] Cereals and pulses -- Specifications and test methods -- Rice

== Discussion
The source of the {{iso17301,clause=3.9,immature kernel}} has not yet been identified.
Allusions to {{iso17301,clause=3.9,unripe kernels,immature kernel}} are plentiful in
the literature.

Term defined in external termbase

If the term is defined in an external termbase, the term is identified as the termbase identifier, then colon, then the identifier for the term within the termbase.

Because colons are not permitted in cross-references or bibliographic anchors, the presence of a colon identifies the first argument in a term citation as identifying an external termbase term. The other two arguments of the macro are as above, the canonical term name, and optionally the text to be displayed. There is no expectation that the termbase be included in the bibliography.

{{termbase-anchor,term}}

// if the display text differs from the cited term
{{termbase-anchor,text,term}}

The termbase-anchor is implementation-specific. Currently, only the IEC’s Electropedia (IEV) is supported, where the reference syntax is IEV:{IEV term ID}.

{{IEV:IEV-term-ID,term}}

// if the display text differs from the cited term
{{IEV:IEV-term-ID,text,term}}

EXAMPLE:

== Discussion
The source of the {{IEV:171-05-02,immature kernel}} has not yet been identified.
Allusions to {{IEV:171-05-02,unripe kernels,immature kernel}} are plentiful in
the literature.