Guide-termrefs

docs/guides/50-using-termrefs.md

@@ -0,0 +1,95 @@
+---
+id: using-termrefs
+date: 20240109
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl'
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Using TermRefs
+
+<img
+  alt="This page is under construction"
+  src={useBaseUrl('images/wip/wip-under-construction.png')}
+/><br/><br/>
+
+:::info Editor's note
+This page currently only uses basic TermRef syntax. Do we also want to show alt(ernative) syntax?  
+If so, there are two options: (1) do so in a separate page, or (2) use (synchronized) Tabs. 
+:::
+
+A [TermRef](@) is a construct that [authors](@) can use to help their readers to better understand particular [words or phrases](terms@) they use in their texts.
+
+:::tip The text below has three examples of a [TermRef](@):
+A **`[TermRef](@)`** is a construct that **`[authors](@)`** can use to help their readers to better understand particular **`[words or phrases](terms@)`** they use in their texts.
+:::
+
+When texts that an [author](@) writes are processed, e.g., to become part of a static website such as the one you are now accessing as you read this, the [TermRefs](@) therein are converted into something that helps readers: in this case, a [TermRef](@) is highlighted; also, if the reader hovers over the [TermRef](@), it shows a popup with some short information about that concept; and finally, it is also turned into a hyperlink that readers can click on to navigate to a page that contains more information about the [concept](@) that the [TermRef](@) references.
+
+This page shows you:
+
+1. How you can create basic [TermRefs](@);
+2. How [TermRefs](@) are converted (into so-called [RenderableRefs](@))
+3. How you can customize the [TermRef](@) syntax;
+4. How you can determine what the [TermRef](@) will look like after it is converted.
+
+## Basic [TermRefs](@)
+
+The most common [TermRefs](@) that you will encounter are of the form 
+
+``` markdown
+[<word or phrase>](@)
+```
+where `<word or phrase>` is the the [showtext](@) part of the [TermRef](@), i.e., the part that - when the texts are converted - typically shows up in some highlighed fashion, links to the documentation of the [concept](@) that it references, and might have a pop-up text with a short description.
+
+This most common variety works if the [showtext](@) is a [term](@) that is defined, or a common derivative form. For example if the [term](@) `showtext` is defined, you can use `[showtext](@)` but you should also be able to use `[showtexts](@)` (plural form), and even `[showtext(s)](@)` (to signify 'one or more showtexts').
+
+This also holds for nouns that have different endings. For example, if the [term](@) 'party' is defined, you can use `[party](@)` but you should also be able to use `[parties](@)` (plural form), and even `[party's](@)` (as in `this is that [party's](@) perogative`)).
+
+### Explicitly mentioning the [term](@)
+
+If this doesn't work (which may happen), but you are sure the [term](@) is defined, then you can use the syntax:
+
+``` markdown
+[<showtext>](<term>@)
+```
+
+where
+
+- `<showtext>` is the (required) [showtext](@) part of the [TermRef](@), and
+- `<term>` is the term to which you want `<showtext>` to refer.
+
+For example, `[organizations or individuals](party@)` will render as [organizations or individuals](party@) (if you hover over it, or click the link, you will see that it will link to the documentation of [party](@)).
+
+Of course, all this relies on that the `<term>` has been properly defined.
+
+### Explicitly mentioning the [term type](@)
+
+Sometimes, a single [term](@) is used to refer to [semantic units](@) of different types. For example, the term 'terminology' can refer to a [concept](@), but it could also refer to a [mental model](pattern@) that shows how a set of related [concepts](@), [relations](@) etc. work together in a coherent fashion. 
+
+You need to be able to refer to both, and the [TermRefs](@) you use should be unambiguous. You can do that by specifying the [term type](@) in the [TermRef](@), as follows
+
+- [terminology](concept:terminology@) (i.e.: `[terminology](concept:terminology@)`) refers to the [concept](@) named `terminology`.
+- [terminology](pattern:terminology@) (i.e.: `[terminology](pattern:terminology@)`) refers to the [pattern](@) named `terminology`.
+
+The texts that are used to identify a term type are not standardized. It is up to the [curators](@) of a [scope](@) to determine what they can be, and to ensure that they are correctly specified in the [headers](@) of the [curated texts](@) that describe the corresponding [semantic units](@).
+
+### Refering to a [term](@) that is defined in another [scope](@)
+
+You can also refer to a [term](@) that wasn't defined in the [scope](@) within which you are creating your [TermRef](@). For example, if would want to refer to the [term](@) `party` as it is defined in the [scope](@) (that is identified by the [scopetag](@)) `essif-lab`, you simply add that [scopetag](@) behind the `@` character, as in [party](@essif-lab) (`[party](@essif-lab)`).
+
+You may also refer to a [term](@) that is defined in a particular version of a [terminology](@), as illustrated by the general syntax
+
+``` markdown
+[<showtext>](@<scopetag>:<vsntag>)
+```
+
+where
+
+- `<showtext>` is the (required) [showtext](@) part of the [TermRef](@).
+- `<scopetag>` is the (optional) [scopetag](@) that specifies the [scope](@) from which the [terminology](@) is to be used; if `<scopetag>` isn't specified, the [current scope](@) is assumed.
+- `<vsntag>` is the (optional) [versiontag](@) that specifies the version of the [terminology](@) that is to be used. If `<vsntag>` isn't specified, then the default version of the [terminology](@) is used, the [vsntag](@) of which is defined in the [SAF](@).
+
+## How [TermRefs](@) are Converted (into [RenderableRefs](@))
+

