Converter Profile

A converter profile is the specification of a class of data objects, instances of which are used by the text conversion tools to generate text fragments from. Converter profiles exist, e.g., for the TRRT and the HRGT.

The text fragments that are generated by the text conversion tool are created by executing a (predefined, or custom) handlebars template that works on a converter profile object. The object defines the available information that converters and their helper functions can use to create texts.

The generic workings of converter profiles is documented in the TEv2 Text Conversion pattern.

Converter Profile Object (Specification)

The converter profile object can be envisaged as a YAML object, that has a number of sections. Every converter profile object has the following sections, but individual text-conversion-tool may specify additional sections (or fields), which can be found in the section "Converter Profile" of their specifications.

Example

Here is an example of what a converter profile object might look like when - the TRRT is run from within the scope with scopetag `mve`, - the TermRef `[converter profile object](#object-spec@tev2)` has been found, and needs to be converted.

int:
  type: "default"
  regex: /(?:(?<=[^`\\])|^)\[(?=[^@\n\]]+\]\([^@)]*@[:a-z0-9_-]*\))(?<showtext>[^@\n\]]+)\]\((?:(?:(?<type>[a-z0-9_-]*):)?)(?:(?<term>[^@\n:#)]*?)?(?:#(?<trait>[^@\n:#)]*))?)?@(?<scopetag>[a-z0-9_-]*)(?::(?<vsntag>[a-z0-9_-]*))?\)/g
ref:
  showtext: "converter profile object"
  type: ""
  term: ""
  trait: "object"
  scopetag: "tev2"
  vsntag: ""
entry:
  id: "converter-profile"
  displayed_sidebar: "tev2SideBar"
  term: "converter-profile"
  termType: "concept"
  glossaryTerm: "Converter Profile"
  glossaryText: "a data object, of a type that is specific for a <a href="/tev2-specifications/docs/terms/tev2-text-conversion-tool" title="TEv2 Text Conversion Tool: a TEv2 Tool whose purpose is to convert particular text constructs (such as TermRefs or MRGRefs) that exist in one or more files with other texts, the contents of which consists of some fixed construct that is populated with elements derived from existing text constructs and/or other resources.">text conversion tool</a>, that <a href="/tev2-specifications/docs/terms/converter" title="Converter: a specification, in the form of a Handlebars Template, for constructing a text that a particular Text Conversion Tool uses to create its output.">converters</a> use to create texts by which the <a href="/tev2-specifications/docs/terms/tev2-text-conversion-tool" title="TEv2 Text Conversion Tool: a TEv2 Tool whose purpose is to convert particular text constructs (such as TermRefs or MRGRefs) that exist in one or more files with other texts, the contents of which consists of some fixed construct that is populated with elements derived from existing text constructs and/or other resources.">tool</a> will replace the text constructs that are located by its <a href="/tev2-specifications/docs/terms/interpreter" title="Interpreter: a Regex that is used to locate a particular text construct (such as a TermRef or MRGRef) in a text, and that populates Named Capturing Groups as specified in the Interpreter Profile of the particular Text Conversion Tool for which it is designed.">interpreter</a>."
  grouptags: []
  formPhrases:
    - "converter-profile"
    - "converter-profiles"
    - "converter-profile-s"
    - "converter-profile-object"
    - "converter-profile-objects"
    - "converter-profile-object-s"
  scopetag: "termdsn"
  locator: "converter-profile.md"
  navurl: "https://tno-terminology-design.github.io/tev2-specifications/docs/terms/converter-profile"
  headingids:
    - "converter-profile"
    - "object-spec"
    - "`int`-fields"
    - "`ref`-fields"
    - "`entry`-fields"
    - "`mrg`-fields"
    - "`saf`-fields"
    - "`err`-fields"
    - "notes"
  termid: "concept:converter-profile"
  vsntag: "documentation"
mrg:
#  In this section, you will find the entire MRG to which the Entry belongs
#  We haven't put that in this example to keep it manageable.
#  See the specifications of MRG files for their construciton.
saf:
  scope:
    scopetag: mve
    scopedir: https://github.com/tno-terminology-design/tev2-mve/tree/master/docs
    curatedir: terms
    glossarydir: mrgs
    defaultvsn: mve-terms
    website: https://tno-terminology-design.github.io/tev2-mve
    navpath: /terms
    navid: term
  scopes:
  - scopetag: tev2
    scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs
  versions:
  - vsntag: mve-terms 
    termselection:
    - "*"
err:
  file: "31-trrt.md"
  dir: "/specs/tools"
  line: 73
  pos: 9
  cause: ""

Section	Description
`int`	(interpreter): includes the interpreter type `int.type` (either the name of a predefined interpreter, or "custom"), and the regex used to locate the reference `int.regex`. The `noRefs` helper, for instance, accesses the `int.regex` to be used as the default type.
`ref`	(reference): the set of properties derived from the named capturing groups by the interpreter.
`entry`	(MRG entry): all fields from the specific MRG entry that was selected.
`mrg`	(MRG): all fields from the terminology section of the MRG from which the MRG entry was taken.¹
`saf`	(SAF): all fields from the SAF of the current scope.¹
`err`	(error): various fields, as specified below, that can be used to construct output that helps users identify an error, and fix it.

tip

Fields from the entry section may also be used in converters without specifying entry as a prefix (e.g., entry.term becomes term). Properties of entry with identical names to sections of the converter profile object, are overwritten by the defined sections.

`int` fields

The int section of a converter profile specifies the particulars of the interpreter that was used, which led to the selection of the MRG entry (as specified in the entry field).¹

Legend

Field contains the field name;
Req'd specifies whether (Y) or not (n, or F) the field is always populated, or optional.
Description specifies the meaning of the field, and other things you may need to know, e.g. why it is needed, a required syntax, etc.

Field	Req'd	Description
`type`	n	Name of the interpreter.
`regex`	n	regex that constitutes the interpreter.

Example of `int` field

int:
  type: "default"
  regex: /(?:(?<=[^`\\])|^)\[(?=[^@\n\]]+\]\([^@)]*@[:a-z0-9_-]*\))(?<showtext>[^@\n\]]+)\]\((?:(?:(?<type>[a-z0-9_-]*):)?)(?:(?<term>[^@\n:#)]*?)?(?:#(?<trait>[^@\n:#)]*))?)?@(?<scopetag>[a-z0-9_-]*)(?::(?<vsntag>[a-z0-9_-]*))?\)/g

`ref` fields

The ref section of a converter profile specifies the values of the named capturing groups produced by the interpreter. Thus, the actual fields in this section depend on the interpreter profile of the tool that is used, as listed in the below tables:

Legend

Field contains the field name;
Req'd specifies whether (Y) or not (n, or F) the field is always populated, or optional.
Description specifies the meaning of the field, and other things you may need to know, e.g. why it is needed, a required syntax, etc.

TRRT `ref`-fields
HRGT `ref`-fields

The fields of this section are defined in the TRRT interpreter profile, as follows:

Field	Req'd	Description
`showtext`	Y	The text in a TermRef that the author expects to be rendered.
`type`	n	The term type of the semantic unit that is referred to.
`term`	n	The term of the semantic unit that is referred to.
`trait`	n	A text that is expected to correspond with one of the `headingids` in the MRG entry of the semantic unit that is referred to.
`scopetag`	n	The scopetag that identifies the scope that curates the semantic unit that is referred to.
`vsntag`	n	A versiontag that identifies the terminology that contains the semantic unit that is referred to.

Example of `ref` field when used by the TRRT

ref:
  showtext: "converter profile object"
  type: ""
  term: "converter-profile"
  trait: "object"
  scopetag: ""
  vsntag: ""

The fields of this section are defined in the HRGT interpreter profile, as follows:

Field	Req'd	Description
`hrg`	n	A terminology-identifier that specifies the MRG for which a HRG is to be generated.
`converter`	n	Specifies the converter to be used to produce HRG entries. This can either be a predefined converter, or a handlebars template. See HRG Converters for details.
`sorter`	n	Specifies the sorter to be used for sorting the HRG list. This can either be a predefined sorter, or a handlebars template. See HRG Sorters for details.

Editor's note

If the contents of the above table differs from the specifications of the HRGT interpreter profile as described in the HRGT specifications, then the latter takes precedence.

Example of `ref` field when used by the HRGT

ref:
  hrg: ""
  converter: "html-with-notes"
  sorter: "default"

`entry` fields

The entry section of a converter profile specifies the particulars of the MRG entry that was selected. If no MRG entry was selected, this section is empty, or does not exist.

There is a set of fields that every MRG entry must have. They are documented here.

The other fields that may occur are those that existed in the header of the curated text that the MRG entry represents. In particular, any front-matter that exists for purposes of other tools, such as your static website generator, are also available in this section.

This feature helps you create and use custom converters: whenever you need a converter to use data that is not available by default, you can simply add the data to the headers of the relevant curated texts, generate the approprate MRG from them, and the data will appear as the field you designated for that data.

Example of `entry` field

entry:
  id: "converter-profile"
  displayed_sidebar: "tev2SideBar"
  term: "converter-profile"
  termType: "concept"
  glossaryTerm: "Converter Profile"
  glossaryText: "a data object, of a type that is specific for a <a href="/tev2-specifications/docs/terms/tev2-text-conversion-tool" title="TEv2 Text Conversion Tool: a TEv2 Tool whose purpose is to convert particular text constructs (such as TermRefs or MRGRefs) that exist in one or more files with other texts, the contents of which consists of some fixed construct that is populated with elements derived from existing text constructs and/or other resources.">text conversion tool</a>, that <a href="/tev2-specifications/docs/terms/converter" title="Converter: a specification, in the form of a Handlebars Template, for constructing a text that a particular Text Conversion Tool uses to create its output.">converters</a> use to create texts by which the <a href="/tev2-specifications/docs/terms/tev2-text-conversion-tool" title="TEv2 Text Conversion Tool: a TEv2 Tool whose purpose is to convert particular text constructs (such as TermRefs or MRGRefs) that exist in one or more files with other texts, the contents of which consists of some fixed construct that is populated with elements derived from existing text constructs and/or other resources.">tool</a> will replace the text constructs that are located by its <a href="/tev2-specifications/docs/terms/interpreter" title="Interpreter: a Regex that is used to locate a particular text construct (such as a TermRef or MRGRef) in a text, and that populates Named Capturing Groups as specified in the Interpreter Profile of the particular Text Conversion Tool for which it is designed.">interpreter</a>."
  formPhrases:
    - "converter-profile"
    - "converter-profiles"
    - "converter-profile-s"
  scopetag: "termdsn"
  locator: "converter-profile.md"
  navurl: "https://tno-terminology-design.github.io/tev2-specifications/docs/terms/converter-profile"
  headingids:
    - "converter-profile"
    - "object-spec"
    - "`err`-fields"
    - "helpers"
    - "capfirst"
    - "ifvalue"
    - "localize"
    - "norefs"
    - "regularize"
  termid: "concept:converter-profile"
  vsntag: "documentation"

`mrg` fields

The mrg section of a converter profile contains the entire MRG in which the MRG entry is located. See the section MRG structure for the details.

`saf` fields

The saf section of a converter profile contains the entire SAF of the current scope. See the section Scope Aministration File (SAF) for the details.

`err` fields

When a file is being processed by a text conversion tool, it can happen that an input structure is found that cannot be associated with an MRG entry. The err section in a converter profile object contains fields that can help construct outputs that help users to identify, and fix, such errors, as follows.

Legend

Field contains the field name;
Req'd specifies whether (Y) or not (n, or F) the field is always populated, or optional.
Description specifies the meaning of the field, and other things you may need to know, e.g. why it is needed, a required syntax, etc.

Field	Req'd	Description
`file`	Y	Name of the file, including the extension, where the specific reference was found.
`dir`	Y	Relative directory path from the location the tool was called to the directory where the `file` was found.
`line`	Y	Linenumber in the file where the reference was found.
`pos`	Y	Position on the line of the start of the reference that was found.
`cause`	n	A description of the cause of a possible error.

Example of `err` field

err:
  file: "31-trrt.md"
  dir: "/specs/tools"
  line: 73
  pos: 9
  cause: ""

Notes

While most often this is not the case, the contents of the SAF of the current scope can differ from the fields from the terminology section of the mrg from which the MRG entry was taken. That happens when an MRG entry is taken from an MRG that was imported (i.e.: not generated from within the current scope). For such cases converters - specifically: helper functions used therein, such as localize - may need to refer to information from either the current scope, or the scope in which the MRG that contains the MRG entry was generated.↩

Converter Profile