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>" %}

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.
• 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 markdowntable or essiflab;
  • a handlebars expression.

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

<glossary layout>	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="markdowntable" 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

Specifying the MRGref using the predefined glossary layout called markdown-table-row.

| Term | Description |
| :--- | :---------- |
{% hrg="tev2" converter="markdowntable" %}
---

Simple customized layout

Specifying the MRGref using a handlebars expression, as follows.

| Term | Description |
| :--- | :---------- |
{% hrg="tev2" converter="| {{glossaryTerm}} | {{glossaryText}} |\n" %}
---

Note that this is a simple handlebars expression, 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 expressions.

Actual implementation

Specifying the MRGref using the handlebars expression similar to the implementation here, is done as follows.

| Term | Description |
| :--- | :---------- |
{% hrg="tev2" converter=| [{{#if glossaryTerm}}{{glossaryTerm}}{{else}}{{capFirst term}}{{/if}}]({{localize navurl}}) | {{#if glossaryText}}{{glossaryText}}{{else}}no `glossaryText` was specified for this entry.{{/if}} |" %}
---

This example is derived from the terminology-config.yaml of the essif-lab/framework repository, which is explained further below. The actual reference {% hrg="" %} uses all the defaults (set in the config).

---

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 (Identify) a specific Semantic Unit (in some Scope).">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="https://essif-lab.github.io/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 (Identify) a specific Semantic Unit (in some Scope).">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 (Identify) a specific Semantic Unit (in some Scope).">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="a basic building block of meaning or representation that exists within the 'mind' of a party, e.g., a concept, relation, or property. Parties use terms (words/phrases) to refer to these intangible building blocks.">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 criterion 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="essiflab" 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

Specifying the MRGref using the predefined glossary layout called essiflab:

---
# Docusaurus header fields:
id: glossary
sidebar_label: Glossary
---

# Glossary

{% hrg="tev2" converter="essiflab" %}

---
Here endeth the glossary.

Simple customized layout

Specifying the MRGref using a handlebars expression, as follows:

Editor's note

@Ca5e: please check that the SIMPLE converter handlebar expression in the below example sufficiently describes what the essiflab layout is about. The actual, more difficult version should be placed in the next chapter (customizing )

---
# Docusaurus header fields:
id: glossary
sidebar_label: Glossary
---

# Glossary

{% hrg="tev2" converter="\n### [{{#if glossaryTerm}}{{glossaryTerm}}{{else}}{{capFirst term}}{{/if}}]({{localize navurl}})\n\n{{#if glossaryText}}{{glossaryText}}{{else}}Error: no glossary text has been specified for this term.{{/if}}\n" %}

---
Here endeth the glossary.

Note that this is a simple handlebars expression, 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 expressions.

Actual implementation

Specifying the MRGref using the handlebars expression as it was originally implemented, is done as follows:

Editor's note

@Ca5e: please check that the handlebar expression that is ACTUALLY USED for the essiflab converter is specified here below.

---
# Docusaurus header fields:
id: glossary
sidebar_label: Glossary
---

# Glossary

{% hrg="tev2" converter="\n## [{{glossaryTerm}}]({{localize navurl}})\n\n{{glossaryText}}\n" %}
---
Here endeth the glossary.

Note that this is a simple handlebars expression, 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 expressions.

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 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 (Identify) a specific Semantic Unit (in some Scope).">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="https://essif-lab.github.io/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 (Identify) a specific Semantic Unit (in some Scope).">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 (Identify) a specific Semantic Unit (in some Scope).">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="a basic building block of meaning or representation that exists within the 'mind' of a party, e.g., a concept, relation, or property. Parties use terms (words/phrases) to refer to these intangible building blocks.">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 criterion 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 expression.

The handlebar expressions can use all fields that exist in MRG entries as variables. For example, {{glossaryText}} is the variable that contains the text specified in the glossaryText field of the MRG entry.

Editor's note

There may be merit in allowing/enabling handlebar expressions to also use variables that access fields in the MRG headers - see tev2-tools/issue #4

Editor's note

@Ca5e: can you write a few examples here, ranging from very simple converters (that have the property of not being very robust against missing values in variables) to complexer ones (that are robust(er))?