Concepts, designations, terms and definitions

General

In many standards organizations, a dedicated "Terms and definitions" section is included in their documents in order to provide a local dictionary containing definitions for terms used within a document.

This dictionary can be considered a "concept collection" or a "concept dictionary".

Some organizations allow the specification of more than one "terms and definitions" section, for example, in order to separate normative and informative concepts.

There are multiple possibilities when managing these concepts:

  • all concepts are defined locally in the document;

  • some concepts are locally defined while some are externally sourced

  • all concepts are sourced from one or more external entries (e.g. a termbase, a document)

Working with a concept collection within Metanorma requires understanding the following topics that are explained below:

  1. How to work with a concept collection;

  2. How to work with individual concepts.

Working with a concept collection

Basics

To create a concept collection, commonly understood as a "terms and definitions section" within Metanorma, all you need is to apply the correct title for a section heading. Metanorma will be able to insert that in the correct location in the resulting document.

Take ISO for example, its “Terms and definitions” clause is always at Clause 3 according to the ISO DIR 2. Regardless where the "Terms and definitions" clause is defined, it will always be rendered at Clause 3.

Example 1. Creating a terms and definitions clause in Metanorma ISO
== Terms and Definitions

renders as

3. Terms and definitions

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

Notice that in Metanorma ISO, there is predefined text that is automatically generated, not entered by the user. This is also the case for many standards bodies that specify rules for document structure.

Clause title

A terms and definitions clause will be recognized if either title below is given regardless of case:

  • Terms and definitions;

  • Terms, definitions and symbols;

  • Terms, definitions and abbreviated terms; or

  • Terms, definitions, symbols and abbreviated terms

Note
This behavior differs across standard flavors; please refer to specific documentation for a particular flavor.

Concept source

If the concepts of a standard are partly or fully sourced from an external document or collection, that external item is cited in a source attribute to the section.

The syntax to apply one or more concept sources is as follows:

[source=REFERENCE_ANCHOR]
== Terms and definitions

Where the REFERENCE_ANCHOR is the reference anchor of the cited item. The definition of this cited reference item is typically entered under the "Normative references" clause.

Note
The source 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.

Example 2. Setting ISO 712 as a terminology source for the concepts collection
[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 1. Illustration of predefined text of the Terms and Definitions section adjusted with a single source (“ISO 712”).

Multiple sources are allowed. The sources are to be quoted into a single value, and delimited by commas.

[source="REFERENCE_ANCHOR1,REFERENCE_ANCHOR_2"]
== Terms and definitions
Example 3. Setting multiple terminology sources for the terms and definitions clause
[source="ISO712,ISO24333"]
== Terms and Definitions

which renders as

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

Predefined text / Boilerplate

Appending to predefined text

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

Such predefined text typically serve the following purposes:

  • indicate provenance of definitions (see Concept source); and

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

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

Note
Behavior prior to release metanorma-standoc 1.7.0 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:

Example 4. Appended predefined text
== 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 from 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:

Example 5. Overridden predefined text
== 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:

Rendering of overriden predefined text

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.

Example 6. Emptying predefined text
== Terms and definitions

[.boilerplate]
=== {blank}

=== Term 1

Subclauses

Concept grouping subclauses

Any clause within a “Terms and 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 clause

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]:

Example 7. Providing an introductory non-term clause
== Terms and definitions

[.nonterm]
=== Terms from ISO 10303-1

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

* integrated resource

[.nonterm]
=== Terms from ISO 10303-11

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

* entity;
* entity data type;
Inclusion of non-term subclauses
Figure 3. 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 8. Non-term attribute wrongly applied to a term-containing subclause

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

== Terms and definitions

[.nonterm]
=== Terms from ISO 10303-1

For the purpose of this part of ISO 10303, the following terms
from 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 4. Incorrect rendering of a term subclause due to wrong application of [.nonterm]

Therefore the [.nonterm] attribute must be removed:

== Terms and definitions

=== Terms from ISO 10303-1

For the purpose of this part of ISO 10303, the following terms
from 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 5. Proper rendering of a term subclause

Working with individual concepts

General

Concepts entered within “terms and definitions” sections follow a strict data input scheme:

  • 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 is optionally followed by alternative/admitted terms, which must be marked up in an alt:[...] command; deprecated terms, which must be marked up in a deprecated:[...] command; and a term domain, which must be marked up in a domain:[...] command.

  • 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 source is a citation cross-reference to a normative reference, optionally followed by a comma and a modification if applicable. If the comma is appended without text, then the term will be shown as modified, with no specific modification.

Note
A term can be cross-referenced from other terms, through the smart terms reference mechanism or by assigning an anchor.
Example 9. Defining a term
=== 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 6. 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 10. Using many term options, with examples, notes and source
[[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 7. Example of a single term with elaborated specifications

Domain, subject and usage information

Domain, subject and usage information apply to concepts as described in ISO 10241-1.

Concepts can be provided with extended metadata in a definition list, after the term subheading, marked with the option attribute [%metadata] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].

The following keys are allowed:

domain

The domain of the term

subject

The subject of the term

usageinfo

Usage information about the term

Example 11. Concept with domain, subject and usage information
== Terms and definitions
=== Term 1

[%metadata]
domain:: hydraulics
subject:: pipes
usageinfo::
+
---
Usage depends on precedent.

Refer to your local standards body.
---

Designations

General

A designation is the cover term for names of concepts that are included in terms.

It covers:

  • the preferred name (displayed as the heading for the term);

  • the alternative or admitted names (specified as admitted:[…​] or alt:[…​]), and

  • the deprecated names (specified as deprecated:[…​]).

Preferred designations

The first preferred designation is specified as a section heading under the “Terms and definitions” clause.

Example 12. A single preferred designation
== Terms and definitions

=== application

one or more processes creating or using product data

Metanorma allows specifying multiple preferred designations [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].

Each designation in Metanorma AsciiDoc must appear in its own paragraph.

Note
Some standards bodies do not allow multiple preferred designations.

The preferred:[…​] command can be used to specify additional designations for the second and subsequent designations.

By default, they will be rendered in the same term title as the first preferred designation, delimited by semicolons.

Example 13. Applying multiple preferred designations
== Terms and definitions

=== application
preferred:[app]

one or more processes creating or using product data
Admitted designations

Admitted designations, also called alternative designations, are entered using the command admitted:[…​] (or alt:[…​]).

Example 14. Example from ISO 10303-2
=== application interpreted model
admitted:[AIM]

information model that includes the application constructs necessary to satisfy
the requirements of an application reference model
Deprecated designations

Deprecated designations are entered using the deprecated:[…​] command.

Example 15. Example from ISO 10303-2
=== business object model
deprecated:[BO Model]

single integrated information model for the scope of an AP
Designation metadata

Metadata about designations can be given in a definition list, immediately after the definition of the designation (including the term subheading), marked with option attribute [%metadata] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].

The following keys are supported:

language

the language of the designation. Specified as an ISO 639-* code.

script

the script of the designation. Specified as an ISO 15924 code.

geographicArea

the geographic area of the designation. Specified as an ISO 3166-1 code.

type

type of expression used as designation; supported values are

  • prefix

  • suffix

  • abbreviation

  • full

isInternational

designation is valid across languages and country; value is boolean

abbreviationType

type of abbreviation used; supported values are:

  • truncation

  • acronym

  • initialism

pronunciation

guide to pronunciation for designation; accepts a string value

absent

the designation is absent; value is boolean

letter-symbol

the designation is not a linguistic expression, but a letter or symbol; value is boolean

Grammar of the designation is encoded as keys within the tag grammar:

grammar
gender

the gender of the designation. Multiple values are allowed, comma delimited. Supported values are:

  • masculine

  • feminine

  • neuter

  • common.