docs/terms/converter-profile.md

@@ -32,11 +32,78 @@ The generic workings of [converter profiles](@) is documented in the [TEv2 Text
 
 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.
 
+<details>
+  <summary>Example</summary>
+Here is an example of what a converter profile object might look like for the [TermRef](@) `[converter profile object](converter-profile#object@)`
+
+~~~ yaml
+int
+  type: "???"
+  ???
+ref
+  showtext: "converter profile object"
+  termType: ""
+  termid: "converter-profile"
+  trait: "object"
+  scopetag: ""
+  vsntag: ""
+entry
+  # Docusaurus header
+  id: converter-profile
+  displayed_sidebar: tev2SideBar
+  # TEv2 Curated Text Header
+  term: converter-profile
+  termType: concept
+  glossaryTerm: Converter Profile
+  glossaryText: "a data object, of a type that is specific for a [text conversion tool](@), that [converters](@) use to create texts by which the [tool](text-conversion-tool@) will replace the text constructs that are located by its [interpreter](@)."
+  grouptags:
+  formPhrases: [ "converter-profile{ss}", "profile{ss}" ]
+  # Curation status
+  status: proposed
+  created: 20231218
+  updated: 20240108
+  # Origins/Acknowledgements
+  contributors: RieksJ
+  attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)"
+  originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)"
+mrg:
+  scopetag: "tev2"
+  scopedir: "https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs"
+  curatedir: "terms"
+  glossarydir: "glossaries"
+  defaultvsn: "documentation"
+  website: "https://tno-terminology-design.github.io/tev2-specifications/docs"
+  navpath: "/terms"
+  navid: "id"
+  license: "LICENSE.md"
+  statuses:
+    - "proposed"
+    - "approved"
+    - "deprecated"
+  issues: "https://github.com/tno-terminology-design/tev2-specifications/issues"
+  curators:
+    - name: "RieksJ"
+      email:
+        id: "rieks.joosten"
+        at: "tno.nl"
+  defaulttype: "concept"
+  vsntag: "documentation"
+  altvsntags:
+    - "latest"
+err
+  file: | Y | Name of the file where the specific reference was found. |
+  line: 73
+  pos: 9
+  cause: ""
+~~~
+
+</details>
+
 | Section | Description |
 | ------- | ----------- |
-| `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. |
+| `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. | 
+| `entry` | (MRG entry): all fields from the specific [MRG entry](@) that was selected. | 
 | `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. |
 
@@ -71,6 +138,7 @@ When a file is being processed by a [text conversion tool](@), it can happen tha
 ```
 
 ## 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"
