Configuration Files for TEv2 tools
Every TEv2 tool execution can be configured using a configuration file that specifies the parameters (arguments) that otherwise would need to be supplied on the command line. The file is supplied by using the command line parameter -c <path> or --config <path>, where <path> is the path (including the filename).
The configuration file is in a YAML format. When the -c or --config option is specified when calling a TEv2 tool, the tool attempts to read the specified file and evaluates all fields that are not in a specific section, as well as all fields that are in a tool-specific section. A field whose name is defined in the specifications for that tool will be interpreted. All other fields are ignored.
The options specified on the command line have precedence over the options specified in the configuration file. Similarly, the options specified in tool specific sections have precedence over the (general) options specified in the 'root' of the configuration file. The tool specific sections are specified in the configuration file by using the command line name of the tool as the section name.
Example configuration file
# TNO Terminology Design tools configuration file (yaml)
## General
scopedir: . # path of the scope directory where the SAF is located
onNotExist: warn # the action in case an MRG was specified, but wasn't found in the SAF
output: . # (root) directory for output files to be written to
## Machine Readable Glossary Tool
mrgt:
vsntag: # versiontag for which the MRG needs to be (re)generated. Leave empty to process all versions
## Human Readable Glossary Tool
hrgt:
interpreter: default # Type of interpreter, i.e., a regex, or a predefined type (`default`)
converter: markdown-section-3 # Type of converter, i.e., a mustache/handlebars template, or a predefined type (`markdown-table-row, `markdown-section-2`, `markdown-section-3`)
input:
- "*gloss*.md"
## Term Reference Resolution Tool
trrt:
interpreter: default # Type of interpreter, i.e., a regex, or a predefined type (`default`, `alt`)")
converter: html-hovertext-link # Type of converter, i.e., a mustache/handlebars template, or a predefined type (`markdown-link`, `html-link`, `html-hovertext-link`, `html-glossarytext-link`)")
input: # glob pattern strings for files to be processed by the TRRT
- "**/*.md"
Below, you can find all of the possible options you can specify in the various configuration sections. These match the parameters that can be specified on the command line.
If a parameter is specified on the command line, it must be preceded by the -- (e.g., as in --scopedir), or the alternative short form can be used as described in the specifications of the individual tools.
Legend
The columns in the following table are defined as follows:
Parameterspecifies the parameter and further specifications.Req'dspecifies whether (Y) or not (n) the parameter is required to be present when the tool is being called for actual processing (so not in case ahelporversionparameter is specified). IfY, the parameter MUST either be present in the configuration file, or as a command line parameter.Descriptionspecifies the meaning of theValuefield, and other things you may need to know, e.g. why it is needed, a required syntax, etc.
- Generic
- MRG Import
- MRGT
- HRGT
- TRRT
Parameters that can be used by most, if not all tools can be put both in tool-specific sections, or in the 'root' of the YAML file.
| Generic Parameters | Req'd | Description |
|---|---|---|
scopedir: <path> | Y | Path of the scope directory where the SAF is located. |
onNotExist: <action> | n | The action in case something that is necessary for further processing didn't exist. |
The <action> parameter can take the following values.
<action> | Description |
|---|---|
'throw' | An error is thrown (an exception is raised), and processing will stop. |
'warn' | A message is displayed (and logged) and processing continues. |
'log' | A message is written to a log(file) and processing continues. |
'ignore' | Processing continues as if nothing happened. |
Parameters that are specific to the MRG Import tool can be put in the YAML section mrg-import.
| MRG Import Parameters | Req'd | Description |
|---|---|---|
onNotExist: <action> | n | The action in case an MRG file unexpectedly does not exist. |
prune: <bool> | n | If <bool> is true, remove all MRG files in the glossarydir where the scopetag is not administered in the SAF. |
The <action> parameter can take the following values.
<action> | Description |
|---|---|
'throw' | An error is thrown (an exception is raised), and processing will stop. |
'warn' | A message is displayed (and logged) and processing continues. |
'log' | A message is written to a log(file) and processing continues. |
'ignore' | Processing continues as if nothing happened. |
Parameters that are specific to the MRGT can be put in the YAML section mrgt.
| Key | Req'd | Description |
|---|---|---|
onNotExist: <action> | n | The action in case an MRG file unexpectedly does not exist. |
vsntag: <vsntag> | n | Versiontag for which the MRG needs to be (re)generated. |
prune: <bool> | n | If <bool> is true, remove all MRG files in the local scope from the glossarydir where the vsntag (or altvsntag) is not administered in the SAF |
The <action> parameter can take the following values.
<action> | Description |
|---|---|
'throw' | An error is thrown (an exception is raised), and processing will stop. |
'warn' | A message is displayed (and logged) and processing continues. |
'log' | A message is written to a log(file) and processing continues. |
'ignore' | Processing continues as if nothing happened. |
Parameters that are specific to the hrgt can be put in the YAML section hrgt:
| Parameter | Req'd | Description |
|---|---|---|
output: <dir> | Y | (Root) directory for output files to be written. |
input: <glob-pattern> | Y | Glob pattern string for files to be processed by the HRGT. |
interpreter: <regex> or <predeftype> | n | Type of MRGRef interpreter, i.e., a (PCRE) regex, or a predefined type (default). |
converter: <template> or <predeftype> | n | Type of MRGRef converter, i.e., a mustache/handlebars template, or a predefined type ( markdown-table-row, markdown-section-2, markdown-section-3). |
sorter: <template> or <predeftype> | n | Value to use for sorting, i.e., a mustache/handlebars template, or a predefined type ( default). |
force: <bool> | n | If <bool> is true, allow files in the output directory to be overwritten. If <bool> is false or unspecified, output files will not overwrite existing files. |
The <action> parameter can take the following values.
<action> | Description |
|---|---|
'throw' | An error is thrown (an exception is raised), and processing will stop. |
'warn' | A message is displayed (and logged) and processing continues. |
'log' | A message is written to a log(file) and processing continues. |
'ignore' | Processing continues as if nothing happened. |
Predefined HRGT interpreters
There is only one predefined HRGT interpreter (called default). It need not be specified (as it is default).
It is described in section MRG References syntax
Predefined HRGT converters
Each of the predefined HRGT converters produces a list of some of the contents of the MRG entries that are in the terminology (MRG) as detected by the HRGT interpreter. The below table lists the predefined converters, and specifies what each such MRG entry is converted into.
The moustache-variables {{glossaryTerm}} and {{glossaryText}} will be replaced with the contents of their corresponding fields from the MRG entry. The {{glossaryTerm}} is typically converted into a link to the rendered version of the curated text of the semantic unit to which the TermRef refers.
| Converter | Convert every MRG entry into |
|---|---|
markdown-table-row | A markdown table row of two cells, the first containing {{glossaryTerm}} and the second {{glossaryText}}. Of course, this will only work if the MRGref is preceded by a markdown table header. |
markdown-section-2 | A level 2 markdown section, using {{glossaryTerm}} as the header, and {{glossaryText}} as the (textual) contents of that section. |
markdown-section-3 | Same as markdown-section-2, except that it is a level 3 markdown section. |
Predefined sorting values
There is only one predefined HRGT sorting value (called default). It need not be specified (as it is default).
It is described in section HRGT sorters.
Parameters that are specific to the TRRT can be put in the YAML section trrt:
| TRRT Parameters | Req'd | Description |
|---|---|---|
output: <dir> | Y | (Root) directory for output files to be written. |
input: <glob-pattern> | Y | Glob pattern string for files to be processed by the TRRT. |
interpreter: <regex> or <predeftype> | n | Type of TermRef interpreter, i.e., a regex, or a predefined type (default, alt). |
converter[n]: <template> or <predeftype>1 | n | Type of TermRef converter, i.e., a mustache/handlebars template, or a predefined type (markdown-link, html-link, html-hovertext-link, html-glossarytext-link). |
force: <bool> | n | If <bool> is true, allow files in the output directory to be overwritten. If <bool> is false or unspecified, output files will not overwrite existing files. |
Predefined TRRT interpreters
The predefined TRRT interpreter types match the behavior of the syntaxes described on the TermRef syntax page, which are:
Predefined TRRT converters
Each of the predefined TRRT converters produces some kind of link to the rendered version of the curated text of the semantic unit to which the TermRef refers, as follows:
| Converter | Convert a TermRef into a link of the form |
|---|---|
markdown-link | [{{showtext}}](<url>) |
html-link | <a href="<url>">{{showtext}}</a> |
html-hovertext-link | <a href="<url>" title="<hoverText>" >{{showtext}}</a>,where <hoverText> is created from the hoverText-field in the corresponding MRG entry. |
html-glossarytext-link | <a href="<url>" title="<glossaryText>" >{{showtext}}</a>,where <glossaryText> is created from the glossaryText-field in the corresponding MRG entry. |
- Multiple converters may be specified by appending a number to the parameter key, e.g.,
converter[1]: <template>converter[2]: <template>, wherenis the termid occurrence count from which to start using a specific converter during resolution of a file. Usingconverter, without a number, is equal to usingconverter[0]↩