isPreposition

the designation is a preposition; value is boolean

isParticiple

the designation is a participle; value is boolean

isAdjective

the designation is an adjective; value is boolean

isVerb

the designation is a verb; value is boolean

isAdverb

the designation is an adverb; value is boolean

isNoun

the designation is a noun; value is boolean

grammarValue

other miscellaneous grammatical information

Example 16. Encoding designation metadata for multiple designations
== Terms and definitions
=== Term 1

[%metadata]
language:: eng

admitted:[Alternative term name]

[%metadata]
script:: Hans

deprecated:[Deprecated term name]

[%metadata]
type:: full
language: fre
grammar::
gender::: masculine, feminine

The metadata for a term, discussed immediately above, is given in the same definition list as the metadata about the first preferred designation, which is given in the term header.

Empty designations

A designation can be empty:

Example 17. Providing an empty designation
== Terms and definitions
=== {blank}

admitted:[]
Note
This is supported in ISO 10241-1.
Non-verbal designations / representations

A figure or formula can be used instead of a verbal expression, provided it immediately follows a blank designation, before any metadata definition list.

Example 18. Providing one or more non-verbal designations
== Terms and definitions
=== {blank}

[stem]
++++
t_90
++++

admitted:[]

....
ASCII ART
....
Note
This is supported in ISO 10241-1.

Definitions

Multiple definitions

A term may have multiple definitions, where each definition could have its own source.

Metanorma allows the encoding of this more complex structure through embedding each distinct definition within an open block, with a [.definition] role attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6].

Example 19. Multiple definitions for one designation
=== widget

alt:[doohickey]

[.definition]
--
device performing an unspecified function

[.source]
<<ISO2382,clause 2121372>>
--

[.definition]
--
general metasyntactic variable

[.source]
<<ISO2382,clause 2121373>>
--

Multiple definitions are rendered in Metanorma as an ordered list of definitions:

Rendering of multiple definitions for one designation

widget

doohickey

  1. device performing an unspecified function [SOURCE: ISO 2382, 2121372]

  2. general metasyntactic variable [SOURCE: ISO 2382, 2121373]

Non-verbal representation of definitions

This notation can also be used to incorporate non-verbal representations of terms, including tables, formulas, and figures, which can be given after or instead of a verbal definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].

Verbal definitions and non-verbal representations can be given term sources separately:

Example 20. Verbal definitions and non-verbal representations
=== widget

alt:[doohickey]

[.definition]
--
device performing an unspecified function

[.source]
<<ISO2382,clause 2121372>>

|===
| A | B

| C | D
|===

[.source]
<<ISO2382,clause 2121373>>
--

Sourcing individual concepts

General

By default, term sources are considered authoritative, and are of either identical or modified status, depending on whether modification text is provided after a citation.

Modifying sourced concepts

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

Example 21. Indicating a modified definition without further qualification
[.source]
<<ISO7301,section 3.2>>,

renders as

Example of a single source tagged as modified
Figure 8. 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 22. A term and definition originating from multiple sources
[.source]
<<ISO7301,section 3.2>>,

[.source]
<<ISO7302,section 3.10>>,
Sourcing concepts from termbases

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 23. An IEC Electropedia (IEV) reference

IEC 60050-113:2011, 113-01-07

In some cases, like ISO/IEC 2382, terminological clauses are numbered as plain numbers without character separators (dashes or periods).

In ISO, terminological entries are technically identified by identifiers, not clauses.

However, when the location is cited as a number, Metanorma will consider the location a top-level clause, which will be represented in the ISO style “Clause X”, instead of the desired “X”.

Example 24. Indicating a modified definition with qualification
[.source]
<<ISO2382,clause 2121372>>, Notes to entry and accepted term
"`computer program`" have been omitted.

In this case, we will have to apply additional markup to indicate the number is not a top-level clause using the droploc% flag.