@@ -80,14 +148,35 @@ Multiple custom [helper functions](https://handlebarsjs.com/guide/expressions.ht
 {{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.<br/>
-*It takes the input, splits the input at spaces, and capitalizes the first character of every split item, after which the output is returned.*
+
+The function of the helper `capFirst` is to capitalize every first character from every word in a string.
+
+```ts title="Examples for 'capFirst'"
+{{capFirst entry.glossaryTerm}}   # e.g. "converter profile" becomes "Converter Profile"
+{{capFirst entry.glossaryText}}   # e.g. "This is a description; for SOME TERM" becomes "This Is A Description; For SOME TERM"
+```
+
+The helper `capFirst` replaces the first character of every word of its argument with the capitalized equivalent. 
+Words are obtained by splitting the input on space characters.<br/>
+*It takes a string as input, splits the string at spaces, capitalizes the first character of every split item,
+reconstructs the input string fomr the split items, and returns the result.*
 
 ### `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.<br/>
-*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.*
+
+The function of the helper `noRefs` is to replace all [TermRefs](@) from a string, with its (capitalized) [showtext](@). Capitalization is done by the helper `capFirst`.
+
+```ts title="Examples for 'noRefs'"
+{{noRefs entry.glossaryText}}
+{{noRefs entry.glossaryText type="markdown"}}
+{{noRefs entry.glossaryText type="markdown, html, interpreter"}}
+{{noRefs entry.glossaryText type="/\[(?<showtext>[^\]]+)\]\((?:[^)]+)\)/, html"}}
+```
+
+The helper `noRefs` uses 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.<br/>
+*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](@).
 
@@ -108,30 +197,30 @@ Available `type` values:
 </APITable>
 ```
 
-```ts title="NoRefs example"
-{{noRefs entry.glossaryText}}
-{{noRefs entry.glossaryText type="markdown"}}
-{{noRefs entry.glossaryText type="markdown, html, interpreter"}}
-{{noRefs entry.glossaryText type="/\[(?<showtext>[^\]]+)\]\((?:[^)]+)\)/, 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.<br/>
- *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.*
+
+The function of the helper `ifValue` is to conditionally render text, based on equality of values. This complements the existing [`#if`-`/if` syntax](https://handlebarsjs.com/guide/builtin-helpers.html#if), that conditionally renders text based on existence of values.
 
 ```ts title="ifValue example"
 {{#ifValue entry.termType equals="concept"}}Artifact is a concept{{/ifValue}}
 {{#ifValue entry.termType equals="image"}}Artifact is an image{{/ifValue}}
 ```
 
+The helper `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.<br/>
+ *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.*
+
 ### `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"
+The function of the helper `localize` is to convert absolute URLs to relative paths within a specific website context if that is possible,
+enhancing internal navigation efficiency and consistency (particularly in static website generator contexts).
+
+```ts title="Examples for 'localize'"
 {{localize entry.navurl}}
 // using the localize helper, converts
-"https://tno-terminology-design.github.io/tev2-specifications/docs/terms/author"
+"https://tno-terminology-design.github.io/tev2-specifications/docs/terms/converter-profile"
 // into
-"/tev2-specifications/docs/terms/author"
+"/tev2-specifications/docs/terms/converter-profile"
 // when the `host` value of the URL matches the MRG website's `host` value
 ```
+
+The helper `localize` parses 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.

docs/terms/showtext.md

@@ -0,0 +1,26 @@
+---
+# Docusaurus header
+id: showtext
+displayed_sidebar: tev2SideBar
+# TEv2 Curated Text Header
+term: showtext
+termType: concept
+glossaryTerm: Showtext (of a TermRef)
+glossaryText: "the first part of a [TermRef](@), i.e., the word or phrase that needs to refer to a particular [concept](@) (or other [semantic unit](@)), and that the reader will see in some marked up way, and that will be rendered such that it provides additional help for [readers](@) to (better) understand the intention of its [author](@)."
+grouptags:
+formPhrases: [ "showtext{ss}", "show-text{ss}" ]
+# Curation status
+status: proposed
+created: 20240125
+updated: 20240125
+# Origins/Acknowledgements
+contributors: RieksJ
+attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)"
+originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)"
+---
+
+# Showtext
+
+The **Showtext** of a [TermRef](@) is its first part, i.e., the word or phrase that needs to refer to a particular [concept](@) (or other [semantic unit](@)), and that the reader will see in some marked up way, and that will be rendered such that it provides additional help for [readers](@) to (better) understand the intention of its [author](@).
+
+Further information can be found in the documentation of [TermRef](@), as well as in the specification of the [TermRef syntax](/docs/specs/syntax/term-ref-syntax).