Skip to content

Commit

Permalink
Update documentation tno-terminology-design/tev2-tools#19 #22
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ca5e
Ca5e committed Jan 21, 2024
1 parent d24a6fb commit a02d4b5
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 79 deletions.
141 changes: 66 additions & 75 deletions docs/specs/syntax/41-mrg-ref-syntax.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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="<tid>" converter="<converter>" %}
{% 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](@).
- `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="<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](#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="<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`.
- `<sorter>` 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}

Expand All @@ -50,6 +54,25 @@ The predefined interpreters for detecting [MRGRefs](@) are as follows:
</APITable>
```

## 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
<APITable>
```

| `<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`. |

```mdx-code-block
</APITable>
```

## 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.
Expand All @@ -62,7 +85,7 @@ The predefined converters for glossary generation are:
<APITable>
```

| `<glossary layout>` | Description |
| `<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. |
Expand All @@ -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.

<Tabs
groupId="converter-specs"
groupId="md-converter"
defaultValue="predefined"
values={[
{label: 'Using predefined layout', value: 'predefined'},
{label: 'Simple customized layout', value: 'simple'},
{label: 'Actual implementation', value: 'actual'},
{label: 'Simple customized layout', value: 'simple'}
]}>

<TabItem value="predefined"><br/>
Expand All @@ -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" %}
---
```
</TabItem>

<TabItem value="simple"><br/>

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 |
Expand All @@ -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).
</TabItem>

<TabItem value="actual"><br/>

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).
</TabItem>

</Tabs>
Expand All @@ -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.

<Tabs
groupId="converter-specs"
groupId="essif-converter"
defaultValue="predefined"
values={[
{label: 'Using predefined layout', value: 'predefined'},
{label: 'Simple customized layout', value: 'simple'},
{label: 'Actual implementation', value: 'actual'},
{label: 'Simple customized layout', value: 'simple'}
]}>

<TabItem value="predefined"><br/>

Specifying the [MRGref](@) using the predefined glossary layout called `essiflab`:
Specifying the [MRGref](@) using the predefined glossary layout called `markdown-section-3`:

~~~ markdown
---
Expand All @@ -166,7 +173,7 @@ sidebar_label: Glossary

# Glossary

{% hrg="tev2" converter="essiflab" %}
{% hrg="essiflab" converter="markdown-section-3" %}

---
Here endeth the glossary.
Expand All @@ -175,12 +182,7 @@ Here endeth the glossary.

<TabItem value="simple"><br/>

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
---
Expand All @@ -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).
</TabItem>

<TabItem value="actual"><br/>

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.
:::
</Tabs>

~~~ 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).
</TabItem>

</Tabs>

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
---
Expand All @@ -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](@).

Expand All @@ -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
<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}}

```

:::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.
2 changes: 1 addition & 1 deletion docs/specs/tools/22-hrgt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading

0 comments on commit a02d4b5

Please sign in to comment.