Example 25. Dropping the "clause" keyword for non-clause
[.source]
<<ISO2382,droploc%clause 2121372>>, Notes to entry and accepted term
"`computer program`" have been omitted.

droploc% serves as an indication for Metanorma not to prepend the number with the location type of “Clause”.

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.

Note
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.

Complex source attributes

Concept sources can be further qualified other than the simple identical or modified statuses by adding explicit status and type attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].

The following attributes are supported for a concept source entry.

status
identical

The managed term in the present context is identical to the term as found in the bibliographic source.

modified

The managed term in the present context has been modified from the term as found in the bibliographic source.

restyled

The managed term in the present context has been restyled from the term as found in the bibliographic source.

context-added

The managed term in the present context has had context added to it, relative to the term as found in the bibliographic source.

generalisation

The managed term in the present context is a generalisation of the term as found in the bibliographic source.

specialisation

The managed term in the present context is a specialisation of the term as found in the bibliographic source.

unspecified

The managed term in the present context is in an unspecified relation to the term as found in the bibliographic source.

type
authoritative

The managed term is authoritative in the present context.

lineage

The managed term constitutes lineage in the present context.

Example 26. Specifying a complex term source
=== widget

device performing an unspecified function

[.source,type=lineage,status=generalisation]
<<ISO2382,clause 2121372>>

Term sources may apply designations instead of the entire term. This is done by placing the term source after the designation, and any metadata definition list describing the designation.

Term sources applying to the entire term are placed at the end of the term clause.

Example 27. Specifying individual term sources for multiple definitions
=== widget

alt:[doohickey]

[.source]
<<ISO2382,clause 3>>

device performing an unspecified function

[.source,type=lineage,status=generalisation]
<<ISO2382,clause 2121372>>

Rich-text within term commands

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

Example 28. Encoding markup within term commands
=== 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.
Example 29. Bad stem 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:

Example 30. Good stem example
=== stem:[t_90]

stem:[t_A]

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

Referencing concepts

General

Instances of terms, symbols or abbreviations used in the document can be marked up to indicate the semantic meaning of the concept. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.14].

This can be done whether the concept is defined:

  • in the current document;

  • in an external, cited document; or

  • in an external termbase.

Marking up mentions of concepts (terms, symbols, or abbreviations) in the content body generally does not impact their rendering.

This tagging is intended for semantic processing of standards documents in Metanorma Semantic XML.

Marking up term instances in the “terms and definitions” clauses may cause terms to render differently in certain flavors, such as for ISO and IEC, in order to display location of where those concepts are defined.

Note
The syntax for citing terms has been changed for v1.10.0. This section describes the current syntax [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.0].

The generic syntax is shown here.

{{<<identifier>>,term,display-text,cross-reference-text,options="..."}}

In this full form of the syntax, only the term argument is mandatory.

All of the following variants below are supported:

{{term}}                // or synonym: term:[term]
// Used if the concept is defined in the current document.

{{term,display-text}}   // or synonym: term:[term,display-text]
// Used if the concept is defined in the current document, and the desired
// display text differs from the concept term.

{{term,display-text,cross-reference}}
{{term,display-text,cross-reference,options="..."}}

{{<<identifier>>,term}}
{{<<identifier>>,term,display-text}}
{{<<identifier>>,term,display-text,cross-reference-text}}
{{<<identifier>>,term,display-text,cross-reference-text,options="..."}}
  • identifier: an identifier for the term being cited (optional).

  • term: the term cited, in its canonical form (mandatory).

  • display-text: text to be displayed, if it is distinct from the cited term (optional). If this argument is not provided, the canonical form and the display text are assumed to be identical.

  • cross-reference-text: text to display for the cross-reference to the concept definition (optional). If this argument is not provided, the default rendering of the cross-reference for the current Metanorma flavour is provided.

  • options: options that determine how the concept is to be displayed (may be flavour-specific).

