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:
- How to work with a concept collection;
- 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.
== Terms and Definitionsrenders as
*3. Terms and definitions*
ISO and IEC maintain terminological databases for use in standardization at the following addresses:
- ISO Online browsing platform: available at http://www.iso.org/obp[]
- IEC Electropedia: available at http://www.electropedia.org[]
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
It is recommended to use the "Terms and definitions" title for the clause heading regardless of the content contained -- Metanorma will automatically render the correct clause title. This is demonstrated in clause-title-example.
.Automatic generation of "Terms and definitions" title depending on content
This encoding:
== Terms and definitions
=== Terms and definitions
==== beef
...
=== Abbreviated terms
foo:: barWill generate the following structure with the correct clause title:
3 Terms, definitions and abbreviated terms
3.1 Terms and definitions
3.1.1 beef ...
3.2 Abbreviated terms
foo: bar
Automated titles will only be generated if the terms & definitions clause and its immediate children are exhaustively covered by the possibilities above: each child element is either a definitions clause or a terms collection, or initial boilerplate text, and there is only one of each type or combination of types. If there are other clauses mixed in, or if there are multiple collections of terms, Metanorma will not replace the terms, because its replacements will likely not be true; for example, if there are two subclauses containing terms, no one subclause should be named "Terms and definitions" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.2].
To force an override this behaviour, and retain the terms and definitions title as given, use the keeptitle=true attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.6].
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 definitionsWhere 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.
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.
[source=ISO712]
== Terms and Definitionsrenders as
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[source="ISO712,ISO24333"]
== Terms and Definitionswhich renders as
Predefined text / Boilerplate
Location of 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 source); and
- provide the location where definitions may be consulted, depending on the flavour.
The predefined text, by default, is placed in the first clause that either contains terms, or is titled as a terms collection.
If a clause contains a terms collection, but is not titled as one, the predefined text moves down to the terms collection; that is to deal with terms collections contained in miscellaneous clauses which contain both terms and extraneous content [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12].
== Terms and definitions
// boilerplate goes here
=== Term 1== Terms and definitions
// boilerplate goes here
=== Normal terms
==== Term 1
=== Other terms
==== Term 2== General
=== Scope
=== Terms and definitions
// boilerplate goes here
==== Term 1
=== MethodologyIn ISO-based flavours, the predefined text is placed as above, but not in a clause that contains both terms collections and symbols or abbreviations.
[heading=terms, definitions and symbols]
== ISO Terms, definitions and symbols
=== Terms and definitions
// boilerplate goes here
==== Term 1
=== SymbolsAppending to predefined text
Any paragraphs or lists found where the predefined text should go 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].
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:
.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 1In 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:
- ISO Online browsing platform: available at http://www.iso.org/obp[]
- IEC Electropedia: available at http://www.electropedia.org[]
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 open block with the style attribute [.boilerplate] can be used to do so [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.0].
(Formerly, a clause with that style attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0].)
Input:
.Overridden predefined text
== Terms and definitions
[.boilerplate]
--
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 1Where:
- 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 open block.
.Emptying predefined text
== Terms and definitions
[.boilerplate]=== Term 1
Moving predefined text
To move the default predefined text elsewhere from where Metanorma calculates it should be, set the content of the boilerplate block as (default)
The (default) text will be overwritten with the correct predefined text, and that text will not appear elsewhere [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12].
== General
=== Scope
=== Terms and definitions
// boilerplate should go here
==== Term 1
[.boilerplate]
--
(default)
--
// boilerplate goes here
=== MethodologySubclauses
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, and any descendant of a [.terms] clause is by default a term (see below).
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]:
.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;
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.
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
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
Empty terms collections
A top-level empty terms collection, with no term subclauses inside it, will be recognised by Metanorma as such by default:
== Terms and definitions
== Next ClauseHowever, a subclause within a terms collection, intended to be an empty terms collection itself, needs special markup, just as a nonterm clause does, in order not to be processed as a single term.
To declare a subclause as an empty terms collection, the style attribute [.terms] is used.
[.terms] is intended to mirror [.nonterm] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.4.5].== Terms and definitions
=== I am a term
=== I am a terms collection
==== Because I contain at least one term
[.terms]
=== I am an empty terms collectionWorking 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). That subheading has as its content a preferred designation for the term (designations).
- The term is followed by other designations:
- preferred (
+preferred:[...]+);- admitted (
+admitted:[...]+or+...+); and - deprecated (
+...+).
- admitted (
- The term is optionally followed by related terms, which are marked up with
+related:[...]+commands. These are cross-references that are expected to be defined elsewhere, by contrast with the other designations, which are defined within the current entry. - The term can also be followed by other metadata, including the term domain, which must be marked up in a
+...+command. Much of this metadata is formatted through a%metadatadefinition list (see metadata). - 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.
.Defining a term "approximate date" (ISO 8601-2, 3.1.1.1)
=== approximate date
calendar date which is an estimate whose value is asserted to be possibly correct
NOTE: The degree of confidence in approximation depends on the application.renders as
.Defining a term "instant" (ISO 8601-1, 3.1.1.3)
=== instant
point on the {{time axis}}
NOTE: An instantaneous event occurs at a specific instant.
[.source]
<<ievtermbank,clause "113-01-08">>
....
[bibliography]
== Normative References
* [[[ievtermbank,IEV]]]renders as
More complex concepts can also be specified, with alternative terms, deprecated terms, related terms, domain, examples and a definition modified from its original source. On providing more extensive metadata about concepts, see metadata.
.Defining a term with additional 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
Domain and subject
Domain and subject 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
.Concept with domain, subject and usage information
== Terms and definitions
=== Term 1
[%metadata]
domain:: hydraulics
subject:: pipesDesignations
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...), and - the deprecated names (specified as
...).
Preferred designations
The first preferred designation is specified as a section heading under the “Terms and definitions” clause.
.A single preferred designation
== Terms and definitions
=== application
one or more processes creating or using product dataMetanorma 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.
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.
.Applying multiple preferred designations
== Terms and definitions
=== application
preferred:[app]
one or more processes creating or using product dataDuplicate designations under the same term of the same type are removed, with a warning [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.8]; e.g. the section heading "application" followed by preferred:[application].
Admitted designations
Admitted designations, also called alternative designations, are entered using the command admitted:[...] (or ...).
.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 modelAdmitted designations are distinct from preferred designations, in that the use of any of the preferred designations is recommended over any of the admitted designations. Normally there is only one preferred designation per term, and any other designations are treated as admitted. Multiple preferred designations are however allowed in cases where they are useful, for instance, in representing multiple equivalent symbols.
Deprecated designations
Deprecated designations are entered using the ... command.
.Example from ISO 10303-2
=== business object model
deprecated:[BO Model]
single integrated information model for the scope of an APDesignation 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.
field-of-application- text indicating the field of application of the designation (typically the domain), and used to disambiguate from other designations identical in the current language. The "field of application" in ISO/IEC appears in angle brackets, after the designation itself [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.2].
[example]
IEV 102-05-28 designation (from ISO/IEC DIR IEC SUP:2021 SK.5)Laplacian,
<of a scalar field>[example]
IEV 102-03-22 designationcomponent,
<of a vector quantity>NOTE: The “field of application” refers to the IEC terminology attribute of “specific use”, which contrasts against the ISO use of “domain”. While they are similar in subtle ways, the “domain” applies to a concept, where “specific use” applies to a designation. The concept "specific use" is used in IEC, heavily within IEV (the IEC 60050 series); it is not used in ISO.
NOTE: Refer to ISO/IEC Directives, IEC Supplement:2021, Annex SK "Rules for terminology work", for more information on “specific use”. Further details are also available in ISO 10241-1.
usage-info- usage information, which is text used to disambiguate the designation from other designations identical in the current language, but not relating to the field of application of the designation. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.2].
[example]
IEV 112-02-11 designation (from ISO/IEC DIR IEC SUP:2021 SK.5)deci,
<prefix>[example]
IEV 102-04-14 designationangle,
<between two straight lines>NOTE: Refer to ISO/IEC Directives, IEC Supplement:2021, Annex SK "Rules for terminology work", on the usage of “usage information”. Further details can be found in ISO 10241-1.
geographic-area- 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 (
trueorfalse) abbreviation-type- 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 (
trueorfalse) letter-symbol- the designation is not a linguistic expression, but a letter, symbol, formula, or equation; value is boolean (
trueorfalse), or else [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.2] one ofletter,symbol,formula,equation.
Grammar of the designation is encoded as keys within the tag grammar:
grammargender- the gender of the designation. Multiple values are allowed, comma-delimited. Supported values are:
masculine
feminine
neuter
common
number- the number of the designation. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.2] Multiple values are allowed, comma-delimited. Supported values are:
singular
dual
plural
isPreposition- the designation is a preposition; value is boolean (
trueorfalse) isParticiple- the designation is a participle; value is boolean (
trueorfalse) isAdjective- the designation is an adjective; value is boolean (
trueorfalse) isVerb- the designation is a verb; value is boolean (
trueorfalse) isAdverb- the designation is an adverb; value is boolean (
trueorfalse) isNoun- the designation is a noun; value is boolean (
trueorfalse) grammar-value- other miscellaneous grammatical information
.Encoding designation metadata for multiple designations
== Terms and definitions
=== Term 1
[%metadata]
language:: eng
admitted:[Alternative]
[%metadata]
script:: Hans
field-of-application: to conventional procedure
deprecated:[Deprecated term name]
[%metadata]
type:: full
language: fre
grammar::
gender::: masculine, feminineThe metadata for a designation, presented 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:
.Providing an empty designation
== Terms and definitions
=== {blank}
admitted:[]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.
.Providing one or more non-verbal designations
== Terms and definitions
=== {blank}
[stem]
++++
t_90
++++
admitted:[]
....
ASCII ART
....Relations
General
In Metanorma, a concept relation is made between the current concept and a target concept, expected to be defined elsewhere.
That means concept relations are references to target concepts. Accordingly, concept relations are specified in a syntax similar to that for concept cross-references (citeterms) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].
Target concepts from various sources can be referenced, as described below.
== Terms and definitions
=== mammoth
extinct woolly pachyderm
=== elephant
animal with a trunk and tusks
related:supersedes[mammoth]
related:narrower[<<linnaean:mammalia>>, mammal]
related:contrast[<<mus_musculus>>, mouse]Concept defined in same document
If the target concept is defined in the same document
related:RELATION[term]Where:
RELATIONis the type of concept relation (concept-relation-types)termis the designation of the target concept
term.Concept defined in external document
If the target concept is defined in an external document (or the same document).
related:RELATION[<<id>>, term]Where:
idis a bibliographic reference anchor for an external document, or an anchor within the current documentRELATIONis the type of concept relation (concept-relation-types)termis the designation of the target concept
Concept defined in termbase
If the target concept is defined in a termbase.
related:RELATION[<<termbase:id>>, term]Where:
termbaseis the termbase reference anchoridis the identifier of the target concept within the specified termbaseRELATIONis the type of concept relation (concept-relation-types)termis the designation of the target concept
Relation types
The following concept relations can be specified
deprecates- the current concept deprecates the nominated concept.Note
related:deprecates[]is equivalent todeprecated:[].
supersedes- the current concept supersedes the nominated concept.
narrower- the current concept is narrower than the nominated concept.NoteThis is similar to the
skos:narrowerproperty in SKOS.
broader- the current concept is broader than the nominated concept.NoteThis is similar to the
skos:broaderproperty in SKOS.
equivalent- the current concept is equivalent to the nominated concept.Note
related:equivalent[]is equivalent toadmitted:[].
compare- in order to better understand the current concept, compare it with the nominated concept.
contrast- in order to better understand the current concept, contrast it with the nominated concept.
see- in order to better understand the current concept, refer to the nominated concept.
Concept relations only provide cross-references to concepts defined elsewhere; admitted and deprecated designations can also provide metadata about the designations, such as usage notes or grammatical information.
If the admitted and deprecated designations are not defined elsewhere in the document, use the admitted:[] and deprecated:[] macros.
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]. Different definitions can be differentiated with different type attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.5.3]
.Multiple definitions for one designation
=== widget
alt:[doohickey]
[.definition,type="official"]
--
device performing an unspecified function
[.source]
<<ISO2382,clause 2121372>>
--
[.definition,type="unofficial"]
--
general metasyntactic variable
[.source]
<<ISO2382,clause 2121373>>
--Multiple definitions are rendered by default in Metanorma as an ordered list of definitions:
*widget*
doohickey
- device performing an unspecified function [SOURCE: ISO 2382, 2121372]
- general metasyntactic variable [SOURCE: ISO 2382, 2121373]
Non-verbal representation of definitions
A non-verbal representation is identified as a definition instance that consists of only tables, formulas, and/or figures.
The non-verbal representation can be given instead of or after 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:
=== 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:
.Indicating a modified definition without further qualification
[.source]
<<ISO7301,section 3.2>>,renders as
Multiple sources
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.
.A term and definition originating from multiple sources
[.source]
<<ISO7301,section 3.2>>,
[.source]
<<ISO7302,section 3.10>>The first source will indicate it is "modified" since there is a trailing comma but no description of modification.
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).
As with other information source types, the termbase must be first defined in a references section.
The IEV is handled specially in Metanorma due to its frequency of use and usage of a specific citation practice as advised by the IEC.
Metanorma requires all IEV references to be to a single reference, named "IEV".
In order to source an IEV term, you would need to:
- Add the "IEV" entry to your reference section using an anchor of your choice;
- Add the
[.source]block at the end of the terminology entry.
Note that the clause should be in quotes, to indicate it is a single cross-reference; a reference like clause=103-104 would be interpreted as the clause range 103 through 104. However, Metanorma will treat a reference with two hyphens as a single cross-reference [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.2].
Formally, in accordance with IEC/TC 1 advised practice, IEV references should be cited as IEC 60050-nnn:yyyy, where n is the top-level clause, and yyyy is the year when that particular specification was published.
Metanorma automatically converts citations of IEV to citations of the appropriate IEC 60050 standards according to the correct practice. The "IEV" entry will be replaced by the appropriate IEC 60050 series references in all outputs, including the canonical XML.
The following source:
<<ievtermbank,clause="113-01-07">>will be rendered as:
IEC 60050-113:2011, 113-01-07
If a terminology entry is sourced from the IEV, Metanorma automatically performs validation of the sourced entry to detect any modifications. 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).
A terminology entry that sources IEV 103-01-02 would use something like \<<ievtermbank,clause="103-01-02">>.
A complete example is given below.
.Definition of "functional" sourced from the IEV
== Terms and definitions
=== functional
function for which the argument is a function and the value a number
NOTE: An example of a functional of the function stem:[f(t)] is
stem:[int_(t_2)^(t_1) bb(d) t]
[.source]
<<ievtermbank,clause="103-01-02">>
...
[bibliography]
== Bibliography
* [[[ievtermbank,IEV]]], _IEV: Electropedia_You may wish to go against IEC practice, and cite IEC 60050 as an entire document, instead of converting references to individual parts of IEC 60050. In that case, you need to use IEC 60050 (all parts) instead of IEV in your bibliography. So a reference to
[.source]
<<ievtermbank,clause="103-01-02">>
...
[bibliography]
== Bibliography
* [[[ievtermbank,IEC 60050 (all parts)]]], _IEV: Electropedia_will have the bibliographic entry reference IEC 60050, instead of resolving that entry to IEC 60050-103.
Citing terminological entries with numeric identifiers
In ISO and IEC, terminological entries are technically identified by "identifiers", not "clauses", even though they may be similar in format.
In some cases, like ISO/IEC 2382, terminological clauses are numbered as plain numbers without character separators (dashes or periods).
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”.
.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.
.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”.
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.
statusidentical- 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.
typeauthoritative- The managed term is authoritative in the present context.
lineage- The managed term constitutes lineage in the present context.
.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.
.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 +...+, +...+ and +...+ can contain their own markup.
.Encoding markup within term commands
=== paddy
alt:[_paddy_ rice]
deprecated:[[smallcap]#cargo# rice]
domain:[rice]
term:[rice] from which the husk only has been removedStem expressions
AsciiDoc permits macros to be nested inside other macros.
Therefore the following markup shows that stem expressions can be used as both admitted terms and preferred terms.
=== stem:[t_90]
alt:[stem:[t_A]]
Time to launch.Referencing concepts through mentions
General
Instances of concepts (terms, symbols or abbreviations) used in the document can be linked to indicate the semantic meaning of the concept. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.14].
Semantically linking a concept instance is performed in through an action called a “concept mention”.
Concept mentions are very useful in showing the reader of the standard what a particular term means.
Concept mentions have different effects on rendering depending where they are used:
- when used in the “terms and definitions” clauses, a concept mention is rendered differently in certain flavors (such as ISO and IEC) in order to display location of where those concepts are defined.
- when used in the content body, rendering of concept mentions are generally not impacted.
Concept mentions are converted into a distinct <concept> element in Metanorma Semantic XML, which includes a cross-reference to the concept definition, the canonical form of the term designation, and the text to be displayed for the term in that instance.
Full syntax for concept mentions
The full syntax for a concept mention is:
{{<<identifier>>,term,display-text,cross-reference-text,options="..."}}In this syntax, only the term argument is mandatory.
identifier: an identifier for the concept being cited (optional).term: the concept designation being cited (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).
{{identifier,term,display-text,cross-reference,options=".."}} markup closely mirrors the markup syntax of cross-references in Metanorma AsciiDoc (\<<anchor,%option,text>>).The full syntax enables multiple simple patterns that can be used for concept mentions.
.Referencing concepts with supported variant syntaxes
{{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="..."}}If the Metanorma flavor being used differentiates "concept mentions" and "concept cross-references" in its rendering, the concept mention {{term,display-text}} will display as:
display-text (Clause 3.1.1)
where Clause 3.1.1 is the location where the concept term is defined.
The concept mention {{identifier,term,display-text,cross-reference-text}} will display as:
display-text (cross-reference-text)
where cross-reference-text hyperlinks to the concept term, as identified by its anchor identifier.
Concepts defined within current document
Reference by term
Concept mentions are encoded by having a designation wrapped with doubled curly braces ({{...}}).
{{concept}}Where,
- the
conceptis a term specified in the document or any designation of that term.
An alternative syntax for a concept mention uses the command ....
term:[concept]Rendering of a concept mention differs according to flavour. Typically, the concept mention contains the term text, and a cross-reference to its definition. Hyperlinking is done on the cross-reference.
.Example of concept mention rendering (modified from OGC 20-010)
This source:
=== conceptual model
model that defines concepts of a universe of discourse
=== conceptual schema
formal description of a {{conceptual model}}Renders by default as:
formal description of a conceptual model [term defined in Clause 3.6]
.Example of concept mention rendering (ISO/IEC Directives Part 2 (2020), 16.5.10)
In Metanorma for ISO, concept mentions render according to ISO DIR 2, Clause 16. The rendering contains the term text, and a cross-reference to its definition, where a hyperlink is added on the cross-reference.
Source:
== Terms and definitions
=== terminological data
....
=== concept
...
=== terminological entry
part of a terminological data collection which contains the
{{terminological data}} related to one {{concept}}Rendered as:
part of a terminological data collection which contains the terminological data (3.1) related to one concept (3.2)
A concept mention can refer to any of the preferred or admitted designations defined in the current document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.5].
.Referencing concepts with preferred or alternate designations
== Terms and definitions
=== first preferred designation
preferred:[another preferred designation]
alt:[alternate designation]
...
=== another designation
...
terms can be referenced using the {{first preferred designation}},
any of the other {{other preferred designation}} or {{alternate designation}}Sometimes a variant of the referenced term, such as its plural form is used in a concept mention. That means that the display text needs to be differentiated from the referenced term.
This can be done by adding the display text after the mentioned concept separated by a comma.
{{concept,display-text}}term:[concept,display-text]===== 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 originIn the rendering, the display text is used instead of the referenced term:
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
If a specific version of the cross-reference text is required, the following syntax is to be used.
{{term,display-text,cross-reference-text}}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 originRenders into:
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
Reference by symbol or abbreviated term
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].
The {{...}} syntax can also be used for referencing symbols or abbreviated terms.
When using the {{...}} syntax, precedence of reference matching starts with terms, then symbols, then abbreviated terms.
The symbol:[] command can also be used to refer to a symbol or an abbreviated term, which directly targets a symbol defined in a definition list within the “Symbols and abbreviated terms” section.
symbol:[] command should be used in that instance. However, do note that such situation already introduces a conceptual conflict within the document since a designation is defined more than once.Concept mentions of symbols and abbreviated terms generally do not get rendered, they are not italicised, referenced, or hyperlinked by default. In order to have them rendered, the overriding syntax for supplying cross-reference text can be used.
.Concept mentions of symbols in content body do not get rendered
The following source:
== Symbols and abbreviated terms
ISO:: International Standards Organization // automatically assigned the anchor `symbol-ISO`
[[xyz]]IEC:: International Electrotechnical Commission // 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].Renders as:
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 in MathML;
- the defined term is too 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.
When a concept has a designation that is not in plain text (such as MathML), a manual anchor can be created for it in order to reference it as a shorthand.
{{<<identifier>>}}If the display text differs from the cited concept, it can be referred through an anchor.
{{<<identifier>>,display-text}}If the display text differs from the mentioned cited concept, referred through an anchor, a canonical name can be provided for the cited concept.
{{<<identifier>>,canonical-term,display-text}}.Example of 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 resources
To refer to concepts from an external resources requires a corresponding bibliographic anchor for that resource. The identifier for the concept is then given in the same fashion as any citation of an external resource.
The following elements are needed to make this inference:
- bibliographic anchor of the external resource, optionally including the locality of the term definition in that resource;
- concept term name;
- (optional) text to be displayed;
- (optional) cross-reference text to be displayed.
A concept from an external resource is referenced through a bibliographic anchor to that external resource, and by providing the term designation used in the external resource.
{{<<bibliographic-anchor>>,term}}Display text can be specified if the cited concept term differs from the desired text to be shown.
{{<<bibliographic-anchor>>,term,display-text}}The cross-reference text for the external document can also be overridden.
{{<<bibliographic-anchor>>,term,display-text,cross-reference-text}}.Example of concept mention referring to a concept from an external resource
[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.
{{<<bibliographic-anchor,locality=X>>,term}}.Concept mention to an external resource with locality
{{<<iso639-1,clause=3.1>>,language}}Display text can be specified if it is different from the cited term.
{{<<bibliographic-anchor,locality1=X>>,term,display-text}}.Concept mention to an external resource with display text and multiple localities
{{<<bibliographic-anchor,clause=4.7,table=1>>,display-text}}.Concept mention to an external resource shown with rendering
[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.
The syntax to reference a termbase for a concept mention is:
{{termbase-id:concept-id,term}}Display text can be specified if the cited concept term differs from the desired text to be shown.
{{termbase-id:concept-id,term,display-text}}The cross-reference text for the external document can also be overridden.
{{termbase-id:concept-id,term,display-text,cross-reference-text}}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}}.Citing termbase concepts from the IEV
This source:
== 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.This will be rendered by default as:
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]
noital- do not italicise the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1]
bold- boldface the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2]
nobold- do not boldface the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2]
ref- provide a reference for 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:
- for all terms (italics and cited):
ital,nobold,ref,nolinkmention,linkref - for acronyms (no special rendering):
noital,nobold,noref,nolinkmention,nolinkref
noital,nobold,noref,nolinkmention,nolinkref for all terms (i.e. no special rendering for a term cited within a term definition.)In ISO, the default behaviour for terms is refined:
- for terms outside the “Terms and definitions” section:
noital,nobold,noref,nolinkmention,nolinkref(no special rendering); - for the first mention of a term within the “Terms and definitions” section:
ital,nobold,ref,nolinkmention,linkref(italics, cited, hyperlinked); - for all subsequent mentions within the “Terms and definitions” section:
ital,nobold,noref,nolinkmention,linkref(italics, hyperlinked, no citation).
In BSI, the default behaviour for terms is: noital,bold,ref,nolinkmention,linkref
.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.This will be displayed by default as:
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 customize concept rendering, these options override the behaviour of whatever the flavour implements.
Implementation note on term anchors
Concept mentions in Metanorma relies on automatically created anchor references for every term defined.
Metanorma automatically creates anchor references for every concept from the document, which is used when referencing by term.
Specifically, anchors are generated from the terms themselves according to these rules:
- the anchor starts with the type of the concept, such as
term-for terminology entries andsymbol-for symbols and abbreviated terms; - the designation is lowercased;
- non-ASCII characters are stripped;
- whitespaces are replaced by
-.
.Example of automatically generated anchors in Metanorma
In the following text,
== Terms and definitions
=== Foo
bar
=== Lor
special kind of {{foo}}the anchors \[[term-foo]] and \[[term-lor]] are automatically created and assigned to the terms 'foo and lor`.
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 {{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 {{foo}}
[[term-foo]]
== My section
lorem