diff --git a/docs/specs/syntax/41-mrg-ref-syntax.md b/docs/specs/syntax/41-mrg-ref-syntax.md index eb9d476d45..94e0f7b229 100644 --- a/docs/specs/syntax/41-mrg-ref-syntax.md +++ b/docs/specs/syntax/41-mrg-ref-syntax.md @@ -21,16 +21,20 @@ The syntax for [MRGRefs](@) is not fixed. While there is a default syntax, [cura The default syntax for [MRGRefs](@) is as follows: ~~~ markdown -{% hrg="" converter="" %} +{% hrg="" converter="" sorter="" %} ~~~ where - `` 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="` 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=""` 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. - `` is a text that specifies either: - a predefined way in which glossary entries are being formatted (see [further down](#predefined-mrgref-converters)), such as `markdowntable` or `essiflab`; - - a [handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars). + - a [Handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars). +- `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 to `default`. +- `` is a text that specifies either: + - a predefined way in which glossary entries are being sorted (see [further down](#predefined-mrgref-sorters)), such as `default` or `glossaryterm`; + - a [Handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars). ## Predefined MRGRef Interpreters {#predefined-mrgref-interpreters} @@ -50,6 +54,25 @@ The predefined interpreters for detecting [MRGRefs](@) are as follows: ``` +## Predefined MRGRef Sorters {#predefined-mrgref-sorters} + +Sorters are similar to [converters](@), in that they can either specify a predefined way of sorting glossary entries, or a [Handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars) that specifies how to sort them. + +The predefined sorters for glossary generation are: + +```mdx-code-block + +``` + +| `` | 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`. | + +```mdx-code-block + +``` + ## Predefined MRGRef Converters {#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. @@ -62,7 +85,7 @@ The predefined converters for glossary generation are: ``` -| `` | Description | +| `` | 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. | @@ -74,15 +97,14 @@ The predefined converters for glossary generation are: ### 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: +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.
@@ -92,14 +114,14 @@ Specifying the [MRGref](@) using the predefined glossary layout called `markdown ```markdown | Term | Description | | :--- | :---------- | -{% hrg="tev2" converter="markdowntable" %} +{% hrg="tev2" converter="markdown-table-row" %} --- ```
-Specifying the [MRGref](@) using a [handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars), as follows. +Specifying the [MRGref](@) using a [Handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars), as follows. ~~~ markdown | Term | Description | @@ -108,21 +130,7 @@ Specifying the [MRGref](@) using a [handlebars expression](https://handlebarsjs. --- ~~~ -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](#custom-glossary-converters) on how to make them more robust, or even better: the documentation on [handlebars expressions](https://handlebarsjs.com/guide/#what-is-handlebars). - - -
- -Specifying the [MRGref](@) using the [handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars) similar to the implementation [here](https://essif-lab.github.io/framework/docs/essifLab-glossary), is done as follows. - -~~~ markdown -| 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](https://github.com/essif-lab/framework/blob/master/docs/terminology-config.yaml) of the [essif-lab/framework](https://github.com/essif-lab/framework/tree/master) repository, which is explained further [below](#converter-for-essif-lab-glossary-look-alikes). The actual reference `{% hrg="" %}` uses all the defaults (set in the config). +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](#custom-glossary-converters) on how to make them more robust, or even better: the documentation on [Handlebars expressions](https://handlebarsjs.com/guide/#what-is-handlebars). @@ -142,20 +150,19 @@ Under the assumption that the [terminology identifier](@) `tev2` refers to a [te ### 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](https://essif-lab.github.io/framework/docs/essifLab-glossary). The markdown file that would produce this would be as follows: +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](https://essif-lab.github.io/framework/docs/essifLab-glossary). The markdown file that would produce this would be as follows.
-Specifying the [MRGref](@) using the predefined glossary layout called `essiflab`: +Specifying the [MRGref](@) using the predefined glossary layout called `markdown-section-3`: ~~~ markdown --- @@ -166,7 +173,7 @@ sidebar_label: Glossary # Glossary -{% hrg="tev2" converter="essiflab" %} +{% hrg="essiflab" converter="markdown-section-3" %} --- Here endeth the glossary. @@ -175,12 +182,7 @@ Here endeth the glossary.
-Specifying the [MRGref](@) using a [handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars), as follows: - -:::warning 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 ) -::: +Specifying the [MRGref](@) using a [Handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars), as follows: ~~~ markdown --- @@ -191,43 +193,20 @@ 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" %} +{% hrg="tev2" converter="### [{{glossaryTerm}}]({{localize navurl}})\n\n{{glossaryText}}\n\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](#custom-glossary-converters) on how to make them more robust, or even better: the documentation on [handlebars expressions](https://handlebarsjs.com/guide/#what-is-handlebars). +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](#custom-glossary-converters) on how to make them more robust, or even better: the documentation on [Handlebars expressions](https://handlebarsjs.com/guide/#what-is-handlebars). -
- -Specifying the [MRGref](@) using the [handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars) as it was originally implemented, is done as follows: - -:::warning Editor's note -@Ca5e: please check that the handlebar expression that is ACTUALLY USED for the `essiflab` converter is specified here below. -::: + -~~~ markdown ---- -# 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](#custom-glossary-converters) on how to make them more robust, or even better: the documentation on [handlebars expressions](https://handlebarsjs.com/guide/#what-is-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 this: +Under the assumption that the [terminology identifier](@) `essiflab` 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: ~~~ markdown --- @@ -238,15 +217,15 @@ sidebar_label: Glossary # Glossary -## [Glossary](/docs/terms/glossary) +### [Glossary](/docs/terms/glossary) an alphabetically sorted list of [terms](@) with the (single) meaning it has in (at least) one context. -## [Curator (of a Scope)](/docs/terms/curator) +### [Curator (of a Scope)](/docs/terms/curator) a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@). -## [Definition](/docs/terms/definition) +### [Definition](/docs/terms/definition) the combination of a [term](@) and a descriptive text, where the [term](@) refers to a [concept](@) or other [semantic unit](@), and the descriptive text enables a set of [parties](@) to have the same understanding about that [concept](@). Ideally, the descriptive text is a criterion that such [parties](@) can use to determine what is, and what is not, an instance (or example) of that [concept](@). @@ -256,14 +235,26 @@ Here endeth the glossary. ## Custom Glossary Converters {#custom-glossary-converters} -When the predefined glossary converters are not appropriate, [curators](@) can define their own converter, by specifying them as a [handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars). +When the predefined glossary converters are not appropriate, [curators](@) can define their own converter, by specifying them as a [Handlebars expression](https://handlebarsjs.com/guide/#what-is-handlebars). -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](@). +The handlebar expressions 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. -:::info 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](https://github.com/tno-terminology-design/tev2-tools/issues/4) -::: +Converters can use the [helper functions](@converter-profile#helper-functions) and [block helpers](https://handlebarsjs.com/guide/block-helpers.html#basic-blocks) 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. + +```ts +{{capFirst entry.term}} + +{{#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"}} + An image of {{term}} +{{/ifValue}} + +``` -:::info 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))? -::: +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. diff --git a/docs/specs/tools/22-hrgt.md b/docs/specs/tools/22-hrgt.md index 9b99ae1a6e..d7495eabdd 100644 --- a/docs/specs/tools/22-hrgt.md +++ b/docs/specs/tools/22-hrgt.md @@ -229,7 +229,7 @@ The predefined sorting options are as follows: | Predefined option | What it does | | :---: | :--- | | `default` | Sorting of [HRG entries](@) is done by using the `term` field of their corresponding [MRG entries](entry@) as sort value. If multiple [entries](mrg-entry@) with the same `term` field contents, exist, these [entries](mrg-entry@) are then sorted according to their `termType` field, making the sort unique.[^1] | -| `glossaryTerm` | Sorting of [HRG entries](@) is done by using the `glossaryTerm` field of their corresponding [MRG entries](@) as sort value. If the `glossaryTerm` field does not exist, sorting value is computed using the `default` sorting methods. | +| `glossaryterm` | Sorting of [HRG entries](@) is done by using the `glossaryTerm` field of their corresponding [MRG entries](@) as sort value. If the `glossaryTerm` field does not exist, sorting value is computed using the `default` sorting methods. | [^1]: Note that the value of the `termid` field of an [MRG entry](@) is unique within the [MRG](@) that holds the [MRG entry](@) - it serves as a 'primary key'. That's why sorting first on the `term` field and then on the `termType` field makes the sort unique. Also note that this sorting differs from sorting on the `termid` field itself, as this would result in an [HRG](@) in which the [entries](hrg-entry@) are grouped according to their `termType` - thus [concepts](@), [patterns](@), and other kinds of [semantic units](@) are then grouped. diff --git a/docs/terms/converter-profile.md b/docs/terms/converter-profile.md index da4c7297c8..f990c11998 100644 --- a/docs/terms/converter-profile.md +++ b/docs/terms/converter-profile.md @@ -28,7 +28,7 @@ A **converter profile** is a data object, of a type that is specific for a [text The generic workings of [converter profiles](@) is documented in the [TEv2 Text Conversion pattern](/docs/overview/tev2-text-conversion). -# Converter Profile Object {#object} +## Converter Profile Object {#object} 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. @@ -37,12 +37,14 @@ The converter profile object can be envisaged as a YAML object, that has a numbe | `int` | (interpreter): includes information about the interpreter type `int.type`, and the regex used to locate the reference `int.regex`. The `noRefs` helper 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` | all fields from the [terminology section](mrg#terminology@) of the [mrg](@) from which the [MRG entry](@) was taken. | +| `mrg` | (MRG): all fields from the [terminology section](mrg#terminology@) of the [mrg](@) from which the [MRG entry](@) was taken. | | `err` | (error): various fields, as specified below, that can be used to construct output that helps users identify an error, and fix it. | Fields from the `entry` section may also be used in [converters](@) without specifying `entry` as a prefix. Properties of the `entry` with identical names to sections of the converter profile object are overwritten. -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: +### `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 @@ -67,3 +69,69 @@ When a file is being processed by a [text conversion tool](@), it can happen tha ```mdx-code-block ``` + +## Helper functions +Multiple custom [helper functions](https://handlebarsjs.com/guide/expressions.html#helpers) have been specified in addition to the [built-in helper functions](https://handlebarsjs.com/guide/builtin-helpers.html) of [Handlebars](https://handlebarsjs.com/guide/#what-is-handlebars), which can be used within [handlebars expressions](@) to modify the [converter](@) output. The input given to a helper function is always the evaluated value of the expression that follows the call, possibly with extra options. + +```ts title="Mustache expression format" +// highlight-next-line +{{ =""}} +{{capFirst entry.term}} +{{noRefs entry.glossaryText type="markdown"}} +``` + + +### `capFirst` +This simple helper with identifier `capFirst` replaces every word's first character with the capitalized equivalent. Words are obtained by splitting the input on space characters.
+*It takes the input, splits the input at spaces, and capitalizes the first character of every split item, after which the output is returned.* + +### `noRefs` +This helper with identifier `noRefs` attempts to use the configured `type` to convert all references to the `showtext` property of the interpreted reference. It also capitalizes the `showtext` replacement using the `capFirst` helper.
+*It takes the input, finds matches using the configured syntax-`type` and uses the capitalized interpreted `showtext` property as a replacement, after which the output is returned.* + +Three standard values are available to be used as the value for the `type` option. Multiple values may be provided, in which case the values are interpreted in order from left to right. If no value is provided, '`interpreter`' is used as the default `type`. If a `type` is provided that does not match any of the standard `type` values, the value is assumed to be a custom [regex](@). + +Available `type` values: + +```mdx-code-block + +``` + +| `type` | Description | +| :------------ | :---------- | +| `interpreter` | Uses the [regex](@) of the configured [interpreter](#interpreter) to find matches. | +| `html` | Uses the [regex](@) `]*?>(?.*?)<\/a>` to find HTML `` tags and uses the value in between the opening and closing tag as `showtext`. | +| `markdown` | Uses the [regex](@) `\[(?[^\]]+)\]\((?:[^)]+)\)` to find Markdown hyperlinks and uses the link text as `showtext`. | +| `custom` | A value for `type` that does not match any of the standard `type` values is assumed to be a custom [regex](@). | + +```mdx-code-block + +``` + +```ts title="NoRefs example" +{{noRefs entry.glossaryText}} +{{noRefs entry.glossaryText type="markdown"}} +{{noRefs entry.glossaryText type="markdown, html, interpreter"}} +{{noRefs entry.glossaryText type="/\[(?[^\]]+)\]\((?:[^)]+)\)/, html"}} +``` + +### `ifValue` +This helper with identifier `ifValue` allows for equality checking by comparing the first value with the value specified as the `equals` argument. Pay attention to the use of a `#` character in front of the opening helper tag (`#ifValue`) and a `/` character at the closing (`/ifValue`) tag in the example.
+ *It compares the input given as the value trailing the opening helper identifier (`ifValue`) and the value of the `equals` option, and returns the value inbetween the opening and closing helper tag if the values are equal.* + +```ts title="ifValue example" +{{#ifValue entry.termType equals="concept"}}Artifact is a concept{{/ifValue}} +{{#ifValue entry.termType equals="image"}}Artifact is an image{{/ifValue}} +``` + +### `localize` +This helper with identifier `localize` attempts to parse the value it was given as a URL and compares it to the `website` value of the [MRG](@) in the converter profile. If both the `host` values (e.g., tno-terminology-design.github.io) match, the `pathname` of the URL is returned. If the given value cannot be interpreted as a URL, or the `host` values do not match, the input value is returned. This can be useful in situations where external links (URL's pointing to a website other than the current `host`) are handled differently from internal links. + +```ts title="localize example" +{{localize entry.navurl}} +// using the localize helper, converts +"https://tno-terminology-design.github.io/tev2-specifications/docs/terms/author" +// into +"/tev2-specifications/docs/terms/author" +// when the `host` value of the URL matches the MRG website's `host` value +```