Note
The {{[identifier],term,display-text,cross-reference,options=".."}} markup closely mirrors the markup syntax of cross-references in Metanorma AsciiDoc (<<anchor,%option,text>>).

Instances of cited terms are converted into a distinct concept element in Metanorma Semantic XML, which includes a cross-reference to the term definition, the canonical form of the term name, and the text to be displayed for the term in that instance.

Concepts defined within current document

Reference by term

To cite a concept defined within a document the following syntax can be used.

Syntax:

// The term is from the current document as a concept.
{{term}}
// or synonym:
term:[term]

// If the desired display text differs from the concept term.
{{term,display-text}}
// or synonym:
term:[term,display-text]

// If a specific version of the cross-reference text is required.
{{term,display-text,cross-reference-text}}

term in concept syntax is matched against any of the preferred terms in the document, but the wording of term is expected to be an exact match.

Note
Metanorma automatically creates anchor references for every concept from the document, which is used when referencing by term.
Example 31. Example from ISO/IEC Directives Part 2 (2020), 16.5.10
== Terms and definitions

=== terminological data
....

=== concept
...

=== terminological entry

part of a terminological data collection which contains the
{{terminological data}} related to one {{concept}}

// equivalent:
part of a terminological data collection which contains the
term:[terminological data] related to one term:[concept]

This will be displayed according to the flavour; the rendering typically contains the term text, and a cross-reference to its definition. Any hyperlinking is done on the cross-reference.

The default Metanorma rendering would look like:

part of a terminological data collection which contains the terminological data [term defined in Clause 3.1] related to one concept [term defined in Clause 3.2]

In the ISO flavour of Metanorma, and flavours derived from it, the rendering follows ISO conventions:

part of a terminological data collection which contains the terminological data (3.1) related to one concept (3.2)

In some cases, the displayed term is a variant of the referenced term, such as its plural form. That means that the display text needs to be differentiated from the referenced term.

Example 32. Example from ISO 8601:2019, 3.1.1.5
===== instant
...

===== time axis
...

===== time scale

system of ordered marks which can be attributed to {{instant, instants}} on the
{{time axis}}, one instant being chosen as the origin

// equivalent:

system of ordered marks which can be attributed to term:[instant, instants] on
the term:[time axis], one instant being chosen as the origin

In the rendering, the display text is used instead of the referenced term:

Rendering of ISO 8601:2019, 3.1.1.5

system of ordered marks which can be attributed to instants (3.7) on the time axis (3.9), one instant being chosen as the origin

It is conceivable that authors will want to override the automatically-generated cross-reference text with their own text, as is already possible for cross-references within Metanorma.

This requires an expanded version of the expression:

===== instant
...

===== time axis
...

===== time scale

system of ordered marks which can be attributed to {{instant, instants}} on the
{{time axis,time axis,see the preceding discussion}}, one instant being chosen
as the origin

Renders into:

Rendering of ISO 8601:2019, 3.1.1.5 with custom text

system of ordered marks which can be attributed to instants (3.7) on the time axis (see the preceding discussion), one instant being chosen as the origin

Note

The terms reference capability relies on automatically created anchor references for every term defined.

For example, in the following text,

== Terms and definitions
=== Foo

bar

=== Lor

special kind of term:[foo]

the anchors [[term-foo]] and [[term-lor]] are automatically created and assigned to the terms 'foo` and lor.

These anchors are generated from the terms themselves according to these rules:

  • the terms are lowercased;

  • non-ASCII characters are stripped;

  • whitespaces are replaced by -.

This means if you wanted to refer to a particular term from body text, you could either:

  • directly refer to the term: e.g., see definition of term:[foo]

  • refer to the anchor of the term: e.g., the topic is further explained in <<term-foo>>

In case you have created manual anchors that conflict with [[term-{X}]], the term reference mechanism is smart enough to rename the generated anchor as [[term-{X}-{n}]], where n is a number from 1, and so forth.

Therefore this will still work as expected:

== Terms and definitions
=== Foo
bar

