Terms

Defining Terms: 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. If the comma is used on its own, then the term will be shown as modified, with no specific modification.

For 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

Alternatively, the following will just show the source as "modified", with no further detail:

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

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.

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

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

[source=ISO712]
== Terms and Definitions

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

[source="ISO712,ISO24333"]
== 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]
domain:[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]
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.

Subclauses

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

[.nonterm]
=== 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

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, 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 crossreference in the Metanorma XML.

The syntax is:

{{local-anchor,term}}

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

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,immature kernel,unripe kernels}} 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 crossreference, 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,term,text}}

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,immature kernel,unripe kernels}} are plentiful in
the literature.

As with citation markup, the bibliographic-anchor element can be supplemented by 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,immature kernel,unripe kernels}} 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 crossreferences 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,term,text}}

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,term,text}}

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.