MRG References - Syntax
MRG References (or MRGRefs for short) are textual constructs that refer to a specific terminology within a particular scope. The purpose of an MRG Reference is that it can be converted (by the HRGT) into a text that contains a human readable glossary of the terms contained in that terminology.The syntax for MRGRefs is not fixed. While there is a default syntax, curators can define their own syntax, and specify that as a command-line parameter or a parameter in the configuration file for appropriate tools, such as the HRGT. If an interpreter is not specified, it defaults to default, the associated syntax of which is specified below.
Default MRGRef Syntax
The default syntax for MRGRefs is as follows:
{% hrg="<tid>" converter="<converter>" sorter="<sorter>" %}
where
<tid>is a terminology identifier, that identifies a terminology (and implies an associated MRG) within the current scope. If empty, or unspecified, it defaults to the default terminology of the current scope.
When the <tid> points to a scope that is not the current scope, the TermRefs that appear in the generated glossary must be resolved using the MRG that contains the identified terminology. Currently, the tools do not support a mechanism for doing this.
converter="<converter>"specifies the converter that is to be used for generating glossary entries. If it isn't specified as part of the MRGRef, it must be specified as a command-line parameter, or as a value in the configuration file that the HRGT uses.<converter>is a text that specifies either:- a predefined way in which glossary entries are being formatted (see further down), such as
markdowntableoressif-lab; - a handlebars template.
- a predefined way in which glossary entries are being formatted (see further down), such as
sorter="<sorter>"specifies the sorter that is to be used for sorting the glossary entries. If it isn't specified as part of the MRGRef, it is derived from the command-line parameter, or the a value in the configuration file that the HRGT uses. If neither is specified, it defaults todefault.<sorter>is a text that specifies either:- a predefined way in which glossary entries are being sorted (see further down), such as
defaultorglossaryterm; - a handlebars template.
- a predefined way in which glossary entries are being sorted (see further down), such as
Predefined MRGRef Interpreters
Predefined glossary interpreters have the advantage that they are easy to use. However, it is possible that in particular contexts, they pose problems. For such cases, curators can specify custom formats.
The predefined interpreters for detecting MRGRefs are as follows:
<interpreter> | Description |
|---|---|
default | {% hrg="<tid>" converter="<converter>" sorter="<sorter>" %}, where converter="<converter>" and sorter="<sorter>" are optional. This is the default interpreter for MRGRefs. |
Predefined MRGRef Sorters
Sorters are similar to converters, in that they can either specify a predefined way of sorting glossary entries, or a handlebars template that specifies how to sort them.
The predefined sorters for glossary generation are:
<sorter> | Expression | Description |
|---|---|---|
default | {{term}}{{termType}} | HRG entries are first sorted on the term field, and then on the termType field. |
glossaryterm | {{glossaryTerm}}{{term}}{{termType}} | HRG entries are first sorted on the glossaryTerm field, and then the same as default. |
Predefined MRGRef Converters
Predefined glossary layouts have the advantage that they are easy to use, and provide for a (small) range of generally useful layouts. Also, using them would produce acceptable results even in non-standard conditions, e.g., when a curated text does not specify its glossaryTerm field.
However, curators can specify other formats. To help them do this, the examples we provide for the predefined formats also show how the same, or similar, results can be achieved by customized specifications of the glossary layouts.
The predefined converters for glossary generation are:
<converter> | Description |
|---|---|
markdown-table-row | HRG entries are compiled as a single markdown table row, where the first cell contains the term, and the second its description. |
markdown-section-2 | HRG entries are compiled as a markdown section, with the term as section header 2 ## , and the description as the section body below. |
markdown-section-3 | HRG entries are compiled as a markdown section, with the term as section header 3 ### , and the description as the section body below. |
Converter for Markdown Tables
An MRGref that specifies converter="markdown-table-row" as its glossary layout is appropriate for generating a glossary as a markdown table within a regular markdown file. Suppose that markdown file contains the following text.
- Using predefined layout
- Simple customized layout
Specifying the MRGref using the predefined glossary layout called markdown-table-row.
| Term | Description |
| :--- | :---------- |
{% hrg="tev2" converter="markdown-table-row" %}
---
Specifying the MRGref using a handlebars template, as follows.
| Term | Description |
| :--- | :---------- |
{% hrg="tev2" converter="| {{glossaryTerm}} | {{glossaryText}} |\n" %}
---
Note that this is a simple handlebars template, that is not very robust against missing variables. See, e.g., the section on custom glossary converters on how to make them more robust, or even better: the documentation on Handlebars.
Under the assumption that the terminology identifier tev2 refers to a terminology (and associated MRG) that holds definitions for the terms Glossary, Curator and Definition, the result could e.g., look something like the following.
| Term | Description |
| :--- | :---------- |
| Glossary | an alphabetically sorted list of <a href="/tev2-specifications/docs/terms/term" title="Term: a word or phrase (i.e.: text) that is used to represent Concepts.">terms</a> with the (single) meaning it has in (at least) one context. |
| Curator (of a Scope) | a person responsible for curating, managing, and maintaining the <a href="/tev2-specifications/docs/terms/terminology" title="Terminology: a set of Terms that are used within a single Scope to refer to Concepts and other Semantic Units of a single Party (e.g. a Community), enabling Parties to reason and communicate ideas they have about one or more specific topics.">terminologies</a>, to ensure shared understanding among a <a href="https://essif-lab.github.io/framework/docs/terms/community" title="Community: a Party, consisting of at least two different Parties (the members of the Community) that seek to collaborate with each other so that each of them can achieve its individual Objectives more efficiently and/or effectively.">community</a> working together on a particular set of <a href="/framework/docs/terms/objective" title="Objective: Something toward which a Party (its Owner) directs effort (an aim, goal, or end of action).">objectives</a>. |
| Definition | the combination of a <a href="/tev2-specifications/docs/terms/term" title="Term: a word or phrase (i.e.: text) that is used to represent Concepts.">term</a> and a descriptive text, where the <a href="/tev2-specifications/docs/terms/term" title="Term: a word or phrase (i.e.: text) that is used to represent Concepts.">term</a> refers to a <a href="/tev2-specifications/docs/terms/concept" title="Concept: a Semantic Unit that captures the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same').">concept</a> or other <a href="/tev2-specifications/docs/terms/semantic-unit" title="Semantic Unit: a basic building block of meaning or representation that exists within the 'mind' of a Party (i.e., in its Knowledge).">semantic unit</a>, and the descriptive text enables a set of <a href="https://essif-lab.github.io/framework/docs/terms/party" title="Party: an Entity that sets its Objectives, maintains its Knowledge, and uses that Knowledge to pursue its Objectives in an autonomous (sovereign) manner. Humans and Organizations are the typical examples.">parties</a> to have the same understanding about that <a href="/tev2-specifications/docs/terms/concept" title="Concept: a Semantic Unit that captures the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same').">concept</a>. Ideally, the descriptive text is a <a href="/tev2-specifications/docs/terms/criterion" title="Criterion: (aka: criteria) a text that people can evaluate to base a judgment or decision on.">criterion</a> that such <a href="https://essif-lab.github.io/framework/docs/terms/party" title="Party: an Entity that sets its Objectives, maintains its Knowledge, and uses that Knowledge to pursue its Objectives in an autonomous (sovereign) manner. Humans and Organizations are the typical examples.">parties</a> can use to determine what is, and what is not, an instance (or example) of that <a href="/tev2-specifications/docs/terms/concept" title="Concept: a Semantic Unit that captures the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same').">concept</a>. |
---
Converter for eSSIF-Lab Glossary lookalikes
An MRGref that specifies converter="markdown-section-3" as its glossary layout is appropriate for generating a glossary that is similar to the one used by eSSIF-Lab. The markdown file that would produce this would be as follows.
- Using predefined layout
- Simple customized layout
Specifying the MRGref using the predefined glossary layout called markdown-section-3:
---
# Docusaurus header fields:
id: glossary
sidebar_label: Glossary
---
# Glossary
{% hrg="essif-lab" converter="markdown-section-3" %}
---
Here endeth the glossary.
Specifying the MRGref using a handlebars template, as follows:
---
# Docusaurus header fields:
id: glossary
sidebar_label: Glossary
---
# Glossary
{% hrg="tev2" converter="### [{{glossaryTerm}}]({{localize navurl}})\n\n{{glossaryText}}\n\n" %}
---
Here endeth the glossary.
Note that this is a simple handlebars template, that is not very robust against missing variables. See, e.g., the section on custom glossary converters on how to make them more robust, or even better: the documentation on Handlebars.
Under the assumption that the terminology identifier essif-lab refers to a terminology (and associated MRG) that holds definitions for the terms Glossary, Curator and Definition, the result could e.g., look something like this:
---
# Docusaurus header fields:
id: glossary
sidebar_label: Glossary
---
# Glossary
### [Glossary](/docs/terms/glossary)
an alphabetically sorted list of <a href="/tev2-specifications/docs/terms/term" title="Term: a word or phrase (i.e.: text) that is used to represent Concepts.">terms</a> with the (single) meaning it has in (at least) one context.
### [Curator (of a Scope)](/docs/terms/curator)
a person responsible for curating, managing, and maintaining the <a href="/tev2-specifications/docs/terms/terminology" title="Terminology: a set of Terms that are used within a single Scope to refer to Concepts and other Semantic Units of a single Party (e.g. a Community), enabling Parties to reason and communicate ideas they have about one or more specific topics.">terminologies</a>, to ensure shared understanding among a <a href="https://essif-lab.github.io/framework/docs/terms/community" title="Community: a Party, consisting of at least two different Parties (the members of the Community) that seek to collaborate with each other so that each of them can achieve its individual Objectives more efficiently and/or effectively.">community</a> working together on a particular set of <a href="/framework/docs/terms/objective" title="Objective: Something toward which a Party (its Owner) directs effort (an aim, goal, or end of action).">objectives</a>.
### [Definition](/docs/terms/definition)
the combination of a <a href="/tev2-specifications/docs/terms/term" title="Term: a word or phrase (i.e.: text) that is used to represent Concepts.">term</a> and a descriptive text, where the <a href="/tev2-specifications/docs/terms/term" title="Term: a word or phrase (i.e.: text) that is used to represent Concepts.">term</a> refers to a <a href="/tev2-specifications/docs/terms/concept" title="Concept: a Semantic Unit that captures the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same').">concept</a> or other <a href="/tev2-specifications/docs/terms/semantic-unit" title="Semantic Unit: a basic building block of meaning or representation that exists within the 'mind' of a Party (i.e., in its Knowledge).">semantic unit</a>, and the descriptive text enables a set of <a href="https://essif-lab.github.io/framework/docs/terms/party" title="Party: an Entity that sets its Objectives, maintains its Knowledge, and uses that Knowledge to pursue its Objectives in an autonomous (sovereign) manner. Humans and Organizations are the typical examples.">parties</a> to have the same understanding about that <a href="/tev2-specifications/docs/terms/concept" title="Concept: a Semantic Unit that captures the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same').">concept</a>. Ideally, the descriptive text is a <a href="/tev2-specifications/docs/terms/criterion" title="Criterion: (aka: criteria) a text that people can evaluate to base a judgment or decision on.">criterion</a> that such <a href="https://essif-lab.github.io/framework/docs/terms/party" title="Party: an Entity that sets its Objectives, maintains its Knowledge, and uses that Knowledge to pursue its Objectives in an autonomous (sovereign) manner. Humans and Organizations are the typical examples.">parties</a> can use to determine what is, and what is not, an instance (or example) of that <a href="/tev2-specifications/docs/terms/concept" title="Concept: a Semantic Unit that captures the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same').">concept</a>.
---
Here endeth the glossary.
Custom Glossary Converters
When the predefined glossary converters are not appropriate, curators can define their own converter, by specifying them as a handlebars template.
The handlebars templates can use all fields of the converter profile as variables. For example, {{glossaryText}}, or {{entry.glossaryText}}, is the variable that contains the text specified in the glossaryText field of the specific MRG entry, and {{err.file}} contains the name of the file where the MRGRef was found.
Converters can use the TEv2 helper functions and block helpers to create a diverse range of glossary entries. The example below illustrates this functionality. Note that the newlines and spaces are strictly handled by the converter, in the example they are primarily for readability.
<a href="{{localize entry.navurl}}">{{capFirst entry.term}}</a>
{{#if entry.glossaryText}}
*Text derived from the {{mrg.scopetag}} glossary at {{mrg.website}}.*
{{entry.glossaryText}}
{{else}}
No description available here at {{err.file}}, please see {{entry.navurl}}.
{{/if}}
{{#ifValue entry.termType equals="image"}}
<img src="{{locator}}.jpg" alt="An image of {{term}}" width="500">
{{/ifValue}}
Partially depending on the TermType property of the MRG entry, this converter string can produce output with images, links, and text, that accurately describes a semantic unit in the terminology that the MRGRef refers to.