=== Lor
special kind of term:[foo]

[[term-foo]]
== My section

lorem
Reference by symbol

Symbols and abbreviated terms defined in the document can also be cited as concepts [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1].

In the case of symbols and abbreviated terms, the symbol:[] macro is used instead of term:[], and targets a symbol defined in a definition list within the “Symbols and abbreviated terms” section.

Note
Such symbols have automatic anchors assigned to them, as with terms, but prefixed with symbol- rather than term-. If the {{…​}} format is used instead, either a term or a symbol is matched; terms are matched by default.
Example 33. Citing concepts in content body do not get rendered
== Symbols and abbreviated terms

ISO:: International Standards Organization // automatically assigned the anchor `symbol-ISO`
[[xyz]]IEC:: International Electrotechnical Commission // is assigned the anchor `xyz`

== Discussion
The vocabulary is authorised by {{ISO}} and {{IEC,the IEC}}.

// equivalent to the sentence above
The vocabulary is authorised by symbol:[ISO] and symbol:[IEC,the IEC].

Unlike terms, symbols and abbreviations are not italicised, referenced, or hyperlinked by default.

The vocabulary is authorised by ISO and IEC.

Reference by anchor

In certain cases it is more appropriate to reference a concept (defined in the current document) by anchor, instead of by term, e.g.:

  • the defined term is not plain text, e.g., a math formula;

  • the defined term is long in length.

To reference a concept by anchor, the anchor of the concept should be provided, and optionally the text to be displayed. The anchor must be given in angle brackets, like a normal cross-reference in Metanorma AsciiDoc.

The following elements are needed to make this inference:

  • anchor of the concept;

  • (optional) text to be displayed.

The syntax is:

// The concept is from the current document, but a manual anchor has been
// created for referencing it as a shorthand, useful in the case where a
// concept term is not in plain text (e.g. MathML).
{{<<identifier>>}}

// If the display text differs from the cited concept term, referred through
// an anchor.
{{<<identifier>>,display-text}}

// If the display text differs from the cited concept term, referred through
// an anchor, and we also want to provide a canonical name for the term.
{{<<identifier>>,canonical-term,display-text}}
Example 34. Referencing concepts by anchors
== 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.

Concepts from external documents

To refer to concepts from an external document requires a corresponding bibliographic anchor for that document. The identifier for the concept is then given in the same fashion as any citation of an external document.

The following elements are needed to make this inference:

  • bibliographic anchor of the external document, optionally including the locality of the term definition in that document;

  • concept term name;

  • (optional) text to be displayed;

  • (optional) cross-reference text to be displayed.

The syntax is:

// The concept is from the current document but a manual anchor has been
// created for referencing it as a shorthand, useful in the case where a
// concept term is not in plain text (e.g. MathML).
{{<<bibliographic-anchor>>,term}}

// If the display text differs from the cited concept term, referred through
// an anchor.
{{<<bibliographic-anchor>>,term,display-text}}

// If the cross-reference text for the external document needs to be overriden.
{{<<bibliographic-anchor>>,term,display-text,cross-reference-text}}
[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>>,immature kernel,unripe kernels}} are plentiful in
the literature.

In Metanorma, this will be displayed by default as:

The source of the immature kernel [term defined in ISO 17301] has not yet been identified. Allusions to unripe kernels [term defined in ISO 17301] are plentiful in the literature.

Note
Metanorma Semantic XML preserves the information that the latter term is cited as unripe kernels, but is defined as immature kernel. However by default, only the display text is rendered.

To supplement the concept reference with a locality, the bibliographic-anchor element can be supplemented by a comma-delimited list of localities and locality values, as is normal for a reference to a locality in an external document.

The syntax is:

{{<<bibliographic-anchor,locality=X>>,term}}

// Simple example:
{{<<iso639-1,clause=3.1>>,language}}

// If the display text differs from the cited term:
{{<<bibliographic-anchor,locality1=X>>,term,display-text}}

// Multiple localities can be used:
{{<<bibliographic-anchor,clause=4.7,table=1>>,display-text}}
[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.

In Metanorma, this will be displayed by default as:

The source of the immature kernel [term defined in ISO 17301, Clause 3.9] has not yet been identified. Allusions to unripe kernels [term defined in ISO 17301, Clause 3.9] are plentiful in the literature.

Concepts from external termbase

To refer to a concept from an external termbase, the termbase identifier and the concept identifier within that termbase are needed.

The following elements are needed to make this inference:

  • termbase identifier;

  • concept identifier within that termbase;

  • (optional) text to be displayed for the term;

  • (optional) text to be displayed for the termbase reference.

Note
The presence of a colon identifies the first argument in a term citation as identifying an external termbase term, since colons are not permitted in cross-references or bibliographic anchors.
Note
Termbase identifiers are treated as special anchors, they do not need to be defined using a bibliographic reference anchor.

The syntax is as follows:

{{termbase-id:concept-id,term}}

// If the display text differs from the cited concept term.
{{termbase-id:concept-id,term,display-text}}

// If the text of the cross-reference to the termbase needs to be overridden.
{{termbase-id:concept-id,term,display-text,cross-reference-text}}
Note
The termbase does not require a corresponding reference in the bibliography.

Currently, only the IEC Electropedia (IEV) is supported, where the reference syntax is [IEV:{IEV concept ID}].

// Not necessary to define the IEV bibliographic anchor.
{{<<IEV:IEV-concept-ID>>,term}}

// If the display text differs from the cited concept term.
{{<<IEV:IEV-concept-ID>>,text,display-term}}

// If the IEV citation text differs from the flavour default.
{{<<IEV:IEV-concept-ID>>,text,display-term,cross-reference-text}}
Example 35. Citing termbase concepts
== 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,ibid.}} are plentiful in
the literature.

In Metanorma, this will be displayed by default as:

Rendering of cited termbase concepts

The source of the immature kernel [term defined in IEV 171-05-02] has not yet been identified. Allusions to unripe kernels [ibid.] are plentiful in the literature.

Rendering options

The following rendering options, introduced with options="…​", are defined for concept mentions.

ital

italicise the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1]

ref

provide a reference for the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1]

noital

do not italicise the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1]

noref

do not provide a reference for the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1]

linkmention

hyperlink the rendered term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6]

nolinkmention

do not hyperlink the rendered term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6]

linkref

hyperlink the reference for the term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6]

nolinkref

do not hyperlink the reference for the term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6]

If these options are missing, Metanorma applies the defaults for the current flavour.

The default behaviour in Metanorma is ital,ref,nolinkmention,linkref for all terms, noital,noref,nolinkmention,nolinkref for acronyms.

In ISO, the default behaviour for terms is refined:

  • for terms outside the “Terms and definitions” section: noital,noref,nolinkmention,nolinkref;

  • for the first mention of a term within the “Terms and definitions” section: ital,ref,nolinkmention,linkref;

  • for all subsequent mentions within the “Terms and definitions” section: ital,noref,nolinkmention,linkref.

Example 36. Using cited concepts with various options
== Discussion

The source of the {{<<IEV:171-05-02>>,immature kernel,options="noital"}} has not yet been identified.
Allusions to {{<<IEV:171-05-02>>,unripe kernels,immature kernel,ibid.,options="noref"}} are plentiful in
the literature. Allusions to {{<<IEV:171-05-02>>,non-ripe kernels,immature kernel,ibid.,options="noref,noital"}}
are rather less frequent.

In Metanorma, this will be displayed by default as:

Rendering of cited concepts with various options

The source of the immature kernel [term defined in IEV 171-05-02] has not yet been identified. Allusions to unripe kernels are plentiful in the literature. Allusions to non-ripe kernels are rather less frequent.

In flavours that customise concept rendering, these options override the behaviour of whatever the flavour implements.